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. 常用命令

### 后端

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

### 前端

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

### 真实浏览器

```powershell
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 / 管理员治理逻辑需要持续按越权、事务、自删、最后管理员等维度审查。
## 2026-04-18 优化修复入口

本附录是任何工程师或智能体在当前仓库状态下开启新一轮优化或修复批次时的强制入口。

### 1. 改代码前的阅读顺序

开始前按以下顺序阅读：

1. `docs/status/REAL_PROJECT_STATUS.md`
2. `docs/code-review/FULL_CODE_REVIEW_REPORT_2026-04-17.md`
3. `docs/team/QUALITY_STANDARD.md`
4. `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`

用途：

- `REAL_PROJECT_STATUS` 告诉你当前已经验证过的工作区真相。
- `FULL_CODE_REVIEW_REPORT` 告诉你已经复核过的风险清单和任务分级。
- `QUALITY_STANDARD` 告诉你当前必须遵守的工程约束。
- `PROJECT_EXPERIENCE_SUMMARY` 告诉你哪些失败模式已经真实消耗过项目时间。

### 2. 先执行的新鲜命令

在做出任何“当前状态”判断前，先执行：

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

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

如果本轮工作涉及认证、会话、路由守卫、导航、弹窗防线或用户主流程，还要执行：

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

### 3. 当前发布阻塞级关注点

在一般优化之前，优先处理这些区域：

- `internal/api/handler/user_handler.go`
  `UpdateUser` authorization boundary
- `internal/service/auth.go`
  password login MFA/device-trust enforcement
- `internal/service/auth.go`
  refresh-token revocation persistence failure handling
- `internal/api/middleware/cors.go`
  unsafe default CORS behavior
- `internal/repository/user.go`
  cursor/sort mismatch in `ListCursor`
- `internal/service/password_reset.go`
  single-use verification code consumption semantics

### 4. 修复批次工作规则

- 不要把历史绿灯当作当前证据。
- 不要在没有分别验证的情况下，把门禁刷新、安全修复和重构混在同一个“已完成”结论里。
- 修 bug 或安全问题时，没有对应回归测试，就不要把任务提升为“完成”。
- 不要让包装脚本掩盖项目正式支持主命令的失败。

### 5. 文档更新规则

当一轮修复改变了真实结论时，必须在同一批次同步更新：

- `docs/status/REAL_PROJECT_STATUS.md`
- 规则变化时更新 `docs/team/QUALITY_STANDARD.md`
- 产出可复用经验时更新 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`