smart-go/docs/auth-api.md

认证 HTTP 约定（Smart Go）

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

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

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

响应体：

{ "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

{
  "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。