518 lines
20 KiB
Markdown
518 lines
20 KiB
Markdown
# Plan: 管理员审核 + Hermes 同步工作流
|
||
|
||
**Status:** active
|
||
**Created:** 2026-06-21
|
||
**Origin:** docs/brainstorms/2026-06-20-hermes-cross-machine-deploy-requirements.md (演进)
|
||
**Plan depth:** Standard
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
实现「管理员审核 + 管理员发起 Hermes 同步」的新工作流。角色创建后进入待审核状态，管理员后台审核通过后填写同步参数（profile 名、主 model key/服务商、多媒体 model key/服务商、定时任务开关），EternalAI 用一次性 sync_token 向 Hermes 发起同步请求，Hermes 回调拉取文件并创建 profile，返回绑定二维码。测试范围限定为鉴权和文件拉取（无真实 Hermes，用 mock 端点验证）。
|
||
|
||
---
|
||
|
||
## Problem Frame
|
||
|
||
当前流程：创作者创建角色后直接上架，用户自行用 API Key + curl 拉取配置到 Hermes。存在以下问题：
|
||
1. 缺少内容审核环节，任何人设都可直接发布
|
||
2. 同步由用户手动操作，无法集中管控
|
||
3. Hermes 配置参数（model key、服务商等）分散在用户侧，不一致
|
||
|
||
新流程：管理员集中审核 + 管理员发起同步 + Hermes 回调拉取 + 二维码绑定。
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### 功能需求
|
||
|
||
- **R1**: 角色创建后状态为 `pending_review`，需管理员审核才能上架
|
||
- **R2**: 独立 Admin 表，管理员有独立登录入口
|
||
- **R3**: 管理员后台可查看待审核列表、角色详情，通过/驳回
|
||
- **R4**: 审核通过后管理员填写同步参数并发起同步
|
||
- **R5**: EternalAI 用一次性 sync_token（HMAC SHA-256 对称密钥）向 Hermes POST 同步请求
|
||
- **R6**: Hermes 用 sync_token 回调 EternalAI 拉取 SOUL.md 和 config.yaml
|
||
- **R7**: Hermes 返回二维码 URL，EternalAI 存储并展示给管理员和创作者
|
||
- **R8**: Hermes webhook URL 全局配置，同步时可覆盖
|
||
- **R9**: 测试范围：鉴权（admin 登录、sync_token 验证）+ 文件拉取（mock Hermes 回调）
|
||
|
||
### 非功能需求
|
||
|
||
- sync_token 5 分钟过期，一次性消费
|
||
- Hermes 回调拉取端点同时支持 sync_token 和现有 API Key 认证
|
||
- 现有用户侧 API Key 拉取流程保留不变
|
||
|
||
---
|
||
|
||
## Key Technical Decisions
|
||
|
||
### KTD1: 独立 Admin 表
|
||
|
||
Admin 与 User 分离，独立登录接口，不混用 JWT。
|
||
|
||
**理由**: 用户选择。管理员权限边界清晰，避免 User 表 isAdmin 字段的权限提升风险。
|
||
|
||
### KTD2: sync_token 用 HMAC SHA-256 对称密钥
|
||
|
||
EternalAI 和 Hermes 预共享 `SYNC_SECRET`，sync_token 是 JWT（HS256），payload 含 `roleId`、`adminId`、`iat`、`exp`（5 分钟）。
|
||
|
||
**理由**: 用户选择。对称密钥实现简单，双方预共享即可。
|
||
|
||
### KTD3: Hermes webhook URL 全局配置 + 可覆盖
|
||
|
||
系统设置表存储 `HERMES_WEBHOOK_URL`，管理员发起同步时可在表单中覆盖。
|
||
|
||
**理由**: 用户选择。大多数情况用全局配置，特殊场景可覆盖。
|
||
|
||
### KTD4: 二维码由 Hermes 生成返回
|
||
|
||
Hermes 创建 profile 后生成二维码 URL 返回给 EternalAI，EternalAI 存储到 Role 记录并展示。
|
||
|
||
**理由**: 用户选择。二维码内容（微信绑定链接）由 Hermes 侧定义。
|
||
|
||
### KTD5: 角色审核状态机
|
||
|
||
```
|
||
pending_review → approved → syncing → synced
|
||
pending_review → rejected
|
||
syncing → failed
|
||
```
|
||
|
||
Role 模型新增 `reviewStatus` 字段（默认 `pending_review`），新增 `qrCodeUrl`、`syncedAt` 字段。
|
||
|
||
### KTD6: Mock Hermes 测试端点
|
||
|
||
在 EternalAI 内部创建 `/api/mock-hermes/*` 端点模拟 Hermes 行为：接收同步请求、用 sync_token 回调拉取文件、返回 mock 二维码。仅测试环境启用。
|
||
|
||
---
|
||
|
||
## High-Level Technical Design
|
||
|
||
### 同步流程时序图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin as 管理员
|
||
participant EAI as EternalAI
|
||
participant Hermes as Hermes (Mock)
|
||
|
||
Admin->>EAI: POST /api/admin/sync/:roleId
|
||
Note over EAI: 生成 sync_token (JWT, 5min)
|
||
EAI->>Hermes: POST {webhook_url} /api/sync
|
||
Note over EAI: Body: { profileName, modelKey,<br/>provider, multimediaModelKey,<br/>multimediaProvider, enableSchedule,<br/>sync_token, file_pull_base_url }
|
||
Hermes->>Hermes: 验证 sync_token 签名
|
||
Hermes->>EAI: GET /api/hermes/roles/:id/SOUL.md
|
||
Note over Hermes: Header: X-Sync-Token
|
||
EAI->>EAI: 验证 sync_token (签名+过期+未消费)
|
||
EAI-->>Hermes: SOUL.md content
|
||
Hermes->>EAI: GET /api/hermes/roles/:id/config.yaml
|
||
Note over Hermes: Header: X-Sync-Token
|
||
EAI-->>Hermes: config.yaml content
|
||
Note over Hermes: 创建 profile, 生成二维码
|
||
Hermes-->>EAI: 200 { qrCodeUrl, profileId }
|
||
Note over EAI: 存储 qrCodeUrl, 更新 reviewStatus=synced
|
||
EAI-->>Admin: 200 { qrCodeUrl, reviewStatus }
|
||
```
|
||
|
||
### 角色审核状态机
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> pending_review : 创建角色
|
||
pending_review --> approved : 管理员通过
|
||
pending_review --> rejected : 管理员驳回
|
||
approved --> syncing : 管理员发起同步
|
||
syncing --> synced : Hermes 返回成功
|
||
syncing --> failed : 同步失败/超时
|
||
failed --> syncing : 重新同步
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### U1. Admin 数据模型与认证
|
||
|
||
**Goal:** 创建独立 Admin 表，实现管理员注册/登录/中间件。
|
||
|
||
**Requirements:** R2
|
||
|
||
**Dependencies:** 无
|
||
|
||
**Files:**
|
||
- `prisma/schema.prisma` — 新增 Admin 模型
|
||
- `src/lib/auth.js` — 新增 `adminSignToken`、`adminVerifyToken`、`adminAuthMiddleware`
|
||
- `src/routes/admin-auth.js` — 新建，管理员登录路由
|
||
- `server.js` — 注册 `/api/admin-auth` 路由
|
||
- `e2e/admin-auth.spec.js` — 新建，管理员认证测试
|
||
|
||
**Approach:**
|
||
- Admin 模型：`id`、`account`（唯一）、`password`（bcrypt）、`createdAt`
|
||
- Admin JWT 与用户 JWT 使用不同 secret（`ADMIN_JWT_SECRET`），防止跨角色伪造
|
||
- `adminAuthMiddleware` 验证 Admin JWT，设置 `req.adminId`
|
||
- 管理员账号通过 `prisma db seed` 或 CLI 脚本创建，不开放注册 API
|
||
|
||
**Test scenarios:**
|
||
- 管理员登录成功，返回 admin JWT
|
||
- 管理员登录密码错误，返回 401
|
||
- 无 token 访问管理员接口，返回 401
|
||
- 用户 JWT 访问管理员接口，返回 403（secret 不同，验证失败）
|
||
- 管理员 JWT 访问用户接口，返回 401（用户中间件不识别 admin token）
|
||
|
||
**Verification:** 管理员可登录，admin JWT 可访问管理员接口，用户 JWT 不可访问管理员接口。
|
||
|
||
---
|
||
|
||
### U2. 角色审核状态机与审核 API
|
||
|
||
**Goal:** Role 模型新增审核状态字段，实现审核 API。
|
||
|
||
**Requirements:** R1, R3
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `prisma/schema.prisma` — Role 模型新增 `reviewStatus`、`qrCodeUrl`、`syncedAt`、`reviewNote` 字段
|
||
- `src/routes/admin.js` — 新建，管理员审核路由
|
||
- `server.js` — 注册 `/api/admin` 路由
|
||
- `e2e/admin-review.spec.js` — 新建，审核流程测试
|
||
|
||
**Approach:**
|
||
- `reviewStatus` 枚举值：`pending_review`（默认）、`approved`、`rejected`、`syncing`、`synced`、`failed`
|
||
- 现有 `POST /api/roles` 创建角色时自动设置 `reviewStatus = 'pending_review'`
|
||
- `GET /api/admin/reviews` — 待审核列表（分页，按 createdAt desc）
|
||
- `GET /api/admin/reviews/:roleId` — 角色详情（含所有字段）
|
||
- `POST /api/admin/reviews/:roleId/approve` — 通过审核，状态 → `approved`
|
||
- `POST /api/admin/reviews/:roleId/reject` — 驳回，状态 → `rejected`，body 含 `reviewNote`
|
||
- 角色库 `GET /api/roles` 只返回 `reviewStatus = 'synced'` 的角色（已同步完成才上架）
|
||
|
||
**Test scenarios:**
|
||
- 创建角色后 reviewStatus 为 pending_review
|
||
- 管理员获取待审核列表，包含 pending_review 角色
|
||
- 管理员通过审核，状态变为 approved
|
||
- 管理员驳回审核，状态变为 rejected，reviewNote 有值
|
||
- 非管理员调用审核接口，返回 401
|
||
- 角色库不显示 pending_review / approved / rejected 状态的角色
|
||
|
||
**Verification:** 审核状态流转正确，非管理员无法操作。
|
||
|
||
---
|
||
|
||
### U3. sync_token 机制与系统配置
|
||
|
||
**Goal:** 实现 sync_token 生成/验证，系统配置存储 Hermes webhook URL。
|
||
|
||
**Requirements:** R5, R8
|
||
|
||
**Dependencies:** U1
|
||
|
||
**Files:**
|
||
- `prisma/schema.prisma` — 新增 SystemConfig 模型（key-value 存储）
|
||
- `src/lib/sync-token.js` — 新建，sync_token 生成与验证
|
||
- `src/routes/admin-config.js` — 新建，系统配置管理路由
|
||
- `server.js` — 注册 `/api/admin/config` 路由
|
||
- `e2e/sync-token.spec.js` — 新建，sync_token 测试
|
||
|
||
**Approach:**
|
||
- SystemConfig 模型：`key`（唯一）、`value`、`updatedAt`
|
||
- 预置配置项：`HERMES_WEBHOOK_URL`、`SYNC_SECRET`
|
||
- `sync-token.js`:
|
||
- `generateSyncToken(roleId, adminId)` — 生成 JWT（HS256），payload `{ roleId, adminId, iat, exp }`，5 分钟过期
|
||
- `verifySyncToken(token)` — 验证签名 + 过期，返回 payload 或 null
|
||
- 使用 `SYNC_SECRET` 从 SystemConfig 读取（首次启动自动生成）
|
||
- `PUT /api/admin/config/:key` — 更新配置项（仅管理员）
|
||
- `GET /api/admin/config` — 获取所有配置（仅管理员，敏感值脱敏）
|
||
|
||
**Test scenarios:**
|
||
- 生成 sync_token，验证签名通过，payload 正确
|
||
- 过期 token（>5min）验证失败
|
||
- 篡改 payload 后验证失败（签名不匹配）
|
||
- 管理员更新 HERMES_WEBHOOK_URL，再次读取值正确
|
||
- 非管理员访问配置接口，返回 401
|
||
|
||
**Verification:** sync_token 生成/验证正确，系统配置可读写。
|
||
|
||
---
|
||
|
||
### U4. 同步发起 API
|
||
|
||
**Goal:** 管理员发起同步，EternalAI 向 Hermes POST 请求。
|
||
|
||
**Requirements:** R4, R5, R6
|
||
|
||
**Dependencies:** U2, U3
|
||
|
||
**Files:**
|
||
- `src/routes/admin-sync.js` — 新建，同步发起路由
|
||
- `src/lib/hermes-client.js` — 新建，Hermes HTTP 客户端
|
||
- `server.js` — 注册 `/api/admin/sync` 路由
|
||
- `e2e/admin-sync.spec.js` — 新建，同步发起测试
|
||
|
||
**Approach:**
|
||
- `POST /api/admin/sync/:roleId` — 发起同步
|
||
- Body: `{ profileName, modelKey, provider, multimediaModelKey, multimediaProvider, enableSchedule, webhookUrl? }`
|
||
- `webhookUrl` 可选，未提供则用 SystemConfig 中的 `HERMES_WEBHOOK_URL`
|
||
- 前置检查：`reviewStatus` 必须为 `approved` 或 `failed`
|
||
- 生成 sync_token，更新 `reviewStatus = 'syncing'`
|
||
- 调用 `hermes-client.js` 的 `postSync(webhookUrl, payload)` 向 Hermes POST
|
||
- Hermes 返回 `{ qrCodeUrl, profileId }` → 存储 `qrCodeUrl`，更新 `reviewStatus = 'synced'`，记录 `syncedAt`
|
||
- Hermes 返回错误 → 更新 `reviewStatus = 'failed'`
|
||
- 请求超时（30s）→ 更新 `reviewStatus = 'failed'`
|
||
- `hermes-client.js`:
|
||
- `postSync(webhookUrl, payload)` — 用 `fetch` POST 到 Hermes，payload 含 sync_token 和 file_pull_base_url
|
||
- `file_pull_base_url` = EternalAI 自身的基础 URL（从 SystemConfig 读取 `ETERNALAI_BASE_URL`）
|
||
|
||
**Test scenarios:**
|
||
- 管理员对 approved 角色发起同步，reviewStatus 变为 syncing
|
||
- Mock Hermes 返回成功，reviewStatus 变为 synced，qrCodeUrl 有值
|
||
- Mock Hermes 返回错误，reviewStatus 变为 failed
|
||
- 对 pending_review 角色发起同步，返回 400
|
||
- 对 syncing 角色发起同步，返回 409（重复同步）
|
||
- 非管理员发起同步，返回 401
|
||
|
||
**Verification:** 同步发起后状态流转正确，成功时存储二维码 URL。
|
||
|
||
---
|
||
|
||
### U5. Hermes 回调拉取端点改造
|
||
|
||
**Goal:** 改造现有 `/api/hermes/` 端点，支持 sync_token 认证。
|
||
|
||
**Requirements:** R6
|
||
|
||
**Dependencies:** U3
|
||
|
||
**Files:**
|
||
- `src/routes/hermes.js` — 改造，新增 sync_token 认证路径
|
||
- `src/lib/auth.js` — 新增 `syncTokenMiddleware`
|
||
- `e2e/hermes-callback.spec.js` — 新建，回调拉取测试
|
||
|
||
**Approach:**
|
||
- 新增 `syncTokenMiddleware`:
|
||
- 读取 `X-Sync-Token` header
|
||
- 验证 sync_token 签名 + 过期
|
||
- 从 payload 提取 `roleId`，与 URL 中的 `:id` 比对，不一致返回 403
|
||
- 验证通过后设置 `req.userId`（通过 Role.creatorId 反查）和 `req.syncTokenPayload`
|
||
- 改造 `apiKeyMiddleware` 逻辑：
|
||
- 优先检查 `X-Sync-Token` header → 走 sync_token 路径
|
||
- 否则检查 `Authorization: Bearer eak_` → 走 API Key 路径
|
||
- 否则检查 `Authorization: Bearer <jwt>` → 走 JWT 路径
|
||
- sync_token 消费后标记为已使用（内存 Set，5 分钟后自动清理；或用 token jti + 短期缓存）
|
||
- SOUL.md 和 config.yaml 端点保持 text/plain 响应不变
|
||
|
||
**Test scenarios:**
|
||
- 用有效 sync_token 拉取 SOUL.md，返回 200 + 文件内容
|
||
- 用有效 sync_token 拉取 config.yaml，返回 200 + 文件内容
|
||
- sync_token 中的 roleId 与 URL :id 不匹配，返回 403
|
||
- 过期 sync_token，返回 401
|
||
- 已消费的 sync_token 再次使用，返回 401
|
||
- 无 token 访问，返回 401
|
||
- 用 API Key（eak_）访问仍正常工作（向后兼容）
|
||
|
||
**Verification:** sync_token 可拉取文件，向后兼容 API Key 认证。
|
||
|
||
---
|
||
|
||
### U6. 二维码存储与状态展示
|
||
|
||
**Goal:** 存储 Hermes 返回的二维码 URL，展示给管理员和创作者。
|
||
|
||
**Requirements:** R7
|
||
|
||
**Dependencies:** U4
|
||
|
||
**Files:**
|
||
- `src/routes/roles.js` — 改造，`GET /api/roles/my/roles` 返回 reviewStatus 和 qrCodeUrl
|
||
- `src/routes/admin.js` — 改造，管理员可查看所有角色的同步状态
|
||
- `app.js` — 改造，创作者角色卡片显示审核状态和二维码
|
||
- `e2e/qr-display.spec.js` — 新建，二维码展示测试
|
||
|
||
**Approach:**
|
||
- `GET /api/roles/my/roles` 返回字段新增 `reviewStatus`、`qrCodeUrl`、`syncedAt`
|
||
- 创作者角色卡片根据 reviewStatus 显示状态标签：
|
||
- `pending_review` → "待审核"（灰色）
|
||
- `approved` → "已通过，等待同步"（蓝色）
|
||
- `syncing` → "同步中"（黄色）
|
||
- `synced` → "已同步"（绿色）+ 显示二维码
|
||
- `failed` → "同步失败"（红色）
|
||
- `rejected` → "已驳回"（红色）
|
||
- synced 状态的角色卡片显示二维码图片（`qrCodeUrl`）和"转发二维码"按钮
|
||
- 管理员后台有"同步状态"页面，显示所有角色的审核+同步状态
|
||
|
||
**Test scenarios:**
|
||
- 创作者查看自己的角色列表，pending_review 角色显示"待审核"标签
|
||
- 同步成功后，创作者角色卡片显示二维码图片
|
||
- 驳回角色显示"已驳回"标签
|
||
- 管理员查看同步状态列表，包含所有角色的 reviewStatus
|
||
|
||
**Verification:** 创作者和管理员都能看到正确的审核状态和二维码。
|
||
|
||
---
|
||
|
||
### U7. 管理员后台 UI
|
||
|
||
**Goal:** 管理员登录页 + 审核列表 + 角色详情审核页 + 同步表单。
|
||
|
||
**Requirements:** R2, R3, R4
|
||
|
||
**Dependencies:** U1, U2, U4
|
||
|
||
**Files:**
|
||
- `index.html` — 新增管理员视图（admin-login、admin-reviews、admin-sync）
|
||
- `app.js` — 新增管理员路由、审核交互、同步表单
|
||
- `styles.css` — 管理员后台样式
|
||
- `e2e/admin-ui.spec.js` — 新建，管理员 UI 测试
|
||
|
||
**Approach:**
|
||
- 管理员入口：首页底部隐藏链接 `/admin`，或直接访问 `#admin-login`
|
||
- 管理员登录页：账号 + 密码，登录后跳转 `#admin-reviews`
|
||
- 审核列表页：表格显示角色名、创作者、创建时间、状态；点击进入详情
|
||
- 角色详情审核页：显示所有角色字段，"通过"和"驳回"按钮
|
||
- 同步表单（审核通过后显示）：
|
||
- profile 名字（text，默认角色名）
|
||
- 主 model 服务商（select：openrouter / together / local）
|
||
- 主 model key（password input）
|
||
- 多媒体 model 服务商（select）
|
||
- 多媒体 model key（password input）
|
||
- 是否开启定时任务（checkbox）
|
||
- Hermes webhook URL（text，默认全局配置值，可覆盖）
|
||
- "发起同步"按钮
|
||
- 同步成功后显示二维码图片和"复制链接"按钮
|
||
|
||
**Test scenarios:**
|
||
- 管理员登录后跳转审核列表
|
||
- 审核列表显示待审核角色
|
||
- 点击角色进入详情，显示完整信息
|
||
- 通过审核后显示同步表单
|
||
- 填写同步参数并提交，显示同步中状态
|
||
- 同步成功后显示二维码
|
||
|
||
**Verification:** 管理员可完成登录→审核→同步的完整 UI 流程。
|
||
|
||
---
|
||
|
||
### U8. Mock Hermes 测试端点
|
||
|
||
**Goal:** 在 EternalAI 内部创建 mock Hermes 端点，用于测试同步流程。
|
||
|
||
**Requirements:** R9
|
||
|
||
**Dependencies:** U3, U5
|
||
|
||
**Files:**
|
||
- `src/routes/mock-hermes.js` — 新建，mock Hermes 端点
|
||
- `server.js` — 注册 `/api/mock-hermes` 路由（仅非 production 环境）
|
||
- `e2e/mock-hermes.spec.js` — 新建，mock Hermes 集成测试
|
||
|
||
**Approach:**
|
||
- `POST /api/mock-hermes/sync` — 模拟 Hermes 接收同步请求
|
||
- 验证 sync_token 签名（用同一 SYNC_SECRET）
|
||
- 用 sync_token 回调 EternalAI 拉取 SOUL.md 和 config.yaml
|
||
- 返回 mock 二维码 URL：`https://mock.hermes.local/qr/<roleId>`
|
||
- 返回 mock profileId：`mock-profile-<roleId>`
|
||
- Mock 端点用 `fetch` 回调 EternalAI 自身的 `/api/hermes/roles/:id/SOUL.md` 和 `/api/hermes/roles/:id/config.yaml`
|
||
- 回调时携带 `X-Sync-Token` header
|
||
- 仅在 `NODE_ENV !== 'production'` 时注册路由
|
||
|
||
**Test scenarios:**
|
||
- POST /api/mock-hermes/sync 收到请求后，回调拉取 SOUL.md 成功
|
||
- POST /api/mock-hermes/sync 回调拉取 config.yaml 成功
|
||
- 返回 mock 二维码 URL 和 profileId
|
||
- 无效 sync_token，mock Hermes 返回 401
|
||
- production 环境下 /api/mock-hermes 路由不存在（404）
|
||
|
||
**Verification:** Mock Hermes 完整模拟同步流程，可用于 E2E 测试。
|
||
|
||
---
|
||
|
||
### U9. E2E 集成测试：完整审核+同步流程
|
||
|
||
**Goal:** 端到端测试从创建角色到同步成功的完整流程。
|
||
|
||
**Requirements:** R1-R9
|
||
|
||
**Dependencies:** U1-U8
|
||
|
||
**Files:**
|
||
- `e2e/full-sync-flow.spec.js` — 新建，完整流程测试
|
||
|
||
**Approach:**
|
||
测试完整流程：
|
||
1. 创作者注册 → 登录 → 创建角色（状态 pending_review）
|
||
2. 管理员登录 → 查看待审核列表 → 查看详情 → 通过审核
|
||
3. 管理员填写同步参数 → 发起同步
|
||
4. Mock Hermes 接收请求 → 回调拉取文件 → 返回二维码
|
||
5. 创作者查看角色列表 → 看到已同步状态 + 二维码
|
||
6. 管理员查看同步状态 → 看到已同步
|
||
|
||
**Test scenarios:**
|
||
- 完整流程：创建 → 审核 → 同步 → 二维码展示
|
||
- 驳回流程：创建 → 审核 → 驳回 → 创作者看到"已驳回"
|
||
- 同步失败流程：创建 → 审核 → 同步（mock 返回错误）→ 状态 failed → 重新同步
|
||
- 向后兼容：现有 API Key 拉取流程仍正常工作
|
||
|
||
**Verification:** E2E 测试覆盖所有核心路径，全部通过。
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
|
||
- Admin 表与认证
|
||
- 角色审核状态机
|
||
- sync_token 生成/验证/消费
|
||
- 同步发起 API
|
||
- Hermes 回调拉取端点改造（sync_token 认证）
|
||
- 二维码存储与展示
|
||
- 管理员后台 UI
|
||
- Mock Hermes 测试端点
|
||
- E2E 测试（鉴权 + 文件拉取）
|
||
|
||
### Out of Scope
|
||
|
||
- 真实 Hermes 服务器对接（用 mock 代替）
|
||
- 微信公众号/小程序绑定实现（二维码内容由 Hermes 侧定义）
|
||
- 管理员注册 UI（通过 seed 脚本创建）
|
||
- 速率限制（已有 P2 待修复，不在本次范围）
|
||
- 现有 API Key 拉取流程的改造（保持向后兼容）
|
||
|
||
### Deferred to Follow-Up Work
|
||
|
||
- 真实 Hermes 服务器对接（需 Hermes 侧实现 `/api/sync` 端点）
|
||
- 微信绑定流程实现
|
||
- 同步重试机制（指数退避）
|
||
- 同步日志审计
|
||
- 多 Hermes 实例支持
|
||
|
||
---
|
||
|
||
## Risks & Dependencies
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|------|------|------|
|
||
| sync_token 内存消费记录在多实例部署下失效 | 重复消费风险 | 后续可改用 Redis；当前单实例够用 |
|
||
| Mock Hermes 端点误暴露到生产环境 | 安全风险 | 仅 `NODE_ENV !== 'production'` 注册路由 |
|
||
| Hermes 回调时 EternalAI 不可达 | 同步失败 | 同步状态设为 failed，管理员可重试 |
|
||
| sync_token 在传输中被截获 | 5 分钟内可滥用 | HTTPS + 一次性消费 + 短过期 |
|
||
|
||
---
|
||
|
||
## Open Questions
|
||
|
||
- **OQ1**: sync_token 一次性消费用内存 Set 还是数据库表？（计划用内存 Set，单实例部署够用；多实例时改 Redis）
|
||
- **OQ2**: 管理员账号初始创建方式？（计划用 `prisma db seed` 脚本，账号密码从环境变量读取）
|
||
- **OQ3**: EternalAI 自身的基础 URL（`ETERNALAI_BASE_URL`）如何获取？（计划从 SystemConfig 读取，首次部署时配置）
|
||
|
||
---
|
||
|
||
## System-Wide Impact
|
||
|
||
- **数据库**: 新增 Admin、SystemConfig 表；Role 表新增 4 个字段
|
||
- **API**: 新增 `/api/admin-auth`、`/api/admin`、`/api/admin/config`、`/api/admin/sync`、`/api/mock-hermes` 路由组
|
||
- **前端**: 新增 3 个管理员视图，改造创作者角色卡片
|
||
- **认证**: 新增 Admin JWT（独立 secret）和 sync_token（HMAC SHA-256）两套机制
|
||
- **向后兼容**: 现有用户 API Key 拉取流程不变
|