|
@@ -0,0 +1,143 @@
|
|
|
|
|
+# Story 010.006: 修复省信息编辑功能
|
|
|
|
|
+
|
|
|
|
|
+## Status
|
|
|
|
|
+Draft
|
|
|
|
|
+
|
|
|
|
|
+## Story
|
|
|
|
|
+**As a** 系统管理员
|
|
|
|
|
+**I want** 能够成功编辑省信息
|
|
|
|
|
+**so that** 维护地区数据
|
|
|
|
|
+
|
|
|
|
|
+## Acceptance Criteria
|
|
|
|
|
+1. 点击"更新"按钮后省信息能够成功更新
|
|
|
|
|
+2. 更新后页面显示更新后的信息
|
|
|
|
|
+3. 错误处理机制完善
|
|
|
|
|
+
|
|
|
|
|
+## Tasks / Subtasks
|
|
|
|
|
+- [ ] 分析省信息编辑功能的当前实现 (AC: 1-3)
|
|
|
|
|
+ - [ ] 检查 `AreaManagement.tsx` 中的编辑对话框逻辑
|
|
|
|
|
+ - [ ] 检查 `AreaForm.tsx` 中的表单验证和默认值设置
|
|
|
|
|
+ - [ ] 检查 `updateMutation` 的API调用和错误处理
|
|
|
|
|
+- [ ] 修复前端编辑表单的数据绑定问题 (AC: 1, 2)
|
|
|
|
|
+ - [ ] 修复 `handleEdit` 函数中的硬编码日期问题
|
|
|
|
|
+ - [ ] 确保表单正确显示现有省信息的实际值
|
|
|
|
|
+ - [ ] 验证表单提交时传递正确的更新数据
|
|
|
|
|
+- [ ] 修复后端更新API的验证逻辑 (AC: 1, 3)
|
|
|
|
|
+ - [ ] 检查 `updateAreaSchema` 的验证规则
|
|
|
|
|
+ - [ ] 确保层级和父级ID关系的验证正确工作
|
|
|
|
|
+ - [ ] 验证部分更新(PATCH语义)正确处理
|
|
|
|
|
+- [ ] 完善错误处理和用户反馈 (AC: 3)
|
|
|
|
|
+ - [ ] 确保API错误信息正确显示给用户
|
|
|
|
|
+ - [ ] 添加表单验证错误的实时反馈
|
|
|
|
|
+ - [ ] 完善成功/失败提示信息
|
|
|
|
|
+- [ ] 添加和修复相关测试 (AC: 1-3)
|
|
|
|
|
+ - [ ] 添加省信息编辑功能的集成测试
|
|
|
|
|
+ - [ ] 修复现有的 `area-select` 测试失败
|
|
|
|
|
+ - [ ] 确保所有测试通过
|
|
|
|
|
+
|
|
|
|
|
+## Dev Notes
|
|
|
|
|
+
|
|
|
|
|
+### 技术架构信息 [Source: architecture/tech-stack.md]
|
|
|
|
|
+- 前端框架:React 19.1.0,使用 TanStack Query 进行状态管理
|
|
|
|
|
+- 后端框架:Hono 4.8.5,使用通用CRUD路由
|
|
|
|
|
+- 数据库:PostgreSQL 17,通过 TypeORM 0.3.25 操作
|
|
|
|
|
+- 验证:使用 Zod schema 进行数据验证
|
|
|
|
|
+
|
|
|
|
|
+### 项目结构信息 [Source: architecture/source-tree.md]
|
|
|
|
|
+- 地区模块包:`packages/geo-areas/`
|
|
|
|
|
+ - 实体:`src/modules/areas/area.entity.ts`
|
|
|
|
|
+ - 服务:`src/modules/areas/area.service.ts`
|
|
|
|
|
+ - Schema:`src/modules/areas/area.schema.ts`
|
|
|
|
|
+ - API路由:`src/api/admin/areas/index.ts`
|
|
|
|
|
+- 地区管理UI包:`packages/area-management-ui/`
|
|
|
|
|
+ - 主组件:`src/components/AreaManagement.tsx`
|
|
|
|
|
+ - 表单组件:`src/components/AreaForm.tsx`
|
|
|
|
|
+ - 客户端API:`src/api/areaClient.ts`
|
|
|
|
|
+- 通用CRUD基础设施:`packages/shared-crud/`
|
|
|
|
|
+ - 通用路由:`src/routes/generic-crud.routes.ts`
|
|
|
|
|
+
|
|
|
|
|
+### 数据模型信息 [Source: packages/geo-areas/src/modules/areas/area.entity.ts]
|
|
|
|
|
+- `AreaEntity` 包含字段:id, parentId, name, level, code, isDisabled, isDeleted, createdBy, updatedBy, createdAt, updatedAt
|
|
|
|
|
+- `AreaLevel` 枚举:PROVINCE=1(省/直辖市), CITY=2(市), DISTRICT=3(区/县), TOWN=4(街道/乡镇)
|
|
|
|
|
+- 自关联关系:parent(父级区域)和 children(子级区域)
|
|
|
|
|
+
|
|
|
|
|
+### Schema验证信息 [Source: packages/geo-areas/src/modules/areas/area.schema.ts]
|
|
|
|
|
+- `updateAreaSchema`: 用于省市区更新验证
|
|
|
|
|
+ - parentId: number.int().min(0).nullable().optional()
|
|
|
|
|
+ - name: string.min(1).max(100).optional()
|
|
|
|
|
+ - level: AreaLevel枚举.optional()
|
|
|
|
|
+ - code: string.min(1).max(20).optional()
|
|
|
|
|
+ - isDisabled: DisabledStatus枚举.optional()
|
|
|
|
|
+ - 自定义验证:层级和父级ID关系验证(省/直辖市 parentId=null,市/区县 parentId>0)
|
|
|
|
|
+
|
|
|
|
|
+### 前端实现信息 [Source: packages/area-management-ui/src/components/AreaManagement.tsx]
|
|
|
|
|
+- `updateMutation`: 使用 `areaClientManager.get()[':id'].$put` 调用更新API
|
|
|
|
|
+- `handleEdit`: 将 AreaNode 转换为 AreaResponse,设置 selectedArea 状态
|
|
|
|
|
+- 问题:`handleEdit` 函数中硬编码了 createdAt 和 updatedAt 为当前时间,而不是使用实际值
|
|
|
|
|
+
|
|
|
|
|
+### 前端表单信息 [Source: packages/area-management-ui/src/components/AreaForm.tsx]
|
|
|
|
|
+- 使用 `react-hook-form` 和 `zodResolver` 进行表单验证
|
|
|
|
|
+- 编辑模式使用 `updateAreaSchema`,创建模式使用 `createAreaSchema`
|
|
|
|
|
+- 表单字段:层级(只读)、父级区域(只读)、区域名称、行政区划代码、状态
|
|
|
|
|
+
|
|
|
|
|
+### 编码标准信息 [Source: architecture/coding-standards.md]
|
|
|
|
|
+- **UI包开发规范**:必须遵循 `ui-package-standards.md`
|
|
|
|
|
+- **测试框架**:使用 Vitest + Testing Library
|
|
|
|
|
+- **测试位置**:`tests/` 文件夹与源码并列
|
|
|
|
|
+- **API路径映射验证**:开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
|
|
|
|
|
+- **类型推断最佳实践**:必须使用RPC推断类型,而不是直接导入schema类型
|
|
|
|
|
+
|
|
|
|
|
+### 测试信息
|
|
|
|
|
+- **测试文件位置**:`packages/area-management-ui/tests/integration/`
|
|
|
|
|
+- **现有测试问题**:`area-select.integration.test.tsx` 有8个测试失败
|
|
|
|
|
+- **测试标准**:需要添加省信息编辑功能的集成测试
|
|
|
|
|
+- **测试框架**:Vitest + Testing Library + React Query测试工具
|
|
|
|
|
+
|
|
|
|
|
+### 潜在问题识别
|
|
|
|
|
+1. **前端数据绑定**:`handleEdit` 函数中硬编码日期值,可能导致表单显示不准确
|
|
|
|
|
+2. **表单验证**:需要确保 `updateAreaSchema` 的层级和父级ID关系验证正确工作
|
|
|
|
|
+3. **错误处理**:需要完善API错误信息的显示和用户反馈
|
|
|
|
|
+4. **缓存更新**:更新成功后需要正确更新查询缓存
|
|
|
|
|
+5. **测试覆盖**:需要添加专门的编辑功能测试
|
|
|
|
|
+
|
|
|
|
|
+## Testing
|
|
|
|
|
+### 测试要求
|
|
|
|
|
+1. **集成测试**:添加省信息编辑功能的完整集成测试
|
|
|
|
|
+2. **表单验证测试**:测试各种验证场景(有效数据、无效数据、边界条件)
|
|
|
|
|
+3. **API错误处理测试**:测试API返回错误时的用户界面反馈
|
|
|
|
|
+4. **缓存更新测试**:验证更新成功后查询缓存正确更新
|
|
|
|
|
+5. **现有测试修复**:修复 `area-select` 组件的测试失败
|
|
|
|
|
+
|
|
|
|
|
+### 测试文件位置
|
|
|
|
|
+- 主测试文件:`packages/area-management-ui/tests/integration/area-management.integration.test.tsx`
|
|
|
|
|
+- 表单测试文件:`packages/area-management-ui/tests/integration/area-select-form.integration.test.tsx`
|
|
|
|
|
+- 选择器测试文件:`packages/area-management-ui/tests/integration/area-select.integration.test.tsx`
|
|
|
|
|
+
|
|
|
|
|
+### 测试框架配置
|
|
|
|
|
+- 使用 Vitest 4.0.14
|
|
|
|
|
+- 使用 Testing Library 进行组件测试
|
|
|
|
|
+- 使用 React Query 的测试工具进行状态管理测试
|
|
|
|
|
+- 遵循现有的mock模式和测试结构
|
|
|
|
|
+
|
|
|
|
|
+## Change Log
|
|
|
|
|
+| Date | Version | Description | Author |
|
|
|
|
|
+|------|---------|-------------|--------|
|
|
|
|
|
+| 2025-12-12 | 1.0 | 故事创建,基于史诗010-06需求 | Bob (Scrum Master) |
|
|
|
|
|
+
|
|
|
|
|
+## Dev Agent Record
|
|
|
|
|
+*This section will be populated by the development agent during implementation*
|
|
|
|
|
+
|
|
|
|
|
+### Agent Model Used
|
|
|
|
|
+*To be filled by dev agent*
|
|
|
|
|
+
|
|
|
|
|
+### Debug Log References
|
|
|
|
|
+*To be filled by dev agent*
|
|
|
|
|
+
|
|
|
|
|
+### Completion Notes List
|
|
|
|
|
+*To be filled by dev agent*
|
|
|
|
|
+
|
|
|
|
|
+### File List
|
|
|
|
|
+*To be filled by dev agent*
|
|
|
|
|
+
|
|
|
|
|
+## QA Results
|
|
|
|
|
+*This section will be populated by the QA agent during review*
|