D08 发票域 · 设计文档

本域总览见《账号计费中心 · 结构大纲》。本文为该域完整设计：定位与边界 / 角色与依赖 / 数据模型 / 核心流程 / 接口契约 / 关键约束与验收标准。 章节顺序理由：先数据模型（事实结构）→ 再核心流程（结构之上的运行路径）→ 最后接口契约（流程的对外投影）。

1. 定位与边界

定位：账期费用的收据化环节。回答三个问题——「这个账期该开多少」（账期费用汇总对量）、「开出来的是哪一张票」（发票实体与发票号）、「票开错了怎么退回去」（作废重开）。申请流与发票实体严格分离：申请是请求与处置的过程，发票是开票结果，一张申请可以被驳回零次或多次开票，也可以在作废后退回重开。

关键口径

边界

• 不管计价与金额生成：申请上的金额由提交方给定并经人工核对，本域不做按定价规则的换算；账期费用汇总的读通道属计量与计费域。
• 不管资金流：开票不改现金余额、不动赠金、不落资金流水；退款与退款渠道对账属退款与对账域。
• 不管欠费判定本身：overdue_since 的置位与清除只在钱包变更事务末尾发生；本域只读该标记。
• 不管税控与票据实物：税控对接、纸质票寄送、税局回执不在本域。
• 不管门户自助入口的编排与展示：客户侧提交与查看由用户自助与门户域承载，详见 D12；本域提供申请人归属与抬头快照口径。
• 不管运营面端点的索引与权限载体：运营面端点语义细节在本域，统一索引登记在 D11。

归属口径：本域端点 = 内部运营链 /internal/invoice-applications（5 个）+ 运营面 /api/account/ops/invoices/applications（5 个）。两通道共用同一实现。

2. 角色与依赖

能力矩阵

• 两条通道的操作人都是可空的（见 §4.7）：运营面取登录主体标识，内部运营链取请求头 X-Operator-Id。

上游依赖

下游被引用

3. 数据模型

关联线是单向指针：申请可指向一张发票，发票不反向持有申请。作废重开时申请指针被清空并重新指向新发票，旧发票行原样留存供追溯。

• 组织与钱包引用是实外键且删除受限：收票主体与资金主体不允许被物理删除而留下无主票据。
• 申请人对身份的引用是可空外键、置空删除：操作人不在本仓用户表中时该列留空，而操作人线索走审计（见 §4.7）。
• 账期汇总只作读数源，不建跨域外键。

3.3 表清单（2 表）

• 抬头缺省为组织名与信用代码，提交方可整体覆盖 title_info。
• 代客创建时申请人列置空——操作人属平台侧身份，不是客户侧申请人，线索走审计。
• 两条入口（运营面、内部运营链）共用同一实现与同一校验序，差别只在鉴权通道与操作人来源。

• 金额下界在入参层以正数约束先拦（0 与负值 422），服务层再兜一次「金额非正即 invalid_amount」，防绕过入参层的调用路径。
• 票种为受限两值，非枚举值一律拒；个人主体开专票恒拒（与实名等级无关）。
• 账期只校验顺序，不校验是否为整月或已封账历史区间——账期正当性由人工核对承担。

• 欠费判据：读 customers.overdue_since 非空即拦（400 overdue_not_invoiceable），拦截失败后申请保持可处理态、不产生任何发票实体。该标记是派生标记（只在钱包变更事务末尾重算），此处取的是「客户当前处于欠费态」，即开票时点的服务状态口径；这与生命周期出口的债务判据（只认现金余额为负）是两个不同用途：出口拦的是未清偿债务，开票拦的是账期服务状态，故此处按标记判定，不改写为现金判据。
• 发票号规则：INV + 账期尾日的年月日八位 + 8 位十六进制随机段（大写），定长 19 字符；尾日段使同账期票据在号面上可归堆，随机段使同秒并发不撞号。全局唯一由 invoice_no 上的唯一约束兜底，跨组织不重号；随机段撞号（概率量级 1/2^32）会由唯一约束冲突显式失败，不静默改号。
• 票面快照与同事务：账期、金额（分）、票种、抬头一并从申请复制到发票实体，此后申请不可再改（唯一可改字段是处理记录）；开票、回写与审计同事务一次提交，不存在「发票已建而申请未回写」的中间态。

• 三个状态字串：submitted / issued / rejected；issued 是唯一可作废的状态，作废后退回 submitted（回环）。
• rejected 在处置语义上为终态：已驳回的申请既不能再开票也不能再驳回（均 409），需要重新开票时另建申请。
• 作废不回退 rejected：作废只能对自己开出的票发起。

• 两步同事务：发票置作废与申请回退必须在同一事务内提交。任何一步失败即整体回滚——否则会出现「票已废而申请仍指向废票」（无法重开）或「申请可重开而旧票仍有效」（一账期两张有效票）。
• 重开生成新号：退回 submitted 后再走 §4.3，新发票号为新建实体的号，与已作废的旧号必然不同；旧票行状态保持作废、号不被复用。
• 作废不校验欠费：作废是把错票收回，不是开出新票；欠费拦截只发生在开票动作上。
• 作废是否退费不属本域：票据作废引起的资金后果（退款、核销）在退款与对账域与钱包与账务域处理。

• 驳回是「不受理」语义：无票据、无号，不留半成品；后续如仍要开票须另建申请。
• 驳回原因写入处理记录（上限 500 字符），是台账上唯一的驳回说明载体；驳回与开票共用同一取单入口与行锁，并发同申请仅一方成功（§4.9）。

• 为什么置空不报错：运营侧身份来自平台侧账号体系，本仓用户表里往往没有对应行；若直接把它写入审计的操作人外键，外键约束会把一次正常的开票动作打成 500。
• 审计怎么留：动作、目标类型、目标标识、处理明细（含发票号与金额）随业务同事务落审计；跨服务操作人线索以文本形式记入明细，运营台可按该线索回溯外部操作者。
• 审计层另有类型守卫：操作人实参若非 UUID 类型则降级为空并告警——降级方向是「审计缺操作人，但主流程不崩」。

• 账期区间如何划定：以申请上的首日与尾日为准；用量侧按同一区间做日聚合，归日为统一业务时区，写入侧只接受落在回溯窗口内的日期，历史账期不被迟到推送污染。
• 金额如何取：以计量金额（用量侧）与按类型聚合的流水为两侧对量依据；「量可重算、钱不可重放」，所以差异先查推送与对账，不靠改申请金额抹平。
• 以什么为单位：汇总源为元、6 位小数；申请与发票金额列为分整数，两者按 1 元 = 100 分对齐，换算结果按四舍五入取整到分。
• 「申请金额不高于账期实际消耗」的自动校验依赖计价落定，当前口径为人工核对并在处理记录中留痕（见 §6.3）。

• 重复开具收敛为显式失败而非静默幂等：第二次开票得到 409，不生成第二张票，也不复用原票号回复——「一申请一有效票」下，重复调用是运营动作失误，需要被看见而不是被吞掉。
• 并发双开由申请行锁串行化：取单即加行锁，后到者在锁上等待，先到者提交后锁重估读到 issued，进入 409 分支；从机制上不可能出现一申请两票。
• 重复作废得到 409（非已开票态即不可作废）；作废后重开是新一次开票，产生新号，不与原动作视为重复。
• 开票失败不留半成品：欠费拦截与状态不匹配都发生在落库之前，申请与发票实体都保持原样。

• 抬头存在哪里：先落申请的文档型抬头列，开票时复制到发票实体的抬头列；发票实体持有票面快照，不随组织资料后续变更而变。
• 与开票主体的关系：收票主体是组织（决定票种门禁与抬头缺省值），资金主体是钱包（由组织反查落票）。抬头可覆盖缺省，但不能改变收票主体。
• 变更口径：申请抬头无独立编辑动作；未开票时改抬头即另建申请，已开票时须走作废重开，避免同一发票号下票面被改写。

5. 接口契约

5.1 内部运营链（内部令牌的运营范围，5 个端点）

• 鉴权：内部令牌须持有运营范围，缺失即 403 forbidden；操作人经请求头 X-Operator-Id 传入，可空。
• 请求体：建申请带收票主体、首尾日、金额（分，正数）、票种（缺省普票）、抬头（可空）；处置体只带处理记录（上限 500 字符，可空）。
• 响应统一为「成功标记 + 申请行」，申请行含发票号与发票标识（未开票为空）。

5.2 运营面（saas:ops:invoice 权限范围，5 个端点）

• 权限范围独立于客户账务与信用额度范围：只持信用额度范围的运营角色访问发票台账即 403（能力隔离在权限范围内落地）。
• 两条通道共用请求体模型与同一服务实现，差异仅有鉴权通道与操作人来源；运营面端点的统一索引与权限载体登记在 D11。

5.3 客户侧入口（归属说明）

• 客户侧不为本域新增第二条写入路径：申请创建、状态机与发票实体全部复用同一套实现，客户侧只多带一个申请人归属。

6. 关键约束与验收标准

6.1 约束

1. 申请与发票分离：申请是流，发票是结果；发票实体只由开票动作创建，被驳回的申请永不产生发票实体。
2. 可处理态唯一：仅 submitted 可被开票或驳回；已开票的申请不可再驳回，已驳回的申请不可再开票或再驳回（一律 409）。
3. 一申请一有效票：开票与回写同事务，发票指针同事务建立；作废时指针与发票状态同事务一并变更。
4. 作废可追溯：作废只改发票状态，发票行与发票号整体留存；重开必然生成新号，旧号不复用、不覆盖。
5. 发票号全局唯一：号面 = 前缀 + 账期尾日 + 随机段；唯一约束兜底，撞号显式失败。
6. 欠费不开票：欠费态标记非空的客户，其申请开票被 400 拒，申请保持可处理态；作废与驳回不受此约束。
7. 金额单位为分：申请与发票金额列一律为分整数；与元口径汇总源换算按 1 元 = 100 分取整到分，链路中不出现二进制浮点中间量。
8. 抬头开票即冻结：抬头随开票复制为票面快照；更正抬头只能另建申请或作废重开。
9. 处置串行化：开票、驳回、作废共用同一取单入口并施加行锁；并发同申请只有先到者成功，后到者得到 409。
10. 操作人可空但不丢线索：操作人不在本仓用户表时外键置空、线索入审计明细，绝不因外键约束把正常处置打成 500。
11. 变更必留审计：建申请、开票、驳回、作废四类动作与业务变更同事务落审计（动作、目标类型、目标标识、明细）。
12. 主体引用受限删除：收票主体与资金主体的引用为受限删除；申请人对用户表、申请对发票为置空删除。
13. 门户与运营面同源：客户侧展示与运营台账消费同一份数据，不存在两套发票事实。
14. 票种受实名门禁：专票需企业实名达 L2，普票需主体达 L1；个人主体恒不可开专票。

6.2 验收标准

6.3 待后续设计细化的开放项

1. 金额自动校验：「申请金额不高于账期实际消耗」的自动判定需等计价口径落定，当前为人工核对与处理记录留痕。
2. 客户侧提交入口的编排：客户侧提交与查看的位置、权限与频次限制归用户自助与门户域，本域只提供申请人归属与抬头快照口径。
3. 抬头编辑语义：是否允许在未开票状态下更正申请抬头（而非另建申请），以及抬头字段的规范化与校验（税号格式、抬头长度）。
4. 重复申请的去重口径：同一主体同一账期存在多条未处置申请时的合并或提示规则；当前不设账期唯一约束。
5. 开票数据源的自动化：账期汇总自动发起开票的条件（封账时点、对账通过阈值、异常人工介入），以及分口径与元口径对账的全自动闭合。
6. 票据外部状态的回接：外部开票处理端的开票结果、拒开与红冲结果如何落回本域（当前本域只承载人工开票的结果记录）。