|
|
@@ -0,0 +1,121 @@
|
|
|
+# 史诗013 - 类型错误修复与代码类型安全增强
|
|
|
+
|
|
|
+## 史诗目标
|
|
|
+修复残疾人后端模块中的类型错误，并在当前史诗中逐步修复其他模块的类型错误，提高整个项目的TypeScript类型安全性，减少运行时错误风险。
|
|
|
+
|
|
|
+## 史诗描述
|
|
|
+
|
|
|
+### 现有系统上下文
|
|
|
+
|
|
|
+**当前相关功能：**
|
|
|
+- **残疾人管理模块**：提供残疾人信息的完整CRUD功能，包含文件模块集成和人才扩展API
|
|
|
+- **企业统计模块**：史诗012中新增的企业统计与人才扩展API
|
|
|
+- **订单管理模块**：订单相关的业务逻辑和视频管理功能
|
|
|
+- **其他业务模块**：channel、company、platform、salary等已移植的allin系统模块
|
|
|
+
|
|
|
+**技术栈：**
|
|
|
+- 后端：TypeScript、Hono、Zod OpenAPI、TypeORM
|
|
|
+- 数据库：PostgreSQL 17
|
|
|
+- API通信：基于Hono RPC的API客户端模式
|
|
|
+- 测试：Vitest（后端模块使用Vitest）
|
|
|
+- 包管理：pnpm workspace
|
|
|
+
|
|
|
+**集成点：**
|
|
|
+- 基于史诗7,8,9,10移植的allin系统模块进行修复
|
|
|
+- 保持现有API的向后兼容性
|
|
|
+- 遵循现有的模块结构和类型定义模式
|
|
|
+- 与现有测试框架集成
|
|
|
+
|
|
|
+**当前类型错误分析：**
|
|
|
+通过对残疾人后端模块的类型检查，发现以下主要类型错误：
|
|
|
+1. **路由层类型不匹配**：`aggregated.routes.ts`中的`bankCards`属性类型不兼容，`File`类型与`null`类型冲突
|
|
|
+2. **测试代码类型错误**：集成测试中的类型断言错误，数组类型与单个实体类型混淆
|
|
|
+3. **响应类型不明确**：API响应中的动态属性访问缺乏类型保护
|
|
|
+4. **实体关系类型**：TypeORM实体关系中的可选类型定义不准确
|
|
|
+
|
|
|
+### 增强详情
|
|
|
+
|
|
|
+**修复范围：**
|
|
|
+本次史诗将分阶段修复以下类型的错误：
|
|
|
+
|
|
|
+**阶段1：残疾人后端模块核心修复（故事013.001）**
|
|
|
+1. 修复`aggregated.routes.ts`中的类型不匹配问题
|
|
|
+2. 修复集成测试中的类型错误
|
|
|
+3. 优化实体类型定义，提高类型安全性
|
|
|
+4. 确保Zod schema与TypeORM实体类型一致
|
|
|
+
|
|
|
+**阶段2：其他模块类型错误修复（后续故事）**
|
|
|
+1. 企业统计模块类型错误修复
|
|
|
+2. 订单管理模块类型错误修复
|
|
|
+3. 核心模块类型错误修复
|
|
|
+4. 共享类型定义优化
|
|
|
+
|
|
|
+**修复策略：**
|
|
|
+1. **精确类型定义**：使用准确的TypeScript类型，避免`any`类型
|
|
|
+2. **类型守卫**：添加运行时类型检查，确保类型安全
|
|
|
+3. **Zod集成**：强化Zod schema的类型推断能力
|
|
|
+4. **测试类型修复**：确保测试代码的类型正确性
|
|
|
+5. **渐进式修复**：逐个模块修复，确保不影响现有功能
|
|
|
+
|
|
|
+**成功标准：**
|
|
|
+1. 残疾人后端模块类型检查通过（`pnpm typecheck`无错误）
|
|
|
+2. 现有功能测试通过，无回归
|
|
|
+3. 类型定义更加精确，减少运行时类型错误风险
|
|
|
+4. 代码可维护性提高，类型提示更加完善
|
|
|
+5. 为其他模块的类型修复建立可复用的模式
|
|
|
+
|
|
|
+## 故事列表
|
|
|
+
|
|
|
+### 故事013-01：残疾人后端模块类型错误修复
|
|
|
+**背景：** 残疾人后端模块在类型检查中发现多处类型错误，包括路由层类型不匹配、测试代码类型错误、实体关系类型定义不准确等问题，需要修复以提高代码质量和类型安全性。
|
|
|
+
|
|
|
+**任务列表：**
|
|
|
+1. 分析`aggregated.routes.ts`中的类型错误，修复`bankCards`属性的`File`类型冲突
|
|
|
+2. 修复`tests/integration/person-extension.integration.test.ts`中的类型错误：
|
|
|
+ - 修复数组类型与单个实体类型的混淆
|
|
|
+ - 修复动态属性访问的类型保护
|
|
|
+ - 修复实体关系类型定义
|
|
|
+3. 检查并修复其他可能存在的类型错误：
|
|
|
+ - 检查`any`类型的使用，替换为具体类型
|
|
|
+ - 优化Zod schema的类型推断
|
|
|
+ - 确保TypeORM实体与TypeScript类型一致
|
|
|
+4. 运行类型检查验证修复结果
|
|
|
+5. 运行现有测试确保无回归
|
|
|
+
|
|
|
+**验收标准：**
|
|
|
+- [ ] 残疾人后端模块类型检查通过（`pnpm typecheck`无错误）
|
|
|
+- [ ] 所有集成测试通过，类型错误已修复
|
|
|
+- [ ] 现有API功能正常，无回归
|
|
|
+- [ ] 类型定义更加精确，减少`any`类型使用
|
|
|
+- [ ] 代码符合项目类型安全标准
|
|
|
+
|
|
|
+### 故事013-02：其他模块类型错误修复（待规划）
|
|
|
+**背景：** 完成残疾人后端模块类型错误修复后，将逐步修复其他模块的类型错误，提高整个项目的类型安全性。
|
|
|
+
|
|
|
+**任务列表：**
|
|
|
+（将在故事013.001完成后详细规划）
|
|
|
+1. 企业统计模块类型错误修复
|
|
|
+2. 订单管理模块类型错误修复
|
|
|
+3. 核心模块类型错误修复
|
|
|
+4. 共享类型定义优化
|
|
|
+
|
|
|
+## 兼容性要求
|
|
|
+
|
|
|
+- [ ] 现有API接口保持不变，只进行类型层面的修复
|
|
|
+- [ ] 数据库schema和实体定义保持兼容
|
|
|
+- [ ] 前端客户端类型定义无需修改
|
|
|
+- [ ] 性能影响最小化，只涉及类型系统
|
|
|
+
|
|
|
+## 风险缓解
|
|
|
+
|
|
|
+- **主要风险**：类型修复可能引入新的逻辑错误或影响现有功能
|
|
|
+- **缓解措施**：充分测试，确保现有测试全部通过；小范围逐步修复
|
|
|
+- **回滚计划**：如果修复导致问题，可以回退类型定义更改，恢复为较宽松的类型
|
|
|
+
|
|
|
+## 完成定义
|
|
|
+
|
|
|
+- [ ] 所有故事完成，验收标准满足
|
|
|
+- [ ] 类型检查通过，无TypeScript错误
|
|
|
+- [ ] 现有功能测试通过，无回归
|
|
|
+- [ ] 代码审查通过，符合类型安全标准
|
|
|
+- [ ] 文档更新反映类型定义的改进
|
yourname