文档纲要
MuoCeon 开发者文档的全貌：定位、面向读者、板块划分、板块导读入口、阅读路径与书写约定。
这里是 MuoCeon 的开发者文档。所有对外接入的协议、流程与约定都集中在这里，作为唯一的对外口径：你在邮件、群聊或示例代码里看到的说法，与这里冲突时，以这里为准。
这份文档是什么
它是一份契约文档，不是教程合集。它只描述外部可观察的行为：端点地址、请求参数、响应结构、错误码、边界条件。
它刻意不描述内部实现——不写数据库表结构、不写缓存键名、不写内部服务调用链。原因很实际：内部实现随时可能重构，而一旦写进对外文档，重构就变成了「破坏兼容性」。你只需要知道「我发什么，服务器回什么」。
| 是 | 不是 |
|---|---|
| 对外接口的稳定约定 | 内部架构说明 |
| 可验证的步骤与预期结果 | 泛泛而谈的概念科普 |
| 出错时的判定依据 | 排障工单系统 |
面向谁
| 读者 | 关心的事 | 建议起点 |
|---|---|---|
| 外部开发者 | 让自己的应用接入 MuoCeon 账号登录 | 接入指南 |
| 服务端开发者 | 校验令牌、调用受保护资源、处理错误 | 令牌、错误码 |
| 移动端 / 桌面端开发者 | 无密钥客户端如何安全地拿到令牌 | 回调地址规则 |
| 产品与运营 | 接入前要准备什么、审核关注什么 | 申请客户端 |
| 普通用户 | 授权页在问什么、怎么取消授权 | 常见问题 |
不需要读过 MuoCeon 的源码，也不需要了解它的内部结构。
文档板块
文档按板块组织，每个板块解决一类问题，彼此不重叠：
| 板块 | 回答的问题 | 内容形态 | 导读 |
|---|---|---|---|
| 介绍 | 这份文档覆盖什么、我该从哪读起 | 纲要、板块导读、阅读路径、书写约定 | 本页 |
| 接入指南 | 我怎么从零接上，每一步怎么验证 | 分步骤、带示例、每步有预期结果 | 接入指南导读 |
| API 文档 | 某个端点/字段的精确含义是什么 | 参数表、响应示例、字段约束 | API 文档导读 |
| 常见问题 | 我卡住了/用户疑惑了，先看这里 | 问题—原因—解决办法，面向不同读者分层 | 常见问题导读 |
当前接入指南内容最完整：第三方 OAuth 接入的全部内容（申请、流程、权限与安全、端点与错误码）都在其中。API 文档先给出总览、版本与上下文的骨架，逐字段的接口文档会按上下文补充；常见问题已覆盖普通用户与开发者的高频疑问。
板块导读
「介绍」不是一页，而是四页：本页给全貌，另外三页分别讲清每个板块装了什么、按什么顺序读、哪些内容不在其中。
| 导读 | 讲什么 | 什么时候读 |
|---|---|---|
| 接入指南导读 | 接入指南的四组内容、页面依赖关系、三步走的顺序 | 决定开始接入之前 |
| API 文档导读 | API 文档与接入指南的分工、按版本与上下文怎么查字段、参数表的读法 | 需要精确字段定义时 |
| 常见问题导读 | 面向用户与面向开发者的分界、按现象和错误码检索的方式 | 卡住，或用户来问时 |
三页都不长，但每一页都会明确写出「哪些内容不在这个板块里」——知道边界，比知道目录更有用。
阅读路径
文档不需要从头读到尾。按你的处境选一条：
第一次接入，想尽快跑通
- 本页，确认文档范围；
- 第三方 OAuth 接入，认清三个角色；
- 申请客户端与登记回调，拿到凭证；
- 快速开始，十五分钟跑通一次完整流程；
- 收尾时读令牌，把校验做扎实。
已经在接，但一直报错
要做移动端或桌面端
要理解安全边界
按顺序读 Scope 与受众 → 回调地址规则 → 认证强度 → 令牌。
书写约定
文档中的地址一律用占位符，接入时替换为你的实际值：
| 占位符 | 含义 |
|---|---|
{issuer} | 授权服务器标识，例如 https://id.example.com/v1/oauth |
{origin} | {issuer} 的源，例如 https://id.example.com |
{consentUi} | 同意页地址，从元数据的 authorization_endpoint 读取 |
{clientId} / {clientSecret} | 你在开发者平台登记后获得的凭证 |
三条通用约定：
- 以元数据为准：域名、路径、支持的算法都可能随部署变化，写代码时从元数据发现读取，不要照抄示例里的域名。
- 示例是示意，不是契约：示例中的令牌、
sub、state都是假值；契约由参数表和字段说明定义。 - 能力有边界：文档会明确写出「第三方不适用」的能力（如令牌交换、细粒度授权），不要试图绕过——服务端会直接拒绝。
变更与反馈
- 文档随接口演进同步更新；接口行为变更会在对应页面注明影响面。
- 发现文档与实际行为不一致，按「文档写错了」来报，不要按「照文档做失败」来绕过——前者会被修正，后者会留下一个长期隐患。
- 开发者平台尚未上线，创建客户端目前走人工登记；上线后申请流程与字段不变，见申请客户端。