hfb_sys/docs/代码质量改进计划.md

HFB Sys 代码质量改进计划

当前基线

更新时间：2026-09-02。

• 后端约 374 个 Go 文件、6.6 万行代码，64 个测试文件。
• 前端约 249 个 Vue/TypeScript 文件、8.4 万行代码，7 个测试文件、32 个测试；大型页面样式已外置，订单详情 setup 已独立为 composable 目录中的脚本模块。
• 数据库使用 61 个 Goose 迁移文件，SQL 约束由 scripts/check-sql-guard.sh 检查。
• 后端总语句覆盖率基线为 30%；核心模块门禁为 order 40%、payment 20%、wallet 34%、withdrawal 30%。
• 前端支付、钱包、提现和订单展示目标文件已建立 V8 覆盖率门禁：语句 80%、分支 70%、函数 80%、行 80%。
• Vue 页面大小门禁为 1800 行，scripts/check-vue-size.sh 在本地检查中执行，防止大型 SFC 回涨；订单详情页的指标、支付流水和展示工具已拆出独立模块。
• Repository 已普遍传递请求 Context；当前约 376 处 GORM WithContext 调用。

已落地门禁

本地和部署前统一运行：

./scripts/check.sh

门禁包含：

1. SQL 迁移约束与完整性检查。
2. go vet、Go 全量构建、测试和覆盖率基线。
3. Prettier、ESLint、Vue/TypeScript 类型检查。
4. Vitest 和 Vite 生产构建。

本地门禁通过 scripts/check.sh 统一执行；需要完整租赁链路时，在本地 MySQL 8.4 上设置 HFB_E2E_DSN 运行 E2E。覆盖率门禁采用“只能提高、不能回退”的基线策略，新增测试后应同步上调阈值。

后续重点

P0：资金正确性

• 扩充支付通知乱序、重复回调和退款重试测试。
• 扩充钱包并发入账、提现审核竞争和事务回滚测试。
• 保持金额使用整数分存储，禁止业务层使用浮点数累计金额。

P1：前端回归保护

• 为支付收银台、订单操作、提现和后台财务组件增加测试。
• 优先测试状态转换、权限可见性和请求参数，不追求低价值快照数量。
• 逐步建立前端覆盖率基线。

P1：结构治理

• 将大型管理页面拆成展示组件、操作对话框和 composable。
• 将路由组装按公开、用户、卖家、管理员领域拆分，保持 router.New 只负责依赖组装。
• 单次拆分必须保持接口、路由名称和用户行为不变。

P2：可观测性

• 区分 /health 存活探针和 /health/ready 就绪探针。
• 持续观察慢查询、退款重试、订单超时任务和备份恢复演练结果。