NextEdu/docs/architecture/roadmap/tech-debt.md

技术债清单

从 004 第三部分"已知架构问题和技术债"迁入，记录已知的架构问题和技术债，按优先级排序。

P0 - 高优先级（影响安全/性能/可维护性）

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 全量修复

• 状态: 已评估，419 个错误，推迟到独立迭代
• 影响: 开启 noUncheckedIndexedAccess 后，所有数组/对象索引访问返回 T | undefined，需要全量修复类型错误
• 评估结果: 2026-07-07 评估，开启后产生 419 个 tsc 错误，主要涉及 array[0]、array[index]、Object.keys()[i] 等模式
• 建议: 独立迭代逐步修复，按模块分批进行（优先修复 data-access 层，再修复 actions 层，最后修复组件层）
• 关联: 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 等模块因结构特殊，架构图较简化
• 建议: 根据实际使用反馈持续优化

已解决项

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
• 验证: 根目录文档齐全