charge-java/huapiaoer-sdk/MIGRATION.md

区块链发票 → 航信电子发票 迁移文档

一、背景

深圳税局已停止微信区块链电子发票接口服务（即系统原有的 new-tax-control-fapiao 业务），现有发票功能将全部切换至航信（票慧通）乐企版 v5.1 电子发票平台。

替换范围：所有发票开具、查询、下载、状态跟踪功能。

不受影响：微信支付、退款、订单管理、充电业务等。

---

二、新旧流程对比

2.1 开票流程

旧流程（微信区块链发票）：
  用户选订单 → 获取微信抬头填写URL → 用户在微信小程序填抬头
  → 微信回调通知 → 管理员审核开票 → 微信开具 → 微信回调 → 下载

新流程（航信电子发票）：
  用户选订单 + 填写抬头信息 → 管理员审核 → 航信开具
  → 系统轮询结果 → 自动发邮件 / 下载

2.2 关键差异

事项	旧（微信）	新（航信）
抬头收集	用户跳转微信小程序填写 → 异步回调	用户申请时在 App 内直接填写
开票触发	调用微信 fapiao-applications API	调用航信 openBlueInvoice API
结果获取	微信主动回调 /invoice/notify	系统每 5 分钟轮询航信查询
发票文件	微信临时链接（30 秒有效）	永久 PDF / OFD / XML 链接
邮件发送	不支持	开票成功后自动发送到用户邮箱
发票红冲	微信 API	航信 openRedInvoice API

2.3 API 端点变化

端点	状态	说明
POST /invoice/applyInvoice	变更	返回值从 TitleUrl 改为 Invoice 对象
POST /invoice/notify	移除	航信为轮询模式，不再需要回调
POST /invoice/titleWriteNotice	移除	抬头信息在申请时直接提交
GET /invoice/downloadInvoice/{id}	保留	改为返回航信 PDF/OFD/XML URL
GET /invoice/list	不变	用户发票列表
GET /finance/handleInvoice/{id}	变更	后端改为调用航信开票
GET /finance/downloadInvoice/{id}	变更	改为返回航信下载链接
GET /finance/getUserTitle/{applyId}	移除	航信无此概念
GET /finance/getInvoice/{applyId}	变更	改为查询本地 InvoiceDetail 表
GET /finance/listInvoice	不变	管理端发票列表
GET /finance/export/invoiceList	不变	发票导出
GET /finance/confirmManualInvoice/{id}	不变	手动确认开票

---

三、配置说明

3.1 新增配置

在 application.yml 中添加（admin 和 miniapp 模块均需配置）：

huapiaoer:
  app-secret: 票慧通提供的appsecret
  nsrsbh: 开票方税号（商家税号）
  b2cshopid: 商家税号（同 nsrsbh）

3.2 保留的旧配置

wechat.fapiao.* 配置暂保留但不再使用，后续可清理。

---

四、数据库变更

执行 database/7.sql：

-- 发票详情增加下载链接字段
ALTER TABLE charge_admin.t_invoice_detail
  ADD COLUMN IF NOT EXISTS invoice_url VARCHAR(512) COMMENT '发票PDF下载地址',
  ADD COLUMN IF NOT EXISTS ofd_url VARCHAR(512) COMMENT '发票OFD下载地址',
  ADD COLUMN IF NOT EXISTS xml_url VARCHAR(512) COMMENT '发票XML下载地址';

-- 发票抬头管理：增加默认抬头字段
ALTER TABLE charge_app.t_invoice_title
  ADD COLUMN IF NOT EXISTS is_default TINYINT(1) DEFAULT 0 COMMENT '是否默认抬头';

• t_invoice 表结构不变，数据兼容
• 历史发票记录的 t_invoice_detail 数据不受影响

---

五、文件变更清单

5.1 新增文件

文件	说明
common/.../config/HuapiaoerProperties.java	航信配置属性类
service/.../miniapp/HuapiaoerInvoiceService.java	航信开票业务封装

5.2 修改文件

文件	变更摘要
service/pom.xml	新增 huapiaoer-sdk:5.1.0 依赖
admin/.../application-dev.yml	新增 huapiaoer 配置块
admin/.../application-prod.yml	新增 huapiaoer 配置块
miniapp/.../application-dev.yml	新增 huapiaoer 配置块
miniapp/.../application-prod.yml	新增 huapiaoer 配置块
entity/.../InvoiceDetail.java	新增 invoiceUrl/ofdUrl/xmlUrl 字段
service/.../InvoiceService.java	applyInvoice() 返回值改为 Invoice
service/.../InvoiceServiceImpl.java	申请时直接保存抬头信息
service/.../InvoiceDetailService.java	移除微信 updateInvoiceDetail 方法
service/.../InvoiceDetailServiceImpl.java	移除微信发票详情更新逻辑
service/.../WxPayService.java	移除全部 10 个发票方法声明
service/.../WxPayServiceImpl.java	移除全部发票实现及依赖注入
miniapp/.../InvoiceController.java	简化接口，移除回调端点
admin/.../FinanceController.java	改为调用航信服务
admin/.../InvoiceStatusJob.java	轮询航信替代微信，频率 5 分钟
miniapp/.../SaTokenConfigure.java	移除 /invoice/notify 等免认证路径

---

六、部署步骤

6.1 部署前准备

1. 向票慧通申请 appSecret、确认商家税号（nsrsbh / b2cshopid）

2. 执行数据库 DDL：

   ALTER TABLE charge_admin.t_invoice_detail
    ADD COLUMN invoice_url VARCHAR(512) COMMENT '发票PDF下载地址',
    ADD COLUMN ofd_url VARCHAR(512) COMMENT '发票OFD下载地址',
    ADD COLUMN xml_url VARCHAR(512) COMMENT '发票XML下载地址';
   

6.2 配置文件

1. 在 4 个 application-*.yml 中填写 huapiaoer.app-secret、huapiaoer.nsrsbh、huapiaoer.b2cshopid
2. 生产环境使用真实的航信正式环境 https://erp.huapiaoer.com（默认值，无需额外配置）

6.3 构建与发布

# 1. 安装 huapiaoer-sdk 到本地
mvn install -pl huapiaoer-sdk -DskipTests

# 2. 编译全部模块
mvn compile -pl huapiaoer-sdk,entity,common,service,admin,miniapp

# 3. 打包部署
mvn package -DskipTests

6.4 部署后验证

1. 用户申请开票：在 App 中选择订单申请开票，确认可以直接提交抬头信息
2. 管理端开票：在后台审核并点击"开具发票"，确认调用航信成功
3. 状态轮询：等待 5 分钟（或手动触发定时任务），确认发票状态更新为"已开票"
4. 下载发票：确认可以获取 PDF/OFD/XML 下载链接
5. 邮件发送：确认填写了邮箱的发票自动发送邮件

---

七、回滚方案

如需回退到旧系统（如微信接口恢复）：

1. 恢复部署旧版本代码
2. 数据库无需回滚（新字段不影响旧逻辑）

---

八、发票抬头管理（新增功能）

替换微信的抬头管理能力，改为充电桩系统自行管理。

API 端点

端点	方法	说明
GET /invoice/title/list	GET	当前用户的抬头列表（默认抬头排前）
GET /invoice/title/{id}	GET	查看单个抬头详情
POST /invoice/title	POST	新增抬头
PUT /invoice/title/{id}	PUT	修改抬头
DELETE /invoice/title/{id}	DELETE	删除抬头
PUT /invoice/title/{id}/default	PUT	设为默认抬头

自动化

• 用户申请开票时，填写的抬头信息自动保存到抬头表（去重）
• 用户下次申请开票时可直接从保存的抬头中选择

---

九、定时任务

任务	旧频率	新频率	说明
InvoiceStatusJob	每天 18:00	每 5 分钟	轮询航信查询开票结果，更新状态并自动发送邮件

---

九、异常处理

1. 航信 API 返回失败（code != "200"）：抛出 HuapiaoerException，前端提示错误信息
2. 网络异常：抛出 HuapiaoerException（code=500），定时任务会在下一轮重新处理
3. 定时任务轮询失败：记录错误日志，下一轮（5 分钟后）继续重试，直到成功
4. 邮件发送失败：仅记录日志，不影响开票结果