Ticket/history/Codex三期工程执行文档.md

Codex 三期工程执行文档

适用范围：基于当前已经完成的通用后台底座，继续建设“农产品收购发票开票平台”业务闭环。
使用方式：建议你后续给 Codex 下任务时，一次只下发一个“任务包”，不要跨太多模块，这样实现时间更短、回归范围更可控。

1. 业务功能规划

1.1 新增业务菜单

当前系统管理、日志管理等菜单已经具备，后续只新增业务菜单，不重复建设已有后台功能。

建议新增一级菜单：

• 发票业务

建议在 发票业务 下新增 4 个菜单：

• 待开票列表
  • 用于查看业务系统返回的待开票数据、筛选、勾选、发起开票
• 开票任务
  • 用于查看开票状态、失败原因、票号信息、重试操作
• 认证中心
  • 用于处理票通认证状态、短信认证、扫码认证
• 票通账号配置
  • 用于维护公司与票通账号、默认开票参数、基础映射关系

说明：

• 开票结果 不建议单独再做一个菜单，直接并入 开票任务
• 票通回调、主动查询补偿、业务系统回写 不需要前端菜单，做后端能力即可

1.2 建议目录规划

为了适配当前项目结构，建议继续沿用现有 modules / features 风格，不要一开始就做大规模重构。

后端建议新增目录：

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

前端建议新增目录：

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：

• 单次上下文更清晰
• 改动范围更集中
• 验证更容易
• 出问题时也更容易回退和继续推进