user-system/docs/team/TECHNICAL_GUIDE.md

技术指南

更新时间：2026-03-25

本文件不再承载泛化培训内容，改为当前项目的技术入口索引。

1. 先读什么

建议阅读顺序：

1. README.md
2. docs/status/REAL_PROJECT_STATUS.md
3. docs/team/QUALITY_STANDARD.md
4. docs/team/PRODUCTION_CHECKLIST.md
5. docs/team/PROJECT_EXPERIENCE_SUMMARY.md

2. 当前项目最重要的真实结论

• 主验收路径是 cd frontend/admin && npm.cmd run e2e:full:win
• 当前闭环的是浏览器级真实 E2E，不是完整 OS 级自动化
• smoke 仅用于诊断，不是运行时依赖
• 非测试代码中的 panic、fake success、mock runtime provider 都应视为缺陷

3. 常用命令

后端

go test ./... -count=1
go vet ./...
go build ./cmd/server

前端

cd frontend/admin
npm.cmd run lint
npm.cmd run build

真实浏览器

cd frontend/admin
npm.cmd run e2e:full:win

4. 常见工程经验

• 如果结论依赖真实用户流程，就不要只跑单元测试。
• 如果终端出现乱码，不要把乱码文本继续复制进业务逻辑。
• 如果错误分级依赖字符串子串，后续大概率会回归；优先改成显式错误类型。
• 如果 service 依赖具体 repository 类型断言，后续替换实现或测试 mock 会变脆。

5. 文档维护规则

• 状态变更：更新 docs/status/REAL_PROJECT_STATUS.md
• 规则变更：更新 docs/team/QUALITY_STANDARD.md
• 发布门槛变更：更新 docs/team/PRODUCTION_CHECKLIST.md
• 阶段性经验：更新 docs/team/PROJECT_EXPERIENCE_SUMMARY.md