PyCodev开发框架系统操作手册
版本V1.0
1. 文档说明
本手册面向实施、培训、运维和软著材料整理场景，结合当前仓库的功能实现、目录结构，对 PyCodev 开发框架系统的安装部署、基础配置、功能操作和日常维护方式进行统一说明。
系统采用 Python 后端与 Vue 3 前端架构，围绕系统管理、表单管理、流程管理和系统监控四类能力构建标准后台平台。用户可通过统一登录入口进入工作台，并基于角色与菜单权限完成组织管理、表单设计、流程审批与定时任务运维等操作。
2. 系统概述
PyCodev 开发框架系统是一套面向企业后台场景的全栈开发平台。后端基于 Python、Uvicorn 和框架内核实现统一运行时能力，前端基于 Vue 3 和 Element Plus 构建管理端界面，支持系统管理、表单管理、流程管理和系统监控等核心能力。
系统采用模块化组织方式，遵循 controller、entity、service 的职责划分原则，并通过统一的请求处理、权限校验、返回结构、日志留痕和调度框架，支撑业务系统快速搭建和持续演进。
3. 运行环境与部署方式
• 后端运行环境：Python 3.10 及以上，建议配合虚拟环境安装依赖。
• 前端运行环境：Node.js 18 及以上，用于本地开发与生产构建。
• 数据存储：MySQL 用于业务数据持久化，Redis 用于登录态、验证码、限流和部分缓存。
• 部署建议：生产环境使用 Nginx + Gunicorn(UvicornWorker) + MySQL + Redis，并将 Web 与 Scheduler 拆分部署。
• 后端依赖安装：pip install -r requirements.txt。
• 前端依赖安装：cd vue && npm install。
• 后端启动：python main.py。
• 调度器启动：python scheduler_main.py。
• 前端开发启动：cd vue && npm run dev。
• 前端生产构建：cd vue && npm run build。
4. 安全机制与运维要点
• 系统统一使用 Token + Redis Session 的双重登录态校验机制。
• 接口权限依赖角色、菜单和权限标识进行控制，控制器统一返回 Result.success() / Result.error() 结构。
• 登录流程支持验证码、失败锁定和请求限流，降低暴力尝试风险。
• 系统内置登录日志、操作日志与定时任务运行记录，便于审计与问题追踪。
日常运行过程中，建议将数据库连接、Redis、定时调度与上传目录配置纳入统一环境管理，并在发布前执行迁移检查、接口冒烟和编码检查，确保系统具备稳定可追踪的交付质量。
• 数据库迁移执行：python tools/run_migrations.py --profile dev。
• 接口冒烟测试：python tools/smoke_test.py --base-url http://127.0.0.1:8081 --pretty。
• 基线查询采样：python tools/query_baseline.py --base-url http://127.0.0.1:8081。
• SQL Explain 检查：python tools/explain_queries.py --profile dev。
• 乱码检查：python tools/check_mojibake.py。
• 编码检查：python tools/check_text_encoding.py。
5. 登录与工作台
系统通过统一登录页进入后台管理端。登录成功后默认进入工作台，工作台集中展示常用入口、业务概览和快捷导航，便于管理员快速进入高频模块。
用户可在个人中心查看当前账号资料并执行密码修改，形成完整的登录、鉴权与个人信息维护闭环。
图 1 系统登录入口
展示系统统一登录入口，用户输入账号、密码和验证码后进入管理后台。
图 2 工作台首页（一）
展示系统登录后的主工作台界面和核心导航入口。
图 3 工作台首页（二）
展示工作台扩展内容区域与业务概览信息。
图 4 个人信息维护
展示当前登录用户的账号资料查看与维护界面。
图 5 修改密码
展示用户修改个人密码的操作界面。
6. 系统管理
系统管理模块负责账号、角色、菜单、部门、岗位等基础主数据维护，是平台权限体系和组织结构的核心入口。
管理员可通过该模块完成用户新增、角色授权、菜单配置、组织树维护和岗位定义，从而为业务模块提供统一身份与权限基础。
图 6 用户管理
展示用户列表、搜索、启停和编辑等操作入口。
图 7 新增用户
展示新增用户时填写基础资料、所属部门和角色信息的界面。
图 8 角色管理
展示角色列表、数据权限和菜单权限管理入口。
图 9 新增角色
展示创建角色及维护角色标识、排序和权限配置的界面。
图 10 菜单管理
展示系统菜单树、路由配置和权限标识管理界面。
图 11 新增菜单
展示新增目录、菜单或按钮权限时的参数维护界面。
图 12 部门管理
展示树形部门结构的维护界面。
图 13 新增部门
展示新增部门时填写上级部门、负责人和状态信息的界面。
图 14 岗位管理
展示岗位列表、岗位编码和状态维护界面。
图 15 新增岗位
展示新增岗位时维护岗位名称、编码和排序信息的界面。
7. 表单管理
表单管理模块用于维护动态表单定义、字段布局、发布版本与运行数据。管理员可先设计表单结构，再发布版本供流程或业务页面调用。
运行期表单数据与设计期表单定义分离管理，便于后续查询、追踪和版本演进。
图 16 表单列表
展示表单定义列表、查询和版本入口。
图 17 表单设计
展示拖拽式或配置式表单设计界面。
图 18 表单预览
展示表单发布前的预览效果，用于核对字段布局和交互。
图 19 表单数据列表
展示运行期表单数据的查询与检索界面。
图 20 表单数据详情
展示单条表单运行数据的详情查看界面。
8. 流程管理
流程管理模块提供流程定义维护、流程设计、模型校验、流程发布和运行时审批等能力，是系统中实现业务流转的核心模块。
管理员可创建流程模型并发布版本；普通业务用户可在我的待办、我的已办、我发起的等页面中处理和追踪流程实例。
图 21 新增流程
展示新增流程定义时填写流程编码、名称和基础描述信息的界面。
图 22 流程设计
展示流程节点、连线和业务表单绑定的设计界面。
图 23 流程模型
展示流程模型列表和版本管理入口。
图 24 流程校验
展示流程发布前的模型校验结果界面。
图 25 我的待办
展示待办审批任务列表及通过、驳回、加签等操作入口。
图 26 待办详情
展示流程实例详情、任务记录、流转日志和流程图查看界面。
图 27 我的已办
展示用户已处理流程任务的历史记录。
图 28 我发起的
展示当前用户发起流程的实例列表与状态跟踪界面。
9. 系统监控
系统监控模块聚合运行健康信息、定时任务、登录日志和操作日志，是日常巡检和问题追踪的重要入口。
在生产环境中建议独立启动 Scheduler 进程，确保定时任务单实例执行，避免多 worker 场景下重复调度。
图 29 系统监控总览
展示系统监控首页和总体运行信息。
图 30 新增定时任务
展示定时任务配置界面，可维护触发方式、执行地址和启停状态。
图 31 登录日志
展示用户登录成功、失败和来源信息的审计界面。
图 32 操作日志
展示后台用户操作记录与接口审计信息。
10. 常见操作建议
• 新增用户前先维护部门、岗位和角色，减少后续资料反复编辑。
• 设计表单时建议先预览再发布，避免流程绑定后频繁调整字段结构。
• 流程发布前先执行模型校验，确认节点、审批人和表单绑定关系完整。
• 生产环境中定时任务应由独立 Scheduler 进程执行，避免重复触发。
• 登录日志和操作日志应定期巡检，发现异常访问或误操作时可快速追溯。
11. 结语
本手册基于当前仓库实现和界面截图生成，覆盖了系统登录、组织权限、表单设计、流程审批和监控运维等主要操作路径，可作为项目实施培训、用户交付和软著材料整理时的正式操作文档使用。后续若系统页面或流程发生变化，建议同步更新 doc/images 截图并重新执行生成脚本，以保持文档与系统实际界面一致。