取号管理 ★
一句话：集中管理「单据编号怎么生成」——一个模板定义前缀 + 日期 + 流水（或随机串、UUID）+ 后缀的拼号规则，表单和业务模块按「模板编码」引用它取号；流水计数在服务端串行发放，跳号可审计，已出过号的模板不允许删除。
功能在哪
- 菜单路径：基础设施 → 数据管理 → 取号管理（菜单原名「单据模板」）
- 地址栏路由：
/infra/data-manage/bill-template - 主要权限：
infra:bill-template:query（列表/详情）、:create（新增）、:update（编辑）、:delete（删除）
界面认识
查询条件：模板名称、模板编码、分类（字典「单据模板分类」：业务单据 / 基础数据 / 其他）、生成方式、状态。
列表列：
| 列 | 说明 |
|---|---|
| 序号 / 模板名称 / 模板编码 | 编码是被引用的键 |
| 分类 | 业务单据 / 基础数据 / 其他 |
| 生成方式 | 时间流水 / 随机数编号 / UUID |
| 范例 | 服务端按当前配置试算出的样例号，不消耗流水 |
| 重置周期 | 跟随日期格式 / 不重置 / 按天 / 按月 / 按年 |
| 当前流水 | 鼠标悬停有说明：出号后回写的展示值，可能略滞后于实际流水 |
| 状态 | 开关，直接启用/停用 |
| 更新时间 / 操作 | 行内四个按钮全展开：测试、日志、编辑、删除 |
常用操作
新建一个模板
「新增」→ 弹窗「新建模板」，左右两栏：基本信息 与 生成配置。
- 左栏填「模板名称」「模板编码」，选「分类」，按需调「排序」「状态」「备注」；
- 右栏选「生成方式」，下方字段随方式变化（见下节）；
- 看「范例」框——它由服务端实时试算，改一项就重算一次，确认号码长相符合预期；
- 「确定」保存。
模板编码保存后别改
编辑态「模板编码」禁用，表单里也写着原因：表单与其它模块通过它引用本模板。保存后不建议修改——它同时是流水计数的标识，改了等于换一个计数器，流水会从头开始。
三种生成方式
| 方式 | 号码主体 | 适用 | 注意 |
|---|---|---|---|
| 时间流水 | 日期段 + 左补零流水号 | 采购单、销售单等有连续编号要求的单据 | 唯一会消耗流水计数的方式 |
| 随机数编号 | 16 位或 32 位随机串（纯数字 / 字母+数字） | 邀请码、临时单号 | 表单旁注：随机方式不消耗流水计数，理论上存在重复可能，建议给目标列加唯一索引兜底 |
| UUID | 36 位大写字符串（含连字符） | 只需全局唯一、不需人读的场景 | 蓝色提示：加上前后缀后容易超过 varchar(64)，请确认目标列长度足够 |
「时间流水」的可调项：
| 字段 | 取值与说明 |
|---|---|
| 前缀 / 后缀 | 固定字符串，各最长 50 字符（占位提示「如 CG」「如 -A」） |
| 日期格式 | 不含日期 / 年（2026）/ 年月（202609）/ 年月日（20260906）/ 到时 / 到分 / 到秒（20260906143045）/ 到毫秒（20260906143045123） |
| 流水位数 | 1–9 位。旁注：流水值超过该位数时不会截断，而是输出更长的号码（截断会产生重复号），届时日志里会有告警提示调大位数 |
| 起始值 / 步长 | 起始值 ≥ 0，步长 ≥ 1 |
| 重置周期 | 旁注：「跟随日期格式」按日期的最小单位推导：含日按天、含月按月、含年按年。注意到秒、到毫秒的格式仍然按天重置——按秒重置会让每张单子的流水都是 1，等于没有流水 |
| 流水分组 | 开关。旁注：开启后按前缀分别计数。前缀是固定字符串时开不开都一样；它主要为表单里「前缀取自客户编号」这类场景准备——那时每个客户各自从 1 开始 |
测试取号
行内「测试」→「取号测试 - {模板名称}」，两种方式二选一（单选：模拟取号（不消耗流水） / 真实取号（消耗流水））。面板顶部说明原文：
模拟取号（默认）只试算下一个号，不消耗流水、不写日志，可反复执行；真实取号与业务出号走同一路径，会消耗流水并在日志中记为「测试取号」，严格取号场景请优先使用模拟，避免正式单据跳号。
真实取号会吃掉一个号，且不归还
点「真实取号」会先弹「真实取号确认」：「真实取号将消耗模板「{名称}」的一个流水号，且不可归还（可能造成正式单据跳号）。确认执行吗？」（按钮「确认取号」/「取消」）。成功提示分别是「真实取号成功，流水已消耗」与「模拟取号成功，流水未消耗」。验证配置请一律用模拟。
面板下方的「执行历史（仅本次页面会话）」只在当前页面积累，刷新即清空；「模板当前状态」显示实时流水，便于对照。
取号日志
行内「日志」→「取号日志 - {模板名称}」。查询条件：取号时间（必填且不超过 3 个月）、单据编号、来源（业务出号 / 表单预占 / 测试取号）、结果。列：取号时间、单据编号、生成方式、周期、序号、来源、取号人、结果、失败原因。
页面顶部说明原文（要点）：
仅模板开启「取号日志」后才会记录。取号时间区间必填且不超过 3 个月……业务事务回滚时号码不归还，出现跳号属正常现象——日志正是跳号的审计凭证。
「取号日志」默认关闭
表单里的开关旁注：开启后每次取号都会记录日志（谁、何时、何途径、取得何号、当时的周期与序号），用于严格追溯场景；日志写在独立事务里，不影响取号结果。默认关闭。 高频取号模板请评估写入量后再开。
停用与删除
- 停用：列表「状态」开关，或编辑表单里选「停用」；停用后取号请求会被拒绝，模板与流水都保留；
- 删除：确认文案 「确认删除模板「{名称}」吗？此操作不可恢复。」；但只要它出过号就会被拦住：「模板「{名称}」已生成过单号，不允许删除。如需停止使用请改为「停用」」。
字段说明
| 字段 | 必填 | 说明与校验提示 |
|---|---|---|
| 模板名称 | 是 | 「模板名称不能为空」 |
| 模板编码 | 是 | 「模板编码不能为空」，且需符合编码格式（字母/数字/下划线，以字母或下划线开头）；编辑态禁用 |
| 分类 | 否 | 业务单据 / 基础数据 / 其他 |
| 排序 | 否 | 数字越小越靠前 |
| 状态 | 是 | 开启 / 停用 |
| 备注 | 否 | 最长 500 字 |
| 生成方式 | 是 | 「生成方式不能为空」 |
| 前缀 / 后缀 | 否 | 各最长 50 字符 |
| 日期格式 | 时间流水必填 | 见上表八种粒度 |
| 流水位数 | 时间流水必填 | 「流水位数不能为空」，1–9 |
| 起始值 / 步长 | 否 | 起始值 ≥ 0，步长 ≥ 1 |
| 重置周期 | 否 | 默认「跟随日期格式」 |
| 流水分组 | 否 | 开关，按前缀分别计数 |
| 随机位数 / 随机类型 | 随机数编号必填 | 16 位 / 32 位；纯数字 / 字母+数字 |
| 范例 | 只读 | 服务端试算结果，不消耗流水 |
| 取号日志 | 否 | 开关，默认关闭，独立事务写入 |
视角对照
| 视角 | 看到什么 |
|---|---|
超管 admin / 租户管理员 docadmin | 全部模板，可增删改、测试、看日志 |
| 只授「查询」的角色 | 只能看列表与范例，测试/编辑/删除按钮不显示 |
| 套餐未含此菜单的租户 | 侧边栏「数据管理」下没有本页，取号能力由平台方统一配置 |
| 普通员工 | 无此菜单；填表单时编号自动生成，感知不到模板存在 |
进阶
- 号码连续性不是承诺：业务事务回滚、真实取号测试、服务重启都会造成跳号。若客户要求「编号严格连续无空洞」，需要改用「先落库占号、失败回收」的业务方案，而不是调取号参数；
- 表单预占：表单打开时就预取一个号（来源记为「表单预占」），用户不提交也会消耗流水——这是跳号的常见来源，排查时按来源筛一下即可；
- 流水位数宁大勿小：位数不够时号码会变长而不是截断，虽不会重复但会影响列宽与打印排版；按预估年单量一次给够（如日单量 4 位、按月重置给 6 位）；
- 多租户：流水计数按租户隔离，同一模板编码在不同租户各自从起始值开始；
- 改了配置会怎样：日期格式、重置周期、位数改动立即对下一次取号生效，已发出的号不受影响；「当前流水」列可能略滞后，以测试面板的「模板当前状态」为准。
常见问题
Q：删除时提示「已生成过单号，不允许删除」？ A：这是刻意保护——已出号的模板被历史单据引用，删掉会让追溯断链。改为「停用」即可。
Q：模拟取号和真实取号该用哪个？ A：验证配置一律用模拟取号（不消耗流水、不写日志、可反复执行）。真实取号只在需要复现线上出号链路时使用，并且号会被吃掉。
Q：编号出现跳号，是不是出 bug 了？ A：多数情况正常：事务回滚不归还号码、表单预占未提交、真实取号测试都会跳号。开启「取号日志」后按时间与来源即可定位到每一次出号。
Q：「当前流水」和测试面板显示的不一致？ A：列表的「当前流水」是出号后回写的展示值，可能略滞后；以测试面板的「模板当前状态」为准。
Q：流水涨到超过设定位数会怎样？ A：不截断，直接输出更长的号码（截断会产生重复号），同时日志里给出告警提示调大位数。
Q：想让每个客户各自从 1 开始编号？ A：把「前缀」在表单里配成取自客户编号，并打开「流水分组」——开启后按前缀分别计数。
Q：随机数编号会不会重复？ A：理论上有可能（它不消耗流水计数）。给目标列加唯一索引兜底，冲突时重取即可；对唯一性要求高的场景请用时间流水或 UUID。