📝 docs(prd): 更新省市区管理页面PRD文档

- 修改Epic目标为创建异步加载树形省市区管理页面
- 更新Epic描述，聚焦于性能优化和异步加载机制
- 调整Stories内容，包括创建新页面、实现异步加载、智能新增删除等功能
- 新增清理原有代码的Story
- 更新兼容性要求和风险缓解策略
- 完善Definition of Done标准，确保功能完整性和性能优化效果

docs/prd/epic-006-area-management-ux-improvement.md

@@ -1,8 +1,8 @@
-# 省市区管理用户体验改进 - Brownfield Enhancement
+# 异步加载树形省市区管理页面 - Brownfield Enhancement
 
 ## Epic Goal
 
-优化省市区管理功能的用户体验，将现有的表格视图和树形视图双模式简化为单一的树形视图，并改进新增和删除操作的交互方式，使省市区管理更加直观和高效。
+创建新的树形省市区管理页面，支持按层级异步加载子节点，避免一次性加载全部数据，提升页面性能和用户体验。
 
 ## Epic Description
 
@@ -12,8 +12,8 @@
 - 省市区管理页面目前提供表格视图和树形视图两种模式（AreasPage.tsx:346-548）
 - 表格视图显示所有省市区数据的平面列表，支持分页、筛选和搜索功能
 - 树形视图以层级结构展示省市区关系，支持展开/收起操作（AreaTree.tsx:34-138）
-- 新增按钮统一为"新增省市区"，需要用户手动选择层级和父级区域
-- 删除操作在两种视图中都支持，但仅删除当前节点，不处理子节点
+- 当前树形视图一次性加载所有省市区数据，可能导致性能问题
+- 后端已支持按需加载子树API：`GET /api/v1/admin/areas/tree/{id}`
 - AreaForm组件提供完整的表单验证和三级联动选择器
 
 **Technology stack:**
@@ -35,66 +35,89 @@
 ### Enhancement Details
 
 **What's being added/changed:**
-1. **移除表格视图模式** - 将现有的双视图模式简化为单一的树形视图
-   - 删除 AreasPage.tsx 中的 Tabs 组件和表格视图相关代码（第 359-515 行）
-   - 移除表格视图相关的状态管理（page, pageSize, keyword 等）
-   - 保留树形视图的完整功能，包括搜索和筛选
-
-2. **优化新增操作** - 将"新增省市区"按钮改为"新增省"，并支持在树形结构中直接新增市和区
-   - 修改页面顶部按钮为"新增省"（AreasPage.tsx:339-342）
-   - 在 AreaTree 组件中为节点添加上下文新增按钮
-   - 省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
+1. **创建新的异步加载树形页面** - 直接创建新的树形省市区管理页面，支持按层级异步加载
+   - 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
+   - 默认只加载省级节点，点击节点时异步加载子节点
+   - 保持现有的搜索和筛选功能
+
+2. **实现异步加载机制** - 修改 AreaTree 组件支持按需加载子节点
+   - 修改 AreaTree 组件的节点展开逻辑，从一次性加载改为按需加载
+   - 使用现有的 `getSubTree` API 按需加载子树
+   - 添加加载状态指示器，显示异步加载过程
+
+3. **优化新增操作** - 在新的树形页面中支持智能新增功能
+   - 页面顶部按钮为"新增省"
+   - 在树形结构中直接新增市和区：省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
    - AreaForm 组件支持智能预填层级和父级信息
 
-3. **改进删除交互** - 在树形结构中直接支持删除操作，支持删除当前节点及所有子节点
+4. **增强删除功能** - 支持删除当前节点及所有子节点
    - 后端新增批量删除API：`DELETE /areas/:id/with-children`
    - 前端调用新的批量删除API，支持递归删除子节点
    - 删除确认对话框显示准确的子节点数量
 
-4. **增强树形视图功能** - 在树形节点上直接提供新增子节点（市、区）的功能
-   - 增强 AreaTree 组件的操作按钮（第 95-127 行）
-   - 保持悬停显示的操作模式
-   - 根据节点层级显示不同的新增按钮
+5. **优化数据缓存策略** - 使用 TanStack Query 管理异步加载状态和缓存
+   - 利用现有的 TanStack Query 缓存机制优化重复请求
+   - 实现错误处理和重试机制
+   - 保持已加载节点的状态，避免重复请求
 
 **How it integrates:**
-- 修改 AreasPage 组件，移除表格视图相关的代码，优化状态管理
-- 增强 AreaTree 组件，在节点上添加新增子节点的操作按钮
-- 更新 AreaForm 组件，简化新增流程，支持基于上下文自动设置层级
-- 后端需要新增批量删除API，支持删除当前节点及所有子节点
-- 前端调用新的批量删除API实现删除功能
+- 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
+- 修改 AreaTree 组件，支持按需加载子节点
+- 使用现有的 `getSubTree` API 按需加载子树
+- 后端需要新增批量删除API：`DELETE /areas/:id/with-children`
+- 利用现有的 TanStack Query 数据管理和缓存机制
+- 保持现有的 AreaForm 组件和表单验证功能
 - 保持现有的搜索、筛选和状态切换功能
+- 增强 AreaTree 组件的操作按钮，支持在节点上直接新增子节点
 
 **Success criteria:**
-- 用户进入省市区管理页面时默认显示树形视图
-- 新增省市区操作更加直观，减少用户操作步骤
-- 删除操作在树形视图中直接可用，支持删除当前节点及所有子节点
-- 删除操作提供明确的确认提示，显示将删除的子节点数量
-- 现有功能不受影响，数据一致性保持
-- 用户体验显著提升，操作路径缩短
-- 后端批量删除API正常工作，保持事务一致性
+- 用户进入省市区管理页面时默认只显示省级节点
+- 点击省级节点时异步加载该省下的市级节点
+- 点击市级节点时异步加载该市下的区级节点
+- 异步加载过程显示加载状态指示器
+- 已加载的节点保持展开状态，避免重复加载
+- 页面顶部按钮为"新增省"，支持智能新增功能
+- 在树形结构中直接新增市和区：省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
+- 支持删除当前节点及所有子节点，删除确认对话框显示准确的子节点数量
+- 现有搜索、筛选和CRUD操作功能保持正常
+- 页面性能显著提升，减少初始加载数据量
+- 用户体验流畅，加载过程无卡顿
 
 ## Stories
 
-1. **Story 1:** 移除表格视图模式，将省市区管理页面改为单一树形视图
-   - 删除 AreasPage.tsx 中的 Tabs 组件和表格视图相关代码（第 359-515 行）
-   - 移除表格视图相关的状态管理（page, pageSize, keyword, level, parentId, isDisabled 等）
-   - 删除 DataTablePagination 组件引用
-   - 保留树形视图的完整功能，包括搜索和筛选
-   - 验证现有功能不受影响
-
-2. **Story 2:** 优化新增操作，支持在树形结构中直接新增市和区
-   - 修改页面顶部按钮为"新增省"（AreasPage.tsx:339-342）
-   - 在 AreaTree 组件中为节点添加上下文新增按钮
-   - 省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
-   - AreaForm 组件支持智能预填层级和父级信息
-   - 验证新增操作流程简化，用户无需手动选择层级和父级
-
-3. **Story 3:** 增强树形视图交互，在节点上提供新增子节点和删除当前及所有子节点功能
+1. **Story 1:** 创建新的异步加载树形省市区管理页面
+   - 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
+   - 默认只加载省级节点，使用现有的 `getAreaTree` API 获取省级数据
+   - 页面顶部按钮为"新增省"
+   - 保持现有的搜索和筛选功能
+   - 验证页面初始加载性能提升
+
+2. **Story 2:** 实现树形节点的异步加载机制
+   - 修改 AreaTree 组件的节点展开逻辑，支持按需加载子节点
+   - 使用现有的 `getSubTree` API 按需加载子树
+   - 添加加载状态指示器，显示异步加载过程
+   - 实现错误处理和重试机制
+   - 验证异步加载功能正常工作
+
+3. **Story 3:** 实现智能新增和删除功能
+   - 在树形结构中直接新增市和区：省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
    - 后端新增批量删除API：`DELETE /areas/:id/with-children`
    - 前端调用新的批量删除API，支持递归删除子节点
-   - 增强 AreaTree 组件的操作按钮（第 95-127 行）
    - 删除确认对话框显示准确的子节点数量
-   - 验证批量删除功能正常工作，保持事务一致性
+   - 验证新增和删除功能正常工作
+
+4. **Story 4:** 优化数据缓存和状态管理
+   - 使用 TanStack Query 管理异步加载状态和缓存
+   - 保持已加载节点的状态，避免重复请求
+   - 确保现有 CRUD 操作功能保持正常
+   - 验证搜索和筛选功能不受影响
+   - 验证所有现有功能通过回归测试
+
+5. **Story 5:** 清理原有代码
+   - 删除原有的 Areas.tsx 文件 (web/src/client/admin/pages/Areas.tsx)
+   - 更新路由配置，指向新的 AreasTreePage 组件
+   - 验证所有功能迁移完成，无功能缺失
+   - 清理不再使用的导入和依赖
 
 ## Compatibility Requirements
 
@@ -102,31 +125,34 @@
 - [x] 现有其他 APIs 保持不变：所有现有的 area API 接口保持兼容
 - [x] 数据库 schema 无变化：AreaEntity 实体和表结构保持不变
 - [x] UI 变化遵循现有模式：使用现有的 Shadcn/ui 组件和设计系统
-- [x] 性能影响最小：树形视图数据已缓存，批量删除使用事务保证性能
+- [x] 性能影响最小：异步加载减少初始数据量，批量删除使用事务保证性能
 - [x] 现有功能无回归：所有现有的 CRUD 操作、搜索、筛选功能保持完整
 
 ## Risk Mitigation
 
-**Primary Risk:** 需要新增后端批量删除API，增加了技术复杂度
-**Mitigation:** 批量删除API设计为幂等操作，使用数据库事务确保数据一致性；前端提供明确的删除确认提示，显示将删除的子节点数量
+**Primary Risk:** 异步加载可能影响现有树形视图的交互体验
+**Mitigation:** 提供加载状态反馈，确保用户体验流畅；保持现有API兼容，支持快速回退
 
-**Secondary Risk:** 用户习惯现有表格视图，可能不适应单一树形视图
-**Mitigation:** 保留现有数据筛选和搜索功能，确保树形视图提供足够的信息展示；树形视图已实现完整的层级展示和操作功能
+**Secondary Risk:** 需要新增后端批量删除API，增加了技术复杂度
+**Mitigation:** 批量删除API设计为幂等操作，使用数据库事务确保数据一致性；前端提供明确的删除确认提示，显示将删除的子节点数量
 
-**Technical Risk:** 移除表格视图可能影响某些特定使用场景
-**Mitigation:** 保留所有核心功能（搜索、筛选、CRUD操作），树形视图提供更直观的层级关系展示
+**Technical Risk:** 异步加载状态管理可能引入复杂性
+**Mitigation:** 使用现有的 TanStack Query 缓存机制，实现错误处理和重试机制
 
-**Rollback Plan:** 可以快速恢复表格视图代码（保留在git历史中），批量删除API可以保留作为可选功能；如果用户体验问题严重，可以恢复双视图模式
+**Rollback Plan:** 可以恢复为一次性加载模式，修改仅限于前端组件逻辑；批量删除API可以保留作为可选功能
 
 ## Definition of Done
 
 - [ ] 所有 stories 完成且验收标准满足
 - [ ] 现有功能通过测试验证：所有现有的 CRUD 操作、搜索、筛选功能正常工作
-- [ ] 集成点正常工作：AreasPage、AreaTree、AreaForm 组件集成正常
+- [ ] 集成点正常工作：新的 AreasTreePage、AreaTree、AreaForm 组件集成正常
 - [ ] 后端批量删除API正常工作，保持事务一致性
+- [ ] 异步加载功能正常工作，显示加载状态指示器
+- [ ] 智能新增功能正常工作：页面顶部"新增省"按钮，节点上"新增市/区"按钮
+- [ ] 原有 Areas.tsx 文件已删除，路由配置已更新
 - [ ] 文档适当更新：更新相关组件文档
 - [ ] 现有功能无回归：所有现有功能通过回归测试
-- [ ] 用户体验验证：树形视图操作流程简化，用户反馈积极
+- [ ] 用户体验验证：异步加载流畅，操作路径简化，用户反馈积极
 
 ---
 
@@ -135,16 +161,18 @@
 "请为这个棕地epic开发详细用户故事。关键考虑：
 
 - 这是对运行在 React + TypeScript + Shadcn/ui + TanStack Query + Hono RPC 技术栈的现有系统的增强
-- 集成点：现有的 AreasPage (web/src/client/admin/pages/Areas.tsx)、AreaTree (web/src/client/admin/components/AreaTree.tsx)、AreaForm (web/src/client/admin/components/AreaForm.tsx) 组件，以及需要新增的后端批量删除API
-- 现有模式遵循：Shadcn/ui 设计系统，现有的树形视图交互模式，React Hook Form 表单管理
+- 集成点：创建新的 AreasTreePage 组件，修改现有的 AreaTree 组件，以及需要新增的后端批量删除API
+- 现有模式遵循：Shadcn/ui 设计系统，现有的树形视图交互模式，React Hook Form 表单管理，TanStack Query 异步数据加载模式
 - 关键兼容性要求：需要新增批量删除API `DELETE /areas/:id/with-children`，其他现有API保持不变
 - 每个故事必须包含验证现有功能保持完整的检查
-- 特别注意：删除功能需要支持删除当前节点及所有子节点，需要后端提供相应的批量删除能力
+- 特别注意：异步加载功能需要支持按层级加载子节点，避免一次性加载全部数据
 - 技术细节：
-  - AreasPage 组件目前使用 Tabs 实现双视图模式（第 346-548 行）
-  - AreaTree 组件已实现树形结构展示和基本操作（第 34-138 行）
-  - AreaForm 组件支持完整的表单验证和三级联动选择器
-  - 需要移除表格视图相关代码（第 359-515 行）
-  - 需要增强树形节点的操作按钮（第 95-127 行）
-
-这个epic应该在保持系统完整性的同时，实现省市区管理用户体验的显著提升。"
+  - 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
+  - 修改 AreaTree 组件的节点展开逻辑，支持按需加载子节点
+  - 使用现有的 `getSubTree` API 按需加载子树
+  - 页面顶部按钮为"新增省"，节点上支持"新增市/区"按钮
+  - 后端需要新增批量删除API：`DELETE /areas/:id/with-children`
+  - 利用现有的 TanStack Query 缓存机制管理异步加载状态
+  - 完成后删除原有的 Areas.tsx 文件，更新路由配置
+
+这个epic应该在保持系统完整性的同时，实现省市区管理页面性能和用户体验的显著提升，并清理原有代码。"