BBIT-Kai
258 lines
8.9 KiB
Markdown
258 lines
8.9 KiB
Markdown
# 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 也更容易持续推进。
|