# 认证 HTTP 约定（Smart Go）

与 OAuth2 授权码 + PKCE 对齐，见仓库内 PKCE 校验实现：`internal/auth/oauth2`。

## 统一 JSON 信封（`/api/v1/auth/*`）

| HTTP | 说明 |
|------|------|
| `401` | 认证失败（如用户名或密码错误） |
| `403` | 已认证但无权限（如用户已禁用） |
| `200` | 其余：业务成功或 **OAuth 客户端/PKCE 元数据** 类错误（看 `code`） |
| `5xx` | 服务端异常 |

响应体：

```json
{ "code": 200, "msg": "操作成功", "data": { } }
```

- 业务成功时 `code` 为 `200`。
- 凭据错误以 **HTTP 401** 为准，可不依赖 `body.code` 做分支。

## `POST /api/v1/auth/login`

在校验 **用户名 + 密码** 通过后，签发与 `GET /oauth/authorize` **同一存储**的 **authorization_code**（绑定 PKCE），并 **Set-Cookie** 会话（便于浏览器再走 `/oauth/authorize`）。

### 请求体（JSON）

| 字段 | 必填 | 说明 |
|------|------|------|
| `user_name` | 是 | 登录名 |
| `password` | 是 | 密码 |
| `tenant_id` | 否 | 缺省为平台租户 |
| `client_id` | 是 | 已注册的 OAuth 客户端 |
| `redirect_uri` | 是 | 须在该客户端允许列表内 |
| `code_challenge` | 是 | PKCE S256 |
| `code_challenge_method` | 是 | 须为 `S256`（大小写不敏感） |
| `state` | 否 | 成功时在 `data.state` 回显 |
| `scope` | 否 | 缺省 `openid` |

### 成功 `HTTP 200`

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "authorization_code": "<plain_code>",
    "state": "<若请求携带>"
  }
}
```

前端用本地保存的 `code_verifier` 请求：

`POST /oauth/token`，`grant_type=authorization_code`，参数与标准授权码换 token 一致（`code`、`redirect_uri`、`client_id`、`code_verifier`）。

### 失败示例

- 用户名或密码错误：**HTTP 401**，`msg` 提示凭据错误。
- 用户禁用：**HTTP 403**。
- `client_id` / `redirect_uri` / PKCE 不合法：**HTTP 200**，`code`≠`200`，`msg` 说明原因。

## `POST /api/v1/auth/logout`

清除会话 Cookie；响应为信封 `code: 200`。