# pythonstyle-vue **Repository Path**: chinacsj123/pythonstyle-vue ## Basic Information - **Project Name**: pythonstyle-vue - **Description**: PythonStyle是一个企业级开发框架,采用MVC架构,统一入口,自动实现访问路由。内置模块包含:用户管理、部门管理、角色管理、菜单及按钮授权、日志管理、登录模块等。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 13 - **Forks**: 3 - **Created**: 2025-01-16 - **Last Updated**: 2026-11-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # PyCodev Vue3 v2.0 PyCodev 是一个面向企业后台场景的 Python 全栈开发框架,当前版本由 `ASGI + Uvicorn` 后端和 `Vue 3 + Element Plus` 管理端组成。 项目默认聚焦五类框架能力: - 系统管理 - 系统监控 - 流程管理 - 表单管理 - MCP 原子能力(Agent 调用入口) ## 核心特性 - 保留 `m/c/a` 开发组织方式,便于继续扩展后台业务模块 - 每个模块提供 `module.yml` 清单,启动时校验字段、版本与依赖,缺清单或依赖成环直接失败 - 后端统一返回结构、统一配置加载、统一权限控制链路 - 支持行级数据权限:全部、自定义部门、本部门、本部门及以下,系统、表单、Agent、流程模块统一接入 - 内置登录认证、菜单权限、验证码、操作日志、登录日志、定时任务 - 提供流程定义、流程运行时、表单设计、表单数据管理基础能力 - 支持 MySQL、Redis、任务调度、多环境配置与迁移脚本管理 - 提供 FastMCP 服务入口与声明式工具注册(`@auto_mcp_tool` + `ToolRegistry`) - 自动生成 OpenAPI 3.0 描述,开发环境可直接访问 `/docs` 与 `/openapi.json` - 每个响应自动返回 `X-Request-ID`,并写入日志前缀,便于按请求号排查问题 - 提供 `/metrics` Prometheus 指标、JSON 结构化日志和慢 SQL 告警 - 提供 Agent 管理页面:智能助手对话工作台、模型配置、能力注册、模型调用日志、能力观测,并在布局右侧提供快捷入口 - 对话工作台支持内置异步 MCP 编排、只读工具调用、流式回答和统计 BI 报表,并自动生成可点击下载的自包含 HTML 报表链接;当前编排引擎为内置异步循环,未接入 LangGraph 图执行 ## 路由与参数约定 - 路由规则固定为 `/m/c/a`:`m`=模块名,`c`=控制器名,`a`=控制器内的方法名。例如 `/system/user/list` 表示 `system` 模块下 `user` 控制器的 `list` 方法。 - 路径前 3 段只用于定位路由,不参与业务参数解析;从第 4 段开始才是参数对。 - `m/c/a` 以路径为准,查询串中的 `m/c/a` 只在路径未提供对应段时补充;业务参数同名时查询串优先。 - 参数支持两种写法,可混用,同名时查询串优先: - 路径参数:`/system/user/list/pageNum/2/pageSize/20` - 查询串:`/system/user/list?pageNum=2&pageSize=20` - 后端统一通过 `utils.getRequest()`、`utils.getRequestJson()`、`utils.getPage()`、`utils.getPageSize()` 读取,二者都会自动兼容。 - `m`、`c`、`a` 是路由定位字段,不参与路径参数解析,避免覆盖路由分发。 - 菜单“路由参数”按 JSON 对象填写,例如 `{"page":"1","status":"0"}`;前端会解析后拼接到菜单地址,后端保存时统一规范化为紧凑 JSON 字符串。 - 参数安全约束:路径参数键名只允许字母、数字、下划线、点和短横线,最多 32 对,单值最长 2048 字符,含控制字符的片段会被丢弃;菜单参数键名同样校验并拒绝 `__proto__`、`prototype`、`constructor`,单值最长 200 字符,数组最多 20 项;`getPage()` / `getPageSize()` 遇到非法数字会回退默认值。 ## 接口文档与请求追踪 启动后端后可直接访问: - Swagger UI:`http://127.0.0.1:8081/docs` - ReDoc:`http://127.0.0.1:8081/redoc` - OpenAPI JSON:`http://127.0.0.1:8081/openapi.json` 接口文档由 `RouteRegistry` 中已注册的非私有路由自动生成,无需额外维护注解。生产环境可在配置中关闭: ```yaml openapi: enabled: false ``` 服务端会复用调用方传入的合法 `X-Request-ID`(8-128 位字母、数字、点、下划线或短横线),否则自动生成新的请求号,并在响应头和日志前缀中返回,例如: ```text 2026-11-05 20:46:50 - INFO - [4f2c9d7e8a1b4c3d9e0f1a2b3c4d5e6f] 处理请求 ``` ## 日志与指标 `resources/application.yml` 中的日志配置: ```yaml log: format: text # text:本地可读;json:日志平台采集 level: INFO slow_query_threshold_ms: 1000 ``` - 访问日志包含 `request_id`、`user_id`、`method`、`path`、`status`、`elapsed_ms`; - `format: json` 时输出单行 JSON,便于 Loki/ELK 采集; - 日志正文会对 `password`、`token`、`Authorization` 等字段做脱敏; - 超过 `slow_query_threshold_ms` 的 SQL 记录 `pycodev.sql` 告警,只记录 SQL 摘要,不记录参数。 Prometheus 指标端点: - 地址:`http://127.0.0.1:8081/metrics` - 未配置 `metrics.token` 时只允许本机访问;跨机采集时在配置中设置随机令牌,并通过 `X-Metrics-Token` 或 `Authorization: Bearer ` 传入; - 主要指标:`http_requests_total`、`http_request_duration_seconds`、`db_query_duration_seconds`、`redis_operation_duration_seconds`、`scheduler_jobs_total`、`upload_bytes_total`、`agent_model_calls_total`。 ## 模块清单 `pycodev/modules//module.yml` 是模块契约。启动时会先校验清单,再扫描路由;缺清单、依赖缺失、版本不满足或依赖成环都会直接报错,不会出现部分路由静默消失。 ```yaml name: flow version: 2.0.0 description: 流程定义、流程设计、流程运行时、实例流转与待办已办 depends_on: system: ">=2.0.0" menus: [] permissions: [] migrations: [] entrypoints: {} ``` - `name` 必须与目录名一致,`version` 使用数字版本号; - `depends_on` 支持映射(可带版本约束)或模块名列表; - 可选 `menus`、`permissions`、`migrations`、`entrypoints`、`lifecycle`; - 启动只做清单校验,不执行副作用;安装/升级/卸载通过 `python tools/module_lifecycle.py` 显式执行; - 安装/升级会按声明顺序执行 `migrations`,卸载默认只把模块标记为 `disabled`,不删除数据; - 校验结果写入 `app.state["modules"]`,手工检查可执行 `python tools/check_module_manifests.py`。 新增模块的完整步骤见 [doc/新成员上手指南.md](doc/新成员上手指南.md)。 ## 相关文档 - 错误码说明:[doc/error-codes.md](doc/error-codes.md) - OpenAPI 静态产物:[doc/openapi.json](doc/openapi.json) - 新成员上手指南:[doc/新成员上手指南.md](doc/新成员上手指南.md) - 架构决策记录:[doc/架构决策记录.md](doc/架构决策记录.md) - 框架完善实施方案:[doc/框架完善实施方案.md](doc/框架完善实施方案.md) - MCP 原子能力手册:[doc/MCP原子能力可视化使用手册.md](doc/MCP原子能力可视化使用手册.md) - 智能化底座路线图:[doc/智能化企业管理系统底座路线图.md](doc/智能化企业管理系统底座路线图.md) ## 目录结构 ```text . ├── main.py ├── scheduler_main.py ├── mcp_main.py ├── pycodev/ ├── resources/ ├── vue/ ├── doc/ ├── tests/ ├── tools/ ├── static/ ├── logs/ ├── artifacts/ ├── requirements.txt └── gunicorn_run.sh ``` 后端主目录说明: ```text pycodev/ ├── app.py ├── core/ │ └── mcp_registry/ ├── mcp/ ├── compat/ ├── libs/ ├── common/ ├── model/ ├── config/ └── modules/ ├── agent/ ├── content/ ├── flow/ ├── form/ ├── monitor/ ├── system/ └── test/ ``` 前端主目录说明: ```text vue/src/ ├── api/ ├── assets/ ├── components/ ├── directive/ ├── layout/ ├── router/ ├── stores/ ├── utils/ └── views/ ├── agent/ ├── flow/ ├── form/ ├── monitor/ ├── system/ ├── login.vue ├── register.vue └── index.vue ``` ## 环境要求 - Python 3.10+ - Node.js 18+ - MySQL 8+ - Redis 6+(推荐) ## 后端启动 推荐在项目根目录创建虚拟环境(`.venv/` 已被忽略,不会进入版本库): Windows: ```powershell python -m venv .venv .\.venv\Scripts\activate python -m pip install -r requirements.txt ``` Linux / macOS: ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt ``` > 不要把虚拟环境直接创建在仓库根目录(会生成 `Scripts/`、`lib/`、`pyvenv.cfg` 等文件);也不要直接把虚拟环境目录从其他磁盘复制过来,`pip.exe` 等启动器会记录创建时的绝对路径而失效。 直接启动: ```bash python main.py ``` 开发库连接信息直接维护在 `resources/application-dev.yml`,按本机 MySQL 实际账号密码修改即可,不需要额外设置环境变量。 或使用 Uvicorn: ```bash python -m uvicorn main:app --host 127.0.0.1 --port 8081 ``` 独立启动调度器: ```bash python scheduler_main.py ``` 启动 MCP 服务(默认 stdio 传输,供 Claude Desktop、IDE 等 MCP 客户端接入): ```bash python mcp_main.py ``` MCP 相关环境变量: - `PYCODEV_MCP_TOKEN`:stdio 模式下可用的进程环境令牌;仅在未显式传入 token 时读取。`http`/`sse` 传输不会读取该变量,调用方必须每次显式传入有效 token - `PYCODEV_MCP_TRANSPORT`:传输方式,默认 `stdio`;改为 `http`/`sse` 后所有工具(含公开健康检查)都强制要求 Bearer token - `PYCODEV_MCP_ALLOW_ASSERTED_AUTH`:是否允许调用方通过 `auth.user_id` 断言身份,默认关闭;仅对 stdio 本地进程生效,HTTP/SSE 传输即使开启也会拒绝 令牌签名密钥与有效期直接在 `resources/application.yml` 的 `token` 配置段中设置,不再读取环境变量。 注意:stdio 模式下 stdout 专用于 JSON-RPC,新增启动日志必须使用 `logging`(默认输出到 stderr),不要使用 `print()`。 ## 前端启动 ```bash cd vue npm install npm run dev ``` 前端质量检查与生产构建: ```bash cd vue npm run lint npm test npm run typecheck npm run build npm run size # 基于已有 dist 生成体积报告 npm run build:size # 构建并执行体积预算检查 npx playwright install chromium # 首次运行 E2E 前安装浏览器 npm run test:e2e ``` Playwright E2E 会自动拉起后端(8081)和 Vite 开发服务(81);本地已有后端实例时直接复用。登录验证码通过 `tools/get_captcha_code.py` 从 Redis 读取,仅用于本地和 CI 冒烟。 体积预算配置在 `vue/bundle-size.budget.json`,报告输出到 `vue/dist/bundle-size.json`。`tsconfig.json` 已开启 `allowJs`、关闭 `checkJs`,新代码可直接使用 `.ts`,旧代码无需一次性迁移。 ## 配置说明 主要配置文件位于 `resources/`: - `application.yml` - `application-dev.yml` - `application-ci.yml` - `application-loadtest.yml` - `application-pro.yml` - `application-pro.example.yml` 默认开发库配置位于 [resources/application-dev.yml](resources/application-dev.yml),数据库地址、账号、口令、上传限制等均直接写在配置文件中,按实际环境修改即可。 ## 数据迁移 查看待执行迁移: ```bash python tools/run_migrations.py --profile dev --dry-run ``` 执行迁移: ```bash python tools/run_migrations.py --profile dev ``` ## 常用检查 语法检查: ```bash python -m py_compile main.py scheduler_main.py mcp_main.py ``` 单元测试: ```bash python -m unittest discover -s tests -v ``` 覆盖率检查(阈值 50%,与 CI 一致): ```bash coverage run -m unittest discover -s tests coverage report ``` 乱码与编码检查: ```bash python tools/check_mojibake.py python tools/check_text_encoding.py python tools/check_business_exception_usage.py python tools/check_module_manifests.py python tools/generate_openapi.py --check ``` ## 开发约束 - Python 使用 4 空格缩进 - 文件名、模块名使用 `snake_case` - 后端接口统一通过 `Result.success()` / `Result.error()` 返回 - 简单 CRUD 可以继续放在 `pycodev/modules//controller` + `entity` - 模块可按需增加 `service` 层,默认仍以 `controller` + `entity` 为主,复杂业务再引入 `service` - 跨模块复用的通用能力优先沉淀到 `pycodev/libs/`,不要把某个页面或模块的专属业务硬塞进 `libs/` - 当前前端接口目录保留 `vue/src/api/sysetm/` 这一既有拼写以兼容旧代码 ## 后端分层约定 - `controller`:负责收参、登录态/权限入口校验、调用业务层、返回 `Result` - `entity`:负责 ORM、基础 CRUD、分页查询、简单数据映射 - `service`:负责业务编排、复杂校验、状态流转、事务控制、跨实体聚合 - `error_codes.py`:按模块维护业务错误码常量,供 `controller` / `service` 引用,避免在业务代码里散写数字错误码 - 单表分页、单表详情、单表增删改、简单状态切换等场景,可以不强制新增 `service` - 涉及多表写入、缓存/Redis、上传、调度器、日志、权限上下文、发布/审核/统计等流程时,应优先引入 `service` - `service` 不能只是对 `entity` 的空转发;没有实际业务编排价值时不要为分层而分层 ### 推荐模式 - 简单场景:`controller -> entity` - 复杂业务场景:`controller -> service -> entity` - 跨模块基础能力场景:`controller/service -> libs` ### 必须进入 `service` 的场景 - 一次操作需要同时写入多个实体或多张表 - 一次操作涉及 Redis、上传、定时任务、权限缓存、登录态、日志等协同处理 - 存在发布、审核、启停、撤回、归档、统计、同步等状态流转 - 同一段业务后续需要被接口、定时任务、内部任务或其他模块复用 - 控制器中已经出现明显的多段校验、分支编排、异常处理、数据聚合 ### `service` 编写示例 ```python from pony.orm import db_session from pycodev.libs.business_exception import BusinessException from pycodev.modules.system.entity.user import UserEntity from pycodev.modules.system.entity.user_role import UserRoleEntity class UserService: @staticmethod @db_session def add_user(params): if not params.get("role_ids"): raise BusinessException(code=202, msg="请选择用户角色") user_id = UserEntity.add_data(params) if not user_id: raise BusinessException(code=201, msg="操作失败") UserRoleEntity.replace_user_roles(user_id, params["role_ids"]) ``` 事务边界约定: - 推荐把 `db_session` 放在 `service` 方法上,由 `service` 统一控制多表写入事务。 - `entity` 继续负责 ORM 和基础读写,不承担完整业务编排。 - 上传、HTTP 调用、远程代理、长时间计算不要整段包进同一个 `db_session`;这类操作应先完成外部动作,再进入必要的数据库写入阶段。 - 为兼容旧接口,控制器方法名可以保留历史拼写;新增内部实现和新增入口优先使用规范命名,例如 `run_once_task` 优于 `run_onece_task`。 ### 禁止事项 - 不要把复杂业务流程继续堆在 `controller` - 不要让 `entity` 同时承担 ORM、查询组装和完整业务规则 - 不要把 `service` 写成仅一行调用 `entity` 的空转发层 - 不要把某个模块专属的页面业务逻辑下沉到 `libs/` ## 异常约定 - `BusinessException` 是后端可预期业务错误的统一异常类型,至少包含 `code`、`msg`、`data` - `controller` 和 `service` 中遇到参数缺失、登录态失效、权限不足、业务状态不满足等可预期错误时,优先 `raise BusinessException(...)` - 全局入口会统一把 `BusinessException` 转成 `Result.error(...)`,控制器里不要重复包一层相同的错误返回 - 成功响应仍然使用 `Result.success(...)` - 底层未知异常、系统异常、第三方异常不要强行伪装成业务成功,继续交给全局兜底处理 - 错误码采用“通用框架码 + 模块业务码号段”两级体系,`1xxx` 认证域已正式启用,独立说明见 [doc/error-codes.md](doc/error-codes.md) - 模块业务码优先定义在各模块自己的 `error_codes.py` 中,例如 `pycodev/modules/system/error_codes.py`,不要继续在业务代码里散写 `3101/4102/5108` 这类数字 - 模块内引用业务码时,优先使用 `from pycodev.modules. import codes as _codes` 这一统一导入方式 - 新增业务异常时优先使用 `BusinessException` 工厂方法;提交前建议执行 `python tools/check_business_exception_usage.py`,校验业务异常写法、`error_codes.py` 常量声明、错误码文档登记与模块号段归属 ## 部署建议 推荐使用: - `Nginx` - `Gunicorn + UvicornWorker` - `MySQL` - `Redis` 相关部署模板位于 `tools/deploy/`。 Linux 生产环境先安装依赖,`gunicorn` 与 `uvicorn-worker` 已在 `requirements.txt` 中固定版本: ```bash python -m pip install -r requirements.txt .venv/bin/gunicorn --version ``` 启动脚本会使用 `.venv/bin/gunicorn` 拉起 Web 与 Scheduler: ```bash bash gunicorn_run.sh start ``` `gunicorn` 仅支持 Linux/Unix,Windows 本地开发请继续使用 `python main.py` 或 `uvicorn`。 ### Docker Compose 仓库提供 `Dockerfile`、`docker-compose.yml` 和 `resources/application-docker.yml`,可一键拉起 MySQL、Redis、Web、Scheduler、Nginx: ```bash docker compose up -d --build ``` 启动后访问 `http://127.0.0.1:8080`。说明: - `application-docker.yml` 中的数据库、Redis、Token、指标口令仅用于本地/测试,生产必须替换; - 首次启动由 MySQL 容器执行 `resources/sql/pycodev_schema.sql`; - Web 使用 `uvicorn --workers 2`,Scheduler 单独进程,避免重复调度; - 日志、上传文件、导出文件和 artifacts 使用命名卷持久化; - `/metrics` 不通过 Nginx 公网入口暴露,需要在内网直接抓取 Web 容器。