expressgy/cursor-init
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5580941ffb
cursor-init/tasks/字典模块开发计划.md
expressgy 5580941ffb feat(dict): 新增字典项排序接口 
- 实现了 PUT /api/dict/sort 接口，用于批量排序和移动字典项。
- 添加了 SortDictSchema 用于请求验证。
- 添加了 SortDictResponsesSchema 用于 API 文档。
- 使用原生 SQL 和 CASE 语句实现了 sortDict 服务层方法，进行高效的批量更新，解决了之前遇到的 ORM 类型问题。
- 在字典模块的控制器中添加了新路由。
- 在 dict.test.md 中为排序接口添加了全面的测试用例。
2025-07-07 21:56:18 +08:00

8.3 KiB
Raw Blame History

字典模块开发计划

重新设计的字典表结构

表名: 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(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
  • 默认为系统字典
  1. 获取字典项内容
  • 根据code或id查找字典项
  1. 获取完整字典树
  • 获取完整的字典树
  • 可根据status、is_system等条件过滤
  1. 获取指定字典树
  • 通过code或id或pid查找字典树
  • 可根据status、is_system等条件过滤
  1. 更新字典项内容
  • 通过id修改字典内容，可选参数修改，不是传递全部参数，至少包括一个参数
  1. 字典项排序
  • 拖动排序
  1. 删除字典项
  • 软删除，防止依赖找不到

缓存机制

  • 提供方法将整个字典写入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 - 实现字典项排序路由
    • 7.6 在 dict.test.md 中添加排序接口测试用例

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