Skip to content

十二、质量与验证 ​

本章速览:读完后你会知道 —— ① 测试与闸门各防什么(927 条用例 / 24 条架构规则 / 文档与配置检查器);② 为什么规模数字必须进闸;③ 发布前必须跑哪 6 步。

这个项目的质量策略是"把纪律变成闸门":能机械检查的绝不靠自觉, 检查不过就不许发布。数字、清单、契约、行为都有对应的闸。

12.1 测试与检查体系 ​

层工具/位置规模命令
后端单测/集成JUnit 5 + Mockito + 真实 HTTP(部分)927 条用例 / 216 个测试类mvn -B -o clean test(必须 clean)
架构规则ArchitectureGuardTest24 条架构规则包含在 test 中
模块边界ModuleBoundaryTest业务模块互不实现依赖同上
文档覆盖docs/tools/check-doc-coverage.mjs10 类覆盖 + 4 项结构 + 4 项附录准确性node docs/tools/check-doc-coverage.mjs
文档数字ArchitectureGuardTest 规则 17规模数字/迁移号/表数/@Mapper/页面数在 test 中
API 接线docs/tools/check-api-wiring.mjs前端 332 路径 ↔ 后端端点node …(含未接 UI 清单)
配置台账vite-cosmos-web/scripts/check-config-registry.mjs176 键 ↔ 面板 ↔ 读点在 web verify 中
MCP 契约docs/tools/check-mcp-tools.mjs70 工具 ↔ 真机 tools/list需两个令牌,手动/巡检
部署守卫deploy/scripts/check-deploy-guards.sh闸 A–F(挂载/健康/回滚/密钥/迁移期望键)bash …
宿主体检deploy/scripts/doctor.sh25 项(端口/挂载/令牌/备份/迁移/环回)bash deploy/scripts/doctor.sh
管理端 e2ePlaywright53 passed / 1 skipped(生产只读)npm run test:e2e
管理端单测Vitest请求层/工具/组件npm test
前端构建vue-tsc -b + vite build双前端npm run build
文档站构建VitePress(源文件仍是本文)30 页(首页 + 15 章 + 14 附录)npm --prefix docs-site run build
灾难恢复restore-drill.sh / 官方 mysql-restore.sh恢复演练(101 表 / ~42s)手动,每季度/大改后

12.2 为什么"数字进闸" ​

文档里的规模数字是读者判断完整度的依据,却最容易漂:历史上 Java 文件 820→793、 @TableName 97→93、测试 826→836、后台页面 92→91、Flyway 149→163 都漂过。 架构规则 17 与文档检查器把"可机械计数"的项固化:改代码不同步文档 = 测试红。

同理,端点/表/配置键/错误码/脚本/路由/定时任务都有"源码 ↔ 文档"双向核对, 新增而不登记会直接失败 —— 这是"文档是可执行事实"的落地方式。

12.3 审查记录与修复文化 ​

docs/全项目审查记录.md 记录每一轮全链路审查的「症状 → 根因 → 修法 → 验证」。 比较典型的几类(都沉淀成了测试或闸):

  • 假成功/谎报:更新 0 行仍报成功、存上了却说没存上、跳过没有理由;
  • 静默失效:配置写脏值被静默回退、出网档位错字变成放行、润色缓存永远返回模板;
  • 边界泄漏:附件 mime 注入面、孤儿清理引用面漏项、导出包把笔记变文章;
  • 时间炸弹:固定日期测试在 30 天后永久变红(本轮已修)。

纪律:修一次,补一类测试;修复必须给真机证据(生产库行、日志、请求响应), 不允许"看代码觉得好了"。

12.4 发布前清单 ​

  1. mvn -B -o clean test(必须 clean);
  2. npm run build(后台 + 门户);后台 npm run test:e2e;
  3. node docs/tools/check-doc-coverage.mjs、check-api-wiring.mjs;
  4. web 侧 npm run verify(样式 token / i18n / 配置台账 / build);
  5. bash deploy/scripts/check-deploy-guards.sh;bash deploy/scripts/doctor.sh;
  6. 部署后:curl -sk https://127.0.0.1/api/health -H 'Host: vite66.cn'、健康检查通过、 启动日志 ERROR=0、能力健康看板无异常跳过。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。