# Story 006.002: 实现智能新增和删除功能

## Status
Draft

## Story
**As a** 管理员用户，
**I want** 在树形省市区管理页面中直接新增和删除省市区数据，
**so that** 我可以更高效地管理省市区层级关系，简化操作流程。

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

## Tasks / Subtasks
- [x] 重新设计 AreaForm 组件，移除层级和父级选择字段 (web/src/client/admin/components/AreaForm.tsx)
- [x] 在 AreaTreeAsync 组件中添加节点操作按钮：省级节点显示"新增市"，市级节点显示"新增区" (web/src/client/admin/components/AreaTreeAsync.tsx)
- [x] 实现智能预填逻辑：根据操作上下文自动设置层级和父级信息
- [ ] 后端实现批量删除API：`DELETE /areas/:id/with-children` (packages/server/src/api/admin/areas/index.ts)
- [ ] 前端集成批量删除API，支持递归删除子节点
- [ ] 实现删除确认对话框，显示准确的子节点数量
- [ ] 添加错误处理和重试机制
- [ ] 编写单元测试，验证智能预填功能
- [ ] 编写集成测试，验证批量删除API
- [ ] 编写E2E测试，验证完整的增删功能流程

## Dev Notes

### 技术栈要求
- **前端框架**: React 19.1.0+，使用函数组件和Hooks [Source: architecture/tech-stack.md#L13]
- **状态管理**: @tanstack/react-query 5.83.0+，服务端状态管理 [Source: architecture/tech-stack.md#L18]
- **UI组件库**: shadcn/ui，基于Radix UI的组件库 [Source: architecture/admin-dashboard-standards.md#L26]
- **HTTP客户端**: 基于Hono Client的封装 [Source: architecture/component-architecture.md#L50]

### 项目结构
- **AreaForm组件**: `web/src/client/admin/components/AreaForm.tsx` [Source: architecture/source-tree.md#L110]
- **AreaTreeAsync组件**: `web/src/client/admin/components/AreaTreeAsync.tsx` [Source: 006.001.story.md#L28]
- **后端API**: `packages/server/src/api/admin/areas/index.ts` [Source: architecture/source-tree.md#L66]
- **现有树形API**: `packages/server/src/api/admin/areas/tree.ts` [Source: architecture/source-tree.md#L67]

### API 集成
- **现有区域API**: `GET /api/v1/admin/areas` 获取区域列表 [Source: packages/server/src/api/admin/areas/index.ts]
- **现有树形API**: `GET /api/v1/admin/areas/tree` 获取完整树形结构 [Source: packages/server/src/api/admin/areas/tree.ts#L8-L47]
- **子树API**: `GET /api/v1/admin/areas/tree/{id}` 按需加载子树 [Source: packages/server/src/api/admin/areas/tree.ts#L95-L150]
- **新增批量删除API**: `DELETE /api/v1/admin/areas/:id/with-children` 删除节点及所有子节点

### 数据模型
- **AreaNode 接口**: 包含 id, name, code, level, parentId, isDisabled, children 等字段 [Source: web/src/client/admin/pages/Areas.tsx#L27-L36]
- **层级定义**: 1=省/直辖市, 2=市, 3=区/县 [Source: web/src/client/admin/pages/Areas.tsx#L304-L311]
- **智能预填逻辑**:
  - 页面顶部"新增省": level=1, parentId=null
  - 省级节点"新增市": level=2, parentId=当前省份ID
  - 市级节点"新增区": level=3, parentId=当前城市ID

### 组件交互
- **AreaForm 组件**: 现有的表单组件，需要移除层级和父级选择字段，改为智能预填 [Source: web/src/client/admin/components/AreaForm.tsx]
- **AreaTreeAsync 组件**: 异步加载树形组件，需要添加节点操作按钮 [Source: 006.001.story.md#L28]
- **Dialog 组件**: 使用 shadcn/ui 对话框组件 [Source: web/src/client/admin/pages/Areas.tsx#L551-L565]
- **Confirm Dialog**: 删除确认对话框，显示子节点数量

### 批量删除API设计
- **端点**: `DELETE /api/v1/admin/areas/:id/with-children`
- **参数**:
  - `id`: 要删除的区域ID (路径参数)
  - `recursive`: 是否递归删除子节点 (查询参数，默认true)
- **响应**:
  - 成功: 200 OK，返回删除的节点数量
  - 失败: 相应错误状态码和错误信息
- **实现要求**: 使用数据库事务保证数据一致性

### 错误处理
- **表单提交失败**: 显示用户友好的错误信息
- **删除操作失败**: 显示具体的失败原因
- **网络错误**: 实现重试机制
- **数据一致性**: 确保删除操作的原子性

### 用户体验
- **加载状态**: 显示异步操作进度指示器
- **操作反馈**: 使用 Sonner toast 通知操作结果 [Source: architecture/admin-dashboard-standards.md#L33]
- **确认对话框**: 删除前显示准确的子节点数量，防止误操作
- **响应式设计**: 支持桌面端和移动端 [Source: architecture/admin-dashboard-standards.md#L508-L523]

### 项目结构对齐
- **组件位置**: 符合现有的组件组织模式
- **API设计**: 遵循现有的RESTful API规范
- **文件命名**: 保持现有的kebab-case命名约定 [Source: architecture/source-tree.md#L166]
- **导入导出**: 使用ES模块和现有别名系统 [Source: architecture/source-tree.md#L170]

## Testing

### 测试标准
- **测试文件位置**:
  - 前端单元测试: `web/tests/unit/client/admin/components/AreaForm.test.tsx` [Source: architecture/testing-strategy.md#L27]
  - 前端集成测试: `web/tests/integration/client/admin/pages/AreasTreePage.test.tsx` [Source: architecture/testing-strategy.md#L37]
  - 后端API测试: `packages/server/tests/integration/api/admin/areas.test.ts` [Source: architecture/testing-strategy.md#L183]
- **测试框架**: Vitest + Testing Library (前端) / Vitest + hono/testing (后端) [Source: architecture/testing-strategy.md#L29]
- **测试模式**: 使用 Happy DOM 环境进行前端组件测试 [Source: architecture/testing-strategy.md#L97-L106]
- **覆盖率要求**: 核心业务逻辑 ≥ 80% [Source: architecture/testing-strategy.md#L30]

### 关键测试场景
- AreaForm组件智能预填功能测试
- 节点操作按钮显示逻辑测试
- 批量删除API功能测试
- 删除确认对话框显示准确的子节点数量
- 错误处理和重试机制测试
- 数据一致性测试（删除操作原子性）

### 测试数据管理
- **测试数据工厂**: 创建测试区域数据，包含层级关系
- **数据库事务**: 集成测试使用事务回滚保证数据隔离
- **边界测试**: 测试空节点、单节点、多层级节点的删除操作

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-10-28 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record

### Agent Model Used
- Claude Sonnet 4.5

### Debug Log References
- 修复 AreaForm 组件类型错误：smartLevel 参数类型问题
- 修复按钮样式问题：ghost 变体文字不可见，改为 outline 变体
- 修复悬停显示问题：添加 group 类到节点行

### Completion Notes List
- ✅ 重新设计 AreaForm 组件：移除层级和父级选择字段，改为智能预填
- ✅ 在 AreaTreeAsync 组件中添加节点操作按钮：省级节点显示"新增市"，市级节点显示"新增区"
- ✅ 实现智能预填逻辑：根据操作上下文自动设置层级和父级信息
- 🔄 后端实现批量删除API：进行中

### File List
- [web/src/client/admin/components/AreaForm.tsx](web/src/client/admin/components/AreaForm.tsx) - 重新设计表单组件
- [web/src/client/admin/components/AreaTreeAsync.tsx](web/src/client/admin/components/AreaTreeAsync.tsx) - 添加节点操作按钮
- [web/src/client/admin/pages/AreasTreePage.tsx](web/src/client/admin/pages/AreasTreePage.tsx) - 实现智能预填逻辑

## QA Results
*此部分将由QA代理在质量保证过程中填写*