long-agent
2cd76b2835
- PRODUCTION_CHECKLIST: add RBAC/admin governance checklist section - PROJECT_EXPERIENCE_SUMMARY: add lessons from 2026-04-10 reviews (live ≠ done, main-entry green > local green, test noise = quality issue, docs lag = rework) - QUALITY_STANDARD: add stub→live review threshold rules
3.1 KiB
3.1 KiB
技术指南
更新时间：2026-03-25
本文件不再承载泛化培训内容，改为当前项目的技术入口索引。
1. 先读什么
建议阅读顺序：
README.mddocs/status/REAL_PROJECT_STATUS.mddocs/team/QUALITY_STANDARD.mddocs/team/PRODUCTION_CHECKLIST.mddocs/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
6. 2026-04-10 多轮 Review 实操指引
6.1 如何判断“是否闭环”
- 结论优先级：文档支持的主入口 > repo 内单步命令 > 局部 smoke、单个用例、
-short结果。 - 只要
go test ./... -count=1仍被LL_001卡住，或npm.cmd run e2e:full:win仍未跑通，就不能把项目表述为“全量验证通过”。 go build ./cmd/server通过，只能证明 repo 内该命令通过；不能自动推出包装脚本里的 build 路径也稳定。
6.2 如何审查 stub 转 live 的高风险改动
- 先看权限边界：调用者是否真的具备读取或修改目标资源的资格。
- 再看治理边界：是否存在
self-action、last-admin、越权枚举、越权提升等问题。 - 再看一致性：多步写操作是否在事务内；失败时是否有显式回滚。
- 最后看文档与测试：是否补了负向测试、边界测试、回滚测试，以及状态文档与规范文档。
6.3 当前需要持续关注的热点
internal/service/scale_test.go：LL_001仍是全量go test ./... -count=1的门槛。frontend/admin/scripts/run-playwright-auth-e2e.ps1：需要优先保证文档支持的e2e:full:win入口自身稳定，而不是只验证子命令。frontend/admin/src/components/common/ui-consistency.test.tsx：原生弹窗噪声仍会污染测试结果，应继续清理。internal/api/handler/user_handler.go与internal/service/user_service.go：RBAC / 管理员治理逻辑需要持续按越权、事务、自删、最后管理员等维度审查。