# API 说明

所有管理接口都要求 `Authorization: Bearer <server.json 的 AdminToken>`。响应为 JSON，除非说明为空文本或二进制。错误通常使用 HTTP 状态码和 `{ "error": "..." }`，少数游戏协议保留上游文本错误。未知路径为 404，错误方法为 405，认证失败为 401，权限不足为 403，业务冲突为 409。当前 332 条游戏/动态/正则路由均接入 C#；完整版本兼容性仍按清单保留核验状态。

## 管理接口

| 方法和相对路径 `/control/v1/` | 请求 / 作用 |
| --- | --- |
| GET `snapshot` | 在线状态、玩家数、请求计数、持久化修订、路由迁移状态 |
| GET `accounts` | 账户列表，不返回验证值和游戏 nonce |
| POST `accounts` | `{email, password, displayName}`；password 为明文游戏密码，由服务器计算协议摘要及验证值 |
| GET `accounts/{id}/profile` | 管理员账户资料 |
| GET `accounts/{id}/inventory`、`export` | 库存、配装、个人房间快照 |
| POST `accounts/{id}/currency` | `{currency, delta}`；支持 RegularCredits、PremiumCredits、FusionPoints、CrewShipFusionPoints、PrimeTokens |
| POST `accounts/{id}/item` | `{type, count}`；按图鉴元数据发放，装备附带额外槽位，包含伙伴/默认武器/礼包/邮件等副作用；未知物品返回 400 |
| POST `accounts/{id}/remove-item` | 装备使用 `{category,id}`；计数物品使用 `{category,type,count}` |
| POST `accounts/{id}/rename` | `{name}` |
| POST `accounts/{id}/ban` | `{banned}`，同时撤销游戏登录 nonce |
| POST `accounts/{id}/kick` | `{}`，撤销游戏登录 nonce |
| POST `accounts/{id}/tutorial` | `{skipTutorial:true/false}`；仅管理员可修改。启用时补齐初始装备、序章进度和已完成任务的飞船模块，保留已有装备、余额、配装及其他任务；关闭不会回退已完成进度。账号资料返回 `SkipTutorial` |
| POST `accounts/{id}/password` | `{password}`，撤销游戏登录 nonce |
| POST `accounts/{id}/import` | `{inventory:{...}}`；替换提供的数组，合并对象，过滤账户标识/凭据字段；依据已完成任务补回军械库等飞船模块，不重复发放任务奖励 |
| POST `accounts/{id}/message` | `{sndr,sub,msg,att?,countedAtt?,RegularCredits?,PremiumCredits?}`；进入游戏邮箱，读取后一次性发奖 |
| GET `catalog?q=...&category=...&skip=0` | 返回 `total` 与最多 80 条物品；路径和中文名搜索 |
| GET `routes` | RouteInfo 数组，包含状态、来源和正则示例路径 |
| GET `logs?after=0` | 内存中最近 500 条请求，按递增 ID 增量获取 |
| GET `config` | 账户自动注册配置、监听和版本信息 |
| POST `config` | `{autoCreateAccount:true}`，保存于存档并覆盖静态默认值 |
| POST `maintenance` | `{enabled:true}`，游戏 API 返回 503，管理接口仍可使用 |
| POST `shutdown` | `{}`，先返回确认，再正常停止服务 |
| GET / POST `world` | 世界生成配置和内容覆盖；POST 返回 `gameApiEnabled:true`，下次游戏世界请求即使用新配置 |

`countedAtt` 示例：`[{"ItemType":"/Lotus/Types/Items/MiscItems/Ferrite","ItemCount":20}]`。礼物、礼包和活动邮件通过共享获取逻辑发奖；重复读取不会再次领取，失败会回滚奖励和已读状态。

## 游戏接口

完整路径、方法、对应上游控制器见 [api-coverage.json](api-coverage.json)。API 使用保留大小写的字段，不要把 `ItemId`、`ItemType`、`Nonce` 转为小写。

登录示例：`POST /api/login.php`，正文 `{"email":"tenno@example.test","password":"<游戏客户端 Whirlpool 摘要>","ClientType":"Windows","kick":true}`。后续请求采用 `?accountId=<id>&nonce=<Nonce>`。管理 API 创建账户使用明文密码，游戏 API 登录使用客户端摘要，两者不可混用。

接收 JSON 正文，也接收游戏使用的 `application/octet-stream` 中的 JSON；支持 gzip 和 zlib deflate。压缩解码后正文上限 16 MiB。`e`/`ezip` 标记按上游假定正文已经由兼容客户端处理，不在这里实现客户端加密协议。

Mongo 扩展 JSON 字段使用 `{"$oid":"24位十六进制"}` 和 `{"$date":{"$numberLong":"毫秒时间戳"}}`，整数种子按 64 位整数保存。老版本 `$id` 可在部分入参中读取，但没有完整的历史版本响应转换。

已实现的主要接口组包括：世界状态与商人、任务结算/任务链、遗物/奖励、Nightwave/Calendar/Kahl、Circuit/Descent/深层科研、氏族/联盟/道场/研究/金库、市场/制造/出售/交易/赠礼、MOD/紫卡/赋能/专精/Helminth、宠物/模组装备/Railjack/Nemesis，以及上游 custom 管理接口。每条路径、方法和源文件请以清单为准。

例如：`GET /cdn/worldState.php` 返回当前世界；`POST /api/descentRewards.php` 使用 `{"Mode":"r","Category":"DM_COH_NORMAL"}` 获取本周奖励。`POST /api/endlessXp.php` 使用 `Mode=r`、`Category=EXC_NORMAL/EXC_HARD` 与本周提供的 `Choices` 初始化 Circuit，`Mode=c` 领取已达到的阈值奖励。重复初始化不清零已有经验，重复领取不重复发奖。

任务结果上传仍使用 `/api/missionInventoryUpdate.php` 和对应上游别名。存档更新、奖励与领取回执在单次事务中提交；非法材料/装备、失败的奖励获取会回滚该请求。`InventoryJson` 是协议要求的 JSON 字符串，不能当作嵌套对象处理。

Android 登录通过 `ClientType=Android` 和 `GoogleTokenId` 使用 Google 身份令牌；`GoogleClientIds` 决定允许的受众。缺配置或 Google 服务不可用为 503。新增 Android 账户按上游注册流程调用 `signupAndroid` 对应路由。服务端保存已校验的 Google subject，不保存原始 token，也不使用共享 Android 密码。

HTTP Arbiter 提供大厅选择、实例计数、离开通知及统计。`HubServers` 必须指向实际运行的外部 UDP Hub；配置地址并不启动 UDP/NRS 服务。IRC 聊天已集成到服务器进程，登录响应和 `/custom/tunables.json` 使用同一地址解析规则，见 [游戏内通讯](IN-GAME-CHAT.md)。

## PublicExport

支持 15 种 JSON 文档、图标映射 Manifest 和上游 15 种语言的 LZMA 索引；中文/英文文档转换与索引字节已测试。示例：

- `GET /PublicExport/index_zh.txt.lzma`
- `GET /PublicExport/Manifest/ExportWarframes_zh.json!<hash>`
- `GET /PublicExport/Manifest/ExportRecipes_en.json!<hash>`
- `GET /PublicExport/Manifest/ExportManifest.json!<hash>`

文档内容来自固定版本元数据，索引后缀按上游兼容路由解析。游戏二进制资源需自行放入 `GameAssetRoot`（默认为运行目录下的 `assets`）：

| 请求 | 根目录内的文件 |
| --- | --- |
| `/PublicExport/Lotus/Interface/...!hash` | `PublicExport/Lotus/Interface/...`，移除哈希后缀 |
| `/origin/<平台>/<版本>/H.Cache.bin` 或 `/<版本>/H.Cache.bin` | `H.Cache.bin` |
| `/origin/<平台>/index.txt.lzma` | `content/index.txt.lzma` |
| `/0/...!hash`、`/0_<语言>/...!hash` | 若根目录有 `0` 则直接匹配，否则匹配 `stripped-assets/0...`；保留哈希文件名 |
| `/SplitCaches/...`、`/Lotus/...`、`/Tools/...`、`/7.../...` | `content/` 下的同路径 |

文件字节原样返回。缺文件为 404，目录穿越/中间符号链接为 400。当前不提供 Range/流式下载，不包含资源下载器。配置与全系统边界见 [MIGRATION.md](MIGRATION.md)。