增加项目的各个功能

.plan/3onvvJGzAx9Dhi05JkVpx.md

@@ -0,0 +1,212 @@
+# 实施计划：按现有架构接入测试管理模块
+
+## 目标
+在当前 Flask + SQLAlchemy 手写分层架构下，按现有模式扩展测试管理能力。保持 `model/dao/service/controller/views` 分层，不引入 FastAPI、异步框架、Celery、WebSocket 等大改架构内容。先实现同步 CRUD 与核心数据流，异步任务/实时推送/外部缺陷系统作为后续阶段。
+
+## 当前架构约束
+- 路由集中在 `app/api/views.py` 的 Flask Blueprint `api` 下。
+- Controller 位于 `app/api/controller/*Controller.py`。
+- Service 位于 `app/api/service/*Service.py`。
+- DAO 位于 `app/api/dao/*Dao.py`。
+- Model 位于 `app/api/model/*Model.py`，使用 SQLAlchemy declarative。
+- 数据库连接使用 `common/sqlSession.py` 的 `SqlSession`。
+- 响应统一使用 `common/apiResponse.py`。
+
+## 命名与接口策略
+当前已有接口路径是 `/it/api/...` 风格，不采用设计稿中的 `/api/v1/projects/{project_id}/...` 作为硬切换。
+
+新增接口建议挂在同一个 Blueprint 下，保持风格：
+- 项目：`/project/list`、`/project/detail`、`/project/create`、`/project/update`、`/project/delete`
+- 环境：`/environment/list`、`/environment/create`、`/environment/update`、`/environment/delete`
+- 模块：`/module/tree`、`/module/create`、`/module/update`、`/module/delete`
+- 用例：`/case/list`、`/case/detail`、`/case/create`、`/case/update`、`/case/delete`
+- 用例快照：`/case/snapshot/create`、`/case/snapshot/list`
+- 用例评审：`/case/review/create`、`/case/review/update`、`/case/review/list`
+- 测试计划：`/plan/list`、`/plan/detail`、`/plan/create`、`/plan/update`、`/plan/delete`
+- 计划用例：`/plan/case/add`、`/plan/case/list`、`/plan/case/execute`
+- 轮次：`/plan/round/list`、`/plan/round/create`
+- 报告：`/report/list`、`/report/detail`、`/report/generate`
+- 造数：`/data/builder/list`、`/data/builder/detail`、`/data/builder/create`、`/data/builder/update`、`/data/builder/delete`、`/data/builder/execute`、`/data/task/status`
+
+## 阶段 1：模型层与基础 DAO
+新增 model 文件：
+- `projectModel.py`
+  - `Project`
+  - `ProjectMember`
+  - `Environment`
+- `caseModel.py`
+  - `Module`
+  - `TestCase`
+  - `CaseSnapshot`
+  - `CaseReview`
+- `planModel.py`
+  - `TestPlan`
+  - `PlanCase`
+  - `TestRound`
+- `reportModel.py`
+  - `Report`
+  - `DefectSync`
+- `dataBuilderModel.py`
+  - `DataBuilder`
+  - `DataTask`
+
+实现细节：
+- PostgreSQL `JSONB` 使用 `sqlalchemy.dialects.postgresql.JSONB`。
+- PostgreSQL 数组 `tags VARCHAR(64)[]` 使用 `ARRAY(String(64))`。
+- `BIGSERIAL` 模型上用 `BigInteger` + `Sequence` 或直接 `BigInteger primary_key=True autoincrement=True`，保持 SQLAlchemy 兼容。
+- 所有 `created_time/updated_time` 使用 `TIMESTAMP, server_default=text('CURRENT_TIMESTAMP')`，风格参考现有 `UpdateSqlProject`。
+- 如需软删除，设计稿多数表未含 `is_delete`。为了保持删除接口一致性，优先给业务主表补 `is_delete` 字段：`project`、`module`、`test_case`、`test_plan`、`data_builder`。关联/历史表可物理保留不删。
+
+新增 DAO 文件：
+- `projectDao.py`
+- `caseDao.py`
+- `planDao.py`
+- `reportDao.py`
+- `dataBuilderDao.py`
+
+DAO 公共实现规则：
+- 列表方法统一接收 `filter_list, page, limit`。
+- 详情方法统一按 `id` + `is_delete=0` 查询。
+- 删除方法统一更新 `is_delete=1`。
+- 创建/更新方法返回 `(id, err_msg)` 或 `(obj, err_msg)`，与现有 `UpdateSqlProjectDao` 保持一致。
+
+## 阶段 2：项目、环境、模块、用例基础 CRUD
+新增 Service：
+- `projectService.py`
+- `caseService.py`
+
+新增 Controller：
+- `projectController.py`
+- `caseController.py`
+
+先实现：
+- 项目 CRUD
+- 项目成员新增/删除/列表
+- 环境 CRUD
+- 模块树 CRUD
+- 用例 CRUD
+- 用例详情返回不暴露 `is_delete`
+- 用例列表支持：`projectId/moduleId/priority/caseType/status/tags/keyword/pageNo/pageSize`
+
+关键逻辑：
+- 创建用例时生成 `case_key`，项目内递增，如 `TC-001`。初版可按当前项目最大 id 或 count 生成，后续再优化并发锁。
+- 更新用例时可选生成快照，初版提供单独 `/case/snapshot/create`。
+- 删除用例只更新 `test_case.is_delete=1`。
+
+## 阶段 3：评审与快照
+在 `caseDao/service/controller` 内补：
+- 创建快照
+- 查询快照列表
+- 创建评审记录
+- 更新评审状态/评论
+
+接口：
+- `POST /case/snapshot/create` body: `{caseId, createdBy}`
+- `GET /case/snapshot/list?caseId=...`
+- `POST /case/review/create` body: `{caseId, reviewerId, comments?}`
+- `POST /case/review/update` body: `{reviewId, status, comments?}`
+- `GET /case/review/list?caseId=...`
+
+## 阶段 4：测试计划与执行闭环
+新增 Service/Controller：
+- `planService.py`
+- `planController.py`
+
+实现：
+- 测试计划 CRUD
+- 轮次创建/列表
+- 批量添加用例到计划
+- 执行计划用例，更新状态、实际结果、缺陷链接、附件、执行时间、执行耗时
+- 计划详情聚合统计：`total_cases/completed/pass_rate/passed/failed/blocked`
+- 进度接口：按轮次、执行人聚合
+
+接口：
+- `GET /plan/list`
+- `POST /plan/create`
+- `GET /plan/detail?planId=...`
+- `POST /plan/delete`
+- `POST /plan/case/add`
+- `GET /plan/case/list?planId=...&roundNo=...`
+- `POST /plan/case/execute`
+- `GET /plan/progress?planId=...`
+
+初版不自动创建外部缺陷，只保存 `defect_links`。外部 JIRA/TAPD/禅道集成后续单独做。
+
+## 阶段 5：报告
+新增：
+- `reportService.py`
+- `reportController.py`
+- `reportDao.py`
+
+实现同步版报告生成：
+- 根据 `plan_id` 聚合 `plan_case` 状态
+- 保存 `report.summary` 和简单 HTML `content`
+- 列表/详情查询
+
+接口：
+- `GET /report/list?planId=&pageNo=&pageSize=`
+- `POST /report/generate` body: `{planId, generatedBy}`
+- `GET /report/detail?reportId=...`
+
+不实现 PDF 导出、异步任务、模板编辑器；这些需后续引入任务队列/文件服务。
+
+## 阶段 6：造数模块 MVP
+新增：
+- `dataBuilderService.py`
+- `dataBuilderController.py`
+- `dataBuilderDao.py`
+- `common/dataBuilderExecutor.py`
+
+实现：
+- 造数器 CRUD
+- 同步执行 JSON 定义
+- 支持 step type：`http`、`db`
+- 先不支持不安全的 `script exec`，避免安全风险
+- 执行结果保存到 `data_task`
+
+接口：
+- `GET /data/builder/list?projectId=...`
+- `POST /data/builder/create`
+- `GET /data/builder/detail?builderId=...`
+- `POST /data/builder/update`
+- `POST /data/builder/delete`
+- `POST /data/builder/execute` body: `{builderId, params, async:false}`
+- `GET /data/task/status?taskId=...`
+
+## 阶段 7：路由注册
+修改 `app/api/views.py`：
+- 保留现有 SQL 管理接口。
+- 追加新模块路由。
+- 每个路由实例化对应 Controller，返回 `ApiResponse`。
+
+为避免 `views.py` 过大，若当前应用允许多 Blueprint，后续可拆 `projectViews.py/caseViews.py/...`；本次先保持单文件，符合现有架构。
+
+## 阶段 8：数据库初始化 SQL
+新增建表 SQL 文件需要用户确认放置位置。建议：
+- `sql/test_management_schema.sql`
+
+注意：当前仓库不应主动创建文档，但 schema SQL 属于代码资产，可在用户确认后创建。
+
+## 阶段 9：验证
+最低验证：
+- Python 语法检查：`python -m py_compile` 对新增/改动 py 文件。
+- 手动接口链路：
+  1. 创建项目
+  2. 创建模块
+  3. 创建用例
+  4. 查询用例列表/详情
+  5. 创建计划
+  6. 添加用例到计划
+  7. 执行用例
+  8. 生成报告
+
+## 非本次直接实现范围
+- WebSocket 实时推送
+- Celery 异步任务
+- PDF 导出/OSS 上传
+- 外部缺陷系统自动创建
+- 前端页面
+- Docker Compose
+- Python 脚本沙箱执行
+
+这些会影响架构和依赖，需要单独确认后再做。

.plan/YCGiVLWod2rghU8nT3fEv.md

@@ -0,0 +1,856 @@
+# 角色/用户/菜单管理详细设计文档
+
+## 1. 目标
+
+基于当前项目已有的分层框架（model / dao / service / controller / views）新增以下能力：
+
+1. 角色管理
+   - 角色表
+   - 权限表
+   - 用户角色关联表
+   - 角色权限关联能力
+2. 用户管理
+   - 用户表
+   - 用户与角色分配
+3. 菜单管理
+   - 菜单表
+   - 角色分配菜单
+
+本次仅输出详细设计，不直接改业务代码。
+
+---
+
+## 2. 当前项目框架观察
+
+### 2.1 现有分层风格
+
+当前项目采用如下结构：
+
+- `app/api/model/*.py`
+- `app/api/dao/*.py`
+- `app/api/service/*.py`
+- `app/api/controller/*.py`
+- `app/api/views.py`
+
+### 2.2 当前职责边界
+
+#### model
+- 定义 SQLAlchemy 表模型
+- 每个领域通常独立一个 model 文件
+
+#### dao
+- 负责数据库增删改查
+- 已有通用风格：
+  - `create`
+  - `update_by_id`
+  - `get_by_id`
+  - `list_by_filters`
+  - `delete_by_id`
+
+#### service
+- 作为 controller 与 dao 之间的业务入口
+- 目前多数是对 dao 的薄封装
+- 适合放跨表组合查询、业务校验、聚合逻辑
+
+#### controller
+- 负责参数获取、必填校验、字段映射、返回结构拼装
+- 不应直接 `session.query(...)`
+
+#### views
+- Flask 路由层
+- 负责 request 参数读取、ApiResponse 包装、session 生命周期控制
+
+### 2.3 当前接口命名风格
+
+已有接口风格：
+- `/project/list`
+- `/project/detail`
+- `/project/create`
+- `/project/update`
+- `/project/delete`
+- `/product/list`
+- `/product/detail`
+- `/product/create`
+- `/product/update`
+- `/product/delete`
+
+建议新增模块保持一致：
+- `/role/list`
+- `/role/detail`
+- `/role/create`
+- `/role/update`
+- `/role/delete`
+- `/user/list`
+- `/user/detail`
+- `/user/create`
+- `/user/update`
+- `/user/delete`
+- `/menu/tree`
+- `/menu/create`
+- `/menu/update`
+- `/menu/delete`
+- `/role/permission/*`
+- `/role/menu/*`
+- `/user/role/*`
+
+---
+
+## 3. 总体设计原则
+
+1. 严格按当前框架分层
+2. controller 不直接查数据库
+3. 跨表聚合通过 service + dao 实现
+4. 保持与现有字段风格一致：
+   - 主键 `id`
+   - 软删字段 `is_delete`
+   - 时间字段 `created_time` / `updated_time`
+5. 优先支持后台管理能力，不先引入复杂 RBAC 继承体系
+6. 菜单、权限、角色、用户四个域解耦，但通过关联表关联
+
+---
+
+## 4. 业务对象与关系
+
+### 4.1 核心对象
+
+1. 用户 `user`
+2. 角色 `role`
+3. 权限 `permission`
+4. 菜单 `menu`
+
+### 4.2 关联对象
+
+1. 用户角色关联 `user_role`
+2. 角色权限关联 `role_permission`
+3. 角色菜单关联 `role_menu`
+
+### 4.3 关系说明
+
+- 用户 : 角色 = 多对多
+- 角色 : 权限 = 多对多
+- 角色 : 菜单 = 多对多
+- 菜单自身 = 树形父子关系
+
+### 4.4 推荐鉴权思路
+
+后续登录后：
+- 用户拥有多个角色
+- 角色聚合出权限集合
+- 角色聚合出菜单集合
+- 前端基于菜单渲染导航
+- 后端基于权限点做接口校验
+
+---
+
+## 5. 数据库表结构设计
+
+以下采用 PostgreSQL 风格，保持与现有模型一致。
+
+---
+
+## 5.1 用户表 `user`
+
+### 用途
+存储后台系统用户基础信息。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| username | VARCHAR(64) | UNIQUE NOT NULL | 登录用户名 |
+| real_name | VARCHAR(64) |  | 真实姓名 |
+| password_hash | VARCHAR(255) | NOT NULL | 密码哈希 |
+| mobile | VARCHAR(32) |  | 手机号 |
+| email | VARCHAR(128) |  | 邮箱 |
+| avatar | VARCHAR(255) |  | 头像地址 |
+| status | SMALLINT | DEFAULT 1 | 1启用 0禁用 |
+| last_login_time | TIMESTAMP |  | 最后登录时间 |
+| created_by | BIGINT |  | 创建人 |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+| updated_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 |
+
+### 索引建议
+- unique(username)
+- index(status)
+- index(is_delete)
+
+---
+
+## 5.2 角色表 `role`
+
+### 用途
+定义系统角色。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| code | VARCHAR(64) | UNIQUE NOT NULL | 角色编码，如 admin/test_manager |
+| name | VARCHAR(64) | NOT NULL | 角色名称 |
+| description | TEXT |  | 角色描述 |
+| status | SMALLINT | DEFAULT 1 | 1启用 0禁用 |
+| is_system | SMALLINT | DEFAULT 0 | 是否系统内置角色 |
+| created_by | BIGINT |  | 创建人 |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+| updated_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 |
+
+### 索引建议
+- unique(code)
+- index(status)
+- index(is_delete)
+
+---
+
+## 5.3 权限表 `permission`
+
+### 用途
+定义后端权限点。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| code | VARCHAR(128) | UNIQUE NOT NULL | 权限编码，如 project:create |
+| name | VARCHAR(128) | NOT NULL | 权限名称 |
+| module | VARCHAR(64) |  | 所属模块，如 project/user/menu |
+| action | VARCHAR(64) |  | 动作，如 list/create/update/delete |
+| description | TEXT |  | 描述 |
+| status | SMALLINT | DEFAULT 1 | 1启用 0禁用 |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+| updated_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 |
+
+### 索引建议
+- unique(code)
+- index(module)
+- index(status)
+
+---
+
+## 5.4 菜单表 `menu`
+
+### 用途
+定义前端菜单树。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| parent_id | BIGINT | DEFAULT 0 | 父菜单ID，0表示根节点 |
+| name | VARCHAR(64) | NOT NULL | 菜单名称 |
+| code | VARCHAR(64) | UNIQUE | 菜单编码 |
+| type | SMALLINT | DEFAULT 1 | 1目录 2菜单 3按钮 |
+| path | VARCHAR(255) |  | 路由路径 |
+| component | VARCHAR(255) |  | 前端组件路径 |
+| icon | VARCHAR(64) |  | 图标 |
+| permission_code | VARCHAR(128) |  | 对应权限编码，可选 |
+| sort | INTEGER | DEFAULT 0 | 排序 |
+| visible | SMALLINT | DEFAULT 1 | 1显示 0隐藏 |
+| status | SMALLINT | DEFAULT 1 | 1启用 0禁用 |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+| updated_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 |
+
+### 索引建议
+- index(parent_id)
+- unique(code)
+- index(sort)
+
+---
+
+## 5.5 用户角色关联表 `user_role`
+
+### 用途
+维护用户与角色多对多关系。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| user_id | BIGINT | NOT NULL | 用户ID |
+| role_id | BIGINT | NOT NULL | 角色ID |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+
+### 约束建议
+- unique(user_id, role_id)
+- index(user_id)
+- index(role_id)
+
+---
+
+## 5.6 角色权限关联表 `role_permission`
+
+### 用途
+维护角色与权限多对多关系。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| role_id | BIGINT | NOT NULL | 角色ID |
+| permission_id | BIGINT | NOT NULL | 权限ID |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+
+### 约束建议
+- unique(role_id, permission_id)
+- index(role_id)
+- index(permission_id)
+
+---
+
+## 5.7 角色菜单关联表 `role_menu`
+
+### 用途
+维护角色与菜单多对多关系。
+
+### 建表字段
+
+| 字段 | 类型 | 约束 | 说明 |
+|---|---|---|---|
+| id | BIGSERIAL | PK | 主键 |
+| role_id | BIGINT | NOT NULL | 角色ID |
+| menu_id | BIGINT | NOT NULL | 菜单ID |
+| is_delete | INTEGER | DEFAULT 0 | 软删标识 |
+| created_time | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
+
+### 约束建议
+- unique(role_id, menu_id)
+- index(role_id)
+- index(menu_id)
+
+---
+
+## 6. Model 设计
+
+建议新增单独 model 文件：
+
+### 6.1 `app/api/model/userModel.py`
+包含：
+- `User`
+- `UserRole`
+
+### 6.2 `app/api/model/rbacModel.py`
+包含：
+- `Role`
+- `Permission`
+- `RolePermission`
+- `Menu`
+- `RoleMenu`
+
+> 也可以拆成 `roleModel.py` / `menuModel.py`，但按当前项目规模，两个文件足够。
+
+### 6.3 Model 设计原则
+- 继承与现有一致：`declarative_base()` + `to_dict`
+- 字段命名与数据库列一致
+- 关联关系不强制写 SQLAlchemy relationship，保持当前项目风格简洁
+
+---
+
+## 7. DAO 设计
+
+---
+
+## 7.1 `app/api/dao/userDao.py`
+
+### 基础方法
+- `create(session, model_cls, add_info)`
+- `update_by_id(session, model_cls, obj_id, update_info, soft_delete=True)`
+- `get_by_id(session, model_cls, obj_id, soft_delete=True)`
+- `list_by_filters(session, model_cls, filter_list, page=1, limit=20, order_column=None)`
+- `delete_by_id(session, model_cls, obj_id)`
+
+### 用户专项方法
+- `get_user_role_ids(session, user_id)`
+- `replace_user_roles(session, user_id, role_ids)`
+- `get_user_roles(session, user_ids)`
+
+---
+
+## 7.2 `app/api/dao/rbacDao.py`
+
+### 基础方法
+同现有通用 DAO 风格。
+
+### 角色/权限/菜单专项方法
+- `get_role_permission_ids(session, role_id)`
+- `replace_role_permissions(session, role_id, permission_ids)`
+- `get_role_menu_ids(session, role_id)`
+- `replace_role_menus(session, role_id, menu_ids)`
+- `get_role_names_map(session, role_ids)`
+- `get_menu_tree_items(session, filter_list)`
+- `get_permission_list(session, filter_list, page, limit)`
+
+---
+
+## 8. Service 设计
+
+---
+
+## 8.1 `app/api/service/userService.py`
+
+### 职责
+- 用户基本 CRUD
+- 用户与角色分配
+- 聚合用户角色名称
+
+### 方法建议
+- `create(session, model_cls, add_info)`
+- `update_by_id(session, model_cls, obj_id, update_info, soft_delete=True)`
+- `get_by_id(session, model_cls, obj_id, soft_delete=True)`
+- `list_by_filters(session, model_cls, filter_list, page_num=1, page_size=20, order_column=None)`
+- `delete_by_id(session, model_cls, obj_id)`
+- `assign_roles(session, user_id, role_ids)`
+- `get_user_role_ids(session, user_id)`
+- `get_user_roles_map(session, user_ids)`
+
+---
+
+## 8.2 `app/api/service/rbacService.py`
+
+### 职责
+- 角色 CRUD
+- 权限 CRUD
+- 菜单 CRUD
+- 角色绑定权限
+- 角色绑定菜单
+- 菜单树构建
+
+### 方法建议
+- `create(session, model_cls, add_info)`
+- `update_by_id(session, model_cls, obj_id, update_info, soft_delete=True)`
+- `get_by_id(session, model_cls, obj_id, soft_delete=True)`
+- `list_by_filters(session, model_cls, filter_list, page_num=1, page_size=20, order_column=None)`
+- `delete_by_id(session, model_cls, obj_id)`
+- `assign_permissions(session, role_id, permission_ids)`
+- `assign_menus(session, role_id, menu_ids)`
+- `get_role_permission_ids(session, role_id)`
+- `get_role_menu_ids(session, role_id)`
+- `build_menu_tree(session, filters)`
+
+---
+
+## 9. Controller 设计
+
+controller 仅负责：
+- 参数获取 `_get(...)`
+- 必填校验
+- 字段映射
+- 调用 service
+- 序列化返回
+
+不得直接 `session.query(...)`
+
+---
+
+## 9.1 `app/api/controller/userController.py`
+
+### 建议方法
+- `user_list`
+- `user_detail`
+- `user_create`
+- `user_update`
+- `user_delete`
+- `user_role_assign`
+- `user_role_list`
+
+### 返回增强建议
+`user_list` 每项增加：
+- `role_ids`
+- `role_names`
+
+---
+
+## 9.2 `app/api/controller/rbacController.py`
+
+### 角色相关
+- `role_list`
+- `role_detail`
+- `role_create`
+- `role_update`
+- `role_delete`
+- `role_permission_assign`
+- `role_permission_list`
+- `role_menu_assign`
+- `role_menu_list`
+
+### 权限相关
+- `permission_list`
+- `permission_detail`
+- `permission_create`
+- `permission_update`
+- `permission_delete`
+
+### 菜单相关
+- `menu_tree`
+- `menu_detail`
+- `menu_create`
+- `menu_update`
+- `menu_delete`
+
+---
+
+## 10. 接口清单设计
+
+以下接口路径保持当前项目风格。
+
+---
+
+## 10.1 角色管理接口
+
+### 角色列表
+- `GET /role/list`
+- 参数：`keyword`, `status`, `pageNo`, `pageSize`
+- 返回：角色分页列表
+
+### 角色详情
+- `GET /role/detail`
+- 参数：`roleId`
+
+### 创建角色
+- `POST /role/create`
+- 参数：
+  - `code`
+  - `name`
+  - `description`
+  - `status`
+  - `isSystem`
+
+### 更新角色
+- `POST /role/update`
+- 参数：
+  - `roleId`
+  - 可选更新字段
+
+### 删除角色
+- `POST /role/delete`
+- 参数：`roleId`
+
+---
+
+## 10.2 权限管理接口
+
+### 权限列表
+- `GET /permission/list`
+- 参数：`keyword`, `module`, `status`, `pageNo`, `pageSize`
+
+### 权限详情
+- `GET /permission/detail`
+- 参数：`permissionId`
+
+### 创建权限
+- `POST /permission/create`
+
+### 更新权限
+- `POST /permission/update`
+
+### 删除权限
+- `POST /permission/delete`
+
+---
+
+## 10.3 菜单管理接口
+
+### 菜单树
+- `GET /menu/tree`
+- 参数：可选 `status`
+- 返回树形结构
+
+### 菜单详情
+- `GET /menu/detail`
+- 参数：`menuId`
+
+### 创建菜单
+- `POST /menu/create`
+
+### 更新菜单
+- `POST /menu/update`
+
+### 删除菜单
+- `POST /menu/delete`
+
+---
+
+## 10.4 角色权限分配接口
+
+### 查询角色权限
+- `GET /role/permission/list`
+- 参数：`roleId`
+- 返回：`permissionIds` + 权限明细列表
+
+### 分配角色权限
+- `POST /role/permission/assign`
+- 参数：
+  - `roleId`
+  - `permissionIds: []`
+
+建议语义：覆盖式保存
+
+---
+
+## 10.5 角色菜单分配接口
+
+### 查询角色菜单
+- `GET /role/menu/list`
+- 参数：`roleId`
+- 返回：`menuIds` + 菜单树
+
+### 分配角色菜单
+- `POST /role/menu/assign`
+- 参数：
+  - `roleId`
+  - `menuIds: []`
+
+建议语义：覆盖式保存
+
+---
+
+## 10.6 用户管理接口
+
+### 用户列表
+- `GET /user/list`
+- 参数：`keyword`, `status`, `pageNo`, `pageSize`
+
+### 用户详情
+- `GET /user/detail`
+- 参数：`userId`
+
+### 创建用户
+- `POST /user/create`
+- 参数：
+  - `username`
+  - `realName`
+  - `password`
+  - `mobile`
+  - `email`
+  - `status`
+
+### 更新用户
+- `POST /user/update`
+- 参数：
+  - `userId`
+  - 可选更新字段
+
+### 删除用户
+- `POST /user/delete`
+- 参数：`userId`
+
+---
+
+## 10.7 用户角色分配接口
+
+### 查询用户角色
+- `GET /user/role/list`
+- 参数：`userId`
+- 返回：`roleIds` + 角色列表
+
+### 分配用户角色
+- `POST /user/role/assign`
+- 参数：
+  - `userId`
+  - `roleIds: []`
+
+建议语义：覆盖式保存
+
+---
+
+## 11. 返回结构建议
+
+### 11.1 角色列表项
+
+```json
+{
+  "id": 1,
+  "code": "admin",
+  "name": "管理员",
+  "description": "系统管理员",
+  "status": 1,
+  "is_system": 1,
+  "created_time": "2025-01-01 10:00:00"
+}
+```
+
+### 11.2 用户列表项
+
+```json
+{
+  "id": 1,
+  "username": "zhangsan",
+  "real_name": "张三",
+  "mobile": "13800000000",
+  "email": "a@test.com",
+  "status": 1,
+  "role_ids": [1, 2],
+  "role_names": ["管理员", "测试经理"]
+}
+```
+
+### 11.3 菜单树项
+
+```json
+{
+  "id": 1,
+  "parent_id": 0,
+  "name": "系统管理",
+  "code": "system",
+  "type": 1,
+  "path": "/system",
+  "component": "Layout",
+  "icon": "setting",
+  "sort": 1,
+  "children": []
+}
+```
+
+---
+
+## 12. 文件清单
+
+本次功能落地预计新增/修改以下文件。
+
+### 12.1 新增 model
+- `app/api/model/userModel.py`
+- `app/api/model/rbacModel.py`
+
+### 12.2 新增 dao
+- `app/api/dao/userDao.py`
+- `app/api/dao/rbacDao.py`
+
+### 12.3 新增 service
+- `app/api/service/userService.py`
+- `app/api/service/rbacService.py`
+
+### 12.4 新增 controller
+- `app/api/controller/userController.py`
+- `app/api/controller/rbacController.py`
+
+### 12.5 修改 views
+- `app/api/views.py`
+
+### 12.6 可能新增 SQL 脚本（如果你需要）
+- 数据库建表 SQL
+- 初始化菜单/权限/角色种子数据 SQL
+
+---
+
+## 13. 分层职责清单
+
+### model
+- 只定义表结构
+
+### dao
+- 只做数据库查询/写入
+- 负责关联表的增删查
+
+### service
+- 负责组合查询、覆盖式分配逻辑、聚合返回结构前的数据准备
+
+### controller
+- 参数校验、字段映射、调用 service、返回结构组装
+
+### views
+- 路由注册、request/response 包装
+
+---
+
+## 14. 推荐实现顺序
+
+### 第一阶段：基础 RBAC 数据层
+1. 建表 SQL
+2. model
+3. dao
+4. service
+
+### 第二阶段：角色/权限/菜单接口
+1. role CRUD
+2. permission CRUD
+3. menu CRUD
+4. role-permission assign
+5. role-menu assign
+
+### 第三阶段：用户接口
+1. user CRUD
+2. user-role assign
+3. user list/detail 聚合角色信息
+
+### 第四阶段：初始化与联调
+1. 初始化菜单
+2. 初始化权限
+3. 初始化管理员角色
+4. 初始化管理员用户
+
+---
+
+## 15. 关键设计决策
+
+### 15.1 分配类接口采用覆盖式保存
+原因：
+- 前端实现简单
+- 后端一致性更好
+- 避免增删混合接口过多
+
+### 15.2 菜单与权限分离
+原因：
+- 菜单是导航资源
+- 权限是操作资源
+- 一些按钮权限不一定出现在菜单树中
+
+### 15.3 用户表单独建设，不复用现有 project_member
+原因：
+- `project_member` 是项目成员关系，不是系统账户主表
+- 用户管理需要登录凭据、状态、手机号、邮箱等字段
+
+### 15.4 先不引入复杂组织架构
+原因：
+- 当前需求聚焦 RBAC + 用户 + 菜单
+- 可后续扩展部门/租户/产品维度数据权限
+
+---
+
+## 16. 后续可扩展项
+
+1. 登录认证
+   - JWT / Session
+2. 密码重置
+3. 数据权限
+   - 按产品/项目/部门的数据访问范围
+4. 操作审计日志
+5. 菜单与接口权限自动同步
+6. 超级管理员保护机制
+
+---
+
+## 17. 需要你确认的点
+
+请你确认以下设计取舍：
+
+1. 用户表是否需要登录密码字段（默认：需要）
+2. 权限是否按 `module:action` 编码（默认：是）
+3. 菜单是否需要按钮类型 `type=3`（默认：需要）
+4. 分配接口是否采用覆盖式保存（默认：是）
+5. 是否需要初始化内置角色：
+   - 超级管理员
+   - 测试经理
+   - 测试工程师
+6. 用户是否允许多角色（默认：允许）
+7. 菜单是否只做系统后台菜单，不含项目业务模块动态菜单（默认：只做后台菜单）
+
+---
+
+## 18. 下一步建议
+
+如果你确认这份设计，我下一步可以继续给你输出两部分：
+
+1. **完整建表 SQL**
+2. **按当前项目风格拆好的代码落地清单**
+   - 每个文件该写哪些类、哪些方法、哪些接口
+