hl-api-changelog/changelogs-v2/2026-09/20_7980_发票签发重传重开三写口补同一把锁新增100503冲突码触达C端-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7980	发票签发组三个写口（admin 完成开票 / admin 重新上传 / mp 申请重开）补同一把 @Lock4j name，杜绝 reupload ∥ reissue 一单两票漏洞，新增可重试冲突码 100503（会传导至小程序 C 端）	multiple	wx(GIT)	修改接口	deployed	not_required	not_required	mmg				PR #8043 已 squash 合并 dev-v3(合并提交 09b8f2323)。2026-09-20 对 hl-order-service-v3 重跑了一次部署流程(滚动重启两实例),部署后 COMMIT=5d14bc524;git merge-base --is-ancestor 09b8f2323 5d14bc524 返回 YES,确认本次改动在运行版本内——但如实说明:部署前该服务已经是 5d14bc524(另一会话此前已把这个 commit 推上测试服),本次重跑部署没有让改动「从生效变生效」，只是重新确认了一遍。gateway_status=not_required 判据不变:三个端点路径/方法零变化,hl-gateway 一直是 4cbccc26b 未动,发票端点走网关实测全部正常返回。🔴 测试服直接证据(redis-cli MONITOR)只覆盖三处写口中的一处——issueInvoice;另两处(reuploadInvoice/reissueInvoice)由代码改动本身(与 issueInvoice 逐字相同的 name/keys)与反射守卫单测 InvoiceIssueLockNameGuardTest(断言三处 name 非空且相等)覆盖,未在测试服上单独抓包或调用,不要读成三处都实测过互斥。100503 本身测试服未能复现(并发两个 issueInvoice 得到 200+581502,不是 100503;581502 是业务状态守卫,证明没有产生并发脏写,但只是旁证不是互斥证据);原因判断同 fleet 那轮,临界区极短。frontend_status=pending 维持不变,详见「八、测试环境已验证」完整记录。 前端实证翻 not_required(mmg 2026-09-20):admin 侧 issue/reupload 封装于 api/invoice.js,唯一调用方 IssueModal handleSubmit catch「业务错误码由 request.js 拦截器统一 toast」、finally 复位 submitting,100503 命中拦截器透后端「资源被占用,请稍后重试」原样展示(提示可重试/不静默/不当系统异常三条全满足),同 fleet #7980 先例不建字典;mp reissue 传导 C 端属小程序系列,由 mp loop 消费。	2026-09-20	dev-v3

order-v3: 发票签发组三个写口补同一把 @Lock4j name，新增可重试冲突码 100503（会传导至小程序 C 端）

存放目录:

• 一期(v2,无 order-v3 标签的工单)→ changelogs/{YYYY-MM}/
• 二期(v3,order-v3 标签的工单)→ changelogs-v2/{YYYY-MM}/

服务: hl-order-service-v3（另涉 hl-mp-service 两个透传入口） PR: #8043 Issue: #7980（AC-4） 日期: 2026-09-20 影响范围: 管理后台「发票财务管理」的「完成开票」「重新上传」两个写操作 + 小程序 C 端「申请重开发票」

---

⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）

• InvoiceAdminService.issueInvoice、InvoiceAdminService.reuploadInvoice、InvoiceMpService.reissueInvoice 三处 @Lock4j 此前写了逐字相同的 keys（'order-invoice:issue:' + #invoiceId），却都没写 name——lock4j 落 Redis 的锁键含方法名，name 缺省时退化为「全限定类名 + 方法名」，于是三个方法各持一把互不相干的锁，可以并发互相踩踏。
• 后果是真实数据缺陷：reupload ∥ reissue 会在同一张发票上留下两行非 VOIDED 记录——reissue 先把旧票置 VOIDED 并插入新票（REQUESTED），随后 reupload 把（已经作废的）旧票又写回 ISSUED，order_invoice 表上无 UNIQUE、OrderInvoice 实体无 @Version，没有第二道兜底能挡住这个结果。
• 本次给三处补上同一个显式 name = "order-invoice:issue"，三者才真正互斥（同一张发票的开票/重传/重开现在会排队执行）。接口路径、请求/响应字段、既有错误码全部零增删，唯一的契约变化是新增一个可能返回的失败码。
• 🔴 新增的失败路径会到达小程序 C 端：用户点「申请重开发票」时，若财务端此刻正在同一张票上做「完成开票」或「重新上传」，会等待最多约 3 秒后收到 code=100503（"资源被占用,请稍后重试"）。传输层仍是 HTTP 200，失败信息在响应体的 code 字段里——前端如果只看 HTTP 状态码会把这次失败误判为成功。反向同理：财务端两个接口也可能因为 C 端正在 reissue 而收到同一个码。
• 🔴 两句话都要看，缺一句都会误判：
  1. 这条失败路径源码级真实存在——acquireTimeout 默认 3000ms、超时经 LockFailureExceptionHandler 统一转 100503、@ResponseStatus(HttpStatus.OK) 确认 HTTP 200 + body 携带业务码，这套链路已逐行读码确认；InvoiceIssueLockConcurrencyIT 的持锁超时用例实测到等待约 3024ms 后抛出该码。
  2. 但触发概率极低——同一用例测得三者中任一方法单次临界区（一次 UPDATE/一次 UPDATE+一次 INSERT）实测上界约 89ms，远小于 3000ms 的 acquireTimeout，只有同一 invoiceId 在同一瞬间被两个写口同时命中才会撞上。这不代表它不会发生，前端仍应做防御性处理（识别 code=100503 提示可重试），但不必按高频交互设计。
• ✅ 测试服部署已确认，但直接证据只覆盖三处写口中的一处：2026-09-20 hl-order-service-v3 测试服 COMMIT 5d14bc524 已含本次改动（git merge-base --is-ancestor 09b8f2323 5d14bc524 → YES）。redis-cli MONITOR 实时抓包证实调用 issueInvoice 时锁键与预期完全一致、无方法名混入——但这只验证了 issueInvoice 一处；reuploadInvoice/reissueInvoice 另两处未在测试服上单独抓包或调用，是由代码改动本身（与 issueInvoice 逐字相同的 name/keys）与反射守卫单测 InvoiceIssueLockNameGuardTest 覆盖的，不要读成"三处共用同一把锁"已在测试服实测确认。
• 🔴 100503 测试服未能复现，且第二次读数不是它本来该是的样子：对同一发票并发发两个 issueInvoice，一个 code=200，另一个是 code=581502（INVOICE_CANNOT_ISSUE 业务状态守卫），不是 100503。这说明没有产生并发脏写（第二个请求命中的是"状态已不是 REQUESTED"的正常业务拒绝），但这是旁证，不是互斥证据——不能拿它证明锁生效，只能证明没有出现数据损坏。原因判断与 fleet 那一轮相同：单次临界区极短（上界约 89ms），远小于 3 秒超时。

---

一、背景

InvoiceAdminService.issueInvoice（完成开票）、InvoiceAdminService.reuploadInvoice（重新上传）、InvoiceMpService.reissueInvoice（C 端申请重开）三个方法操作的是同一张 order_invoice 记录，前置条件互相重叠（reuploadInvoice 与 reissueInvoice 都要求旧票处于 ISSUED/PUSHED），三处代码注释里都写着「并发: @Lock4j 串行化」，但三个 @Lock4j 的 SpEL keys 虽逐字相同，name 全部缺省。lock4j 生成的实际 Redis 锁键是 <name>#<keys 求值>，name 缺省时用「方法所在类全限定名 + 方法名」兜底，三个方法名不同 ⇒ 三把不同的锁，注释里承诺的"串行化"此前并不成立。工单 #7980 AC-4 给三处补齐同一个显式 name，串行化才真正生效。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	完成开票	PUT	/v3/admin/order/invoice/{id}/issue	新增可能返回的错误码	抢锁超时返 100503（原接口/字段不变）
2	重新上传发票文件	PUT	/v3/admin/order/invoice/{id}/reupload	新增可能返回的错误码	抢锁超时返 100503（原接口/字段不变）
3	申请重开发票（mp internal）	POST	/v3/internal/mp/order/invoice/{invoiceId}/reissue	新增可能返回的错误码	抢锁超时返 100503；经 hl-mp-service 两个透传入口到达小程序 C 端（见第 3 节业务边界）

---

三、接口详情

1. 完成开票 PUT /v3/admin/order/invoice/{id}/issue

VO: InvoiceIssueReqVO → Void

使用场景

财务在管理后台「发票财务管理」列表里，对状态为 REQUESTED（待开票）的发票执行开票：先调 POST /v3/admin/order/invoice/upload 上传文件拿到 fileUrl，再调本接口把发票状态从 REQUESTED 推进到 ISSUED，同时落 issued_at/issued_by，开票金额由后端此刻自动计算写入。本次改动不涉及本接口的入参/出参字段，只新增一条"被 reupload/reissue 占用同一把锁"的失败分支。

入参

路径参数 id（发票 ID）+ Body：

字段	位置	类型	必填	约束	说明
id	Path	Long	✅	-	发票 ID
fileUrl	Body	String	✅	@NotBlank	发票文件 OSS URL（由 /upload 接口返回）
pdfName	Body	String	✅	@NotBlank	发票 PDF 文件名
pdfSize	Body	Long	✅	@NotNull	文件大小（字节）
invoiceNo	Body	String	-	-	发票号（财务登记）

出参 Result<Void>

字段	类型	说明
data	null	无返回数据，Result.data 恒为 null

请求示例

{
  "fileUrl": "https://oss.example.com/invoice/abc.pdf",
  "pdfName": "发票_2026062100001.pdf",
  "pdfSize": 204800,
  "invoiceNo": "25441000000123456789"
}

响应示例

{ "code": 200, "message": "成功", "data": null, "success": true }

空数据 / 降级响应

本接口无「空数据」概念（成功恒返回 data: null），也没有降级路径。

错误响应

{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }

code	触发条件
400	参数校验失败（fileUrl/pdfName/pdfSize 缺失）
581500	发票不存在（INVOICE_NOT_FOUND）
581502	发票当前状态不是 REQUESTED，不允许开票（INVOICE_CANNOT_ISSUE）
581525	订单核单未完成（reviewStatus≠COMPLETED），不可开票（INVOICE_ORDER_NOT_REVIEWED）
100503（本次新增）	抢锁等待超过 3 秒（本组另一写口——reupload 或 C 端 reissue——正持有 order-invoice:issue 锁），可重试
401	未登录（网关拦截）

实测说明（本接口是三处写口中唯一在测试服上单独取证的一处）：

• IT 层（InvoiceIssueLockConcurrencyIT）：100503 路径源码级真实存在——持锁方在 acquireTimeout（默认 3000ms）内未释放时，后到方约等待 3024ms 后收到该码；正常场景下单次临界区实测上界约 89ms，远小于超时阈值。
• 测试服层（2026-09-20，hl-order-service-v3 COMMIT 5d14bc524）：redis-cli MONITOR 抓包证实真实调用锁键为 lock4j:order-invoice:issue#order-invoice:issue:{invoiceId}，无方法名混入；并发发两个 issueInvoice（同一发票）实测结果是一个 200、另一个 581502（业务状态守卫）而不是 100503——证明没有并发脏写，但这是旁证不是互斥证据，100503 本身未在测试服复现；单独调一次 issueInvoice 回归 code=200，正常路径未受影响。详见「⚠️ 关键变化」与「八、测试环境已验证」。

业务边界

• 无 @Idempotent 保护（与本组其他历史改动不同）：本接口只有 @Lock4j 串行化 + REQUESTED 状态守卫去重，双击/网络重试若落在"状态已不是 REQUESTED"会走 581502，不是幂等拦截。
• 抢锁失败（100503）时该次请求未进入方法体，零写入——@Lock4j 是方法级环绕拦截，拿不到锁直接抛异常，业务代码一行不会执行。
• 金额此刻由后端自动计算写入（CANCELLED 订单取净实收 paid-refunded，其余取应收总额），不接受前端传入金额。
• 老数据兼容：无字段变化，不涉及旧数据兼容问题。

---

2. 重新上传发票文件 PUT /v3/admin/order/invoice/{id}/reupload

VO: InvoiceReuploadReqVO → Void

使用场景

财务对状态为 ISSUED/PUSHED 的发票覆盖上传新文件（不作废旧发票、不新建发票，只更新文件字段 + issued_at/issued_by）。本次改动不涉及本接口的入参/出参字段，只新增一条"被 issue/reissue 占用同一把锁"的失败分支——补锁之前，reupload 与 C 端 reissue（两者前置条件同样是 ISSUED/PUSHED）能同时进入临界区，是本工单要堵的主要漏洞场景（见「⚠️ 关键变化」）。

入参

路径参数 id（发票 ID）+ Body：

字段	位置	类型	必填	约束	说明
id	Path	Long	✅	-	发票 ID
fileUrl	Body	String	✅	@NotBlank	新发票文件 OSS URL（由 /upload 接口返回）
pdfName	Body	String	✅	@NotBlank	发票 PDF 文件名
pdfSize	Body	Long	✅	@NotNull	文件大小（字节）
invoiceNo	Body	String	-	-	发票号（如有变更可更新）

出参 Result<Void>

字段	类型	说明
data	null	无返回数据，Result.data 恒为 null

请求示例

{
  "fileUrl": "https://oss.example.com/invoice/abc_v2.pdf",
  "pdfName": "发票_2026062100001_v2.pdf",
  "pdfSize": 204800,
  "invoiceNo": "25441000000123456789"
}

响应示例

{ "code": 200, "message": "成功", "data": null, "success": true }

空数据 / 降级响应

本接口无「空数据」概念（成功恒返回 data: null），也没有降级路径。

错误响应

{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }

code	触发条件
400	参数校验失败（fileUrl/pdfName/pdfSize 缺失）
581500	发票不存在（INVOICE_NOT_FOUND）
581503	发票当前状态不是 ISSUED/PUSHED，不允许重新上传（INVOICE_CANNOT_REUPLOAD）
581525	订单核单未完成，不可重传（INVOICE_ORDER_NOT_REVIEWED）
100503（本次新增）	抢锁等待超过 3 秒（本组另一写口——issue 或 C 端 reissue——正持有 order-invoice:issue 锁），可重试
401	未登录（网关拦截）

实测说明：IT 层链路与第 1 节一致（同一 InvoiceIssueLockConcurrencyIT，触发条件同为等待超过 acquireTimeout 3000ms）。🔴 但本接口未在测试服上单独抓包或调用——2026-09-20 测试服直接证据只覆盖 §1 issueInvoice；本接口的锁互斥依据是代码改动本身（reuploadInvoice 与 issueInvoice 使用逐字相同的 name="order-invoice:issue"/keys）以及反射守卫单测 InvoiceIssueLockNameGuardTest（断言三处 name 非空且相等），不是独立的测试服实测。

业务边界

• 无 @Idempotent 保护，仅 @Lock4j 串行化 + canReupload（ISSUED/PUSHED）状态守卫去重。
• 抢锁失败（100503）时该次请求零写入，旧文件字段不会被覆盖。
• 不作废旧发票、不新建发票，只更新文件字段（对齐修复旧 mp 端 reissue 守卫永远抛错的历史 bug：旧逻辑要求 ISSUED/UPLOADED/DELIVERED，但全系统无代码写入后两态）。
• 老数据兼容：无字段变化，不涉及旧数据兼容问题。

---

3. 申请重开发票（mp internal） POST /v3/internal/mp/order/invoice/{invoiceId}/reissue

VO: InvoiceReissueReqVO → InvoiceReissueRespVO

使用场景

小程序 C 端用户对状态为 ISSUED/PUSHED 的已开发票申请「重开」（改抬头/税号等）：后端把旧发票置 VOIDED，同事务插入一张继承旧票字段、按请求覆盖可改字段的新发票（REQUESTED，待财务重新开票）。这是 hl-order-service-v3 的 internal 接口，C 端用户不会直接访问它，而是通过 hl-mp-service 的两个公网入口调用（见下方「业务边界」）。本次改动不涉及本接口的入参/出参字段，只新增一条"被 issue/reupload 占用同一把锁"的失败分支。

入参

路径参数 invoiceId（旧发票 ID）+ Body：

字段	位置	类型	必填	约束	说明
invoiceId	Path	Long	✅	-	旧发票 ID
invoiceType	Body	String	✅	@NotBlank，枚举见六.5	发票类型
titleType	Body	String	✅	@NotBlank，枚举见六.5	抬头类型
titleName	Body	String	✅	@NotBlank，≤100 字符	发票抬头名称
taxNo	Body	String	条件必填	≤30 字符	税号（titleType=COMPANY 时必填）
email	Body	String	✅	@Email，≤100 字符	收件邮箱

orderId/amount 由后端反查旧发票得出，前端不传；userId 从鉴权头解析。

出参 Result<InvoiceReissueRespVO>

字段	类型	说明
oldInvoiceId	Long	被作废的旧发票 ID
oldInvoiceStatus	String	旧发票状态（固定 VOIDED）
newInvoiceId	Long	新申请的发票 ID
newInvoiceStatus	String	新发票状态（固定 REQUESTED，待财务开票）
mqEventName	String	已发布 MQ 事件名（本批不发 MQ，恒为 null）
appliedAt	LocalDateTime	申请时间

请求示例

{
  "invoiceType": "VAT_NORMAL",
  "titleType": "COMPANY",
  "titleName": "上海呼籁旅行科技有限公司（新）",
  "taxNo": "91310115MA1K48XXXX",
  "email": "finance2@hulalv.com"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "oldInvoiceId": 77001234567001,
    "oldInvoiceStatus": "VOIDED",
    "newInvoiceId": 77001234567003,
    "newInvoiceStatus": "REQUESTED",
    "mqEventName": null,
    "appliedAt": "2026-05-10T14:30:25"
  },
  "success": true
}

空数据 / 降级响应

本接口无「空数据」概念（成功恒返回完整 InvoiceReissueRespVO）。降级路径：hl-mp-service 到 hl-order-service-v3 的 Feign 熔断打开时，MpV3InvoiceFeignFallbackFactory 返回 Result.error("发票服务不可用，请稍后重试")（code=500，此为既有降级行为，本次未改动）。

错误响应

{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }

code	触发条件
400	参数校验失败（titleName/email 等缺失或格式非法）
581500	旧发票不存在，或旧发票所属订单不属于当前用户（INVOICE_NOT_FOUND，IDOR 场景统一返此码，不额外区分"不存在"与"无权限"）
581501	旧发票状态不是 ISSUED/PUSHED，不可重开（INVOICE_NOT_VOIDABLE）
581513	发票类型非法（须 VAT_NORMAL/VAT_SPECIAL）
581516	收件邮箱为空
581523	增值税专用发票只能开给单位（titleType 须为 COMPANY）
581524	订单当前状态不可申请开票（INVOICE_ORDER_NOT_APPLICABLE）
100503（本次新增）	抢锁等待超过 3 秒（本组另一写口——issue 或 reupload——正持有 order-invoice:issue 锁），可重试

实测说明：IT 层链路与第 1 节一致；InvoiceIssueLockConcurrencyIT 的两条用例分别覆盖"未超时→排队成功"和"超时→100503"两个分支，落库结果同一订单下非 VOIDED 票恰好一行，无一单两票残留。🔴 但本接口未在测试服上单独抓包或调用——2026-09-20 测试服直接证据只覆盖 §1 issueInvoice；本接口（hl-order-service-v3 internal，经 hl-mp-service 两个透传入口对外）的锁互斥依据是代码改动本身（reissueInvoice 与 issueInvoice 使用逐字相同的 name="order-invoice:issue"/keys）以及 InvoiceIssueLockNameGuardTest，不是独立的测试服实测。

业务边界

• 🔴 C 端实际入口有两个，均在 hl-mp-service，网关路由未变：
  • POST /mp/v3/order/invoice/{invoiceId}/reissue（MpV3InvoiceController，hl-mp-service/.../mp/controller/v3/MpV3InvoiceController.java:54）：return invoiceFeignClient.reissueInvoice(invoiceId, req); 直接透传 Feign 返回的 Result，code=100503 与 message 原样保留，HTTP 200。
  • POST /mp/invoice/{invoiceId}/reissue（MpInvoiceController，hl-mp-service/.../mp/controller/MpInvoiceController.java:108）：调用 invoiceFeignClient.reissueInvoice(invoiceId, req).getCheckedData()，Result.getCheckedData()（Result.java:143-152）在 !isSuccess() 时 throw new BusinessException(this.code, this.message)，即抛出 BusinessException(100503, "资源被占用,请稍后重试")；该异常在 hl-mp-service 自己的 GlobalExceptionHandler.handleBusiness 里被捕获，同样标注 @ResponseStatus(HttpStatus.OK)，重新包装成 Result.error(100503, "资源被占用,请稍后重试")。两条路径最终都是 HTTP 200 + body.code=100503，只是中转方式不同（透传 vs 解包重抛），前端不用区分走的是哪一个入口，统一按 code=100503 处理即可。
• 抢锁失败（100503）时该次请求零写入：旧发票不会被置 VOIDED，不会插入新发票行——不存在"部分成功"的中间态。
• 无 @Idempotent 保护，仅 @Lock4j 串行化 + canReupload 状态守卫去重（杜绝两个并发 reissue 请求各读旧票 ISSUED 快照后各自 VOIDED 旧票并各插一条新票）。
• bankName/bankAccount/registAddress/registPhone 四个专票字段在 reissue 中继承旧发票，请求体不传；invoiceType/titleType/taxNo/email 未传时同样继承旧发票对应字段。
• 老数据兼容：无字段变化，不涉及旧数据兼容问题。

---

四、契约约束与正确调用方式（接口类必写）

本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。

✅ 正确 / ❌ 错误 客户端处理方式

本次不涉及请求体字段的互斥/联动规则变化，契约约束集中在"如何处理新失败码"：

场景	处理方式
✅ 收到 code=100503	提示"另一个开票相关操作正在进行，请稍后重试"，允许用户重试，不当系统错误上报、不静默吞掉
✅ 判断成功/失败	一律读响应体 code（===200 才算成功），不能只看 HTTP 状态码
❌ 只看 HTTP 状态码	100503 场景下 HTTP 仍是 200，只看状态码会把失败误判为成功，前端界面会"假装成功"但后端实际零写入
❌ 把 100503 当致命错误弹全屏报错	应视为可重试的低频并发退避，不要引导用户联系客服或上报崩溃监控

切换状态时的必要动作

本次改动不涉及"要么 A 要么 B"的字段互斥关系。唯一需要前端配合的动作是：同一张发票的「完成开票」「重新上传」「申请重开发票」三个操作现在会互相排队，如果产品设计上允许财务与用户在同一张发票上短时间内各自发起操作，两侧都需要能正确展示 100503 的重试提示，而不是分别按"我这边一定成功"设计交互。

---

五、数据库行为（涉及写操作时必写）

场景	order_invoice 表行为（改动前）	order_invoice 表行为（改动后）
reupload 持锁期间 reissue 并发进来	两者都能进入临界区：reissue 先把旧票置 VOIDED 并插入新票（REQUESTED），reupload 随后把（已作废的）旧票又写回 ISSUED ⇒ 同一订单出现两行非 VOIDED（旧 ISSUED + 新 REQUESTED），数据不一致	reissue 在 reupload 持锁期间抢锁失败，直接返回 100503，不执行任何 UPDATE/INSERT；reupload 完成释放锁后 reissue 才能进入临界区（或超过 3 秒被拒）
issue/reupload/reissue 各自的写操作本身	无变化：issue 写 status=ISSUED+issued_at+issued_by+amount；reupload 写文件相关字段；reissue 一次 UPDATE（旧票→VOIDED）+ 一次 INSERT（新票 REQUESTED）	无变化，只是三者现在对同一 invoiceId 串行化执行

无 SET NULL 相关行为：本次改动不涉及任何列的置空规则，三个方法各自写入的列集合与改动前完全一致。

---

六、边界行为

• 未登录 → 401（网关拦截）
• 发票不存在 / 无权限（IDOR） → 581500（INVOICE_NOT_FOUND，两种场景统一返此码，不额外泄露"存在但不属于你"）
• 下游 hl-order-service-v3 不可用（熔断打开）→ hl-mp-service 侧 MpV3InvoiceFeignFallbackFactory 返 code=500（既有行为，本次未改）
• 抢锁失败 → 100503，HTTP 仍 200，本次新增的唯一边界分支，零写入
• 老数据兼容 → 本次不涉及字段增删，存量发票记录无需迁移，行为在锁生效前后对"未并发"的单次请求完全一致

---

六.5、枚举 / 数据字典（接口出现枚举时必写）

发票状态（com.hulalv.invoice.enums.InvoiceStatus）

所属字段: oldInvoiceStatus/newInvoiceStatus（本节第 3 个接口出参）；决定 reupload/reissue 是否可执行的判据字段 | 类型: String

值	中文	说明
REQUESTED	待开票	已申请，等待财务开票；issue 只接受此状态
ISSUED	已开票	已上传文件，用户可查看/下载；reupload/reissue 只接受此状态或 PUSHED
PUSHED	已推送	已推送客户（本期不真发通知，仅落状态）；reupload/reissue 同样接受
VOIDED	已作废	终态，由 reissue 副作用产生；不可再 reupload/reissue

抬头类型（titleType，本节第 3 个接口入参）

所属字段: InvoiceReissueReqVO.titleType | 类型: String

值	中文	说明
PERSONAL	个人	抬头为个人姓名，taxNo 非必填
COMPANY	单位	抬头为公司名，taxNo 必填；invoiceType=VAT_SPECIAL 时只能是此值（否则 581523）

发票类型（invoiceType，本节第 3 个接口入参）

所属字段: InvoiceReissueReqVO.invoiceType | 类型: String

值	中文	说明
VAT_NORMAL	增值税普通发票	默认场景
VAT_SPECIAL	增值税专用发票	要求 titleType=COMPANY，且 taxNo/银行信息/注册信息在申请阶段已齐（reissue 继承旧票）

---

六.6、修改前后对比（修改/删除类接口必写，新增跳过）

字段级对比

字段	改前	改后
（无）	三个接口的请求体/响应体字段零变化	同左

行为级对比

行为	改前	改后
issue/reupload/reissue 三者的并发关系	各自持有一把不同的锁（name 缺省退化为类名+方法名），互不阻塞	三者共享同一把锁（name="order-invoice:issue"），对同一 invoiceId 串行化执行
reupload ∥ reissue 并发结果	可能在同一订单下留下两行非 VOIDED（旧 ISSUED + 新 REQUESTED），数据不一致	后到方抢锁失败直接拒绝（100503）或排队等待，落库结果始终只有一行非 VOIDED
新增的失败码	无	100503（RESOURCE_LOCKED），HTTP 200 + body.code=100503；路径真实存在（issueInvoice 测试服已实测确认锁键；另两处依赖代码同源+反射守卫用例覆盖），但测试服并发实测未触发 100503 本身，实际频率极低

---

六.7、影响评估（修改/删除类必写）

• 是否破坏向后兼容: 否——三个接口的请求体/响应体字段、既有错误码全部零增删，正常（无并发）场景下行为与改动前完全一致。
• 前端是否必须同步上线: 是——小程序 C 端与管理后台前端都需要能识别 code=100503 并提示"稍后重试"，否则用户会在极低概率下看到 HTTP 200 却操作失败、且没有任何提示的情况（当前前端逻辑若只判断 HTTP 状态码或只处理已知错误码列表，会把这次失败静默吞掉或误判成功）。
• 前端 workaround 清理点: 无——本次不涉及此前的前端兜底/反推逻辑。

---

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

• 仅影响: 管理后台「发票财务管理」的「完成开票」「重新上传」两个写操作 + 小程序 C 端「申请重开发票」（含其两个 hl-mp-service 入口）在并发场景下的失败分支
• 零影响:
  • 发票申请接口（adminApplyInvoice/mpApplyInvoice，两者的并发漏洞属于 #7980 P2，本工单未修，见 InvoiceAdminService.adminApplyInvoice 方法注释）
  • 发票详情、列表、下载、推送、企业信息自动回填等只读或非本组写接口
  • 三个接口自身的入参校验、状态机判定、金额计算等既有业务逻辑（未改动一行）
  • 单次请求（无并发命中）下的行为——三个接口改动前后表现完全一致
  • hl-gateway 路由配置——三个端点路径/方法零变化

---

八、测试环境已验证

部署

hl-order-service-v3 部署后 COMMIT = 5d14bc524（滚动重启两实例均 UP）。

⚠️ 如实说明：部署前它已经是 5d14bc524（BEHIND 0/N）——另一会话此前已把该 commit 推上测试服；本次是重新走了一遍部署流程，COMMIT 没有变化，不是本次部署使改动生效，本次部署只是重新确认了一遍。

祖先链判定（仓库目录 /opt/hulalv/HL，git fetch origin dev-v3 后）：git merge-base --is-ancestor 09b8f2323 5d14bc524 → YES（#7980 AC-4 的合并提交已在运行版本内）。

hl-gateway 一直是 4cbccc26b（BEHIND 70/Y），未动；发票端点走网关全部正常返回，本次取证不受影响。

🔴 直接证据（证据 A）——只覆盖三处写口中的一处

redis-cli MONITOR（db 0，连接参数取自 Nacos hl-order-service-v3-test.yml）实时抓包，调用 issueInvoice（invoice_id=2100889866400104450）时捕获：

EVALSHA ... "lock4j:order-invoice:issue#order-invoice:issue:2100889866400104450" ... "30000"
lua "set" 同键 ... "NX" "PX" "30000"
lua "get" / "del" 同键

键形与期望完全一致、没有方法名混入 ⇒ 证明补丁在运行的字节码里生效。

但这里必须收窄，不要读成"三处共用同一把锁"已被测试服实测确认：MONITOR 实际只跑了三个写口里的一个（issueInvoice）。正确表述是——测试服直接证据覆盖三处中的一处（issueInvoice）；另两处（reuploadInvoice/reissueInvoice）由代码改动本身与反射守卫用例 InvoiceIssueLockNameGuardTest（断言三处 name 非空且相等）覆盖，未在测试服上单独抓包。

100503 未复现（证据 B）

对另一张票并发发两个 issueInvoice，一个 code=200，另一个是 code=581502（INVOICE_CANNOT_ISSUE 业务状态守卫）——不是 100503。

如实说明：未打出锁超时码，原因仍是临界区极短（与 fleet 那轮 34 并发未触发同因）。第二个请求是被业务状态守卫拦下，说明没有产生并发脏写，但这是旁证，不是互斥证据——不能拿它证明锁真的挡住了并发，只能证明这次没有观察到数据损坏。

两面都要写：路径源码级真实存在（已读码确认 + InvoiceIssueLockConcurrencyIT 实测过等待约 3024ms 后抛出该码），但测试服未能触发，不代表更长事务/更大载荷/生产数据量下不会触发。

回归（证据 C）

单独调一次 issueInvoice，code=200，正常路径未被锁破坏。这是回归证据，不与互斥证据混同。

取证是干净的

三张发票全是测试夹具（客户名「核团甲/乙/丙」，apply_reason 写着 #7932 造数）。改前均 REQUESTED / NULL / NULL，改后 ISSUED + 金额 + 票号，已按改前快照逐列 UPDATE 还原（含 file_url/pdf_name/pdf_size/issued_at/issued_by/update_time），复读与改前完全一致；Redis 侧 --scan lock4j:*order-invoice* 复扫为空，无残留锁键。

⚠️ 过程中发生过一次 code=401（token 被别的会话顶掉），该次调用之前没有任何读数，已重新登录并把那一段整个重做，证据 A 用的是重登后的结果——这一条也计入取证可信度的一部分。

---

十、相关文档

• 关联 Issue: wx/HL#7980（AC-4）
• 关联 PR: wx/HL#8043

关联 / 联系人

链接

• Issue: #7980
• PR: #8043
• Merge commit: 09b8f2323

联系人

• 后端负责人: @wx