fix(handlers): add handlers

docs/SCALAR_GUIDE.md

@@ -0,0 +1,155 @@
+# IAM Service — Scalar 调用顺序指南
+
+## Authentication（认证方式）
+
+本服务使用 **JWT Bearer Token**：
+
+- 登录成功后拿到 `access_token`
+- 后续请求在 Header 中带：
+  - `Authorization: Bearer <access_token>`
+- 租户上下文：
+  - 保护接口默认从 Token claim 的 `tenant_id` 推导租户
+  - 可选兼容 `X-Tenant-ID: <uuid>`，若同时提供 Header 与 Token，则必须一致，否则返回 403
+
+## 通用响应结构
+
+成功响应：
+
+```json
+{ "code": 0, "message": "Success|Created|Accepted", "data": {}, "trace_id": null }
+```
+
+错误响应（示例）：
+
+```json
+{ "code": 20006, "message": "Missing authorization header", "details": null, "trace_id": null }
+```
+
+常见错误码（节选）：
+
+- 20006：缺少必要 Header（如 Authorization）
+- 20003：无权限（403）
+- 20005：账号或密码错误
+- 30000：请求参数错误（400）
+- 30002：资源不存在（404）
+- 30003：资源冲突（409）
+- 40000：请求过于频繁（429）
+- 10001：数据库错误（500）
+
+## Step-by-step（可复制流程）
+
+### Step 0：创建租户（可选）
+
+**POST** `/tenants/register`
+
+- Header：无
+- Body：
+
+```json
+{ "name": "Tenant A", "config": { "theme": { "primary": "#1d4ed8" } } }
+```
+
+成功（201）从 `data.id` 取出租户 ID：
+
+```json
+{ "code": 0, "message": "Created", "data": { "id": "<tenant_id>", "name": "Tenant A", "status": "active", "config": {} }, "trace_id": null }
+```
+
+下一步依赖：`tenant_id`（用于注册/登录时的 `X-Tenant-ID`）。
+
+### Step 1：注册用户
+
+**POST** `/auth/register`
+
+- 必需 Header：`X-Tenant-ID: <tenant_id>`
+- Body：
+
+```json
+{ "email": "user@example.com", "password": "securePassword123" }
+```
+
+成功（201）从 `data.id` 取出 `user_id`（后续可用于用户管理接口）：
+
+```json
+{ "code": 0, "message": "Created", "data": { "id": "<user_id>", "email": "user@example.com" }, "trace_id": null }
+```
+
+### Step 2：登录获取访问令牌（Authentication 入口）
+
+**POST** `/auth/login`
+
+- 必需 Header：`X-Tenant-ID: <tenant_id>`
+- Body：
+
+```json
+{ "email": "user@example.com", "password": "securePassword123" }
+```
+
+成功（200）从 `data.access_token` 取出访问令牌：
+
+```json
+{ "code": 0, "message": "Success", "data": { "access_token": "<jwt>", "refresh_token": "<opaque>", "token_type": "Bearer", "expires_in": 900 }, "trace_id": null }
+```
+
+下一步依赖：`access_token`。
+
+### Step 3：获取当前租户信息（Tenant）
+
+**GET** `/tenants/me`
+
+- 必需 Header：`Authorization: Bearer <access_token>`
+- 可选 Header：`X-Tenant-ID: <tenant_id>`（如提供必须与 token tenant_id 一致）
+
+成功（200）：
+
+```json
+{ "code": 0, "message": "Success", "data": { "id": "<tenant_id>", "name": "Tenant A", "status": "active", "config": {} }, "trace_id": null }
+```
+
+### Step 4：查看当前用户权限（Me）
+
+**GET** `/me/permissions`
+
+- 必需 Header：`Authorization: Bearer <access_token>`
+
+成功（200）：
+
+```json
+{ "code": 0, "message": "Success", "data": ["tenant:read","tenant:write"], "trace_id": null }
+```
+
+下一步依赖：确认具备目标权限（例如 `user:read` / `role:read`）。
+
+### Step 5：列出用户（User）
+
+**GET** `/users?page=1&page_size=20`
+
+- 必需 Header：`Authorization: Bearer <access_token>`
+- 分页规则：
+  - `page` 默认 1，必须 >= 1
+  - `page_size` 默认 20，范围 1..=200
+
+成功（200）：
+
+```json
+{ "code": 0, "message": "Success", "data": [{ "id": "<user_id>", "email": "user@example.com" }], "trace_id": null }
+```
+
+### Step 6：列出角色（Role）
+
+**GET** `/roles`
+
+- 必需 Header：`Authorization: Bearer <access_token>`
+
+成功（200）：
+
+```json
+{ "code": 0, "message": "Success", "data": [{ "id": "<role_id>", "name": "Admin", "description": "..." }], "trace_id": null }
+```
+
+## 限流说明（Auth）
+
+- `/auth/login`：约 2 req/s，burst 10（同一 IP）
+- `/auth/register`：约 1 req/s，burst 5（同一 IP）
+- 触发后返回：HTTP 429 + `code=40000`
+