初始化项目

2026-04-30 10:47:26 +08:00
commit c932419c73
147 changed files with 45298 additions and 0 deletions
@@ -0,0 +1,219 @@
+# 农产品收购发票开票平台待开发功能梳理
+
+## 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. 最终结论
+
+当前项目“底座已具备，业务未开工”的特征非常明确。接下来不需要继续投入系统管理模块，而应集中资源完成以下三块：
+
+- 我方业务系统对接
+- 票通开票与认证对接
+- 开票任务闭环与前端业务页面
+
+只要这三块完成，项目才会从“通用后台”真正进入“农产品收购发票开票平台”的可用状态。