96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
# 技术债清单
|
||
|
||
> 从 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
|
||
- **验证**: 根目录文档齐全
|