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

字典模块开发计划

重新设计的字典表结构

表名: sys_dict

字段设计:

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(500) 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：数据库实体和基础架构

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

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

• 2.0 创建字典项接口 (POST /api/dict)

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

• 3.0 获取字典项内容接口 (GET /api/dict/:id)

  • 3.1 更新 dict.docs.md - 添加获取字典项业务逻辑
  • 3.2 扩展 dict.schema.ts - 定义获取字典项Schema
  • 3.3 扩展 dict.response.ts - 定义获取字典项响应格式
  • 3.4 扩展 dict.service.ts - 实现获取字典项业务逻辑
  • 3.5 扩展 dict.controller.ts - 实现获取字典项路由
  • 3.6 更新 dict.test.md - 添加获取字典项测试用例

• 4.0 获取完整字典树接口 (GET /api/dict/tree)

  • 4.1 更新 dict.docs.md - 添加获取完整字典树业务逻辑
  • 4.2 扩展 dict.schema.ts - 定义获取字典树查询Schema
  • 4.3 扩展 dict.response.ts - 定义字典树响应格式
  • 4.4 扩展 dict.service.ts - 实现获取完整字典树业务逻辑
  • 4.5 扩展 dict.controller.ts - 实现获取完整字典树路由
  • 4.6 更新 dict.test.md - 添加获取完整字典树测试用例

• 5.0 获取指定字典树接口 (GET /api/dict/tree/:code)

  • 5.1 更新 dict.docs.md - 添加获取指定字典树业务逻辑
  • 5.2 扩展 dict.schema.ts - 定义获取指定字典树Schema
  • 5.3 扩展 dict.response.ts - 定义指定字典树响应格式
  • 5.4 扩展 dict.service.ts - 实现获取指定字典树业务逻辑
  • 5.5 扩展 dict.controller.ts - 实现获取指定字典树路由
  • 5.6 更新 dict.test.md - 添加获取指定字典树测试用例

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

• 6.0 更新字典项内容接口 (PUT /api/dict/:id)

  • 6.1 更新 dict.docs.md - 添加更新字典项业务逻辑
  • 6.2 扩展 dict.schema.ts - 定义更新字典项Schema
  • 6.3 扩展 dict.response.ts - 定义更新字典项响应格式
  • 6.4 扩展 dict.service.ts - 实现更新字典项业务逻辑
  • 6.5 扩展 dict.controller.ts - 实现更新字典项路由
  • 6.6 更新 dict.test.md - 添加更新字典项测试用例

• 7.0 字典项排序接口 (PUT /api/dict/sort)

  • 7.1 更新 dict.docs.md - 添加字典项排序业务逻辑
  • 7.2 扩展 dict.schema.ts - 定义字典项排序Schema
  • 7.3 扩展 dict.response.ts - 定义字典项排序响应格式
  • 7.4 扩展 dict.service.ts - 实现字典项排序业务逻辑
  • 7.5 扩展 dict.controller.ts - 实现字典项排序路由

• 8.0 删除字典项接口 (DELETE /api/dict/:id)

  • 8.1 更新 dict.docs.md - 添加删除字典项业务逻辑（软删除）
  • 8.2 扩展 dict.schema.ts - 定义删除字典项Schema
  • 8.3 扩展 dict.response.ts - 定义删除字典项响应格式
  • 8.4 扩展 dict.service.ts - 实现删除字典项业务逻辑
  • 8.5 扩展 dict.controller.ts - 实现删除字典项路由

阶段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生成的内容作出修改
• 所有接口都需要遵循项目的编码规范和错误处理机制
• 字典模块需要支持树形结构的递归查询和操作
• 缓存机制需要考虑数据一致性和失效策略
• 软删除机制需要确保不影响现有业务逻辑