feat: 优化web

docs/auth-api.md

@@ -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`。

docs/cors-https-checklist.md

@@ -0,0 +1,13 @@
+# CORS / HTTPS 清单（开发 → 生产）
+
+## 开发（当前）
+
+- Go 已加 [`internal/server/cors.go`](../internal/server/cors.go)：仅 **Origin 为 `http://localhost:*` / `http://127.0.0.1:*` / `http://[::1]:*`** 时反射 `Access-Control-Allow-Origin` 并允许 **Credentials**。
+- 前端 `web/.env.local` 设置 `NEXT_PUBLIC_API_ORIGIN=http://127.0.0.1:8000`（与 Go 监听一致）。
+- OAuth `redirect_uri` 须与 Go /oauth 客户端种子登记一致（如 `http://localhost:3000/oauth/callback`）。
+
+## 生产
+
+- **同源**：Next 与 Go 同站点 / 反代为同一 Origin 时，浏览器 **简单请求无 CORS**；请关闭或收紧对公网暴露的 CORS。
+- **HTTPS**：Cookie `Secure`、`SameSite` 与 OAuth 重定向须用 **HTTPS**；参阅 `configs` 里 Session 配置。
+- 多环境 `redirect_uri`：在 OAuth 客户端表中登记各环境回调 URL。