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

# 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：

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