# 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 也更容易持续推进。