bbit/Ticket

Fork 0

Files

T

BBIT-Kai f7a27d99e1 优化后端框架

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

6.6 KiB

Raw Blame History

农产品收购发票开票平台待开发功能梳理

1. 梳理结论

结合当前前端、后端代码和原系统设计.md，目前项目已经完成的是“通用后台底座”，尚未进入“农产品收购发票开票业务闭环”开发阶段。

当前可以从后续范围中移除的内容，主要是：

平台账号登录、JWT 鉴权、当前用户信息获取
动态菜单、按钮权限、路由权限控制
用户、组织、角色、菜单、字典管理
操作日志、接口访问日志
基础工作台、后台布局、通用表格表单交互

因此，新文档不再把上述能力作为一期建设重点，后续应聚焦“业务系统对接 + 票通对接 + 开票状态闭环 + 业务页面”。

2. 当前已完成能力

2.1 后端已完成

认证基础：/api/auth/login、/api/auth/logout、/api/auth/me
权限体系：JWT、权限码校验、角色菜单绑定
系统管理接口：
- /api/system/users
- /api/system/orgs
- /api/system/roles
- /api/system/menus
- /api/system/dicts
日志查询接口：
- /api/logs/operation
- /api/logs/api-access
初始化能力：默认组织、管理员、菜单、字典种子数据

2.2 前端已完成

登录页、主布局、动态路由、页签导航
工作台首页
用户管理
组织管理
角色管理
菜单管理
字典管理
操作日志、接口日志

3. 当前未完成的核心业务能力

3.1 业务主线能力

以下是当前最需要补齐的一期闭环：

获取当前用户所属公司上下文
对接我方业务系统，查询待开票农产品收购数据
选择待开票数据并发起蓝字数电发票开具
对接票通认证流程，处理短信认证、扫码认证
查询开票结果并回写我方业务系统
接收票通回调，驱动本地状态更新
支持失败重试、处理中补偿查询、审计留痕

目前以上 7 项在现有前后端代码中都还没有真正落地。

3.2 后端待开发清单

3.2.1 我方业务系统对接

需要新增业务系统集成模块，至少包括：

登录后获取当前用户 companyId、公司名称、纳税人识别号
根据 companyId 查询待开票列表
开票前写库/锁单
开票结果回写
回写失败后的补偿重试

3.2.2 票通集成能力

需要新增票通专用模块，至少包括：

票通基础配置管理
3DES 加密、RSA 签名、验签、解密
invoiceBlue.pt 蓝字开票接口封装
getTaxBureauAccountAuthStatus.pt 认证状态查询
sendLoginSmsCode.pt 短信验证码发送
smsLogin.pt 短信登录
getAuthenticationQrcode.pt 实名认证二维码获取
queryAuthQrcodeScanStatus.pt 二维码扫码状态查询
queryInvoice.pt 发票结果主动查询
电子税局退出登录接口封装

3.2.3 开票任务与状态机

需要新增开票任务中心，而不是直接同步开票：

invoice_job、invoice_job_item、tax_account、audit_log 等业务表
invoiceReqSerialNo 幂等号生成与复用
本地状态流转：
- PENDING
- PROCESSING
- NEED_AUTH
- SUCCESS
- FAILED
- BIZ_SYNC_FAILED
认证后继续原任务，而不是重新生成任务
调用超时后转处理中，并通过主动查询补状态

3.2.4 对外业务接口

当前还缺少原设计中的业务接口：

GET /api/invoice-candidates
POST /api/invoice-jobs
GET /api/invoice-jobs/{jobId}
POST /api/invoice-jobs/{jobId}/retry
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/callbacks/piaotong/invoice

3.2.5 后台任务与可靠性

还需要补齐后台可靠性能力：

定时查询 PROCESSING 任务
回调去重与乱序保护
开票结果与业务回写失败补偿
关键字段脱敏存档
面向票通/业务系统的错误码映射

3.3 前端待开发清单

3.3.1 业务页面

当前前端没有任何开票业务页面，需要新增：

待开票列表页
开票确认弹窗
票通认证弹窗
开票结果页/任务详情页
票通账号配置页
开票日志或任务追踪页

3.3.2 页面交互能力

需要补齐以下交互：

按公司查看待开票数据
勾选待开票单据并显示金额汇总
发起开票前的参数确认
根据 operationProposed 展示不同认证方式
认证完成后继续原开票任务
展示开票状态、失败原因、票号、数电发票号码
支持手动刷新、重试、查看明细

3.3.3 菜单与品牌调整

当前前端仍偏“通用管理平台”，还需要调整为业务平台形态：

新增发票业务菜单，而不是只有系统管理菜单
工作台改为展示开票业务统计，而不是菜单/权限数量
登录页、工作台、导航标题统一到“农产品收购发票开票平台”业务语境

4. 建议保留的一期范围

结合现状，建议把一期范围压缩成“最小可用闭环”：

登录后拿到公司上下文
查询待开票列表
发起蓝字数电普票开具
票通认证：短信 + 扫码
开票状态查询
开票结果回写我方业务系统
票通回调接收
失败重试与日志留痕

5. 建议暂缓到二期的内容

以下内容建议暂不纳入当前主线：

冲红流程
红字确认单申请/审核
发票文件下载
二维码开票扩展能力
微信/支付宝卡包
企业注册入驻
更复杂的经营分析报表

6. 推荐实施顺序

第一阶段：打通后端主链路

建业务系统客户端
建票通客户端与加密签名能力
落业务表结构
完成开票任务、状态机、回调、主动查询

第二阶段：补前端业务页面

待开票列表
发起开票
认证弹窗
结果页与重试

第三阶段：做稳定性和运维补齐

补偿任务
日志审计
配置维护页
错误提示和异常兜底

7. 最终结论

当前项目“底座已具备，业务未开工”的特征非常明确。接下来不需要继续投入系统管理模块，而应集中资源完成以下三块：

我方业务系统对接
票通开票与认证对接
开票任务闭环与前端业务页面

只要这三块完成，项目才会从“通用后台”真正进入“农产品收购发票开票平台”的可用状态。

6.6 KiB Raw Blame History