# API 实现与兼容性状态

服务端使用 C#/.NET 和 XFEExtension.NetCore.ServerInteractive；WinUI 3 管理端独立运行。没有 JavaScript 引擎、Node 子进程、上游 HTTP 代理或 WebView。对照上游提交 `aafde8476edd91275de0f30bffe4cf79f4cfc81c`。

## 路由覆盖

309 条普通 GET/POST 路由与 23 条正则路由均已接入原生处理器，`pending = 0`。网页路由按要求排除；`/cdn/` 和 `/:id/dynamic/` 别名不重复计数。17 条较小控制器标为 `ported`，315 条仍标为 `partial`，表示具有业务实现，但完整上游分支和所有客户端版本的行为等价性尚未验证。**332/332 是入口实现覆盖，不是全游戏完成率。**

完整清单由当前源码编译后生成：[JSON](api-coverage.json)、[CSV](api-coverage.csv)。`EveryRegisteredRouteDispatchesWithoutMissingImplementationOrUnhandledException` 会逐条调用全部入口，在有效账户和独立状态下检查不出现 500/501。它不替代各 API 的正常业务用例。

## 已有 C# 业务实现

| 模块 | 实现范围 |
| --- | --- |
| 主机与账户 | HTTP/TLS、gzip/zlib、16 MiB 解码上限、Whirlpool/PBKDF2、自动注册、nonce、封禁/改名/改密、Android Google 令牌校验与注册 |
| 库存与个性化 | 图鉴驱动物品获取、槽位、余额、导入导出、现代与部分旧版配装、指挥官/漂泊者/Kahl、飞船与个人房间、花园和装饰 |
| 任务与成长 | 任务经验、星图、掉落、轮次/缓存奖励、赏金、突击/警报/裂隙/入侵、遗物、集团、扫描、收藏奖励、段位、任务链奖励与邮件 |
| 周期玩法 | Nightwave、Kahl、Calendar/Hex、Circuit、Duviri、Descent、深层科研、世界轮换、Ghoul/Plague Star 活动与配置的活动目标 |
| 经济与装备 | 市场/集团/商人/Baro/Varzia/Darvo、礼包、登录奖励、制作/加速/取消、装备材料、孵化/烙印/魅影、出售/交易/赠礼、MOD/紫卡/赋能/极化/专精/Incarnon |
| 伙伴与舰队 | 模组武器、Moa/Hound、感染伙伴、宠物状态、资源提取器、Railjack 舰员/残骸/研究/融合 |
| Helminth/Nemesis | 喂养、吞噬/加速、移植、振奋、源力石安装/拆除、Lich/Sister/Coda 的生成/战斗/击杀/转化/配方/历史 |
| 氏族与联盟 | 成员/等级/权限、邀请、联盟、研究、房间、装饰、染料、金库、广告、跑酷排行榜、活动进度与奖杯 |
| 社交与统计 | 好友/忽略/头像、HTTP 匹配会话、资料、个人与氏族统计、排行榜、Ollie 邮件、异步助战 |
| 数据与管理 | PublicExport/15 种语言、纹理/缓存本地文件、HTTP Arbiter、上游 custom API、WinUI 管理 API、Cheat 配置与账户/装备/任务编辑 |

奖励、材料、货币和跨账户交易通过同一存档事务提交。失败会回滚；邮件、每周领取、重复任务上传、部分任务阶段等具有领取记录或请求回执。制作取消恢复原装备与其配置，不重造丢失经验的替代品。制作蓝图受预留检查，不能在任务完成前售出或交易。

## 验证结果

- 128 项 .NET 自动化用例通过，包括全部入口分派、成功与失败路径、跨账户权限、重复请求、数据重启恢复及共享元数据不被修改。
- 23 项真实 ServerInteractive HTTP 检查通过，覆盖压缩登录、鉴权、库存写入、世界状态、每周奖励、重复解锁、文件字节、无网页、日志脱敏和正常退出。
- WinUI 保留原生 TitleBar、Mica、Per-Monitor V2 DPI 和按工作区计算的初始尺寸；本轮同步 API 状态展示。没有完成全 UI 自动化回归。

复现：运行 `scripts/Test.ps1`、`scripts/Smoke-Test.ps1`、`scripts/Export-Coverage.ps1`。测试均使用独立临时状态，不使用正式玩家存档；HTTP 脚本默认独立编译当前源码，支持 `-ServerPath` 验证发布包。TRX 位于 `artifacts/test-results/core-tests.trx`，HTTP 报告位于 `artifacts/http-smoke-*/results.json`。

## 依赖条件与已知边界

1. 尚未完成真实 Warframe 客户端的登录→飞船→任务→结算→重连验证，也没有逐一验证所有历史版本。旧版奖励表/蓝图变更、配装和档案序列化、任务特殊副作用等仍需要对照流量补充用例；不能宣称所有版本完全兼容。
2. IRC 已内置在 C# 服务器中，覆盖频道、私聊、社交通知、名单与会话生命周期；支持 `2026.08.19.11.06` 原生握手及 nonce/token，其他原生版本的未校验兼容入口限本机 TLS，详见 [游戏内通讯](IN-GAME-CHAT.md)。NRS 和 UDP Hub 的实时服务仍需外部提供；没有可用 `HubServers` 时，Hub 分配返回 503。
3. Android 登录需要配置 `GoogleClientIds` 并访问 Google 公钥服务。测试覆盖注入身份提供者的账户流程和无效令牌；真实 OAuth 账户授权尚未联调。缺配置返回 503，无效令牌返回 400。
4. 游戏客户端、纹理、平台缓存文件不随包分发。`GameAssetRoot` 配置的文件不存在时返回 404。当前二进制响应读入内存，尚未实现大缓存流式传输/Range 下载。
5. 世界生成器覆盖主要常驻周期玩法与 Ghoul/Plague Star，未自动重建上游所有历史限时活动的每个配置开关。管理员可通过 `/control/v1/world` 提供具体 Goals/Alerts 等内容。氏族周常奖励接口按当前上游实现生成奖励；上游未完成的额外周常协议不由服务器凭空补造。
6. 配装及部分任务结果/Helminth 振奋等沿用客户端提交数据的协议，不构成服务端完整反作弊系统。历史排行榜当前保留实现中的日/周/活动排名语义，没有完整赛季归档数据库。
7. 单进程 JSON 快照存档支持原子提交和上一版备份，不等同上游 MongoDB 的全库迁移。大型存档、多实例并发和生产规模性能尚未验证。

## 维护约定

对照上游 controller、service、模型默认值、版本分支、响应和副作用编写迁移逻辑。只返回 200、空对象或仅登记路径不算业务实现。某些上游本身就是固定应答的接口（例如 Steam packs 回调和道场分配 fallback）保留其语义，不产生额外奖励。

新增路由需要同时接入 `GameEngine.Execute` 与 `RouteCatalog`。多对象修改使用 `StateStore.Update`；物品/货币差额使用 `Inventory.Combine`。外部 Google 网络验证放在存档锁外。清单状态不应仅因入口测试通过而从 `partial` 升为 `ported`。

世界、掉落、旧版配方等元数据由 `Import-WorldData.ps1` 解析静态 TypeScript 字面量生成，禁止执行上游脚本作为运行时后端。更换上游提交或 PublicExport 版本后，需要重新生成数据、运行验证并重新评审兼容性。