# COCO 星云问题中心 · 项目接入指南

接口规范：1.3.0。面向各项目的服务端/云函数；不需要 MySQL、OSS 或官网管理员密码。

## 1. 地址与接入准备

- [管理后台](http://coco-starcloud.com/issues.html#admin)：管理员添加游戏，填写唯一标识、名称后保存，再点击“生成密钥”。此后可反复点击“查看密钥”并显示/复制。分类、平台、标签自动共用官网规范；提交模板和游戏版本已移除，公开扩展 JSON 保留。
- [OpenAPI 3.1 文件](http://coco-starcloud.com/api-docs/issues-openapi.json)：可导入 Apifox、Postman 或用于客户端生成；工具兼容性需由接入方确认。
- [Node.js SDK](http://coco-starcloud.com/api-docs/coco-issues-client.mjs)：下载后放在服务端项目，Node.js 20+，无额外运行依赖。

推荐的正式 API Base URL（以下路径都拼接在它后面）：

```text
https://api.coco-starcloud.com/coco-starcloud/api/v1
```

服务端保存三个值：`COCO_ISSUES_BASE_URL`、`COCO_GAME_CODE`、`COCO_ISSUES_API_KEY`。API Key 由上述后台创建，管理员可以再次查看；每个游戏使用自己的 Key。Nginx 只挂载 `/coco-starcloud`，`/api/v1` 是应用自身的版本前缀，两段都必须保留。

2026-10-05 服务器证书和 443 已配置，用户放行安全组后，公网已通过严格 CA 与主机名校验建立 TLS 1.3 连接。经上述 HTTPS 入口调用 `/health` 返回 `code=0`、`coco-issues-api` / `v1`，`/games` 返回 `opcg`、`lol-tcg`、`naruto-card`，`/issue-options` 返回统一目录的实际数据。官网公网 API 默认基址采用上述 HTTPS 地址，本地隔离联调仍使用回环地址；API 协议改变不代表官网页面已启用 TLS。原 HTTP 服务端入口仍保留且不强制跳转；不要通过 HTTP 发送 API Key 或其他凭证。TLS 和只读目录成功不等于登录、写入及 SDK 完整认证流程已完成实际运行。

**SDK 限制（构造器于 2026-10-02 核对，HTTPS 入口于 2026-10-05 核实）**：当前 `CocoIssuesClient` 构造器强制 HTTPS，仅允许 localhost/127.0.0.1 的 HTTP 例外。将公网 HTTP 基址传给它仍会立即抛出 `HTTPS is required`，不会发请求。第 7 节示例可配置上述已验证的 HTTPS 基址，接入方仍须提供本游戏的有效 Key 并完成自己的认证与写入验证；只读目录及 TLS 成功不代表完整 SDK 流程已运行。不要删除 SDK 的安全检查或绕过证书校验。本轮未修改 SDK 或 API 应用代码。

旧版生成的 Key 只保存摘要，无法恢复原文，仍可正常认证；管理员主动轮换一次后，新 Key 才支持反复查看。不会自动轮换已有 Key，轮换后须更新对应游戏服务端配置。`config.template` 不再接受为有效配置或返回，接口不会自动填充问题正文；`config.publicConfig` 仍公开返回，不得放 Key。

仅管理员 JWT 可调用 `GET /admin/games/{gameCode}/api-key`，成功 `data={apiKey,game}`，不改变 revision，响应禁止缓存。匿名 401、普通用户/游戏 Key 403、无有效密钥 404、旧摘要密钥无法恢复 409、解密配置异常 503。生成/轮换为同路径 POST，停用为 DELETE，均传 `{revision}`。管理员游戏视图新增 `keyRecoverable`；公开游戏接口和列表不返回密钥明文/密文。下游继续使用 `X-API-Key`，不需要也不应该获取管理员权限。

游戏客户端 → 自己的游戏服务端验证玩家身份 → COCO API。Key 不放网页、Unity 包、小程序或其他客户端；游戏服务端固定 gameCode，不直接信任玩家传入的任意游戏标识。此接口的所有问题、评论和图片均为公开内容，不提交隐私或密钥。

## 2. 鉴权与通用响应

游戏服务端请求：

```http
X-API-Key: <从官网后台获取的游戏密钥>
Content-Type: application/json
```

只有 JSON 请求体才需要 `Content-Type`；不要同时发送 `Authorization`。官网用户另用 `Authorization: Bearer <JWT>`，下游无需模拟管理员登录。游戏 Key 可以创建、编辑、关闭、删除自己接入创建的内容，不能修改官网用户的正文或操作其他游戏；管理员可统一处理所有问题。轮换/停用 Key 后旧 Key 立即失效。

应用 JSON 响应始终包含五个字段：

```json
{
  "code": 0,
  "success": true,
  "requestId": "16b352cd-3dd2-4406-88a8-7daa90e54bf7",
  "data": { "items": [] },
  "msg": "操作成功"
}
```

- 成功 HTTP 200/201，`code=0`、`success=true`；创建成功通常为 201。
- 失败 HTTP 4xx/5xx，`code` 等于 HTTP 状态码、`success=false`；`data` 无补充信息时为 `null`。
- `requestId` 与响应头 `X-Coco-Request-Id` 一致；排障保存此值，不记录 Key 或完整上传凭证。
- 所有时间为 UTC ISO 8601。客户端按自己的时区展示。
- OSS 直传、OPTIONS 空响应及云平台拦截错误不属于上述 JSON 协议，必须处理非 JSON 和网络超时。

| HTTP/code | 处理方式 |
| --- | --- |
| 400 | 修正参数、统一选项、附件归属或关闭原因；不要原样重试 |
| 401 | 检查 Key、游戏是否暂停接收；不要自动改用管理员账号 |
| 403 | 当前主体无权操作该游戏或内容 |
| 404 | 资源不存在或已删除；按 externalId 查找不存在时才能尝试首次创建 |
| 409 | 冲突或资源状态不允许；重新读取后比较，不能强行覆盖 |
| 410 | 附件已过期，重新申请上传 |
| 413 / 415 | 请求体过大 / 必须使用 JSON |
| 428 | 缺少当前 `revision` |
| 429 | 降低频率，退避重试 |
| 500 / 503 | 临时服务错误或存储未就绪；保存 requestId 并联系维护者 |

并发冲突示例：

```json
{ "code": 409, "success": false, "requestId": "f60d9e60-9c92-496d-b12a-b286bda1ee1c", "data": { "revision": 2 }, "msg": "内容已被更新，请刷新后再操作" }
```

## 3. 统一选项与问题字段

启动时调用匿名 `GET /issue-options`，返回 `data.categories`、`data.platforms`、`data.labels`、`data.closureReasons`。分类/平台项为 `{id,name,description}`，标签额外含 `color`。提交分类、平台和标签时使用 **name**，不是 id。

- 分类：错误反馈、改进建议、使用咨询、其他反馈。
- 平台：网页、Windows、macOS、Linux、安卓、iOS、微信小程序。
- 标签：从接口读取，可多选。它与分类、关闭状态独立；不要自己新建标签名称。
- 状态：`open` / `closed`。关闭原因：`completed`（已完成）、`not_planned`（不予处理）。

`GET /games/{gameCode}` 的 `data.game` 返回游戏信息；其中分类/平台/标签是只读统一目录，不按游戏定制。

| 问题字段 | 要求 |
| --- | --- |
| title | 新建必填，1–160 字 |
| body | 新建必填，1–20000 字，Markdown；网页不执行 HTML |
| category / platform | 可省略或空串，否则取统一目录 name |
| labels | 可选名称数组；`[]` 清空问题标签 |
| attachmentIds | 可选，最多 9 个已完成上传的附件 ID |
| metadata | 可选公开 JSON 对象，序列化后最多 4000 字符 |
| status / stateReason | 默认 open/null；关闭时传 closed 和明确原因 |
| revision | 更新/删除所需并发修订号，不是游戏版本 |

不再提供 `version`、`versions` 或游戏版本筛选。官网用户创建内容需 `publicConsent:true`；游戏 Key 代用户提交不需要该字段，但游戏端也应提示公开性质。

## 4. 创建、查询、更新、删除

| 操作 | 路径 | 成功 data |
| --- | --- | --- |
| 新建 | `POST /games/{gameCode}/issues` | `{issue,created:true}` |
| 列表 | `GET /games/{gameCode}/issues` | `{items,total,page,limit}` |
| 详情 | `GET /games/{gameCode}/issues/{issueId}` | `{issue}` |
| 修改 | `PATCH /games/{gameCode}/issues/{issueId}` | `{issue,created:false}` |
| 软删除 | `DELETE /games/{gameCode}/issues/{issueId}` | `{id,revision,deleted:true}` |
| 外部编号查找 | `GET /games/{gameCode}/external-issues/{externalId}` | `{issue}` |
| 外部编号创建/修改 | `PUT /games/{gameCode}/external-issues/{externalId}` | `{issue,created}` |

列表、详情可匿名读；外部编号查找/写入需游戏 Key 或相应管理权限（PUT 仅游戏 Key）。列表支持 `status/q/category/platform/label/stateReason/page/limit`，默认 20 条，最大 100 条。`status=all` 可读取两种状态；`stateReason` 隐含 closed，不能与 open 同传。详情包含正文、metadata、附件；列表不是完整内容。

创建请求示例：

```json
{
  "title": "卡牌拖动后未进入战斗区",
  "body": "## 复现步骤\n1. 拖动手牌\n2. 点击确认",
  "category": "错误反馈",
  "platform": "网页",
  "labels": ["程序错误"],
  "attachmentIds": [],
  "metadata": { "matchId": "42" }
}
```

修改仅提交需要变化的字段及当前 revision；每次以响应中的新 `issue.revision` 替换本地值。省略附件/标签表示不变，传空数组表示清空。

```json
{ "revision": 1, "body": "补充后的完整复现步骤" }
```

关闭、修改关闭原因和重新打开复用 PATCH（也可用外部编号 PUT）：

```json
{ "revision": 2, "status": "closed", "stateReason": "completed" }
```

不予处理传 `not_planned`；重新打开传 `{ "revision": 3, "status": "open" }`，服务端清空原因。DELETE 请求体为 `{ "revision": 4 }`；删除是软删除，恢复需管理员在官网操作。

## 5. externalId、防重与同步

建议每条游戏反馈生成稳定的 `externalId`，如 `match-42-feedback-7`，最多 128 字符，同游戏内唯一，作为路径段时 URL 编码。不要使用玩家隐私作为编号。

首次 PUT 传 `revision:0` 和完整新建字段，响应为 201；再次更新传 COCO 当前 revision，响应为 200。首次 PUT 重试若对象已经存在会返回 409，不会重复创建。遇到超时或 409，按同一 externalId GET 查回并对照内容，再决定是否合并更新，不能盲目把 revision 改成最新后覆盖维护者修改。已软删除对象不能通过 PUT 复活。

```text
GET /games/{gameCode}/issue-changes?cursor=0&limit=50
```

增量同步需 Key，返回 `{items,nextCursor,hasMore}`。每项包含 `cursor/type/issueId/externalId/revision/deleted/issue`；`issue` 是读取时的最新快照，不是事件发生时的旧快照。同一问题可能出现多次，按 issueId + revision 幂等处理。

处理完整页成功后才持久化 nextCursor，hasMore 为真继续拉；失败保留原游标后重试。deleted 为真时 issue 为 null，隐藏本地副本。评论变化推进问题修订号，收到事件后重新读取 comments。暂无 Webhook，需要项目服务端主动拉取。

评论：`GET/POST /games/{gameCode}/issues/{issueId}/comments`；创建 body 为 `{body,attachmentIds?}`，结果 `{comment,issueRevision}`。评论编辑/删除在路径后追加 `/{commentId}`，分别 PATCH/DELETE 并携带评论自己的 revision。评论更新也会改变问题 revision，之后更新问题先读取当前详情。`GET .../issues/{issueId}/events` 返回处理记录。

## 6. 图片上传

图片走“申请 → OSS 直传 → 确认 → 关联”四步。下游无需 OSS Key/Secret，不传自己拼接的 attachmentUrls。

1. `POST /attachments/uploads`：`{gameCode,filename,contentType,size}`，size 是原文件字节数。返回 `{attachmentId,upload:{method,url,fields,expiresAt}}`。
2. 向返回的 upload.url POST `multipart/form-data`：逐个加入 fields，**最后追加 file**；不要手写 Content-Type/boundary，也不要把游戏 Key 转发到 OSS。fields 是短期凭证，不写日志。
3. `POST /attachments/{attachmentId}/complete`，JSON 请求体 `{}`。返回 `{attachment:{id,filename,contentType,size,url}}`。只有此步成功，附件才可用于问题。
4. 提交/编辑问题或评论时携带 `attachmentIds:[attachment.id]`。查询结果中的 `attachments[].url` 才用于展示。

支持 PNG/JPEG/WebP，每张最大 5 MiB，每条最多 9 张，图像最大 2500 万像素。服务器解码、去元数据、转 WebP，公开 URL 的文件类型和大小可能与原图不同。签名 5 分钟有效，未关联附件通常 24 小时过期；跨游戏/跨上传者或未完成附件不能关联。编辑的 attachmentIds 整体替换原附件；省略不动，空数组移除。

目前图片返回杭州 `coco-starcloud.oss-cn-hangzhou.aliyuncs.com` 地址；接入方应使用 API 返回 URL，不硬编码域名或路径。服务端上传不受浏览器 CORS 限制；若由游戏网页直接上传 OSS，需维护者为该游戏前端来源增加精确 CORS 许可，不能默认所有域名可直传。

申请额度：每主体每小时 30 次、每游戏每天 500 次；写请求每主体每分钟 300 次。请缓存不含凭证的统一目录、避免频繁重新上传同一张图，不用高频轮询代替同步游标。

## 7. Node.js SDK 示例

适用条件：将 `COCO_ISSUES_BASE_URL` 配置为第 1 节已验证的 HTTPS 基址，或使用本地隔离 `http://127.0.0.1:9010/api/v1`；公网 HTTP 地址不适用。以下涉及认证、创建及上传的完整示例本轮尚未完成实际运行，接入方须按第 8 节验证自己的真实流程。

将 SDK 下载为同目录 `coco-issues-client.mjs`。下面示例只在你自己的服务端运行；环境变量还需提供 `COCO_EXTERNAL_ID`（同一条反馈保持不变），可选 `COCO_SCREENSHOT_PATH`。

```js
import { readFile } from 'node:fs/promises';
import { CocoIssuesClient } from './coco-issues-client.mjs';

const coco = new CocoIssuesClient({
  baseUrl: process.env.COCO_ISSUES_BASE_URL,
  gameCode: process.env.COCO_GAME_CODE,
  apiKey: process.env.COCO_ISSUES_API_KEY
});
const externalId = process.env.COCO_EXTERNAL_ID;
if (!externalId) throw new Error('请配置稳定的 COCO_EXTERNAL_ID');

const catalog = await coco.options();
const category = catalog.categories.find(x => x.id === 'bug').name;
const platform = catalog.platforms.find(x => x.id === 'web').name;
let current;
try { current = (await coco.findExternal(externalId)).issue; }
catch (error) { if (error.status !== 404) throw error; }

if (!current) {
  const attachmentIds = [];
  if (process.env.COCO_SCREENSHOT_PATH) {
    const bytes = await readFile(process.env.COCO_SCREENSHOT_PATH);
    // 本例只读取 PNG；实际调用按原文件设置真实 MIME。
    const attachment = await coco.uploadImage(new Blob([bytes], { type: 'image/png' }), 'battle.png');
    attachmentIds.push(attachment.id);
  }
  current = (await coco.upsert(externalId, 0, {
    title: '卡牌拖动异常', body: '## 复现步骤\n1. 拖动手牌',
    category, platform, attachmentIds
  })).issue;
}
// 已存在时不自动覆盖，交给本项目决定如何合并。
console.log({ issueId: current.id, revision: current.revision, status: current.status });
```

后续使用 `coco.update(id, revision, changes)`、`coco.close(id, revision, 'completed')`、`coco.reopen(id, revision)`、`coco.remove(id, revision)`、`coco.changes(cursor)`。SDK 成功直接返回 data；失败抛出 Error，含 `status/code/success/requestId/data`，message 对应 msg。示例的首次创建仍可能遇到并发 409，按第 5 节重新查询，不自动覆盖。

## 8. 上线自检

确认项目服务端能读取统一目录，以本游戏 Key 完成首次创建、按 externalId 查回、带 revision 更新；图片完成上传确认后可公开读取；官网管理员关闭问题后，下游可通过增量同步读到关闭原因；保存游标并验证删除标记。其他项目自己的玩家登录、代理接口和业务落库由各项目负责接入，不能仅凭本服务已发布就认定这些流程已经完成。
