bbit/Ticket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
Ticket/history/Codex三期工程执行文档.md
T
BBIT-Kai f7a27d99e1 优化后端框架
2026-05-07 10:25:02 +08:00

9.6 KiB
Raw Permalink Blame History

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：

  • 单次上下文更清晰
  • 改动范围更集中
  • 验证更容易
  • 出问题时也更容易回退和继续推进
Reference in New Issue View Git Blame Copy Permalink