|
|
@@ -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*
|
yourname