Files
qipai/docs/devlogs/2026-06-16-M01-A-后端基础工程.md
2026-06-16 21:04:38 +08:00

3.3 KiB
Raw Permalink Blame History

开发日志:2026-06-16 M01-A 后端基础工程

1. 本次目标

建立最小 Fastify + TypeScript 后端 API 骨架,补齐健康检查、配置加载、traceId、基础错误响应、PM2 模板和可复现契约检查。

2. 本次完成

  • 新增 backend/package.jsonbackend/tsconfig.jsonbackend/.env.example
  • 新增 Fastify 应用入口、配置加载、健康/就绪/版本路由。
  • 新增 backend/tests/backend-contract.test.mjs,在未安装依赖前也能校验 M01-A 工程契约。
  • 新增 scripts/dev/windows/check-backend.ps1 并接入 test-all.ps1
  • 新增 deploy/pm2/ecosystem.config.cjs
  • 更新 release manifest dry-run,使其识别后端项目已存在但尚未构建。
  • 锁定 backend/package-lock.json,将后端升级到 Fastify 5 依赖线并移除当前未使用的 Kysely 生产依赖。
  • 将后端运行时要求声明为 Node >=20.0.0、npm >=10.0.0
  • 扩展 scripts/dev/windows/check-backend.ps1,自动执行契约测试、TypeScript 编译并启动真实 HTTP 进程验证 /app-api/health/admin-api/health

3. 修改文件

  • backend/**
  • deploy/pm2/ecosystem.config.cjs
  • scripts/dev/windows/check-backend.ps1
  • scripts/dev/windows/check-release-manifest.ps1
  • scripts/dev/windows/check-repo-completeness.ps1
  • scripts/dev/windows/test-all.ps1
  • scripts/setup/deploy-business.sh

4. 数据库变化

  • 是否有变化:否。
  • 迁移文件:无。
  • 回滚方式:移除本次新增后端骨架文件即可。

5. API 变化

  • 新增:/app-api/health/admin-api/health/app-api/ready/admin-api/ready/app-api/version/admin-api/version
  • 修改:无。
  • 删除:无。
  • 兼容旧接口:当前为新系统基础接口,不替代旧业务接口。

6. 前端变化

  • 小程序:无。
  • 后台管理端:无。

7. 部署变化

新增 PM2 模板;生产仍未执行。后端依赖已安装并锁定,本地 build/start/HTTP 健康检查已通过;生产环境需提供 Node 20+。

8. 测试结果

  • npm --prefix backend test:通过。
  • npm --prefix backend run build:通过。
  • npm audit --omit=dev(在 backend/ 执行):通过,生产依赖审计 0 漏洞。
  • powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-backend.ps1:通过,已覆盖真实 HTTP 健康检查。
  • powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-release-manifest.ps1:通过。
  • wsl -e bash -lc 'cd /mnt/d/qipai && bash scripts/setup/deploy-business.sh --dry-run . ...':通过。

9. 欠缺 / 风险

  • 生产 Ubuntu 的 Node 20+、PM2 启动和 Nginx 反代尚未验收。
  • MySQL 仅完成依赖和配置占位;Kysely 暂未作为生产依赖引入,数据库迁移和连接池将在 M01-B 建立。
  • 审计日志、限流策略和统一错误码仍为基础实现,未覆盖业务级鉴权。

10. 下一步

进入 M01-B 数据库迁移、连接池与旧表兼容层;继续保留 check-backend.ps1 作为每轮后端提交门禁。

11. Git 与 Gitea 推送信息

  • 远端:ssh://git@git.txyundm.cn:2222/panda/qipai.git
  • 分支:main
  • commit6114124
  • push 命令:git push origin main
  • push 结果:本轮最终推送后复核
  • push 时间:2026-06-16
  • HEAD 与 origin/main 是否一致:本轮最终推送后复核
  • 失败原因与重试命令:无