tennis-training-hub/docs/developer-workflow.md

Developer Workflow

Working model

本项目采用“阶段可停可跑”的开发方式。任何较大的改动都应满足：

• 阶段结束即可本地启动
• 阶段结束即可执行验证命令
• 阶段结束即可提交本地 commit

Recommended loop

pnpm check
pnpm test
pnpm test:go
pnpm build
pnpm test:e2e

全部通过后再提交：

git status
git add .
git commit -m "..."

Interrupt-safe development

如果业务开发中被打断，恢复时按以下顺序：

1. git status 查看当前工作树
2. 先跑 pnpm check
3. 再跑 pnpm test
4. 若涉及媒体链路，再跑 pnpm test:go
5. 最后跑 pnpm test:e2e
6. 若当前分支包含部署改动，再执行 docker compose config 与基础 smoke check

不要在一半状态下长时间保留“能编译但主流程不可用”的改动。

Deployment-safe checks

涉及 compose、nginx、数据库或媒体服务调整时，提交前至少确认：

• docker compose config 可通过
• docker compose ps 中 app、db、media、worker 正常
• 一次性迁移容器 migrate 成功退出
• curl -I https://te.hao.work/ 返回 200
• curl http://127.0.0.1:8081/media/health 返回 {"ok":true,...}

Media-related changes

修改录制链路时至少检查：

• client/src/lib/media.ts
• client/src/pages/Recorder.tsx
• media/main.go
• server/routers.ts
• server/_core/mediaProxy.ts

媒体改动完成后至少验证：

• 会话创建
• marker 写入
• finalize
• 视频库登记

Documentation discipline

以下改动必须同步更新文档：

• 新增脚本或验证入口
• 新增或变更媒体 API
• 部署拓扑变化
• 功能能力边界变化
• 新增自动化测试覆盖范围

至少更新：

• README.md
• docs/testing.md
• docs/verified-features.md
• 相关专题文档