# 异步加载树形省市区管理页面 - Brownfield Enhancement

## Epic Goal

创建新的树形省市区管理页面，支持按层级异步加载子节点，避免一次性加载全部数据，提升页面性能和用户体验。

## Epic Description

### Existing System Context

**Current relevant functionality:**
- 省市区管理页面目前提供表格视图和树形视图两种模式（AreasPage.tsx:346-548）
- 表格视图显示所有省市区数据的平面列表，支持分页、筛选和搜索功能
- 树形视图以层级结构展示省市区关系，支持展开/收起操作（AreaTree.tsx:34-138）
- 当前树形视图一次性加载所有省市区数据，可能导致性能问题
- 后端已支持按需加载子树API：`GET /api/v1/admin/areas/tree/{id}`
- AreaForm组件提供完整的表单验证和三级联动选择器

**Technology stack:**
- React + TypeScript 前端框架
- 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)
- 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. **创建新的异步加载树形页面** - 直接创建新的树形省市区管理页面，支持按层级异步加载
   - 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
   - 默认只加载省级节点，点击节点时异步加载子节点
   - 保持现有的搜索和筛选功能

2. **实现异步加载机制** - 修改 AreaTree 组件支持按需加载子节点
   - 修改 AreaTree 组件的节点展开逻辑，从一次性加载改为按需加载
   - 使用现有的 `getSubTree` API 按需加载子树
   - 添加加载状态指示器，显示异步加载过程

3. **优化新增操作** - 在新的树形页面中支持智能新增功能
   - 页面顶部按钮为"新增省"
   - 在树形结构中直接新增市和区：省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
   - 重新设计 AreaForm 组件，移除层级和父级选择字段
   - 智能预填层级和父级信息：
     - 页面顶部"新增省"：层级自动为"省/直辖市"，无父级
     - 省级节点"新增市"：层级自动为"市"，父级自动为当前省份
     - 市级节点"新增区"：层级自动为"区/县"，父级自动为当前城市

4. **增强删除功能** - 支持删除当前节点及所有子节点
   - 后端新增批量删除API：`DELETE /areas/:id/with-children`
   - 前端调用新的批量删除API，支持递归删除子节点
   - 删除确认对话框显示准确的子节点数量

5. **优化数据缓存策略** - 使用 TanStack Query 管理异步加载状态和缓存
   - 利用现有的 TanStack Query 缓存机制优化重复请求
   - 实现错误处理和重试机制
   - 保持已加载节点的状态，避免重复请求

**How it integrates:**
- 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
- 修改 AreaTree 组件，支持按需加载子节点
- 使用现有的 `getSubTree` API 按需加载子树
- 后端需要新增批量删除API：`DELETE /areas/:id/with-children`
- 利用现有的 TanStack Query 数据管理和缓存机制
- 保持现有的 AreaForm 组件和表单验证功能
- 保持现有的搜索、筛选和状态切换功能
- 增强 AreaTree 组件的操作按钮，支持在节点上直接新增子节点

**Success criteria:**
- 用户进入省市区管理页面时默认只显示省级节点
- 点击省级节点时异步加载该省下的市级节点
- 点击市级节点时异步加载该市下的区级节点
- 异步加载过程显示加载状态指示器
- 已加载的节点保持展开状态，避免重复加载
- 页面顶部按钮为"新增省"，支持智能新增功能
- 在树形结构中直接新增市和区：省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
- 支持删除当前节点及所有子节点，删除确认对话框显示准确的子节点数量
- 现有搜索、筛选和CRUD操作功能保持正常
- 页面性能显著提升，减少初始加载数据量
- 用户体验流畅，加载过程无卡顿

## Stories

1. **Story 1:** 创建新的异步加载树形省市区管理页面
   - 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
   - 默认只加载省级节点，使用现有的 `getAreaTree` API 获取省级数据
   - 页面顶部按钮为"新增省"
   - ~~保持现有的搜索和筛选功能~~ (已移除 - 搜索筛选功能在当前异步加载架构中无效)
   - 实现树形节点的异步加载机制，支持按需加载子节点
   - 使用现有的 `getSubTree` API 按需加载子树
   - 添加加载状态指示器，显示异步加载过程
   - 实现错误处理和重试机制
   - 验证异步加载功能正常工作
   - 验证页面初始加载性能提升

2. **Story 2:** 实现智能新增和删除功能
   - 在树形结构中直接新增市和区：省级节点显示"新增市"按钮，市级节点显示"新增区"按钮
   - 重新设计 AreaForm 组件，移除层级和父级选择字段
   - 智能预填层级和父级信息：
     - 页面顶部"新增省"：层级自动为"省/直辖市"，无父级
     - 省级节点"新增市"：层级自动为"市"，父级自动为当前省份
     - 市级节点"新增区"：层级自动为"区/县"，父级自动为当前城市
   - 后端新增批量删除API：`DELETE /areas/:id/with-children`
   - 前端调用新的批量删除API，支持递归删除子节点
   - 删除确认对话框显示准确的子节点数量
   - 验证新增和删除功能正常工作

3. **Story 3:** 优化数据缓存和状态管理
   - 使用 TanStack Query 管理异步加载状态和缓存
   - 保持已加载节点的状态，避免重复请求
   - 确保现有 CRUD 操作功能保持正常
   - 验证搜索和筛选功能不受影响
   - 验证所有现有功能通过回归测试

4. **Story 4:** 清理原有代码
   - 删除原有的 Areas.tsx 文件 (web/src/client/admin/pages/Areas.tsx)
   - 更新路由配置，指向新的 AreasTreePage 组件
   - 验证所有功能迁移完成，无功能缺失
   - 清理不再使用的导入和依赖

## Compatibility Requirements

- [ ] 需要新增批量删除API：`DELETE /areas/:id/with-children`
- [x] 现有其他 APIs 保持不变：所有现有的 area API 接口保持兼容
- [x] 数据库 schema 无变化：AreaEntity 实体和表结构保持不变
- [x] UI 变化遵循现有模式：使用现有的 Shadcn/ui 组件和设计系统
- [x] 性能影响最小：异步加载减少初始数据量，批量删除使用事务保证性能
- [x] 现有功能无回归：所有现有的 CRUD 操作、搜索、筛选功能保持完整

## Risk Mitigation

**Primary Risk:** 异步加载可能影响现有树形视图的交互体验
**Mitigation:** 提供加载状态反馈，确保用户体验流畅；保持现有API兼容，支持快速回退

**Secondary Risk:** 需要新增后端批量删除API，增加了技术复杂度
**Mitigation:** 批量删除API设计为幂等操作，使用数据库事务确保数据一致性；前端提供明确的删除确认提示，显示将删除的子节点数量

**Technical Risk:** 异步加载状态管理可能引入复杂性
**Mitigation:** 使用现有的 TanStack Query 缓存机制，实现错误处理和重试机制

**Rollback Plan:** 可以恢复为一次性加载模式，修改仅限于前端组件逻辑；批量删除API可以保留作为可选功能

## Definition of Done

- [ ] 所有 stories 完成且验收标准满足
- [ ] 现有功能通过测试验证：所有现有的 CRUD 操作、搜索、筛选功能正常工作
- [ ] 集成点正常工作：新的 AreasTreePage、AreaTree、AreaForm 组件集成正常
- [ ] 后端批量删除API正常工作，保持事务一致性
- [ ] 异步加载功能正常工作，显示加载状态指示器
- [ ] 智能新增功能正常工作：页面顶部"新增省"按钮，节点上"新增市/区"按钮
- [ ] 表单设计优化：移除层级和父级选择字段，智能预填层级和父级信息
- [ ] 原有 Areas.tsx 文件已删除，路由配置已更新
- [ ] 文档适当更新：更新相关组件文档
- [ ] 现有功能无回归：所有现有功能通过回归测试
- [ ] 用户体验验证：异步加载流畅，操作路径简化，用户反馈积极

---

## Story Manager Handoff

"请为这个棕地epic开发详细用户故事。关键考虑：

- 这是对运行在 React + TypeScript + Shadcn/ui + TanStack Query + Hono RPC 技术栈的现有系统的增强
- 集成点：创建新的 AreasTreePage 组件，修改现有的 AreaTree 组件，以及需要新增的后端批量删除API
- 现有模式遵循：Shadcn/ui 设计系统，现有的树形视图交互模式，React Hook Form 表单管理，TanStack Query 异步数据加载模式
- 关键兼容性要求：需要新增批量删除API `DELETE /areas/:id/with-children`，其他现有API保持不变
- 每个故事必须包含验证现有功能保持完整的检查
- 特别注意：异步加载功能需要支持按层级加载子节点，避免一次性加载全部数据
- 技术细节：
  - 创建新的 AreasTreePage 组件，专门用于异步加载树形视图
  - 修改 AreaTree 组件的节点展开逻辑，支持按需加载子节点
  - 使用现有的 `getSubTree` API 按需加载子树
  - 页面顶部按钮为"新增省"，节点上支持"新增市/区"按钮
  - 重新设计 AreaForm 组件，移除层级和父级选择字段
  - 智能预填层级和父级信息：页面顶部"新增省"自动为省/直辖市，省级节点"新增市"自动为市，市级节点"新增区"自动为区/县
  - 后端需要新增批量删除API：`DELETE /areas/:id/with-children`
  - 利用现有的 TanStack Query 缓存机制管理异步加载状态
  - 完成后删除原有的 Areas.tsx 文件，更新路由配置

这个epic应该在保持系统完整性的同时，实现省市区管理页面性能和用户体验的显著提升，并清理原有代码。"