fujian_water_biz_doc/specs/002-rev005-invoice-flow/research.md

Phase 0 Research: REV-005 发票业务流实现

Decision 1: 一期入口采用“后台开票 + 客户侧查询下载推送”

• Decision: 一期由后台营业收费员/财务人员发起发票申请与开具；客户侧仅支持查看、下载、推送已开具的电子发票，不直接发起开票申请。
• Rationale: 营收系统_用户操作手册.md 明确存在后台【发票管理】-【发票开具】与【发票查询】入口，同时微网厅操作手册更偏向电子发票查看/推送能力；该分层最贴近老系统且风险最低。
• Alternatives considered:
  • 后台与客户侧都直接发起开票申请：会显著扩大一期鉴权、重复申请与渠道联动范围。
  • 仅后台开票、客户侧不提供结果消费：与老系统电子发票查看/下载口径不符。

Decision 2: SYS-008 采用“异步申请 + 查询兜底”协同模式

• Decision: 提交开票申请后先返回受理号/申请单号，系统通过定时或主动查询接口获取最终开票结果，不假设发票服务一定通过回调返回。
• Rationale: 航信类发票平台常见能力是异步受理 + 查询结果；spec clarifications 已明确该模式，且旧数据字典中也存在 last_try_time、next_try_time、try_count 等查询补偿字段痕迹。
• Alternatives considered:
  • 仅依赖回调：与当前外部接口现实不符，容易导致状态悬挂。
  • 纯同步开票：不适配电子发票平台与批量开票场景。

Decision 3: 一期不支持原始单账单直接任意部分开票

• Decision: 若需要多张发票，沿用老系统拆账/分账后的账单分别开票；后台可保留单笔或批量选择已收费账单发起开票，但不开放对原始单账单直接输入部分金额开票。
• Rationale: 老系统操作手册说明“多张发票”更多依赖分账/拆账结果，数据字典虽然存在映射表和金额字段，但未把“自由部分开票”表达为一期主流程能力；该约束能降低状态和金额校验复杂度。
• Alternatives considered:
  • 直接支持任意部分金额开票：需额外引入余额、累计开票金额、明细拆分与冲突控制。
  • 完全不考虑多票场景：会偏离老系统业务口径。

Decision 4: 在线主模型复用 biz_invoice / biz_cust_invoice / biz_invoice_taxrate

• Decision: 当前在线主模型以 biz_invoice、biz_cust_invoice、biz_invoice_taxrate 为主承接发票申请、客户开票资料与税率配置；旧“营业账开票表”“发票明细表”“开票配置表快照”等细粒度对象按历史只读关系快照或辅助映射处理。
• Rationale: 01_Database_Design.md 与 BACKEND_TABLE_MAPPING.md 已明确当前在线主承接对象，且 backend 现状确实已有发票主表和配置服务；机械复制旧表族会与当前主文档冲突。
• Alternatives considered:
  • 全量恢复旧 IV_* 表族：超出当前主文档与现状。
  • 只保留 biz_invoice 不表达关联快照：无法满足老系统查询与审计定位需求。

Decision 5: backend 现状仅覆盖开票配置 CRUD，REV-005 需扩展业务闭环

• Decision: 后续 implement 阶段在现有 InvoiceController.java、InvoiceServiceImpl.java 基础上扩展业务接口与服务，不另起平行模块。
• Rationale: 当前 Controller/Service 仅包含 /business/invoice/create|update|delete|get|page|list 等配置 CRUD 与模板枚举查询，尚未实现账单校验、申请单生成、SYS-008 协同、查询补偿与结果回写。
• Alternatives considered:
  • 直接新增独立发票业务模块：会造成配置与业务双轨并行。
  • 在当前基础上只补接口文档不改后端：无法支撑后续 implement。

Decision 6: 正式文档需同时对齐当前主文档与老系统操作手册

• Decision: 12_REV_Detailed.md、03_Interface_Design.md、01_Database_Design.md 后续修订时，除对齐主文档既有口径外，还需显式吸收老系统操作手册中的“发票查询、下载、打印、批量开票、电子发票查看/推送”等稳定能力。
• Rationale: 仅依据当前主文档容易把 REV-005 收窄成“申请 + 回写”，而老系统实际交付口径已经包含后台开票、客户侧查看下载与批量处理。
• Alternatives considered:
  • 只看主文档：会遗漏老系统既有稳定业务能力。
  • 只看操作手册：会偏离当前主文档和在线模型口径。

Decision 7: plan 阶段校验以文档门禁为主，backend 只做现状核对

• Decision: 当前 plan 阶段的最小校验仍以 make validate-file、make check-links、make validate-mermaid 为主，backend 只需核实现有 Controller/Service 的能力边界，不引入构建或测试作为当前阶段门禁。
• Rationale: 本阶段交付物仍是 planning 设计产物；代码实现验证应在 /speckit.implement 阶段展开。
• Alternatives considered:
  • 现在就引入 backend 构建/测试：会打断 planning 输出节奏。
  • 完全忽略 backend 现状：会导致后续任务拆解失真。