1. 概述#

自动编码模块提供了统一的编码生成和管理功能，支持多种编码类型的规则配置，包括日期格式化、序列号处理、已删除编码重用等特性。

1.1 系统架构（与当前代码一致）#

编码服务系统采用三层架构：

1. 配置层：通过 codeRules 集中管理所有编码类型的规则配置
2. 服务层：CodeService 提供统一的编码生成和检查接口
3. 底层实现：codeGenerator.js 负责编码生成的具体逻辑

1.2 文件说明#

• src/services/codeService.js：编码服务主类，提供对外接口
• src/utils/codeGenerator.js：编码生成底层实现，包含日期格式化和序列号处理
• config/base/code.js：编码规则配置文件（通过 config/index.js 暴露为 config.code）

2. 使用示例#

2.1 生成编码#

const CodeService = require("../src/services/codeService");

// 生成新编码
const newCode = await CodeService.generateCode("USER_CODE");
console.log("生成的编码:", newCode);

2.2 生成唯一编码（推荐）#

// 生成唯一编码（会自动检查编码唯一性，可配置是否重用已删除的编码）
const uniqueCode = await CodeService.generateUniqueCode("DEPARTMENT_CODE");
console.log("生成的唯一编码:", uniqueCode);

2.3 检查编码是否存在#

// 检查编码是否已存在
const exists = await CodeService.checkCodeExists("ROLE_CODE", "R202305200001");
console.log("编码是否存在:", exists);

2.4 批量生成编码#

// 批量生成10个用户编码
const codes = await CodeService.batchGenerateCode("USER_CODE", 10);
console.log("批量生成的编码:", codes);

2.5 初始化序列号表#

// 在应用启动时初始化序列号表
await CodeService.initSequenceTable();
console.log("序列号表初始化完成");

3. 编码规则配置（当前实现）#

在 config/base/code.js 中配置编码规则（通过 config/index.js 暴露为 config.code）：

const codeRules = {
  USER_CODE: {
    prefix: "U", // 编码前缀
    pattern: "YYYYMMDD", // 日期格式
    sequenceLength: 4, // 序列号长度
    table: "user", // 对应的数据表
    field: "code", // 对应的字段
    autoComplete: false, // 是否启用已删除编码补全功能（可选，默认false）
  },
};

module.exports = codeRules;

4. 已删除编码自动补全功能（与服务层实现一致）#

4.1 功能描述#

编码服务支持配置化的已删除编码重用功能。通过显式配置，可以在生成新编码时优先查找并重用已删除的编码，实现编码的高效利用。注意：此功能默认是关闭的，需要显式配置启用。

4.2 工作原理#

1. 默认行为：系统默认不会重用已删除编码，直接生成全新编码

2. 启用方式：在 config/base/code.js 对应编码类型中显式设置 autoComplete: true

3. 重用流程：

   • 当配置了 autoComplete: true 时，系统会在 forceGenerateCode 函数中调用 findDeletedCodeToReuse
   • 该函数在对应的数据表中查找标记为删除（is_delete = 1）的记录
   • 找到匹配的编码后，系统会将其 is_delete 状态更新为 0，使其可重用
   • 如果未找到可重用编码，则继续生成新的编码

4. 数据筛选：

   • 系统会根据当前日期格式生成匹配模式（如 U20230520%）
   • 按编码升序排序，优先重用序列号较小的编码
   • 限制只返回一条可重用记录

4.3 配置选项#

编码规则中与自动补全功能相关的配置项：

• autoComplete：是否启用已删除编码自动补全功能（布尔值，默认为false）
• table：必须配置，指定要查找已删除记录的数据表
• field：必须配置，指定要查找的编码字段名

4.4 示例配置#

默认配置（不启用自动补全）：

const codeRules = {
  USER_CODE: {
    prefix: "U",
    pattern: "YYYYMMDD",
    sequenceLength: 4,
    table: "user",
    field: "code",
    // autoComplete默认为false，无需显式声明
  },
};

启用自动补全：

const codeRules = {
  USER_CODE: {
    prefix: "U",
    pattern: "YYYYMMDD",
    sequenceLength: 4,
    table: "user",
    field: "code",
    autoComplete: true, // 显式启用自动补全功能
  },
};

5. 错误处理#

所有方法都可能抛出异常，请确保使用 try/catch 捕获并处理：

try {
  const code = await CodeService.generateUniqueCode("USER_CODE");
  // 使用生成的编码
} catch (error) {
  console.error("编码生成失败:", error.message);
  // 处理错误
}

6. 性能优化#

• 使用 sequence_counter 表进行原子操作，避免并发冲突（底层使用 LAST_INSERT_ID）
• 支持降级方案，确保系统稳定性
• 可选的批量生成功能，提高效率
• 自动补全功能默认关闭，减少不必要的数据库查询

7. 注意事项#

• 确保数据库中存在 sequence_counter 表（包含 code_type 唯一键、current_value、update_time）
• 在应用启动时建议调用 initSequenceTable 方法初始化序列号表
• 对于高并发场景，建议使用 generateUniqueCode 方法
• 自动补全功能注意事项：
  • 默认不启用，需要显式配置 autoComplete: true
  • 确保数据表中有 is_delete 字段，用于标记记录是否被删除
  • 系统假设删除操作会设置 is_delete = 1

8. 故障排查#

• 如果编码生成失败，请检查数据库连接是否正常
• 如果序列号表初始化失败，请确保表结构正确
• 如果自动补全功能不工作，请检查：
  1. 是否在编码规则中显式设置了 autoComplete: true
  2. 数据表是否有 is_delete 字段
  3. 删除操作是否正确设置了 is_delete = 1
  4. 日志中是否有相关错误信息

9. 测试#

系统提供了针对自动补全功能的测试脚本，验证不同配置下的行为是否符合预期：

// 运行测试脚本
test / test_auto_complete.js;

测试验证了以下场景：

• 默认情况下（未配置autoComplete）自动补全功能关闭
• 显式设置 autoComplete: false 时自动补全功能关闭
• 仅当显式设置 autoComplete: true 时自动补全功能启用
• 对其他值（如undefined、null、字符串等），自动补全功能保持关闭

10. 最佳实践#

1. 默认不启用：除非明确需要重用已删除编码，否则建议保持默认配置
2. 按需启用：仅在需要严格控制编码连续性或有特殊业务需求的编码类型中启用
3. 合理配置：启用时确保数据表结构正确，并正确实现删除逻辑
4. 监控日志：关注日志中关于编码生成和重用的信息，及时发现问题
5. 性能考虑：在高并发场景下，启用自动补全功能可能增加数据库查询次数，请根据实际情况评估