用户、权限与审核模型
July 13, 2026 · View on GitHub
本文档说明 AI Shortlink 的账户入口、资源所有权和审核边界。前端是否显示按钮只影响操作体验，所有权限最终由服务端 API 强制执行。
角色
| 角色 | 资源范围 | 管理能力 |
|---|---|---|
user | 仅自己创建的短链、活码、二维码项和统计 | 创建与维护自己的资源，提交审核 |
admin | 全部用户和全部资源 | 用户管理、系统设置、跨用户维护和审核 |
账户还具有 active / disabled 状态。禁用账户不能继续作为有效操作者使用管理端。
登录入口
- Magic Link：向已验证邮箱发送 15 分钟有效的一次性链接。打开链接后需主动确认登录，邮件安全扫描不会提前消费令牌；新邮箱首次登录会创建普通用户。
- GitHub OAuth：可选启动配置。使用 GitHub 已验证邮箱匹配现有账户；新邮箱创建普通用户，不会自动授予管理员角色。
- 可信浏览器一键登录：安装或成功验证后绑定浏览器，适合低摩擦重复访问。
- 恢复 Key：用于 Cookie、设备令牌或常规登录入口不可用时重新绑定账户。
系统可配置 Magic Link 与浏览器一键登录的组合模式。GitHub OAuth 是否显示由启动环境中的 Client ID 和 Client Secret 共同决定。
所有权边界
短链和活码都记录 owner_account_id。活码二维码项通过所属活码继承访问边界。
普通用户只能：
- 列出自己的短链与活码。
- 查看、编辑、删除自己的资源。
- 查看自己资源的统计。
- 维护自己活码下的二维码项。
- 提交自己的资源进入审核流程。
普通用户不能：
- 通过猜测 ID 读取或修改其他用户的资源。
- 操作其他用户活码下的二维码项。
- 访问用户管理、全局系统设置和管理员审核接口。
- 通过更新个人邮箱覆盖系统管理员邮箱。
管理员可以访问和维护全部资源。关键边界由 internal/server/authorization_test.go 的路由级回归测试覆盖。
审核流程
创建或修改
|
v
pending ---------> approved
^ |
| | 再次修改
+------ rejected <--+
- 普通用户创建或修改短链、活码或二维码项后，资源进入
pending。 - 只有管理员可以执行通过、驳回或退回待审。
- 未通过审核的短链不会执行公开跳转。
- 未通过审核的活码或二维码项不会在公开活码页生效。
- 审核通过或驳回后，系统会向资源所有者发送事务通知邮件；驳回邮件会包含审核意见，邮件失败不会回滚已经完成的审核决定。
未来的 AI 审核能力只能提供上下文、风险信号和建议，默认不能替代管理员决定或绕过现有状态机，详见 ROADMAP.md。
二维码样式与下载
短链入口二维码和活码入口二维码支持：
- 经典方块：
classic - 圆角模块：
rounded - 圆点模块：
dots - 前景色：
qr_foreground - 背景色：
qr_background - 中心贴图：
qr_logo_url
公开接口 /qr/short/{code}.svg|png 和 /qr/live/{code}.svg|png 根据资源配置动态渲染。管理端还可以将预览导出为 SVG、PNG 和 WEBP。
中心贴图会占用二维码纠错容量。任何样式、缩放、留白或贴图变更都应同时执行视觉检查与真实解码测试。