权限模型详解

M-Doc 的权限体系包含组织角色、文档可见性和 API Scope 三个维度。

---

组织角色权限矩阵

操作	Owner	Admin	Member	Guest
删除组织	✅	❌	❌	❌
转让组织	✅	❌	❌	❌
修改组织设置	✅	❌	❌	❌
管理成员	✅	✅	❌	❌
创建文档	✅	✅	✅	❌
编辑文档	✅	✅	✅	❌
删除文档	✅	✅	❌	❌
查看 org 文档	✅	✅	✅	✅
查看 private 文档	❌	❌	❌	❌

private 文档仅创建者本人可见。

文档可见性

可见性	未登录用户	组织外用户	Guest	Member+
public	✅	✅	✅	✅
org	❌	❌	✅	✅
private	❌	❌	❌	❌

API Scope 权限

OpenAPI 接口通过 Scope 控制访问权限：

Scope	可访问的接口
read:documents	文档列表、文档详情
read:articles	文章树、文章详情、目录清单、文章内容、语义搜索
write:articles	创建文章、更新文章、删除文章、发布文章
admin:all	以上所有（通配权限）

PAT vs API Key

特性	PAT	API Key
Scope 限制	受限于创建时选择的 Scope	无限制（拥有全部权限）
认证方式	Bearer Token	AWS Signature V4
适用场景	脚本、CI/CD、AI 工具	服务端集成

权限检查流程

对于 OpenAPI 请求，权限检查按以下优先级：

1. UnifiedAuthMiddleware：识别认证类型（PAT / API Key）
    ↓
2. PAT → 验证 Token → 检查 Scope
   API Key → 验证签名 → 跳过 Scope（全权限）
    ↓
3. 设置 user_id 到请求上下文
    ↓
4. 控制器获取 user_id，执行业务权限检查

对于内部 API 请求（/api/*）：

1. AuthMiddleware：验证 JWT Token
    ↓
2. 设置 user_id 到请求上下文
    ↓
3. 控制器/Service 检查组织角色和文档权限