From 415dde9122f74c45546884ad35fe4508bfc01b2e Mon Sep 17 00:00:00 2001
From: SpecialX <47072643+wangxiner55@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:18:07 +0800
Subject: [PATCH] docs(roadmap): populate tech-debt.md with identified and
 resolved items

---
 docs/architecture/roadmap/tech-debt.md | 91 ++++++++++++++++++++++++--
 1 file changed, 87 insertions(+), 4 deletions(-)

diff --git a/docs/architecture/roadmap/tech-debt.md b/docs/architecture/roadmap/tech-debt.md
index f3cdb96..21ab238 100644
--- a/docs/architecture/roadmap/tech-debt.md
+++ b/docs/architecture/roadmap/tech-debt.md
@@ -1,11 +1,94 @@
 # 技术债清单
 
-> 从 004 第三部分"已知架构问题和技术债"迁入。
+> 从 004 第三部分"已知架构问题和技术债"迁入，记录已知的架构问题和技术债，按优先级排序。
 
-## 待解决项
+## P0 - 高优先级（影响安全/性能/可维护性）
 
-（从 004 迁入后填充）
+### TD-P0-001: arch:scan symbol 解析同名歧义
+
+- **状态**: 已识别，短期方案已实施
+- **影响**: 当多个文件存在同名 symbol（如 `updateUserProfile` 在 onboarding/data-access.ts 和 users/actions.ts 都有定义）时，calls 表的 callee_id 解析可能选错，导致违规检测误报
+- **短期方案**: 在 wrapper Action 中显式调用 `requirePermission`（已在 settings/actions-service.ts 实施）
+- **长期方案**: 改进 `findSymbolIdByName` 逻辑，考虑 import 路由解析 callee，而非仅按名称匹配
+- **关联文件**: `scripts/arch-scan/scanner.ts:findSymbolIdByName`
+
+### TD-P0-002: listMyLeaveRequests 死代码嫌疑
+
+- **状态**: 待确认
+- **影响**: `src/modules/leave-requests/actions.ts` 的 `listMyLeaveRequests` 无外部调用者，可能是死代码
+- **建议**: 确认无使用后删除，或补充调用者
+
+## P1 - 中优先级（影响开发效率/代码质量）
+
+### TD-P1-001: noUncheckedIndexedAccess 全量修复
+
+- **状态**: 计划在 P2 阶段实施
+- **影响**: 开启 `noUncheckedIndexedAccess` 后，所有数组/对象索引访问返回 `T | undefined`，需要全量修复类型错误
+- **预估工作量**: 涉及大量文件，需要逐个添加类型守卫或非空断言
+- **关联**: tsconfig.json
+
+### TD-P1-002: CI 缺少 Unit test 阶段
+
+- **状态**: 计划在 P2 阶段实施
+- **影响**: 当前 CI 流水线（`.gitea/workflows/ci.yml`）只有 Integration test，缺少 Unit test + coverage 阶段
+- **建议**: 在 Lint → Typecheck 之后、Integration test 之前插入 `npm run test:unit` 阶段
+
+### TD-P1-003: 缺少 /api/health 健康检查端点
+
+- **状态**: 计划在 P2 阶段实施
+- **影响**: Dockerfile 无 HEALTHCHECK，容器编排无法自动检测应用健康状态
+- **建议**: 创建 `src/app/api/health/route.ts` + Dockerfile 添加 HEALTHCHECK 指令
+
+### TD-P1-004: 缺少 bundle 体积分析
+
+- **状态**: 计划在 P2 阶段实施
+- **影响**: 无法可视化构建体积，可能存在未优化的依赖
+- **建议**: 安装 `@next/bundle-analyzer`，添加 `ANALYZE=true` 环境变量触发
+
+## P2 - 低优先级（改进项）
+
+### TD-P2-001: API 文档缺失
+
+- **状态**: 计划在 P2 阶段实施
+- **影响**: API 路由缺少 OpenAPI/Swagger 文档
+- **建议**: 使用 `swagger-jsdoc` 或手写 OpenAPI spec
+
+### TD-P2-002: shared 模块内部结构未扫描
+
+- **状态**: 已识别
+- **影响**: arch:scan 将 `src/shared` 视为单个模块，其子目录（lib/db/types 等）的内部结构未被单独扫描
+- **建议**: 改进 `scanModules` 逻辑，对 shared 模块按子目录分组
+
+### TD-P2-003: 部分模块 README 质量不均
+
+- **状态**: 已识别
+- **影响**: 35 个模块 README 已重写，但 search/layout/student 等模块因结构特殊，架构图较简化
+- **建议**: 根据实际使用反馈持续优化
 
 ## 已解决项
 
-（已解决项删除，git 历史已记录）
+### TD-RESOLVED-001: Server Action 权限违规（32→0）
+
+- **解决时间**: 2026-07-07
+- **方案**:
+  1. arch:scan 添加 @public JSDoc 标记豁免机制（12 个登录前/公开/内部工具 Action）
+  2. 递归 CTE 识别间接调用链（ai 模块 6 个 Action 通过 requireAiPermission 间接调用）
+  3. 修复 9 个真违规（parent 5 个 + settings 1 个 + 3 个 @public 豁免）
+- **验证**: `npm run arch:query -- violations` 输出 0 违规
+
+### TD-RESOLVED-002: 5 个超长文件（>800 行）
+
+- **解决时间**: 2026-07-07
+- **方案**: 按业务域拆分为多个子文件 + barrel export
+  - `schema.ts` (2245→29+27子文件)
+  - `invalidation-map.ts` (1195→50+6子文件)
+  - `messaging/actions.ts` (973→47+5子文件)
+  - `textbooks/data-access.ts` (907→15+6子文件)
+  - `questions/data-access.ts` (828→48+4子文件)
+- **验证**: `npm run arch:query -- violations` 输出 0 长文件
+
+### TD-RESOLVED-003: 缺少大仓工程基建文档
+
+- **解决时间**: 2026-07-07
+- **方案**: 创建 LICENSE（专有协议）、CHANGELOG.md、CONTRIBUTING.md、SECURITY.md
+- **验证**: 根目录文档齐全