📝 docs(prd): update area management UX improvement epic documentation

- 完善现有系统上下文，补充技术栈和集成点详情
- 细化增强细节，添加具体实现代码行号和组件信息
- 补充兼容性要求和风险缓解策略
- 完善验收标准和完成定义
- 优化用户故事的技术细节描述

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

@@ -9,39 +9,60 @@
 ### Existing System Context
 
 **Current relevant functionality:**
-- 省市区管理页面目前提供表格视图和树形视图两种模式
-- 表格视图显示所有省市区数据的平面列表，支持分页和筛选
-- 树形视图以层级结构展示省市区关系，支持展开/收起操作
-- 新增按钮统一为"新增省市区"，需要用户手动选择层级
-- 删除操作在两种视图中都支持
+- 省市区管理页面目前提供表格视图和树形视图两种模式（AreasPage.tsx:346-548）
+- 表格视图显示所有省市区数据的平面列表，支持分页、筛选和搜索功能
+- 树形视图以层级结构展示省市区关系，支持展开/收起操作（AreaTree.tsx:34-138）
+- 新增按钮统一为"新增省市区"，需要用户手动选择层级和父级区域
+- 删除操作在两种视图中都支持，但仅删除当前节点，不处理子节点
+- AreaForm组件提供完整的表单验证和三级联动选择器
 
 **Technology stack:**
 - React + TypeScript 前端框架
-- TanStack Query 数据管理
+- TanStack Query 数据管理和缓存
 - Shadcn/ui 组件库
 - Hono RPC 客户端
+- React Hook Form 表单管理
 - 现有的 AreaTree 组件已实现树形结构展示
 
 **Integration points:**
 - 现有的 AreasPage 组件 (web/src/client/admin/pages/Areas.tsx)
 - AreaTree 组件 (web/src/client/admin/components/AreaTree.tsx)
 - AreaForm 组件 (web/src/client/admin/components/AreaForm.tsx)
-- 后端 area API 接口
+- AreaSelect 组件 (web/src/client/admin/components/AreaSelect.tsx)
+- 后端 area API 接口 (packages/server/src/api/admin/areas/)
+- AreaService 服务 (packages/server/src/modules/areas/area.service.ts)
 
 ### Enhancement Details
 
 **What's being added/changed:**
 1. **移除表格视图模式** - 将现有的双视图模式简化为单一的树形视图
+   - 删除 AreasPage.tsx 中的 Tabs 组件和表格视图相关代码（第 359-515 行）
+   - 移除表格视图相关的状态管理（page, pageSize, keyword 等）
+   - 保留树形视图的完整功能，包括搜索和筛选
+
 2. **优化新增操作** - 将"新增省市区"按钮改为"新增省"，并支持在树形结构中直接新增市和区
+   - 修改页面顶部按钮为"新增省"（AreasPage.tsx:339-342）
+   - 在 AreaTree 组件中为节点添加上下文新增按钮
+   - 省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
+   - AreaForm 组件支持智能预填层级和父级信息
+
 3. **改进删除交互** - 在树形结构中直接支持删除操作，支持删除当前节点及所有子节点
+   - 后端新增批量删除API：`DELETE /areas/:id/with-children`
+   - 前端调用新的批量删除API，支持递归删除子节点
+   - 删除确认对话框显示准确的子节点数量
+
 4. **增强树形视图功能** - 在树形节点上直接提供新增子节点（市、区）的功能
+   - 增强 AreaTree 组件的操作按钮（第 95-127 行）
+   - 保持悬停显示的操作模式
+   - 根据节点层级显示不同的新增按钮
 
 **How it integrates:**
-- 修改 AreasPage 组件，移除表格视图相关的代码
+- 修改 AreasPage 组件，移除表格视图相关的代码，优化状态管理
 - 增强 AreaTree 组件，在节点上添加新增子节点的操作按钮
 - 更新 AreaForm 组件，简化新增流程，支持基于上下文自动设置层级
 - 后端需要新增批量删除API，支持删除当前节点及所有子节点
 - 前端调用新的批量删除API实现删除功能
+- 保持现有的搜索、筛选和状态切换功能
 
 **Success criteria:**
 - 用户进入省市区管理页面时默认显示树形视图
@@ -50,36 +71,62 @@
 - 删除操作提供明确的确认提示，显示将删除的子节点数量
 - 现有功能不受影响，数据一致性保持
 - 用户体验显著提升，操作路径缩短
+- 后端批量删除API正常工作，保持事务一致性
 
 ## 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:** 增强树形视图交互，在节点上提供新增子节点和删除当前及所有子节点功能
+   - 后端新增批量删除API：`DELETE /areas/:id/with-children`
+   - 前端调用新的批量删除API，支持递归删除子节点
+   - 增强 AreaTree 组件的操作按钮（第 95-127 行）
+   - 删除确认对话框显示准确的子节点数量
+   - 验证批量删除功能正常工作，保持事务一致性
 
 ## Compatibility Requirements
 
-- [ ] 需要新增批量删除API
-- [x] 现有其他 APIs 保持不变
-- [x] 数据库 schema 无变化
-- [x] UI 变化遵循现有模式
-- [x] 性能影响最小
+- [ ] 需要新增批量删除API：`DELETE /areas/:id/with-children`
+- [x] 现有其他 APIs 保持不变：所有现有的 area API 接口保持兼容
+- [x] 数据库 schema 无变化：AreaEntity 实体和表结构保持不变
+- [x] UI 变化遵循现有模式：使用现有的 Shadcn/ui 组件和设计系统
+- [x] 性能影响最小：树形视图数据已缓存，批量删除使用事务保证性能
+- [x] 现有功能无回归：所有现有的 CRUD 操作、搜索、筛选功能保持完整
 
 ## Risk Mitigation
 
 **Primary Risk:** 需要新增后端批量删除API，增加了技术复杂度
-**Mitigation:** 批量删除API设计为幂等操作，确保数据一致性；前端提供明确的删除确认提示
+**Mitigation:** 批量删除API设计为幂等操作，使用数据库事务确保数据一致性；前端提供明确的删除确认提示，显示将删除的子节点数量
+
 **Secondary Risk:** 用户习惯现有表格视图，可能不适应单一树形视图
-**Mitigation:** 保留现有数据筛选和搜索功能，确保树形视图提供足够的信息展示
-**Rollback Plan:** 可以快速恢复表格视图代码，批量删除API可以保留作为可选功能
+**Mitigation:** 保留现有数据筛选和搜索功能，确保树形视图提供足够的信息展示；树形视图已实现完整的层级展示和操作功能
+
+**Technical Risk:** 移除表格视图可能影响某些特定使用场景
+**Mitigation:** 保留所有核心功能（搜索、筛选、CRUD操作），树形视图提供更直观的层级关系展示
+
+**Rollback Plan:** 可以快速恢复表格视图代码（保留在git历史中），批量删除API可以保留作为可选功能；如果用户体验问题严重，可以恢复双视图模式
 
 ## Definition of Done
 
 - [ ] 所有 stories 完成且验收标准满足
-- [ ] 现有功能通过测试验证
-- [ ] 集成点正常工作
-- [ ] 文档适当更新
-- [ ] 现有功能无回归
+- [ ] 现有功能通过测试验证：所有现有的 CRUD 操作、搜索、筛选功能正常工作
+- [ ] 集成点正常工作：AreasPage、AreaTree、AreaForm 组件集成正常
+- [ ] 后端批量删除API正常工作，保持事务一致性
+- [ ] 文档适当更新：更新相关组件文档
+- [ ] 现有功能无回归：所有现有功能通过回归测试
+- [ ] 用户体验验证：树形视图操作流程简化，用户反馈积极
 
 ---
 
@@ -87,11 +134,17 @@
 
 "请为这个棕地epic开发详细用户故事。关键考虑：
 
-- 这是对运行在 React + TypeScript + Shadcn/ui 技术栈的现有系统的增强
-- 集成点：现有的 AreasPage、AreaTree、AreaForm 组件，以及需要新增的后端批量删除API
-- 现有模式遵循：Shadcn/ui 设计系统，现有的树形视图交互模式
-- 关键兼容性要求：需要新增批量删除API，其他现有API保持不变
+- 这是对运行在 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 表单管理
+- 关键兼容性要求：需要新增批量删除API `DELETE /areas/:id/with-children`，其他现有API保持不变
 - 每个故事必须包含验证现有功能保持完整的检查
 - 特别注意：删除功能需要支持删除当前节点及所有子节点，需要后端提供相应的批量删除能力
+- 技术细节：
+  - AreasPage 组件目前使用 Tabs 实现双视图模式（第 346-548 行）
+  - AreaTree 组件已实现树形结构展示和基本操作（第 34-138 行）
+  - AreaForm 组件支持完整的表单验证和三级联动选择器
+  - 需要移除表格视图相关代码（第 359-515 行）
+  - 需要增强树形节点的操作按钮（第 95-127 行）
 
 这个epic应该在保持系统完整性的同时，实现省市区管理用户体验的显著提升。"