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

## 1. 梳理结论

结合当前前端、后端代码和原 [系统设计.md](C:\Users\BBIT\Desktop\农产品收购发票开票平台\系统设计.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 业务主线能力

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

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

目前以上 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. 建议保留的一期范围

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

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

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

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

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

## 6. 推荐实施顺序

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

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

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

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

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

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

## 7. 最终结论

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

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

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