Ticket/history/三期工程实施文档.md

Codex 三期工程实施文档（通用票通优先）

1. 文档用途

这份文档不是详细设计书，而是一份可以直接拿去给 Codex 执行的实施文档。

默认路线：

• 先做 通用票通开票模块
• 暂不接你现有业务系统的待开票数据
• 后续再把你的业务系统接到这套票通能力上

适用前提：

• 当前项目前后端已经有通用后台底座
• 已有登录、权限、动态菜单、系统管理、日志管理
• 新增功能应尽量复用现有结构，不做大重构

2. 当前项目可直接复用的基础

Codex 在执行时，默认直接复用这些已有能力：

• 后端 Ktor 启动、鉴权、异常处理、日志、数据库初始化
• 后端 modules/* 的路由组织方式
• 后端 SeedData 的菜单、权限、字典初始化方式
• 前端登录、主布局、动态路由、权限按钮、页签体系
• 前端 features/* 页面组织方式
• 前端现有表格、表单、弹窗、查询页风格

本次新增内容尽量放到以下高层目录：

• server/src/main/kotlin/com/bbit/platform/integration/piaotong
• server/src/main/kotlin/com/bbit/platform/modules/piaotong
• server/src/main/kotlin/com/bbit/platform/database/piaotong
• web/src/api/piaotong
• web/src/types/piaotong
• web/src/features/piaotong
• web/src/components/piaotong

3. 全局实施原则

Codex 执行时，统一遵循下面原则：

• 不改现有系统管理模块的交互风格
• 不做全局重命名和大规模目录重构
• 每次只处理一个任务包，不跨太多模块
• 单个任务包尽量做到“改完即可本地验证一个页面或一组接口”
• 先打通票通主链路，再考虑业务系统适配
• 农产品收购发票从一开始就要纳入支持范围

新增菜单统一按这套来：

• 一级菜单：票通开票
• 二级菜单：
  • 票通企业
  • 数电账号
  • 认证中心
  • 手工开票
  • 开票任务

4. 三期工程总览

第一期目标

把票通模块骨架和基础查询能力搭起来，做到“能看企业、能看账号、能看认证状态、页面和接口结构稳定”。

第二期目标

把认证链路和手工开票主链路打通，做到“可以在系统里完成认证并发起真实开票”。

第三期目标

把推送、补偿、重试、稳定性补齐，做到“开票结果能稳定落定，模块具备持续使用能力”。

5. 第一期：票通底座与基础查询

5.1 本期目标

先把“票通开票”模块作为一个独立业务域立起来，完成最小骨架和只读能力，不急着一开始就打开发票提交。

5.2 本期应完成的内容

• 新增票通开票菜单和页面骨架
• 新增票通相关后端模块骨架
• 落票通配置、加密签名、HTTP 客户端基础能力
• 支持查询企业信息
• 支持查询企业开户行及账号信息
• 支持查询数电账号列表
• 支持查询数电账号认证状态
• 建立本地票通账号表和基础任务表

5.3 本期不要做的内容

• 不做真实开票提交
• 不做认证短信/扫码交互闭环
• 不做票通推送回调
• 不接你自己的业务系统

5.4 可直接给 Codex 的任务包

任务包 1

新增 票通开票 一级菜单和 5 个二级菜单，补齐前端路由和页面骨架，页面先只保留基础查询区和占位内容，不接真实接口。

任务包 2

在后端新增 piaotong 业务域目录和模块注册，补齐配置读取、公共报文封装、RSA/3DES 基础能力、票通 HTTP 客户端基础封装，先不接具体业务页面。

任务包 3

实现 票通企业 相关接口和页面，支持按税号查询企业信息、查询企业开户行及账号信息，并把查询结果在前端页面展示出来。

任务包 4

实现 数电账号 和 认证状态 的基础查询能力，支持查询数电账号列表、查看默认账号、查看认证建议和认证状态，并补齐本地账号表的基础读写。

5.5 本期验收标准

• 菜单、路由、页面已经可访问
• 后端已经形成独立的 piaotong 业务域
• 可以查询企业信息
• 可以查询企业开户行及账号信息
• 可以查询数电账号列表和认证状态
• 代码结构已经为后续认证和开票留出扩展位置

6. 第二期：认证中心与手工开票主链路

6.1 本期目标

把“账号认证 -> 手工录入 -> 发起开票 -> 查看任务状态”这条主链路打通。

6.2 本期应完成的内容

• 认证中心后端接口
• 短信验证码发送与短信登录
• 二维码认证获取与扫码状态查询
• 手工开票页面
• 普通蓝字数电票开票
• 农产品收购发票开票
• 本地开票任务记录
• 开票任务列表和详情页
• 手动查询开票结果

6.3 本期不要做的内容

• 不做票通推送回调
• 不做定时补偿任务
• 不接你的业务系统回写

6.4 可直接给 Codex 的任务包

任务包 1

实现 认证中心 后端接口，支持查询认证状态、发送短信验证码、提交短信登录、获取实名认证二维码、查询二维码扫码状态、退出电子税局登录。

任务包 2

实现 认证中心 前端页面和交互，支持短信认证流程和扫码认证流程，页面能清晰展示当前认证建议、二维码状态和短信状态。

任务包 3

实现 手工开票 页面和后端开票接口，支持手工录入发票基础信息、购买方/销方信息、商品明细，并支持普通开票模式和农产品收购发票模式切换。

任务包 4

实现本地开票任务创建、开票提交、手动状态查询、任务列表和详情页，让用户能看到发票请求流水号、状态、失败原因、票号等核心结果。

6.5 本期验收标准

• 用户可以在系统里完成短信认证或扫码认证
• 用户可以手工录入一张票并发起开票
• 农产品收购发票模式可用
• 能看到本地任务状态和票通返回结果
• 遇到 3999 时能进入认证流程，并可继续原任务

7. 第三期：推送、补偿与稳定性收口

7.1 本期目标

把结果同步和异常处理补齐，让模块从“可演示”进入“可稳定联调和可持续使用”状态。

7.2 本期应完成的内容

• 票通推送回调接收
• 验签、解密、幂等处理
• 主动查询补偿
• 失败任务重试
• 状态机收口
• 日志和异常信息收口
• 联调说明和部署说明

7.3 本期不要做的内容

• 仍然不接你的待开票业务系统
• 不把整套系统改造成完整业务平台

7.4 可直接给 Codex 的任务包

任务包 1

实现票通发票推送回调接口，支持接收推送主要信息和全票面信息，完成验签、解密、幂等判断和本地任务状态更新。

任务包 2

实现主动查询补偿机制，对处理中和待认证后的任务进行补偿查询，避免只依赖回调导致状态长期不落定。

任务包 3

实现失败任务重试和状态机收口，保证同一张发票重试时复用原 invoiceReqSerialNo，并把任务页上的错误提示、状态标签、操作入口整理完整。

任务包 4

整理联调说明、环境配置说明和回调部署说明，补齐必要的日志与调试信息，让后续对接你自己的业务系统时可以直接复用这套票通能力。

7.5 本期验收标准

• 开票结果可以通过推送或主动查询最终落定
• 重复推送不会造成重复更新
• 失败任务可以重试
• 任务状态流转稳定
• 模块已经具备后续接业务系统的基础

8. 给 Codex 的执行边界

后续给 Codex 发任务时，建议直接按“任务包”发，不要一次跨两期。

推荐下发方式：

• 按第一期任务包 1 做，只做菜单、路由和 5 个页面骨架，不接真实接口
• 按第一期任务包 3 做，只做票通企业查询前后端，不动认证和开票
• 按第二期任务包 2 做，只做认证中心前端交互，复用现有后端接口
• 按第二期任务包 4 做，只做本地开票任务和任务列表详情
• 按第三期任务包 2 做，只做主动查询补偿和状态落定

不建议下发方式：

• 一次要求 Codex 同时做菜单、认证、开票、推送、补偿
• 一次要求 Codex 同时接票通和你的业务系统
• 一次要求 Codex 重构现有后台结构后再开发功能

9. 这份文档的最终建议

这三期的节奏，核心是先把“票通能力底座”做出来，再考虑“业务系统接入层”。

如果按当前项目状态来看，这样分期最合理：

• 第一期把结构立稳，先查得到
• 第二期把主链路跑通，先开得出
• 第三期把稳定性补齐，先用得住

后续如果你要再接自己的待开票业务系统，就在这三期完成后再新增第四阶段：

• 读取业务待开票数据
• 自动创建票通任务
• 结果回写业务系统

这样不会推翻前面的实现，Codex 也更容易持续推进。