feat(handler): add app

docs/SCALAR_GUIDE.md

@@ -77,6 +77,8 @@
 
 - Tag：`Tenant`
 - Header：无
+- 二次验证（可选但建议生产启用）：
+  - 若设置环境变量 `IAM_SENSITIVE_ACTION_TOKEN`，则必须传 Header：`X-Sensitive-Token: <token>`，否则返回 403。
 - Body：
 
 ```json
@@ -212,6 +214,82 @@ enabled_apps 维护建议：
 - 下线应用：将 `apps.status` 置为非 `active`（例如 `disabled`），之后将无法再被设置进任何租户的 enabled_apps。
 - 查询可用应用（示例 SQL）：`SELECT id, name, status FROM apps ORDER BY id;`
 
+### Step 4.2：平台层 App 生命周期管理（SuperAdmin）
+
+用于维护“允许的 App 注册表”，并提供应用上下线（审批 + 生效时间）能力。
+
+权限要求（平台级）：
+- `iam:app:read`
+- `iam:app:write`
+- `iam:app:approve`
+- `iam:app:delete`
+
+#### 4.2.1 新增 App
+
+**POST** `/platform/apps`
+
+- Tag：`App`
+- Header：`Authorization: Bearer <access_token>`（平台租户下登录得到的 token）
+- Body（示例）：
+
+```json
+{ "id": "dms", "name": "DMS", "description": "Document Management System", "app_type": "product", "owner": "team-a" }
+```
+
+#### 4.2.2 查询 App 列表（分页/筛选/排序）
+
+**GET** `/platform/apps?page=1&page_size=20&status=active&app_type=product&sort_by=created_at&sort_order=desc`
+
+- Tag：`App`
+- Header：`Authorization: Bearer <access_token>`
+
+#### 4.2.3 更新 App 基础信息
+
+**PATCH** `/platform/apps/{app_id}`
+
+- Tag：`App`
+- Header：`Authorization: Bearer <access_token>`
+- Body（示例）：
+
+```json
+{ "description": "DMS v2", "owner": "team-b" }
+```
+
+#### 4.2.4 申请 App 上下线（需要审批，可设置生效时间）
+
+**POST** `/platform/apps/{app_id}/status-change-requests`
+
+- Tag：`App`
+- Header：`Authorization: Bearer <access_token>`
+- Body（示例：立即禁用）：
+
+```json
+{ "to_status": "disabled", "reason": "security patch" }
+```
+
+- Body（示例：延迟生效）：
+
+```json
+{ "to_status": "disabled", "effective_at": "2026-02-01T00:00:00Z", "reason": "maintenance window" }
+```
+
+#### 4.2.5 审批上下线申请单
+
+**GET** `/platform/app-status-change-requests?status=pending&page=1&page_size=20`
+
+**POST** `/platform/app-status-change-requests/{request_id}/approve`
+
+**POST** `/platform/app-status-change-requests/{request_id}/reject?reason=...`
+
+#### 4.2.6 删除 App（软删除）
+
+**DELETE** `/platform/apps/{app_id}`
+
+- Tag：`App`
+- Header：`Authorization: Bearer <access_token>`
+- 二次验证（可选但建议生产启用）：
+  - 若设置环境变量 `IAM_SENSITIVE_ACTION_TOKEN`，则必须同时传 Header：`X-Sensitive-Token: <token>`，否则返回 403。
+
 ### Step 5：列出用户（User）
 
 **GET** `/users?page=1&page_size=20`
@@ -272,3 +350,25 @@ enabled_apps 维护建议：
 - `/auth/login`：约 2 req/s，burst 10（同一 IP）
 - `/auth/register`：约 1 req/s，burst 5（同一 IP）
 - 触发后返回：HTTP 429 + `code=40000`
+
+## 密码重置（User）
+
+用户自助重置（需要旧密码）：
+
+- **POST** `/users/me/password/reset`
+- Tag：`User`
+- Header：`Authorization: Bearer <access_token>`
+- Body：
+
+```json
+{ "current_password": "oldPassword123", "new_password": "newPassword456" }
+```
+
+租户管理员重置任意用户（生成临时密码）：
+
+- **POST** `/users/{id}/password/reset`
+- Tag：`User`
+- Header：`Authorization: Bearer <access_token>`
+- 权限：需要 `user:password:reset:any`
+- 二次验证（可选但建议生产启用）：
+  - 若设置环境变量 `IAM_SENSITIVE_ACTION_TOKEN`，则必须传 Header：`X-Sensitive-Token: <token>`，否则返回 403。