Open API
P2RESTful + GraphQL 双协议，覆盖读与写的主要能力，带完整错误码与速率限制说明。
实现要点：REST 用于通用场景，GraphQL 用于客户端按需取字段，减少移动端流量。API 版本以 URL 前缀区分（/api/v1）。
Module 12 · V2.0 · Open Platform
开放平台与生态
把社区变成平台，让第三方替你长出功能
P2V2.0提升上限与差异化，可延后交付
模块目标
要达成什么
提供 Open API、OAuth 授权、Webhook、机器人框架与主题/插件机制，构建可扩展的生态。
为什么必须存在
社区的需求长尾极长，平台自己不可能全部覆盖。开放能力是把长尾需求外包给生态的高杠杆手段。
功能清单
共 8 个功能点，每个功能点给出实现要点，可直接作为开发任务的描述。
OAuth 2.0 授权
P2第三方应用通过授权码模式获取用户许可，作用域细分（读内容/发帖/评论/管理通知）。
实现要点：用户在授权页可看到应用请求的具体权限；可随时在「已授权应用」中撤销。
Webhook 与事件订阅
P2应用可订阅事件（新帖、新评论、被举报、版主动作），平台推送时带签名。
实现要点：推送带 HMAC 签名与重试机制（指数退避，最多 5 次）；连续失败自动暂停订阅并通知开发者。
机器人（Bot）框架
P2官方机器人账号标记、可编程接口、允许在评论中自动回复。
实现要点：Bot 账号在用户名后标记 [Bot] 且不可隐藏；Bot 的回复不计入 Karma；需在社区规则中明示是否允许 Bot。
主题与插件机制
P2允许社区自定义主题（配色/布局）与启用平台提供的功能插件（如投票、活动、RSS）。
实现要点：插件以能力开关形式提供，不执行第三方代码（避免安全风险），仅做配置与组合。
数据导出与可迁移
P2用户可导出个人全部数据（帖子/评论/投票记录）；社区 Owner 可导出社区内容归档。
实现要点：导出为异步任务，完成后生成下载链接（有效期 24 小时）。这是「数据主权」的体现，也是信任基础。
多端能力
P2RSS/Atom 订阅、PWA 安装、深链接（Deep Link）、分享卡片（OG/微信）。
实现要点：每个社区与帖子都提供 RSS 输出，兼顾老派用户与自动化场景。
开发者门户
P2应用注册、密钥管理、配额查看、调用统计、沙箱环境与文档。
实现要点：沙箱环境使用独立数据副本，避免开发者测试污染生产数据。
交互设计
2 条关键交互的分步流程，按用户体验顺序描述，可直接作为前端开发与可用性测试脚本。
1
创建第三方应用
- 1
进入开发者门户，注册应用并填写回调地址。
- 2
选择所需作用域，系统给出最小权限建议。
- 3
获得 client_id 与 client_secret，进入沙箱调试。
- 4
调试通过后申请上线，平台审核后应用在应用目录中可见。
2
用户授权
- 1
第三方应用跳转到平台授权页，展示应用名称、开发者与所请求权限。
- 2
用户确认后跳回回调地址并携带授权码，应用换取 Token。
- 3
用户可在设置 → 已授权应用中随时撤销，撤销后 Token 立即失效。
业务规则
6 条硬性约束。这些规则应当在服务层强校验，而非仅在前端提示。
R01
默认配额：1000 请求/小时/应用，认证用户可提升至 6000。
R02
读取敏感数据（邮箱）需单独申请并显示用途说明。
R03
Webhook 连续 20 次失败自动暂停，需手动恢复。
R04
不得缓存用户数据超过 24 小时；不得将数据用于模型训练。
R05
Bot 必须显式标注，禁止伪装为人类用户。
R06
数据导出任务 24 小时内最多发起一次。
涉及数据表
本模块涉及的 9 张表。完整字段、索引与说明见「数据表设计」页。
竞品参考
本模块的设计参照了哪些产品，具体参照了什么。
REReddit
成熟的 Open API 生态催生了大量第三方客户端。
DI
Discourse
插件生态丰富，但执行第三方代码带来安全成本。
LE
Lemmy
ActivityPub 联邦是最彻底的开放形态。
V2
V2EX
开放 API 较早，但能力有限，第三方客户端体验一般。
验收指标
本模块交付时应当达到的量化目标。未达标即视为该模块未完成。
API 可用性≥ 99.9%
Webhook 投递成功率≥ 99%（含重试）
授权转化率授权页 → 确认 ≥ 60%
第三方应用数上线 6 个月内 ≥ 20 个活跃应用
避坑清单
竞品踩过的坑，以及本模块在实现时最容易犯的错误。
API 若不从第一天设计版本化，后续破坏性改版会毁掉生态。
允许插件执行任意代码会带来严重的安全与稳定性风险。
Webhook 不做签名校验会被伪造，导致第三方系统被攻击。
配额若不透明，开发者会困惑于「为什么突然被限流」。