# 实施计划：按现有架构接入测试管理模块

## 目标
在当前 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 脚本沙箱执行

这些会影响架构和依赖，需要单独确认后再做。