Appearance
权限与作用域
三维度权限模型
系统权限由三个维度组成：资源 : 操作 : 作用域
资源
| 资源 | 说明 |
|---|---|
user | 用户 |
character | AI 角色 |
user_character_config | 用户角色配置 |
conversation | 对话 |
project | 项目 |
canvas | 画布 |
file | 文件 |
skill | 技能 |
node_group | 节点组 |
favorite | 收藏 |
generator | 生成器 |
generation | 生成任务 |
bundle | 充值套餐 |
payment | 充值交易 |
transaction_log | 交易流水 |
invite_code | 邀请码 |
| ... | 其他系统资源 |
操作
| 操作 | 说明 |
|---|---|
create | 创建 |
read | 读取 |
update | 修改 |
delete | 删除 |
作用域
| 作用域 | 说明 | 使用者 |
|---|---|---|
own | 自有资源 | 所有用户 |
public | 公开资源 | 所有用户（只读） |
all | 全部资源 | 仅管理员 |
scope 查询参数
列表端点通过 scope 查询参数控制返回范围：
GET /api/v1/characters?scope=own # 只返回自己创建的角色
GET /api/v1/characters?scope=public # 返回所有公开角色
GET /api/v1/characters?scope=all # 返回所有角色（仅管理员）默认值
大部分端点默认 scope=own。
权限检查
| 操作 | scope=own | scope=public | scope=all |
|---|---|---|---|
| 列表查询 | 自有资源 | 公开资源 | 全部资源（管理员） |
| 单个查询 | 自有 | 公开 | 任意（管理员） |
| 创建 | 当前用户为所有者 | — | — |
| 修改 | 仅所有者 | — | 管理员 |
| 删除 | 仅所有者 | — | 管理员 |
公开资源
资源通过 visibility 字段控制公开状态：
visibility: "private"（默认）— 仅创建者可访问visibility: "public"— 所有用户可读（scope=public），但只有创建者可修改/删除
管理员权限
管理员拥有通配符权限，可以：
- 通过
scope=all查看和管理所有用户的资源 - 修改其他用户的信息和权限
- 访问管理员专属端点（服务器配置、JWT 密钥等）
- 修改和删除其他用户的资源
常见权限错误
| 场景 | 状态码 | 说明 |
|---|---|---|
| Token 缺失或无效 | 401 | 需要重新登录 |
| 普通用户使用 scope=all | 403 | 需要管理员权限 |
| 访问他人的私有资源 | 404 | 出于安全考虑，返回 404 而非 403 |
| 修改他人的公开资源 | 403 | 公开资源只有创建者可修改 |
| 账号被封禁 | 403 | 即使 Token 有效也被拒绝 |
安全说明
系统对不存在的资源和无权限访问的资源统一返回 404，避免泄露资源存在性。测试时需注意区分"资源真的不存在"和"无权限访问"两种情况。
测试要点
测试建议
- scope 交叉测试：每个列表端点分别测试 own/public/all 三种 scope
- 404 统一性：无权限和不存在应返回相同的 404
- 公开资源只读：非创建者只能 GET 公开资源，PATCH/DELETE 应被拒绝
- 管理员全权：管理员应能操作所有用户的资源
- 角色降权：移除管理员权限后应立即失去管理能力
- 新注册用户：默认权限是否正确（应有 own 和 public 访问权）