# 参考样例索引 + GoDoc 注释标准

> 本文件是 `backend/README.md` **铁律 11（注释标准）** 的落地模板与样例清单。
> 所有样例代码**可编译**（`go build ./...` + `go vet ./...` 全绿，本地 go 1.27.x），
> 每个导出符号均带 GoDoc 中文注释（功能说明+样例 / 入参逐项 / 出参逐项+异常场景）。
> 架构决策依据见 `../unified/01-architecture/backend-technical-architecture.md`。

---

## 1. 样例包清单

| 包 | 路径 | 落地的架构规格节 | 承载的 ADR / 铁律 | 核心导出 |
|---|---|---|---|---|
| 统一响应 | `internal/infra/response` | §3.1 接口规范 | 铁律 6（HTTP 恒 200 + body code） | `R` / `PageData` / `OK` / `Page` / `Fail` / `ParsePage` |
| 三层错误 | `internal/infra/errors` | §3.2 异常处理 | 错误码分段 1xxx–5xxx | `AppError` / `New` / `WithCause` / sentinel `ErrNotFound` 等 |
| 多租户作用域 | `internal/infra/scope` | §3.5 作用域注入 | 铁律 2（强制作用域） | `Scope` / `Set` / `FromFiber` / `BaseRepo` / `NewBaseRepo` |
| 入参校验 | `internal/infra/validator` | §3.1 入参惯例 | 铁律 7（validateReq 语义） | `Validate` |
| 配置管理 | `internal/infra/config` | §3.4 配置 | ADR-015（12-factor） | `Config` / `Load` / `EnsureRuntimeDirs` |
| 身份主键 | `internal/identity/id` | §7.1 | ADR-013（ULID） | `NewCanonicalUserID` / `NewCanonicalUserIDAt` / `Validate` / `Length` |
| 密码凭证 | `internal/identity/credential` | §3.8 / §7.4 | ADR-016（argon2 惰性升级） | `Check` / `HashArgon2` / `VerifyArgon2` / `Result` / `HashVersion*` |
| SSO token | `internal/identity/token` | §7.2 | ADR-014（SSO 最小可行） | `Issuer` / `Claims` / `Issue` / `Verify` / `Rotate` / `RevokeAll` |
| 异步任务 | `internal/task` | §3.7 | 统一 DB 任务表 | `Task` / `Repo` / `Enqueue` / `Claimable` / `Claim` / `Done` / `Fail` / `ReclaimStale` |

> **规划待建**（尚无代码，目录已占位）：`cmd/api`（装配入口）、`internal/org`（多租户+7 角色）、
> `internal/academic`（教务域）、`internal/teaching`（教学域）、`internal/ai`（Agent 消费方）。
> 新增这些域时，**必须先对齐本文件的注释标准**再写业务逻辑。

---

## 2. GoDoc 注释标准（三段式）

每个**导出**的结构体 / 函数 / 方法 / 常量 / 错误变量，注释必须覆盖三段；缺一段视为不完整：

### ① 功能说明（用途 + 核心逻辑）
- 一句话说清"做什么 + 为什么这样设计"，点明对应的架构规格节 / ADR / 铁律。
- 导出项（被其它包调用）必须附**典型使用样例**（多行 `//` 代码块），让读者不翻实现就能上手。
- 设计取舍 / 坑点用"为什么"句式说明（例："为什么不用 `err != nil` 判""为什么走 `c.Locals` 不走 context"）。

### ② 入参说明（逐项）
- 每个参数：`- 参数名 类型：含义；约束/取值范围`。
- 标注必填/可空、默认值、上限钳制、敏感项（密钥/密码）。
- 无参函数写"入参：无"，不留空。

### ③ 出参说明（逐项 + 异常场景）
- 每个返回值：`- 名称 类型：含义`。
- **异常场景单列**：哪些输入/状态会返回 error / 特殊值（nil、false、dead），以及调用方该如何处理。
- 错误要说明"降级还是 fail-fast""是否 fail-closed"（安全相关明确标注）。

### 包级注释（文件顶部）
- 第一段一句话定位（本包解决什么）。
- 背景 / 数据来源 / 关键约束（ADR、风险登记册条目）。
- **典型使用**完整链路示例（跨包协作时给出端到端调用片段）。

### 与实现一致性（强制）
- 改实现必须同步改注释；注释描述的行为与代码不符 = bug。
- 不写"显然"的废话注释（`// 加 1`）；只写"读代码看不出来"的设计意图、约束、坑。
- 中文用规范标点；代码片段内标识符保持原样不翻译。

---

## 3. 注释模板（复制即用）

```go
// <导出符号> <一句话功能>（对应架构规格 §X / ADR-XXX / 铁律 N）。
//
// 典型使用（调用方）：
//
//	<2~6 行可运行的调用片段>
//
// 入参：
//   - name1 type1：含义；约束（必填/可空/默认值/上限）。
//   - name2 type2：含义；敏感项标注（如"走环境变量，勿入库"）。
//
// 出参：
//   - ret1 type1：含义。
//   - ret2 error：以下场景非 nil——
//     - 场景 A：处理建议（降级/重试/fail-closed）。
//     - 场景 B：处理建议。
//
// 异常场景：
//   - 边界输入 X：行为 Y（为何这样，而非报错）。
```

---

## 4. 构建与一致性校验

```bash
# go.mod `go 1.27`（语言级别 + 最低工具链）；本机 go 1.27.x 直接构建。
# 依赖保持初版锁定版本（validator v10.27.0 等），升 1.27 后实测无意外升级。
go build ./...          # 必须 0 错误
go vet   ./...          # 必须 0 告警（1.27 起默认含 stdversion 检查）
GOTOOLCHAIN=local go build ./...   # 强制本地工具链（防 CI 误拉非预期工具链）

# 一致性自检（注释与实现对齐的最低门槛）
go doc ./internal/infra/response     # 查看包文档是否完整渲染
```

> **新增业务域 checklist**：
> 1. 目录落在正确域（`academic`/`teaching`/`org`/`ai`），不进 `infra`（横切）或反向依赖。
> 2. 数据访问经 Repository + `scope.BaseRepo.scoping`（铁律 2），不裸查。
> 3. Service 返回 `*errors.AppError` sentinel（铁律，不裸抛 gorm 原错）。
> 4. Handler 用 `response.OK/Page/Fail`（铁律 6）+ `validator.Validate`（铁律 7）。
> 5. 每个导出符号带三段式 GoDoc（铁律 11），改实现同步改注释。
> 6. `go build` / `go vet` 全绿后方可提交。