PRD08 后端工程规范与架构治理：OpenSpec change, PRD, PLAN13

docs/plans/13-后端工程规范与架构治理计划.md

@@ -4,120 +4,121 @@ doc_no: "13"
 audience:
   - Dev
   - QA
-  - Ops
-feature_area: backend-architecture-governance
-purpose: "实现 PRD08 中的后端工程规范与架构治理，建立分层约束、测试门禁与文档治理。"
+feature_area: backend-engineering-governance
+purpose: "落地 PRD08 的后端工程治理要求：分层架构、shared 真相源、架构边界测试和复杂度控制。"
 canonical_path: "docs/plans/13-后端工程规范与架构治理计划.md"
 status: draft
-version: "0.1.0"
+version: "1.0.0"
 owner: "StephenQiu30"
 inputs:
   - "docs/prd/08-后端工程规范与架构治理.md"
   - "docs/design/01-个人自部署万能视频下载器技术设计.md"
 outputs:
-  - "后端工程规范与架构治理计划"
+  - "后端工程治理实施计划"
 triggers:
-  - "需要固化后端分层边界"
-  - "需要建立架构边界测试"
+  - "新增或重构后端模块"
+  - "调整 shared 常量或错误码"
 downstream:
-  - "openspec/specs/backend-layer-boundaries/spec.md"
+  - "后续涉及后端治理的实现计划"
 ---
 
 # PLAN13 后端工程规范与架构治理
 
 ## 1. 背景
 
-视频下载后端已积累 router、service、core、schemas、models、worker 等多层职责，但缺少显式的依赖边界约束和架构治理规范。本计划承接 PRD08，将后端分层边界、依赖方向、单一事实来源和文档门禁固化下来。
+PRD08 定义了后端分层架构、SOLID 边界、shared 真相源和测试优先治理要求。PLAN13 将这些要求转化为可执行的渐进治理任务，不追求一次性重排全部代码，而是通过每次真实变更逐步收敛。
 
 ## 2. 目标
 
-1. 固化后端分层架构边界和依赖方向。
-2. 建立架构边界测试防止回归。
-3. 创建 PRD08 和 PLAN13 文档补齐治理链路。
-4. 更新验证脚本检查文档完整性。
+1. 将 PRD08 的分层架构定义落到可验证的目录结构和依赖约束。
+2. 建立 shared 真相源，将分散的错误码和常量迁移到 `packages/shared/`。
+3. 建立架构边界测试，防止跨层依赖引入。
+4. 建立复杂度控制检查，防止单文件/单函数过度膨胀。
 
 ## 3. 非目标
 
-- 不做大规模代码重构或目录迁移。
-- 不引入新的 `repositories/`、`sources/`、`tasks/` 目录。
-- 不改动前端工程规范。
-- 不改动 Worker 内部实现。
+- 不一次性重写全部已有模块。
+- 不引入 CI 自动化架构扫描工具（如 import-linter），留待后续评估。
+- 不覆盖 Worker 层的独立 repository 抽取（由后续 PLAN 处理）。
 
 ## 4. 核心内容
 
-### 4.1 OpenSpec 变更
+### 4.1 Phase 1：Shared 真相源建立
 
-创建 `openspec/changes/backend-architecture-governance/` 目录，包含：
+| 任务 | 文件 | 验证命令 |
+| --- | --- | --- |
+| 在 `packages/shared/` 创建 `codes.py`，定义所有 `failure_code` 常量 | `packages/shared/video_downloader_shared/codes.py` | `python -c "from video_downloader_shared.codes import *"` |
+| 在 `packages/shared/` 创建 `platforms.py`，定义平台 ID 常量 | `packages/shared/video_downloader_shared/platforms.py` | `python -c "from video_downloader_shared.platforms import *"` |
+| 在 `packages/shared/` 创建 `dto.py`，定义跨模块 DTO | `packages/shared/video_downloader_shared/dto.py` | `python -c "from video_downloader_shared.dto import *"` |
+| 更新 `packages/shared/video_downloader_shared/__init__.py` 导出新模块 | `packages/shared/video_downloader_shared/__init__.py` | `python -c "import video_downloader_shared"` |
 
-- `proposal.md`：后端工程规范治理提案
-- `design.md`：目录职责与架构设计
-- `specs/backend-layer-boundaries/spec.md`：分层边界规范
-- `tasks.md`：执行任务拆解
+### 4.2 Phase 2：分层目录骨架
 
-### 4.2 架构边界测试
+| 任务 | 文件 | 验证命令 |
+| --- | --- | --- |
+| 创建 `apps/api/app/domain/` 目录和 `__init__.py` | `apps/api/app/domain/__init__.py` | `python -c "from app.domain import *"` |
+| 创建 `apps/api/app/repositories/` 目录和 `__init__.py` | `apps/api/app/repositories/__init__.py` | `python -c "from app.repositories import *"` |
+| 创建 `apps/api/app/infrastructure/` 目录和 `__init__.py` | `apps/api/app/infrastructure/__init__.py` | `python -c "from app.infrastructure import *"` |
+| 在各 `__init__.py` 中写入层级职责说明注释 | 各 `__init__.py` | 人工审阅 |
 
-创建 `apps/api/tests/test_architecture_boundaries.py`，使用 AST 分析验证：
+### 4.3 Phase 3：架构边界测试
 
-1. router 层不直接导入 `yt_dlp`、`minio`、`redis` 等外部 SDK。
-2. router 层不直接导入 `SessionLocal`（应通过 `Depends(get_db)`）。
-3. service 层不从 router 导入。
-4. core 层不从 service/router 导入。
+| 任务 | 文件 | 验证命令 |
+| --- | --- | --- |
+| 编写架构边界测试：验证 router 不直接引用 ORM | `apps/api/tests/test_architecture_boundaries.py` | `npm test -- test_architecture_boundaries` |
+| 编写架构边界测试：验证 domain 不引用基础设施 | `apps/api/tests/test_architecture_boundaries.py` | `npm test -- test_architecture_boundaries` |
+| 编写架构边界测试：验证 repository 不含业务逻辑 | `apps/api/tests/test_architecture_boundaries.py` | `npm test -- test_architecture_boundaries` |
+| 编写 shared 常量完整性测试：验证无硬编码错误码 | `apps/api/tests/test_shared_constants.py` | `npm test -- test_shared_constants` |
 
-### 4.3 文档更新
+### 4.4 Phase 4：复杂度控制
 
-1. 创建 `docs/prd/08-后端工程规范与架构治理.md`
-2. 创建 `docs/plans/13-后端工程规范与架构治理计划.md`
-3. 更新 `docs/README.md` 添加 PRD08 和 PLAN13 索引
-4. 更新 `scripts/validate-repository.sh` 检查 PRD08/PLAN13 存在性
+| 任务 | 文件 | 验证命令 |
+| --- | --- | --- |
+| 编写文件行数检查脚本 | `scripts/check_complexity.sh` | `bash scripts/check_complexity.sh` |
+| 将复杂度检查集成到 `npm test` | `package.json` | `npm test` |
+| 对超限文件标注拆分 TODO | 各超限文件 | 人工审阅 |
 
-### 4.4 规范推广
+### 4.5 Phase 5：文档与 OpenSpec 同步
 
-将 `backend-layer-boundaries` spec 推广到 `openspec/specs/backend-layer-boundaries/spec.md` 作为基线。
+| 任务 | 文件 | 验证命令 |
+| --- | --- | --- |
+| 将 architecture-boundaries spec 推广到 `openspec/specs/` | `openspec/specs/architecture-boundaries/spec.md` | 人工审阅 |
+| 将 shared-constants spec 推广到 `openspec/specs/` | `openspec/specs/shared-constants/spec.md` | 人工审阅 |
+| 更新 `docs/prd/README.md` 添加 PRD08 | `docs/prd/README.md` | 人工审阅 |
+| 更新 `docs/plans/README.md` 添加 PLAN13 | `docs/plans/README.md` | 人工审阅 |
+| 更新 `scripts/validate-repository.sh` 添加新文件检查 | `scripts/validate-repository.sh` | `bash scripts/validate-repository.sh` |
 
-## 5. 执行顺序
+## 5. 关联文档
 
-1. 创建 OpenSpec change artifacts（proposal、specs、design、tasks）
-2. 创建 PRD08 和 PLAN13 文档
-3. 创建架构边界测试（红灯）
-4. 更新文档和脚本
-5. 推广 spec 到基线
-6. 运行验证测试（绿灯）
+### 5.1 输入文档
 
-## 6. 验证方式
+1. `docs/prd/08-后端工程规范与架构治理.md` — 分层架构、shared 真相源、测试治理要求
+2. `docs/design/01-个人自部署万能视频下载器技术设计.md` — §4.3 目录与模块边界
 
-### 6.1 自动化验证
+### 5.2 输出文档
 
-```bash
-pytest apps/api/tests/test_openapi_contract.py -v
-pytest apps/api/tests/test_api_contract.py -v
-pytest apps/api/tests/test_worker_jobs.py -v
-pytest apps/api/tests/test_task_endpoints.py -v
-pytest apps/api/tests/test_architecture_boundaries.py -v
-bash scripts/validate-repository.sh
-```
+1. `openspec/specs/architecture-boundaries/spec.md`
+2. `openspec/specs/shared-constants/spec.md`
 
-### 6.2 手工验证
+## 6. 验收门禁
 
-- 复核 PRD08、PLAN13 与 `CLAUDE.md`、`WORKFLOW.md`、`docs/README.md` 的治理规则一致。
-- 检查 OpenSpec change 是否完成 verify + archive。
+- `packages/shared/video_downloader_shared/codes.py` 存在并可导入。
+- `apps/api/app/domain/`、`apps/api/app/repositories/`、`apps/api/app/infrastructure/` 目录存在。
+- 架构边界测试通过。
+- `bash scripts/check_complexity.sh` 通过。
+- `bash scripts/validate-repository.sh` 通过。
 
-## 7. 关联文档
+## 7. 风险与边界
 
-### 7.1 输入文档
+渐进治理意味着短期内新旧代码风格并存。Phase 1-2 建立骨架和真相源，Phase 3-4 建立防护，后续每次真实变更时逐步将已有代码迁移到治理结构中。不要求一次性迁移所有已有模块。
 
-1. `docs/prd/08-后端工程规范与架构治理.md`
+## 8. 待确认问题
 
-### 7.2 输出文档
-
-1. `openspec/specs/backend-layer-boundaries/spec.md`
-
-## 8. 风险与边界
-
-- **风险**：AST 分析可能误报 → **缓解**：只检查实际的 import 节点。
-- **风险**：未来引入新目录时需要更新规范 → **缓解**：在 PRD08 中明确目录扩展流程。
+- Worker 层是否需要独立的 repository 抽取，还是复用 API 层 repository。
+- 是否需要在 CI 中添加 `scripts/check_complexity.sh` 作为必过检查。
 
 ## 9. 变更记录
 
 | 日期 | 作者 | 版本 | 变更说明 |
 | --- | --- | --- | --- |
-| 2026-06-16 | StephenQiu30 | 0.1.0 | 初始化文档 |
+| 2026-06-16 | StephenQiu30 | 1.0.0 | 新建 PLAN13：后端工程规范与架构治理 |

docs/plans/README.md

@@ -2,6 +2,22 @@
 
 本目录存放执行计划类文档。
 
+## 文档列表
+
+| 编号 | 标题 | 状态 |
+| --- | --- | --- |
+| PLAN01 | URL 协议与地址安全计划 | accepted |
+| PLAN02 | 错误语义与日志脱敏计划 | accepted |
+| PLAN03 | 平台画像注册与识别计划 | accepted |
+| PLAN04 | 创建任务与状态查询计划 | accepted |
+| PLAN05 | Worker 下载执行与失败分类计划 | accepted |
+| PLAN06 | 取消重试与事件流计划 | accepted |
+| PLAN07 | MinIO 对象归档计划 | accepted |
+| PLAN08 | 预签名下载与过期清理计划 | accepted |
+| PLAN09 | 本机开发与依赖复用计划 | accepted |
+| PLAN10 | DockerCompose 部署与健康检查计划 | accepted |
+| PLAN13 | 后端工程规范与架构治理计划 | draft |
+
 ## 适合放入
 
 1. 阶段计划与任务拆解。