增加项目的各个功能

2026-05-07 19:21:19 +08:00
parent aba1618f89
commit ee6cd4ae66
121 changed files with 9346 additions and 43 deletions
--- a/.plan/3onvvJGzAx9Dhi05JkVpx.md
+++ b/.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 脚本沙箱执行
+
+这些会影响架构和依赖，需要单独确认后再做。