cursor-init/tasks/字典模块开发计划.md

# 字典模块开发计划

## 重新设计的字典表结构

**表名**: `sys_dict`

**字段设计**:

```sql
CREATE TABLE `sys_dict` (
  `id` BIGINT NOT NULL COMMENT '主键ID',
  `code` VARCHAR(50) NOT NULL COMMENT '字典代码，唯一标识',
  `name` VARCHAR(100) NOT NULL COMMENT '字典名称',
  `value` VARCHAR(200) NULL COMMENT '字典值（叶子节点才有值）',
  `description` VARCHAR(200) NULL COMMENT '字典描述',
  `icon` VARCHAR(100) NULL COMMENT '图标（CSS类名或图标路径）',
  `pid` BIGINT NULL DEFAULT 0 COMMENT '父级ID，0表示顶级',
  `level` INT NOT NULL DEFAULT 1 COMMENT '层级深度，1为顶级',
  `sort_order` INT NOT NULL DEFAULT 0 COMMENT '排序号',
  `status` VARCHAR(20) NOT NULL DEFAULT 'active' COMMENT '状态：active-启用，inactive-禁用',
  `is_system` BOOLEAN NOT NULL DEFAULT FALSE COMMENT '是否系统字典',
  `color` VARCHAR(20) NULL COMMENT '颜色标识',
  `extra` JSON NULL COMMENT '扩展字段',
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_code` (`code`),
  KEY `idx_pid` (`pid`),
  KEY `idx_level` (`level`),
  KEY `idx_status` (`status`),
  KEY `idx_sort` (`sort_order`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='系统字典表';
```

## 字典管理模块接口清单

1. 创建字典项

- 默认pid为0
- 字典项不允许同名
- 等级深度不能超过10
- 默认为系统字典

2. 获取字典项内容

- 根据code或id查找字典项

3. 获取完整字典树

- 获取完整的字典树
- 可根据status、is_system等条件过滤

4. 获取指定字典树

- 通过code或id或pid查找字典树
- 可根据status、is_system等条件过滤

5. 更新字典项内容

- 通过id修改字典内容，可选参数修改，不是传递全部参数，至少包括一个参数

6. 字典项排序

- 拖动排序

7. 删除字典项

- 软删除，防止依赖找不到

## 缓存机制

- 提供方法将整个字典写入redis缓存，后续接口查询先从缓存找

## 相关文件 (Relevant Files)

- `src/eneities/sysDict.ts` - 字典表实体定义
- `src/modules/dict/dict.docs.md` - 字典模块业务逻辑文档
- `src/modules/dict/dict.schema.ts` - 字典模块Schema定义
- `src/modules/dict/dict.response.ts` - 字典模块响应格式定义
- `src/modules/dict/dict.service.ts` - 字典模块业务逻辑
- `src/modules/dict/dict.controller.ts` - 字典模块路由控制器
- `src/modules/dict/dict.test.md` - 字典模块测试用例文档
- `src/modules/dict/dict.test.ts` - 字典模块单元测试
- `src/constants/swaggerTags.ts` - 更新Swagger标签定义

### 备注 (Notes)

- 单元测试通常应放置在与它们测试的代码文件相同的目录中
- 字典模块需要支持树形结构的CRUD操作
- 需要实现Redis缓存机制提高查询性能
- 需要处理软删除逻辑，避免数据依赖问题

## 开发计划

### 阶段1：数据库实体和基础架构

- [x] 1.0 创建字典表实体
    - [x] 1.1 ~~创建 `src/eneities/sysDict.ts` 文件，定义字典表实体结构~~
    - [x] 1.2 更新 `src/eneities/index.ts` 导出字典实体
    - [x] 1.3 创建数据库迁移文件，执行字典表创建

### 阶段2：字典模块核心接口开发

- [x] 2.0 创建字典项接口 (POST /api/dict)
    - [x] 2.1 生成接口业务逻辑文档，写入 `dict.docs.md`
    - [x] 2.2 创建 `dict.schema.ts` - 定义创建字典项Schema
    - [x] 2.3 创建 `dict.response.ts` - 定义创建字典项响应格式
    - [x] 2.4 创建 `dict.service.ts` - 实现创建字典项业务逻辑
    - [x] 2.5 创建 `dict.controller.ts` - 实现创建字典项路由
    - [x] 2.6 创建 `dict.test.md` - 编写创建字典项测试用例

- [x] 3.0 获取字典项内容接口 (GET /api/dict/:id)
    - [x] 3.1 更新 `dict.docs.md` - 添加获取字典项业务逻辑
    - [x] 3.2 扩展 `dict.schema.ts` - 定义获取字典项Schema
    - [x] 3.3 扩展 `dict.response.ts` - 定义获取字典项响应格式
    - [x] 3.4 扩展 `dict.service.ts` - 实现获取字典项业务逻辑
    - [x] 3.5 扩展 `dict.controller.ts` - 实现获取字典项路由
    - [x] 3.6 更新 `dict.test.md` - 添加获取字典项测试用例

- [x] 4.0 获取完整字典树接口 (GET /api/dict/tree)
    - [x] 4.1 更新 `dict.docs.md` - 添加获取完整字典树业务逻辑
    - [x] 4.2 扩展 `dict.schema.ts` - 定义获取字典树查询Schema
    - [x] 4.3 扩展 `dict.response.ts` - 定义字典树响应格式
    - [x] 4.4 扩展 `dict.service.ts` - 实现获取完整字典树业务逻辑
    - [x] 4.5 扩展 `dict.controller.ts` - 实现获取完整字典树路由
    - [x] 4.6 更新 `dict.test.md` - 添加获取完整字典树测试用例

- [x] 5.0 获取指定字典树接口 (GET /api/dict/tree/:code)
    - [x] 5.1 更新 `dict.docs.md` - 添加获取指定字典树业务逻辑
    - [x] 5.2 扩展 `dict.schema.ts` - 定义获取指定字典树Schema
    - [x] 5.3 扩展 `dict.response.ts` - 定义指定字典树响应格式
    - [x] 5.4 扩展 `dict.service.ts` - 实现获取指定字典树业务逻辑
    - [x] 5.5 扩展 `dict.controller.ts` - 实现获取指定字典树路由
    - [x] 5.6 更新 `dict.test.md` - 添加获取指定字典树测试用例

### 阶段3：字典管理接口开发

- [x] 6.0 更新字典项内容接口 (PUT /api/dict/:id)
    - [x] 6.1 更新 `dict.docs.md` - 添加更新字典项业务逻辑
    - [x] 6.2 扩展 `dict.schema.ts` - 定义更新字典项Schema
    - [x] 6.3 扩展 `dict.response.ts` - 定义更新字典项响应格式
    - [x] 6.4 扩展 `dict.service.ts` - 实现更新字典项业务逻辑
    - [x] 6.5 扩展 `dict.controller.ts` - 实现更新字典项路由
    - [x] 6.6 更新 `dict.test.md` - 添加更新字典项测试用例

- [x] 7.0 字典项排序接口 (PUT /api/dict/sort)
    - [x] 7.1 更新 `dict.docs.md` - 添加字典项排序业务逻辑
    - [x] 7.2 扩展 `dict.schema.ts` - 定义字典项排序Schema
    - [x] 7.3 扩展 `dict.response.ts` - 定义字典项排序响应格式
    - [x] 7.4 扩展 `dict.service.ts` - 实现字典项排序业务逻辑
    - [x] 7.5 扩展 `dict.controller.ts` - 实现字典项排序路由
    - [x] 7.6 在 `dict.test.md` 中添加排序接口测试用例

- [x] 8.0 删除字典项接口 (DELETE /api/dict/:id)
    - [x] 8.1 更新 `dict.docs.md` - 添加删除字典项业务逻辑（软删除）
    - [x] 8.2 扩展 `dict.schema.ts` - 定义删除字典项Schema
    - [x] 8.3 扩展 `dict.response.ts` - 定义删除字典项响应格式
    - [x] 8.4 扩展 `dict.service.ts` - 实现删除字典项业务逻辑
    - [x] 8.5 扩展 `dict.controller.ts` - 实现删除字典项路由
    - [x] 8.6 在 `dict.test.md` 中添加删除接口测试用例

### 阶段4：缓存机制和优化

- [ ] 9.0 Redis缓存机制实现
    - [ ] 9.1 更新 `dict.docs.md` - 添加缓存机制说明
    - [ ] 9.2 扩展 `dict.service.ts` - 实现Redis缓存写入方法
    - [ ] 9.3 扩展 `dict.service.ts` - 实现Redis缓存读取方法
    - [ ] 9.4 扩展 `dict.service.ts` - 实现缓存失效机制
    - [ ] 9.5 更新所有查询接口，优先从缓存读取
    - [ ] 9.6 更新 `dict.test.md` - 添加缓存机制测试用例

### 阶段5：集成和测试

- [ ] 10.0 模块集成和配置
    - [ ] 10.1 更新 `src/modules/index.ts` - 导出字典模块
    - [ ] 10.2 更新 `src/constants/swaggerTags.ts` - 添加字典模块标签
    - [ ] 10.3 更新主应用文件，注册字典模块路由
    - [ ] 10.4 创建 `dict.test.ts` - 实现单元测试
    - [ ] 10.5 进行端到端测试验证

### 阶段6：文档和部署

- [ ] 11.0 文档完善和部署准备
    - [ ] 11.1 完善API文档，确保Swagger正确显示
    - [ ] 11.2 创建字典模块使用说明文档
    - [ ] 11.3 进行性能测试和优化
    - [ ] 11.4 准备部署脚本和配置
    - [ ] 11.5 最终测试和验证

## 注意事项

- **每个接口的子任务执行完成后，需要停下来等待用户确认进行下一步输入，才能进入下一步，有可能需要对AI生成的内容作出修改**
- 所有接口都需要遵循项目的编码规范和错误处理机制
- 字典模块需要支持树形结构的递归查询和操作
- 缓存机制需要考虑数据一致性和失效策略
- 软删除机制需要确保不影响现有业务逻辑