Startseite Erkunden Hilfe
Registrieren Anmelden
176-template-162
/
mini-starter
geforkt von 155-template-138/mini-starter
2
0
Fork 0
Dateien
Struktur: 57a4eccdfe
Branches Tags
mini-starter
/
docs
/
prd
/
epic-006-area-management-ux-improvement.md

epic-006-area-management-ux-improvement.md 10 KB
Verlauf Originalformat

异步加载树形省市区管理页面 - 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
  • 现有其他 APIs 保持不变：所有现有的 area API 接口保持兼容
  • 数据库 schema 无变化：AreaEntity 实体和表结构保持不变
  • UI 变化遵循现有模式：使用现有的 Shadcn/ui 组件和设计系统
  • 性能影响最小：异步加载减少初始数据量，批量删除使用事务保证性能
  • 现有功能无回归：所有现有的 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应该在保持系统完整性的同时，实现省市区管理页面性能和用户体验的显著提升，并清理原有代码。"