hyb-oa/.trellis/tasks/09-18-reimbursement-periodic-numbering/design.md

业务编号与历史兼容设计

2026-09-18 多角度复核与批准

用户明确“再次从多个角度审查……合适的话……实施改进”。主会话核过小团队可读性、财务对账、历史及银行材料兼容、并发/锁序、容量、切换回退与维护成本，保留矩阵全部建议；付款量低，年度号比每日号更便于识别，业务日期继续单独展示。当前范围已批准，官方current切至本task。本地实现默认不启用，独立复核保持PENDING（inline限制）。

定稿数据与接口

• 新增BusinessNumberPolicy单行v2策略，effective_at首次激活后固定、enabled可暂停/恢复；记录更新人及操作引用，并写既有审计。同版本不得回填或修改生效时间。迁移不插入激活记录。受控CLI只准备不执行生产。
• 新增BusinessNumberCounter，以规则版本+类型/资产前缀+周期唯一键存储BigInt高水位。独立于旧DocumentSequence，避免周期记录混进配置枚举。固定资产统一FA，电子资产沿用既有EA分类前缀（含合法自定义字符，SQL按字面转义匹配并用Unicode字符数截后缀）；同前缀共享计数，消除跨分类重号。
• 新取号器在调用者交互事务内工作，固定一次now并按appTimezone（默认Asia/Shanghai）生成日期。报销monthly，PB/JK/HK/CG/PD/PRJ yearly，FA/EA permanent。最小四位，BigInt扩位，不截断或归零。已有号码与UUID均不改。
• 现有单据分类页补简短说明：分类字段不会覆盖已启用的统一编号，仍服务于旧规则和电子资产前缀；仅沿用既有文字样式，不新增设计或配置开关。
• 配置读取返回当前新建对象采用的策略，不以seed切换；旧补号明确version=1。PurchaseRequest新增numbering_version，存量与直接旧写入默认1；新建草稿在事务内固定1/2，首次提交按保存版本取号，日期段按实际首次取号时间，跨月/年不改已编号对象。
• 新版即时创建取号与对象写入同事务；legacy路径保留。项目自动号进入事务，新号替代count+1；正式手工号继续支持，不替换导入编号。

锁序、切换与冲突

• 策略锁namespace1003/key0：业务事务共享锁，管理事务独占锁；锁后读取策略，不缓存进程状态。启停等候已持共享锁的事务完成，固定生效时刻采用取号时固定的now；切换前已建未编号草稿靠版本字段稳定归属。
• 新计数锁namespace1004，对象键固定登记为业务类型1..8，资产全类共用8；周期/前缀间保守串行，适合小团队。在锁内查同格式已有最大数字与持久高水位，接续更大值；唯一约束最后防线。无锁max+1、进程锁、事务内捕获唯一异常重试均禁止。
• 借款创建保留幂等完整事务；本金还款保持lender→排序loan→共享策略→HK计数→申请/分配→PB计数顺序。管理只锁策略，不取业务/计数锁；不存在反向依赖。普通PB只锁自身来源后取策略/PB计数。
• 同格式外部手工/导入占号通过每次锁内最大值接续；项目在支持的新格式下手工写号需同锁保留高水位。未接入的外部直接SQL写入仍由唯一约束阻止重号，不自动重试或回写。
• 全部写入实例先升级兼容再激活，不从环境变量或seed自动启用。CLI在锁等待和配置检查完成后拒绝已过期生效点；若旧共享取号配置已使用同一月/年日期段，保守拒绝首次激活/恢复并留待专门兼容处理，防止两套独立计数使旧草稿补号撞号。该检查不修改旧配置或旧号，status仅返回相关类型；可预约未来切换，恢复只复用原时点。暂停只影响以后新建对象，已归属v2的采购草稿仍用v2。回退只能使用兼容版本，不删除策略/计数/版本字段或已发号。
• 迁移的触发器禁止改写策略生效点、采购既定版本、删除或降低新计数高水位。策略管理明确记录操作者与引用，兼容实例标记属于操作人确认，不是自动化集群证明。
• 迁移仅加表及默认legacy字段、约束，不批量编号或变更业务号。回退保留新增结构，禁止down migration清空历史。

验证分层

单元覆盖全部格式/业务时区/跨月年/扩位/配置/版本固定/路由与幂等；隔离PG执行全部迁移，并发、回滚、删除占号、同格式接续、策略启停及旧草稿归属。混合BX/HK来源、旧PB及银行客户流水/行身份沿原用例验证。不能把单测stub当PG并发或把定向验证当G20完整门禁。原G20四未过另接续，零重试和原预算不变。

2026-09-18 官方资料调研

用户补充公司不足10人、科技初创公司，并要求先调研国内财务、OA、ERP做法。以下是公开原始资料，不是市场使用比例调查，也不代表所有版本的默认值。

来源	已核实事实	对本项目的含义
金蝶云产品手册：编码规则	可组合常量、日期、基础资料及流水；编码依据单独控制流水；保存时生成并做唯一性校验	日期格式与计数周期必须同时设计，不能只换展示格式
金蝶云产品手册：总账系统参数	凭证号排列规则可按期间或年度	总账凭证号与OA业务编号独立，不为迎合记账期间重编报销/付款号
畅捷通官方：T6小编号，有大学问	已实际阅读文章内教程图片：按业务类型配置前缀、日期、流水依据和起始值；示例日期格式为年月	支持按业务配置，而非所有业务固定按日；该资料发表于2017年，不能外推为当前T+默认规则
钉钉宜搭帮助中心：流水号	默认计数4位；支持不重置、按日/月/年；日期格式和时区可配；文档说明手动重置或计数溢出可能产生重复	作为OA/流程表单代表，证明周期属于可选配置；本项目不能照搬其允许重号的行为

检索受阻、结果无关、只有标题且未读正文的资料未纳入结论；没有声称已核实泛微/致远的具体默认配置。公开资料、实际读取摘要及校验值保存在本轮ignored证据 numbering-public-research/sources-and-findings.json。

不足10人公司的建议矩阵（2026-09-18复核后获批）

依据是单据用途和用户提供的小团队/低付款量背景，未额外读取生产业务量。不同类型统一取号原则，不强求同一重置周期。

类型	实施前工作树事实	推荐的新号	决策状态
报销	BX-日期-四位下限；长期累计	BX-202609-0001，每月重置	用户已选择
付款批次	PB-日期-三位；按业务日，日上限999	PB-2026-0001，每年重置	本轮批准；报销付款与本金还款继续共用PB序列
公司借款	JK-UUID，属于本地待发布实现	JK-2026-0001，每年重置	本轮批准
本金还款申请	HK-UUID，属于本地待发布实现	HK-2026-0001，每年重置	本轮批准；HK是申请、PB是执行批次，分别保留
采购申请	默认CG-日期-流水；yearly元数据未执行重置	CG-2026-0001，每年重置	本轮批准；保留首次提交取号时机
盘点单	PD-日期-流水；yearly元数据未执行重置	PD-2026-0001，每年重置	本轮批准
项目	手工项目号或PRJ-UTC日期-当日数量加一	已有/正式项目号保留；新自动号PRJ-2026-0001，每年重置	本轮批准；修复count+1并发及删除碰号风险
固定资产	FA-年份-六位；yearly元数据未执行重置	新资产可用FA-0001，永久递增、终身不改	本轮批准；比前稿年度资产号更适合少量设备；已有标签不换
电子资产	EA分类前缀和独立序列	保留已有分类边界，新号可去掉年份并永久递增	本轮批准，不新增分类体系
合同	正式合同号录入，续约关联使用-Rn	保留正式编号及既有续约引用	不自动改号
员工与主数据	系统生成/人工/来源系统的稳定编码	保留稳定编码，不按年月重置	不自动改号
发票、银行流水/回单、企微审批	外部系统来源编号	保留外部原号	不自动改号
冻结差旅	CL/TRB等旧编号和冻结链	保留，恢复前再评估	不恢复或为统一编号改旧链

这里的实施前事实来自指定执行树，不将未部署的借款、还款等本地实现说成线上现状。短号方案是本项目建议，不是厂商强制标准。用户先前报销按月选择保留；若后来希望连报销也统一按年，属于新决策，不能自行替换。

共同合同与实施顺序草案

1. 日期段与重置周期一致；按现有业务时区取号，具体创建/提交/付款/业务发生日期在独立字段展示。跨月审批、跨年结清不换号；补录历史借款区分登记日期和原借入日期。
2. 不加入部门、人员、金额、付款状态或可变分类。各业务类型独立全局计数，不按经办人/部门再分段；现有资产分类边界和所有权约束保持。
3. 普通单据四位作为最小补零宽度，超过9999扩位、不归零、不截断；固定资产也从四位起。内部UUID继续用于关联，不承担普通用户展示号。
4. 已经创建对象获得的号码不回收，取消/作废留下空号；内部业务序号不是业务数量或会计凭证连续性的替代。失败事务未发布号码的回滚与已发号后删除须分开验证。
5. 旧号、已有草稿及原审批/付款/审计/银行材料引用保持不变。新旧格式并存，搜索、自然排序、通知跳转、PDF/导出都需验；不进行历史批量改号。
6. 按批准矩阵先完成报销周期计数与历史缺号边界；随后付款/借款/还款共用机制及锁序；最后纳入批准的采购/项目/资产等。分步实施不改变原门禁未完成事实。
7. 复用周期唯一键和事务原子递增，不能按数量加一、无锁最大号加一或在共享计数器上并发清零；保持本金/审批/审计/银行回单合同，不通过编号调整改变业务状态机。
8. 验证覆盖业务时区跨月/年、四位溢出、并发取号、回滚、取消不复用、旧草稿稳定、混合格式消费者及报销/借款付款整链。独立只读复核、生产切换、发布授权分别留项。此前调研未改产品代码，本轮进入实施。

已有实际业务的增量切换方案

原则与本地证据

用户明确已有多个旧号业务。本方案补全历史兼容，最新用户授权复核适合后实施，已确认本节范围。既有业务继续按原审批/付款流程办理，不为编号变更做删除重建、重新提交或重复付款。

本地代码显示：报销创建草稿即取号；采购在首次提交时才取号；报销提交只在form_number缺失时补号。PaymentBatchItem同时保存entity_id与entity_code，关联可以保持而展示号应取持久化原值。paymentOrderXls.js:24以batch_no和行号生成客户流水号，:134用于银行制单。因此仅给旧批次换一个“更好看的号”也会影响后续导出身份，不能当作无风险展示调整。

各类旧业务的处理

对象	切换后处理
已编号报销/采购草稿	原号及原规则归属保留，编辑和提交不换号
切换前创建但尚未取号的采购草稿、历史缺号报销	到原业务取号时机时按旧规则补号；不提前批量编号
审批中、待付款或已付款单据	原号及所有历史引用保持，跨月/年完成也不换号
旧付款批次（含draft、reviewed、failed）	保留batch_no、已有名称及来源快照；继续原流程，不因切换而取消重建
已导出付款材料	客户流水号、原批次行绑定和证据原样保留；显示排序不能改变生成流水的业务行顺序
新付款批次关联旧报销/旧还款申请	PB按新批次自身规则发号，逐项展示原BX/HK，不重写来源号；允许新旧格式在同批次并存
旧资产/项目/合同	编号、标签和正式材料保留；新资产永久短号等仍纳入本轮批准范围

切换边界与首号

• 采用一个明确、持久化的规则生效点T；优先在完成兼容验证后的月初启用，便于解释。2026-10-01只是候选窗口示例，未排期、未执行发布。付款若按年度编号可以在年中启动新格式，无须专门等到2027年。
• 规则选择属于单据创建事实，不能按页面展示时间、最后更新时间或提交当天重新判断。实施时明确可信创建时间与规则版本的持久化方式；已有未编号草稿、补录/导入及跨T的在途事务必须纳入同一判据，不仅靠服务进程的一次启动时间。
• 先具备新旧格式兼容能力、核实全部写入实例都支持切换机制，再受控激活T；不让滚动发布中新旧写入端各自选规则。未准备好就继续旧规则，不倒填过去的生效点。
• 新格式使用独立计数。比如旧PB-20260917-001保留；年中新格式的PB-2026-0001表示新序列第一批，不宣称是2026年公司实际第一笔付款。
• 0001只在确认目标格式尚未被已有/导入/自定义编号占用时成立；有同格式号码须在锁和数据库唯一约束下接续，不能无锁MAX+1或清零旧计数。旧格式计数继续保留给兼容补号路径，已发给已创建对象的号码永不复用。
• 采用存量原号与新号并存，无需为所有旧单额外生成第二套“规范号”或新旧号映射表；这是拒绝历史改号的自然结果。内部关联继续使用原ID，实际编号使用原存储值，兼容未知历史格式而不猜测改写。
• 混合格式的自然编号顺序不等于时间先后；核验现有列表排序、付款明细编号自然排序及筛选/搜索，不擅自把日期排序宣称为原编号排序。显示调整不得影响付款执行或银行制单行身份。

切换前验证与回退

先在本地合成库构造上表全部状态，验证旧对象字段与引用不变、新旧来源可组批、跨月/年和并发取号、旧草稿切换后提交、客户流水号及行绑定稳定、取消不复用、旧格式查询和导出。针对同格式冲突、在途事务和回退后重新启用补反例。

生产前置只需经授权取得格式分布/冲突数/缺号数/各状态数量及范围内关联完整性摘要，不需要票据、银行资料、秘密配置或备份。本次没有查询这些生产事实；此前指定付款批次的只读授权不扩大为全库调查。无证据不声称线上零冲突。

回退须保持所有已发新号与计数，旧兼容路径不得删除新号或回收流水；只能回到仍支持新旧格式的版本。数据库切换、真实配置写入、提交推送部署与独立review均保留原授权边界。