优化后端框架

2026-05-07 10:25:02 +08:00
parent c932419c73
commit f7a27d99e1
73 changed files with 1742 additions and 1596 deletions
@@ -0,0 +1,328 @@
+# Codex 三期工程执行文档
+
+适用范围：基于当前已经完成的通用后台底座，继续建设“农产品收购发票开票平台”业务闭环。  
+使用方式：建议你后续给 Codex 下任务时，一次只下发一个“任务包”，不要跨太多模块，这样实现时间更短、回归范围更可控。
+
+## 1. 业务功能规划
+
+### 1.1 新增业务菜单
+
+当前系统管理、日志管理等菜单已经具备，后续只新增业务菜单，不重复建设已有后台功能。
+
+建议新增一级菜单：
+
+- `发票业务`
+
+建议在 `发票业务` 下新增 4 个菜单：
+
+- `待开票列表`
+  - 用于查看业务系统返回的待开票数据、筛选、勾选、发起开票
+- `开票任务`
+  - 用于查看开票状态、失败原因、票号信息、重试操作
+- `认证中心`
+  - 用于处理票通认证状态、短信认证、扫码认证
+- `票通账号配置`
+  - 用于维护公司与票通账号、默认开票参数、基础映射关系
+
+说明：
+
+- `开票结果` 不建议单独再做一个菜单，直接并入 `开票任务`
+- `票通回调`、`主动查询补偿`、`业务系统回写` 不需要前端菜单，做后端能力即可
+
+### 1.2 建议目录规划
+
+为了适配当前项目结构，建议继续沿用现有 `modules` / `features` 风格，不要一开始就做大规模重构。
+
+后端建议新增目录：
+
+```text
+server/src/main/kotlin/com/bbit/platform/
+  database/invoice/
+    InvoiceJobTable.kt
+    InvoiceJobItemTable.kt
+    TaxAccountTable.kt
+    InvoiceSyncLogTable.kt
+
+  integration/biz/
+    BizSystemClient.kt
+    BizInvoiceDtos.kt
+
+  integration/piaotong/
+    PiaotongClient.kt
+    PiaotongCrypto.kt
+    PiaotongDtos.kt
+
+  modules/invoice/candidate/
+    InvoiceCandidateModule.kt
+
+  modules/invoice/job/
+    InvoiceJobModule.kt
+
+  modules/invoice/auth/
+    InvoiceAuthModule.kt
+
+  modules/invoice/settings/
+    TaxAccountModule.kt
+
+  modules/invoice/callback/
+    PiaotongCallbackModule.kt
+
+  modules/invoice/shared/
+    InvoiceStatus.kt
+    InvoiceServices.kt
+```
+
+前端建议新增目录：
+
+```text
+web/src/
+  api/invoice/
+    candidates.ts
+    jobs.ts
+    auth.ts
+    settings.ts
+
+  types/invoice/
+    candidate.ts
+    job.ts
+    auth.ts
+    settings.ts
+
+  features/invoice/
+    candidates/index.vue
+    jobs/index.vue
+    auth-center/index.vue
+    settings/index.vue
+
+  components/invoice/
+    InvoiceConfirmDialog.vue
+    InvoiceAuthDialog.vue
+    InvoiceJobStatusTag.vue
+```
+
+### 1.3 模块职责划分
+
+建议后续只围绕 4 个业务模块推进：
+
+- `待开票模块`
+  - 对接业务系统待开票列表
+  - 支持筛选、勾选、金额汇总、发起开票
+- `开票任务模块`
+  - 负责本地任务记录、状态流转、重试、详情查询
+- `认证模块`
+  - 负责认证状态查询、短信认证、扫码认证、认证后继续开票
+- `账号配置模块`
+  - 负责公司与票通账号、默认参数、启停状态维护
+
+Codex 执行建议：
+
+- 不要把“票通对接、业务系统对接、前端页面、状态补偿”揉成一个任务
+- 最适合的粒度是“一个模块的一条主链路”
+- 每次任务尽量能做到“改完即可本地验证一个页面或一个接口”
+
+## 2. 需要准备的内容
+
+这一章只写你这边需要准备的内容。票通接口文档已经在项目 `doc/` 目录里，后续不需要你再重复整理一遍。
+
+### 2.1 你自己的业务系统接口资料
+
+这是最关键的一部分，建议你提前准备并确认下面这些接口或数据来源：
+
+- `当前登录人/公司上下文接口`
+  - 至少要能拿到 `userId`、`companyId`、公司名称、销方税号
+- `待开票列表接口`
+  - 至少要能返回待开票主数据、金额、税率、商品信息、购销双方信息、唯一业务单号
+- `开票前写库/锁单接口`
+  - 发起开票前锁定业务数据，避免重复开票
+- `开票结果回写接口`
+  - 回写成功/失败状态、发票号码、数电发票号码、失败原因、票通流水号
+- `可选：解锁或撤销接口`
+  - 如果开票失败后需要解除业务锁定，最好也提前明确
+
+每个接口至少准备 5 类信息：
+
+- 请求地址和调用方式
+- 鉴权方式
+- 请求参数说明
+- 返回字段说明
+- 一份真实示例报文
+
+### 2.2 业务规则说明
+
+Codex 能写代码，但业务规则如果不明确，后面很容易返工。建议你提前确认这些规则：
+
+- 一条待开票数据是否对应一张发票，还是允许合并开票
+- 发票商品行从哪里来，是业务系统直接给，还是平台侧组装
+- 税率、税收分类编码、商品名称是否有默认规则
+- 哪些字段缺失时不能发起开票
+- 开票失败后，业务系统状态如何处理
+- 同一业务单据的重复开票判断依据是什么
+- 一个公司是否可能配置多个票通账号
+
+### 2.3 联调和测试资源
+
+建议你至少准备一套可联调的数据环境：
+
+- 业务系统测试地址
+- 可用的测试公司
+- 至少 1 个可用测试账号
+- 3 组待开票测试数据
+  - 正常成功
+  - 需要认证
+  - 明确失败
+
+最好再补两类样例：
+
+- 一份真实的待开票列表返回数据
+- 一份真实的开票结果回写样例
+
+### 2.4 环境和配置准备
+
+建议你提前准备好下面这些配置：
+
+- 后端数据库连接信息
+- Redis 连接信息
+- 前端、后端联调地址
+- 业务系统的接口鉴权配置
+- 票通测试账号、密钥、平台编码
+- 能接收回调的测试域名或内网穿透地址
+
+说明：
+
+- 票通接口定义已经在 `doc/` 中，重点是确认账号和环境真实可用
+- 如果业务系统接口还没稳定，建议先给一版 mock 或示例 JSON，Codex 可以先按样例落代码
+
+## 3. 具体的三期工程执行内容
+
+### 总体执行原则
+
+三期都建议按“任务包”推进。每个任务包尽量满足下面三个条件：
+
+- 改动范围集中，不跨太多目录
+- 能在一次对话里做完并验证
+- 做完后能形成明确可见结果
+
+建议你后续给 Codex 下指令时，也按下面的任务包来发，不要一次塞完整三期。
+
+### 第一期：业务骨架和数据接入
+
+目标：先把“业务菜单、业务数据接入、基础配置、任务落库”搭起来，不急着一次打通所有票通细节。
+
+一期任务包建议：
+
+1. `新增业务菜单和前端页面骨架`
+   - 新增发票业务菜单
+   - 新建 4 个业务页面空壳
+   - 接通路由和权限码
+
+2. `新增业务表和后端模块骨架`
+   - 新增开票任务、任务明细、票通账号等表
+   - 新增 invoice 相关后端模块目录和路由注册
+
+3. `接入公司上下文和待开票列表`
+   - 打通当前用户所属公司信息
+   - 对接业务系统待开票列表接口
+   - 前端完成待开票列表查询展示
+
+4. `完成票通账号配置页`
+   - 后端完成账号配置增删改查
+   - 前端完成配置页面
+
+5. `完成本地开票任务创建骨架`
+   - 支持勾选数据创建本地任务
+   - 先把锁单、落库、状态初始化串起来
+
+一期验收结果：
+
+- 能看到新菜单
+- 能查到待开票数据
+- 能保存票通账号配置
+- 能创建本地开票任务
+
+### 第二期：开票主流程和认证流程
+
+目标：把“发起开票 -> 遇到认证 -> 完成认证 -> 继续开票”这条主链路打通。
+
+二期任务包建议：
+
+1. `接入票通开票主接口`
+   - 完成票通报文组装、加密、签名
+   - 打通蓝字开票主调用
+
+2. `补齐开票状态机和幂等控制`
+   - 固化 `invoiceReqSerialNo`
+   - 完成 `PENDING / PROCESSING / NEED_AUTH / SUCCESS / FAILED` 状态流转
+
+3. `完成认证中心后端接口`
+   - 查询认证状态
+   - 短信验证码
+   - 短信登录
+   - 扫码二维码和扫码状态查询
+
+4. `完成前端开票确认和认证交互`
+   - 开票确认弹窗
+   - 短信认证弹窗
+   - 扫码认证弹窗
+   - 认证完成后继续原任务
+
+5. `完成开票任务列表和详情页`
+   - 展示任务状态、失败原因、票号信息
+   - 支持查看任务明细
+
+二期验收结果：
+
+- 能从待开票列表发起真实开票
+- 遇到认证时可以完成短信或扫码认证
+- 认证后可以继续原任务
+- 能看到任务状态和开票结果
+
+### 第三期：回调、补偿、稳定性收口
+
+目标：把“结果同步、失败补偿、重试、运维可见性”补齐，让系统进入可持续使用状态。
+
+三期任务包建议：
+
+1. `完成票通回调接收`
+   - 新增回调接口
+   - 完成验签、去重、状态更新
+
+2. `完成主动查询补偿`
+   - 定时查询处理中任务
+   - 补齐回调未达或超时场景
+
+3. `完成业务系统结果回写和补偿`
+   - 开票成功/失败回写业务系统
+   - 回写失败时记录补偿状态并支持重试
+
+4. `完成任务重试和异常处理`
+   - 支持失败任务重试
+   - 保证原幂等号复用
+   - 明确错误提示和异常留痕
+
+5. `完成页面收口和交付文档`
+   - 页面细节优化
+   - 状态文案统一
+   - 补一份联调说明和部署说明
+
+三期验收结果：
+
+- 开票结果可以通过回调或主动查询最终落定
+- 结果能稳定回写业务系统
+- 失败任务可以重试
+- 系统具备基本可运维性
+
+### 给 Codex 的推荐下发方式
+
+后续你可以直接按下面这种方式给 Codex 发任务：
+
+- `按一期第 1 个任务包做，只做菜单、路由和 4 个页面骨架，不做接口`
+- `按一期第 3 个任务包做，只打通待开票列表前后端，不碰票通`
+- `按二期第 3 个任务包做，只做认证中心后端接口和页面交互`
+- `按三期第 2 个任务包做，只做处理中任务的主动查询补偿`
+
+这样做最适合 Codex：
+
+- 单次上下文更清晰
+- 改动范围更集中
+- 验证更容易
+- 出问题时也更容易回退和继续推进