init

docs/auth.md

@@ -0,0 +1,64 @@
+# 认证与登录
+
+## 1) 登录
+
+`POST /api/v1/auth/login`
+
+说明：小程序端调用 `wx.login()` 获取 `code`，后端用该 `code` 向微信 `jscode2session` 换取 `openid/session_key`，并在数据库中创建/更新用户记录。
+
+请求示例：
+
+```bash
+curl -X POST 'http://127.0.0.1:8080/api/v1/auth/login' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "mini_program_id": 2,
+    "code": "wx.login 返回的 code",
+    "nickname": "可选：昵称",
+    "avatar_url": "可选：头像",
+    "gender": 1,
+    "phone": "可选：手机号"
+  }'
+```
+
+成功响应示例（节选）：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "user": {
+      "id": 1,
+      "mini_program_id": 1,
+      "open_id": "oXXX",
+      "nickname": "昵称",
+      "avatar_url": "https://...",
+      "gender": 1,
+      "phone": "110"
+    },
+    "session_key": "wx-session-key",
+    "mini_program": {
+      "id": 1,
+      "name": "某小程序",
+      "app_id": "wx..."
+    }
+  }
+}
+```
+
+## 2) 受保护接口如何带 Token
+
+后端把 `session_key` 当做 Token 使用，调用受保护接口时在 Header 中带：
+
+```
+Authorization: Bearer <session_key>
+```
+
+请求示例：
+
+```bash
+curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs?page=1&page_size=20' \
+  -H 'Authorization: Bearer wx-session-key'
+```
+