开发者指南
OAuth 数据格式
OAuth 数据格式规范
版本: v1.2 最后更新: 2026-02-02 状态: ✅ 生效中
2026-02-02 更新: 新增 Profile 更新端点（PATCH /profile）、头像上传端点（POST /avatar）
1. API 响应字段命名规范
1.1 后端 API (snake_case)
所有 Microcosm 后端 API 返回的字段使用 snake_case 命名:
json
{
"uid": "abc123",
"email": "user@example.com",
"display_name": "用户昵称",
"avatar_url": "https://...",
"api_keys_configured": false,
"created_at": "2026-01-16T00:00:00Z"
}
1.2 前端 User 类型 (camelCase)
前端 SDK 和应用代码使用 camelCase 命名:
typescript
interface User {
uid: string
email: string
displayName: string | null
avatarUrl: string | null
apiKeysConfigured: boolean
createdAt: string
}
2. 字段映射表
| API 响应 (snake_case) | 前端类型 (camelCase) | 类型 | 必填 |
|---|---|---|---|
uid | uid | string | ✅ |
email | email | string | ✅ |
display_name | displayName | string | null | ❌ |
avatar_url | avatarUrl | string | null | ❌ |
api_keys_configured | apiKeysConfigured | boolean | ❌ |
role | role | string | ✅ |
created_at | createdAt | string (ISO 8601) | ❌ |
3. API 响应格式
3.1 Profile API 响应
端点: /api/users/profile 或 /v1/users/me/profile
json
{
"success": true,
"user": {
"uid": "abc123",
"email": "user@example.com",
"display_name": "用户昵称",
"avatar_url": "data:image/png;base64,iVBORw0...",
"api_keys_configured": false,
"role": "user"
}
}
3.2 Token Exchange 响应
端点: /api/oauth/token
json
{
"access_token": "eyJhbGci...",
"refresh_token": "dGhpcyBp...",
"token_type": "Bearer",
"expires_in": 3600,
"user_id": "abc123"
}
注意: user_id 仅作为备选，优先使用 Profile API 获取完整用户信息。
4. OAuth Callback 处理规范
4.1 数据解包
API 响应可能有两种格式，必须兼容处理:
typescript
// 格式 1: 包装格式
{ "success": true, "user": { ... } }
// 格式 2: 直接格式
{ "uid": "...", "email": "...", ... }
// 兼容处理
const userData = responseData.user || responseData
4.2 setUser 必填字段
OAuth callback 中调用 authManager.setUser() 时，必须传递以下字段:
| 字段 | 重要性 | 遗漏后果 |
|---|---|---|
uid | 必须 | 无法识别用户 |
email | 必须 | 无法显示邮箱 |
role | 必须 | 权限判断失败 |
displayName | 必须 | 侧边栏显示 "User" |
avatarUrl | 必须 | 显示默认头像 |
apiKeysConfigured | 推荐 | API Key 状态显示错误 |
4.3 正确示例
typescript
authManager.setUser({
uid: userData.uid,
email: userData.email || "",
role: userData.role || "user",
displayName: userData.display_name || null, // snake_case → camelCase
avatarUrl: userData.avatar_url || null, // snake_case → camelCase
apiKeysConfigured: userData.api_keys_configured || false,
})
5. OIDC Scope 映射 (2026-01-18)
5.1 问题背景
OpenID Connect 标准使用 openid profile email 等 scope，而 Microcosm Open API 使用自定义 scope（如 user:read）。这导致使用标准 OIDC scope 的 OAuth Token 无法访问用户 API（返回 403 Forbidden）。
例外: admin 角色自动绕过 scope 检查，因此管理员用户不受影响，容易掩盖此问题。
5.2 Scope 别名映射
Open API v1.1.2 实现了自动映射:
| OIDC Scope | 映射到 Microcosm Scope | 说明 |
|---|---|---|
profile | user:read | 可访问用户资料 API |
openid | - | 仅用于 OIDC 身份验证 |
email | - | 仅用于获取邮箱声明 |
5.3 影响
- 使用
scope: "openid profile email"的 Token 可以调用用户资料 API - 无需客户端修改，服务端自动映射
- 所有使用 OAuth 接入的生态项目受益
6. Profile 更新端点 (2026-02-02 新增)
6.1 更新用户资料
端点: PATCH /api/users/profile
请求体:
json
{
"display_name": "新昵称"
}
响应:
json
{
"success": true,
"user": {
"uid": "abc123",
"display_name": "新昵称"
}
}
字段验证:
| 字段 | 类型 | 限制 | 说明 |
|---|---|---|---|
display_name | string | 1-50 字符 | 用户昵称 |
6.2 上传头像
端点: POST /api/users/avatar
请求格式: multipart/form-data
字段:
| 字段 | 类型 | 限制 | 说明 |
|---|---|---|---|
avatar | file | 最大 2MB | 支持 JPG/PNG/GIF/WebP |
响应:
json
{
"success": true,
"avatar_url": "https://storage.googleapis.com/double-helix-avatars/avatars/{uid}/avatar.jpg"
}
处理逻辑:
- 图片自动压缩到 512×512 像素
- 自动转换为 JPEG 格式（85% 质量）
- 存储到 GCS Bucket，覆盖旧头像
- 返回公开访问 URL
6.3 获取头像
端点: GET /api/users/avatar
响应:
json
{
"success": true,
"avatar_url": "https://storage.googleapis.com/double-helix-avatars/avatars/{uid}/avatar.jpg"
}
7. 版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| v1.2 | 2026-02-02 | 新增 Profile 更新和头像上传端点说明 |
| v1.1 | 2026-01-18 | 新增 OIDC Scope 映射说明 |
| v1.0 | 2026-01-16 | 初始版本，基于 Double Helix 集成经验 |
单一真相源 (Single Source of Truth)
询问 AI