编码规则易混淆字符独立选择

status: done created: 2026-07-18 complexity: 🟡中等

1. 背景与目标

编码规则流水号段当前只有“排除 I / O / Z”总开关，管理员无法只排除其中一个或两个字符。本变更将配置改为 I、O、Z 三个独立选项，并让预览、真实生成、容量计算和持久化使用同一份字符集合。

完成后应满足：

用户可分别勾选 I、O、Z，支持任意组合和全部不选；
字母及字母数字进制只移除选中的字符，小写进制同步移除对应小写字符；
历史 excludeAmbiguous=1 且没有新字段的数据继续等价于同时排除 I/O/Z；
十进制、十六进制不受选择影响，切换进制时不丢失用户已经选择的字符。

2. 代码现状（Research Findings）

2.1 相关入口与链路

forge-admin-ui/src/views/app-center/components/CodeRuleSegmentEditor.vue：流水号段高级配置当前使用单个 n-switch 修改 excludeAmbiguous。
forge-admin-ui/src/views/app-center/code-rule-utils.js：新分段、回显归一化和预览载荷只维护 0/1 总开关。
CodeRuleService / CodeRuleSegmentMapper.xml：分段保存到 ai_code_rule_segment.exclude_ambiguous。
CodeRuleEngine / CodeRuleRadixCodec：用 boolean 决定是否一次性移除 I/O/Z。

2.2 现有实现

CodeRuleRadixCodec#alphabet(String, boolean) 在开关为 true 时固定移除 I/O/Z 及小写。
AiCodeRuleSegment 与 CodeRuleSegmentDTO 没有具体字符集合字段。
V1.0.36__add_structured_code_rule_segments.sql 中 exclude_ambiguous 是历史兼容字段。

2.3 发现与风险

直接把旧字段改成位掩码会让历史值 1 的语义从“全部排除”变成“只排除 I”，不可接受。
字符集合会改变进制容量、号段步长和 legacy 兼容宽度缓存键，不能只改前端展示。
目标前端文件已有用户未提交的预览/交互改动，本轮必须做局部补丁，禁止覆盖。

3. 功能点

流水号段显示 I、O、Z 三个独立勾选项。
新协议保存规范化的具体排除字符集合。
编码引擎按具体集合执行编码、容量和宽度计算。
历史总开关数据自动回显为全选并保持原生成结果。
Flyway 为存量表补字段并回填历史全选数据。

4. 业务规则

允许字符仅为 I、O、Z；忽略重复值并按 I、O、Z 固定顺序保存。
新字段为空且 excludeAmbiguous=1 时按 I/O/Z 全选处理；新字段非空时以新字段为准。
小写字母进制选择 I/O/Z 时实际移除 i/o/z。
DECIMAL、HEX 的字母表不因该配置改变；配置仍保留，切回字母进制后继续生效。
旧 excludeAmbiguous 字段保留：全选时同步为 1，其余组合为 0，供旧协议兼容读取。

5. 数据变更

操作	表名	字段/索引	说明
新增字段	`ai_code_rule_segment`	`excluded_characters varchar(16)`	保存规范化字符集合，如 `I,O,Z`
数据回填	`ai_code_rule_segment`	`excluded_characters`	历史 `exclude_ambiguous=1` 回填为 `I,O,Z`

6. 接口变更

操作	接口	方法	变更内容
兼容扩展	`/system/code-rule` 详情/新增/更新	GET/POST/PUT	分段新增 `excludedCharacters` 字符串；保留 `excludeAmbiguous`
兼容扩展	`/system/code-rule/preview`、`/ai/code-rule/preview`	POST	预览按具体字符集合生成

7. 影响范围

编码规则配置页流水号段高级配置；
分段 DTO、实体、Mapper XML、定义缓存快照；
编码进制转换、容量计算和 legacy 宽度兼容；
ai_code_rule_segment Flyway 增量迁移。

8. 风险与关注点

不改变规则编码、分段键、序列 key，不重置任何计数器。
字符集合变化会改变未来编码字符表与容量，属于管理员显式配置结果。
不修改现有 V1.0.36/V1.0.37，新增更高版本迁移。

8.5 测试策略

测试范围：前端归一化/交互纯函数、后端 codec/engine、Mapper/Flyway 静态契约、定向 Lint 和前端构建。
覆盖率目标：覆盖单选、组合、全选、全不选、历史总开关、小写映射、十六进制无影响。
独立 Test Spec：是。

9. 待澄清

无。用户已明确要求 I、O、Z 可单独选择。

10. 技术决策

新增 excludedCharacters 字符串协议并保留旧 0/1 字段，避免位掩码破坏历史语义。
字符集合规范化收敛到前端工具函数和后端 CodeRuleRadixCodec，引擎、容量与缓存统一消费规范值。

11. 执行日志

Task	状态	实际改动文件	备注
建立基线	完成	本目录四份 SDD 文档	复用 2026-07-17 编码规则验证基线
前后端实现	完成	UI、DTO/Entity、Codec/Engine、Service/Mapper、V1.0.39	旧总开关兼容为全选
增量验证	完成	Test、Lint、Build、Playwright、静态检查	详细证据见 execution-log.md

12. 审查结论

Spec Compliance：PASS。
Code Quality：PASS；没有重置规则编码、分段键或序列 key。
真实 Flyway 和新版后端保存接口未实跑，按项目分工由用户环境补验。

13. 确认记录（HARD-GATE）

确认时间：2026-07-18
确认人：用户直接提出实现请求