bbit/Ticket

Fork 0

Files

T

BBIT-Kai f7a27d99e1 优化后端框架

2026-05-07 10:25:02 +08:00

11 KiB

Raw Permalink Blame History

通用票通开票模块设计书

1. 设计目标

结论：可以，而且我认为这是一个很适合当前阶段的做法。

在不先对接你现有业务系统待开票数据的前提下，可以先建设一个“通用票通开票模块”，目标是：

先把票通接口、加密签名、认证流程、开票状态流转跑通
先验证票通联调、测试账号、测试税号、回调、查询这些关键链路
先形成一个独立可用的开票能力层
后续再把你自己的待开票数据、锁单、回写逻辑接到这个能力层上

也就是说，第一阶段把系统拆成两层：

通用票通开票层
业务系统适配层

当前先只做第一层。

2. 为什么适合先这样做

先做通用票通模块有 5 个好处：

把最大不确定性先消化掉：票通联调、认证、回调、状态码
不被你现有业务系统接口进度卡住
可以先做出可演示、可测试、可验收的开票闭环
后续接你自己的平台时，改动集中在“数据映射”和“回写适配”
更适合 Codex 分阶段落地，每次任务可以更聚焦

这条路线本质上是先做：

票通能力产品

再做：

你自己业务平台的票通接入

3. 系统定位

这个模块在一期不关心“待开票数据来自哪里”，只关心：

用户手工录入或粘贴开票数据
系统把数据转换成票通标准报文
系统调用票通完成开票
系统处理认证、查询、回调、重试

所以它不是“农产品收购发票业务平台完整体”，而是一个：

通用票通开票控制台

它先支持：

企业和数电账号准备
手工发起蓝字开票
查看开票任务
处理短信/扫码认证
查看开票结果

后续再扩展：

对接你自己的待开票业务单据
自动锁单
自动结果回写

4. 一期范围

一期只做“纯票通能力闭环”，不做以下内容：

不对接你现有业务系统待开票列表
不做你自己的业务锁单/预写库
不做你自己的业务结果回写
不做复杂经营报表
不做红冲

一期只保留这些能力：

企业信息查询
数电账号维护/查询
认证状态查询
短信认证
扫码认证
手工录入开票信息
发起蓝字开票
查询开票状态
接收票通推送
查看开票任务与结果

5. 核心业务流程

5.1 初始化准备

录入或查询开票企业税号
查询企业是否已在票通开通
查询企业下可用数电账号
选择一个开票账号
查询该账号当前认证状态

5.2 手工开票

用户在页面上录入开票信息
系统校验必填字段
系统生成 invoiceReqSerialNo
系统调用 invoiceBlue.pt
记录本地开票任务
返回初始结果

5.3 认证处理

如果票通返回需要认证：

查询认证建议
根据返回结果进入短信认证或扫码认证
认证完成后继续原开票任务
复用原 invoiceReqSerialNo

5.4 结果同步

结果同步同时走两条线：

票通推送
主动查询

处理原则：

推送优先
查询补偿
状态幂等更新

6. 功能模块设计

建议先做 4 个模块。

6.1 企业与账号模块

作用：

查询票通企业信息
查询企业开户行及账号信息
查询数电账号列表
维护本地默认开票账号

建议菜单：

票通企业
数电账号

6.2 认证中心模块

作用：

查询账号认证状态
发送短信验证码
提交短信登录
获取实名认证二维码
查询二维码扫码状态
执行退出电子税局登录

建议菜单：

认证中心

6.3 通用开票模块

作用：

手工录入发票信息
支持普通蓝字数电票
支持农产品收购发票
生成标准开票任务
发起票通开票

建议菜单：

手工开票

6.4 开票任务模块

作用：

查看任务状态
查看票通返回信息
查看发票号码、数电发票号码
查看失败原因
手动查询状态
重试失败任务

建议菜单：

开票任务

7. 页面设计

建议新增 5 个页面。

7.1 票通企业页

展示内容：

企业税号
企业名称
审核状态
开通票种
服务状态

操作：

查询企业信息
查询开户行及账号信息

7.2 数电账号页

展示内容：

数电账号
姓名
身份类型
认证状态
登录状态
风险认证状态
是否绑定公众号

操作：

查询账号列表
登记账号
设为默认账号

7.3 认证中心页

展示内容：

当前认证建议
当前认证状态
短信验证码状态
二维码状态

操作：

查询认证状态
发送短信验证码
提交短信登录
获取扫码二维码
轮询扫码状态
退出登录

7.4 手工开票页

展示内容：

基本信息表单
购买方信息
销方信息
开票项目明细
农产品收购发票专用字段

操作：

保存草稿
发起开票
清空表单

7.5 开票任务页

展示内容：

发票请求流水号
企业税号
数电账号
发票种类
状态
失败原因
发票号码
数电发票号码
开票时间

操作：

查看详情
查询最新状态
重新发起查询
失败后重试

8. 后端设计

8.1 目录建议

server/src/main/kotlin/com/bbit/platform/
  database/piaotong/
    PtInvoiceJobTable.kt
    PtInvoiceJobItemTable.kt
    PtTaxAccountTable.kt
    PtCallbackLogTable.kt

  integration/piaotong/
    PiaotongClient.kt
    PiaotongCrypto.kt
    PiaotongDtos.kt
    PiaotongMapper.kt

  modules/piaotong/company/
    PtCompanyModule.kt

  modules/piaotong/account/
    PtAccountModule.kt

  modules/piaotong/auth/
    PtAuthModule.kt

  modules/piaotong/invoice/
    PtInvoiceModule.kt

  modules/piaotong/task/
    PtTaskModule.kt

  modules/piaotong/callback/
    PtCallbackModule.kt

8.2 后端接口建议

企业与账号

GET /api/piaotong/company/{taxpayerNum}
GET /api/piaotong/company/{taxpayerNum}/bank-info
GET /api/piaotong/accounts
POST /api/piaotong/accounts/register
PUT /api/piaotong/accounts/{id}/default

认证

GET /api/piaotong/accounts/{account}/auth-status
POST /api/piaotong/accounts/{account}/sms-code
POST /api/piaotong/accounts/{account}/sms-login
POST /api/piaotong/accounts/{account}/auth-qrcode
GET /api/piaotong/accounts/{account}/auth-qrcode/{authId}
POST /api/piaotong/accounts/{account}/logout

开票

POST /api/piaotong/invoices
POST /api/piaotong/invoices/validate
GET /api/piaotong/invoices/{jobId}
POST /api/piaotong/invoices/{jobId}/query
POST /api/piaotong/invoices/{jobId}/retry

推送

POST /api/callbacks/piaotong/invoice-summary
POST /api/callbacks/piaotong/invoice-detail

9. 前端设计

9.1 目录建议

web/src/
  api/piaotong/
    company.ts
    account.ts
    auth.ts
    invoice.ts
    task.ts

  types/piaotong/
    company.ts
    account.ts
    auth.ts
    invoice.ts
    task.ts

  features/piaotong/
    company/index.vue
    accounts/index.vue
    auth-center/index.vue
    invoice-create/index.vue
    tasks/index.vue

  components/piaotong/
    InvoiceItemEditor.vue
    InvoicePreviewCard.vue
    AuthQrcodePanel.vue
    InvoiceStatusTag.vue

9.2 菜单建议

新增一级菜单：

票通开票

二级菜单建议：

票通企业
数电账号
认证中心
手工开票
开票任务

10. 数据库设计

10.1 pt_tax_account

保存：

企业税号
数电账号
姓名
身份类型
默认账号标记
最近认证状态
最近登录状态
最近风险认证状态

10.2 pt_invoice_job

保存：

任务 ID
企业税号
数电账号
发票请求流水号
发票类型
特殊票种
状态
票通状态码
状态描述
发票号码
数电发票号码
开票日期
金额
税额
原始请求
原始响应

10.3 pt_invoice_job_item

保存：

所属任务
商品名称
税编
数量
单价
金额
税率
税额

10.4 pt_callback_log

保存：

回调类型
回调时间
回调报文
验签结果
处理结果

11. 状态设计

建议本地状态统一为：

DRAFT
PENDING
PROCESSING
NEED_AUTH
SUCCESS
FAILED

票通状态映射建议：

0000 -> SUCCESS
6666 -> PENDING 或 PROCESSING
7777 -> PROCESSING
3999 -> NEED_AUTH
9999 -> FAILED

12. 关键接口映射

一期建议优先实现以下票通接口：

2.45 查询数电账号列表
2.8 查询数电账号认证状态
2.9 开具蓝字数电发票
2.11 查询发票主要信息
2.13 推送发票主要信息
2.4 获取登录短信验证码
2.5 短信登录
2.6 获取实名认证二维码
2.7 查询实名认证二维码扫码状态
2.47 查询企业信息
2.49 查询企业开户行及账号

可选补充：

2.3 数电账号登记
2.12 查询发票全票面信息
2.14 推送发票全票面信息
2.46 退出电子税局登录

13. 农产品收购发票特别说明

虽然这是“通用票通开票模块”，但你这个项目核心还是农产品收购发票，所以一期最好直接支持它。

需要特别处理：

specialInvoiceKind=02
只能开数电普通票
purchaseInvSellerIdType 必填
buyerTaxpayerNum 必填
购销双方字段语义与普通发票不同

建议做法：

表单层支持“普通票模式”和“农产品收购模式”切换
由后端统一做字段映射和报文转换

14. 与后续业务系统对接的衔接方式

后续如果接你自己的待开票平台，不推翻这套设计，只是增加一层适配。

后续新增的只会是：

待开票列表读取
业务单据锁定
开票任务自动创建
结果回写业务系统

也就是说，后续结构会变成：

你的业务平台 -> 通用票通开票模块 -> 票通

而不是重新写一套票通集成。

15. 推荐实施顺序

建议按下面顺序推进：

第一阶段

建票通企业页
建数电账号页
打通企业查询、账号查询、认证状态查询

第二阶段

建认证中心
打通短信认证、扫码认证

第三阶段

建手工开票页
打通蓝字开票
建开票任务页

第四阶段

接票通推送
做主动查询补偿
做重试

16. 最终结论

可以先不接你自己的待开票数据，先单独构建一个“通用票通开票模块”，而且这条路线很合理。

我建议把它当成：

票通能力底座

先完成这个底座，再把你的业务系统往上挂。这样后续不管接待开票列表、锁单、回写，都会顺很多，也更适合 Codex 分阶段持续推进。

11 KiB Raw Permalink Blame History

通用票通开票模块设计书

1. 设计目标

2. 为什么适合先这样做

3. 系统定位

4. 一期范围

5. 核心业务流程

5.1 初始化准备

5.2 手工开票

5.3 认证处理

5.4 结果同步

6. 功能模块设计

6.1 企业与账号模块

6.2 认证中心模块

6.3 通用开票模块

6.4 开票任务模块

7. 页面设计

7.1 票通企业页

7.2 数电账号页

7.3 认证中心页

7.4 手工开票页

7.5 开票任务页

8. 后端设计

8.1 目录建议

8.2 后端接口建议

企业与账号

认证

开票

推送

9. 前端设计

9.1 目录建议

9.2 菜单建议

10. 数据库设计

10.1 pt_tax_account

10.2 pt_invoice_job

10.3 pt_invoice_job_item

10.4 pt_callback_log

11. 状态设计

12. 关键接口映射

13. 农产品收购发票特别说明

14. 与后续业务系统对接的衔接方式

15. 推荐实施顺序

第一阶段

第二阶段

第三阶段

第四阶段

16. 最终结论

11 KiB

Raw Permalink Blame History