feat: 优化web

2026-04-23 18:58:13 +08:00
commit 544a2f3428
160 changed files with 27327 additions and 0 deletions
@@ -0,0 +1,66 @@
+# 认证 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`。