# AI 接入指南

本页是给代码助手和自动开发工具的明确约束。应同时读取 [OpenAPI](/openapi.json)、[完整手册](/llms-full.txt) 和 [一次性邀请流程](/invitations/)。不要根据本站网页内部请求猜测未公开接口。

## 不变约束

1. 唯一公开生产根地址是 `https://api.screenshare.cn/v1`。
2. 使用 Bearer API Key；密钥只存在服务端，不使用网站 Cookie 或用户密码调用业务 API。
3. 一把组织密钥只绑定一个组织。读取 `/v1/me` 并严格比较 partner_id。
4. 组织授权要求创建者当前为该组织有效的实际 manager 成员，Admin/SSer 不构成跨组织豁免。
5. 创建邀请必须预先持久化 Idempotency-Key、组织、密钥引用和规范化正文。重试保持不变。
6. 邀请是玩家自行进入的页面。不得伪造访客 Cookie、远程信息或跳过首次完整提交。
7. 邀请 ID、正式工单 ID、记录 ID 和 USS UUID 是不同标识，不能互换。
8. 工单详情路径使用 invitation_id。status=resolved 不是查端结论。
9. 公开记录只允许完整 USS UUID 精确查询。没有公开按玩家名枚举的接口。
10. 404 RECORD_NOT_FOUND 不等于 clean；warning 不等于 cheating。
11. Webhook 必须先按原始 body 验签、检查时间，再解析并核对组织；按事件 ID 持久化去重。
12. 事件通知可能重复、乱序或遗漏，保留低频 API 核对流程。
13. 不实现本版本未公开的付款、权限提升、会话内容、附件、账号管理或自动结果写入接口。
14. 按[限流协议](/conventions/)处理动态 Retry-After，不硬编码 60 秒；配额按组织和创建账号共享，轮换密钥不能增加组织额度。
15. 每把密钥最多并发 2 个工单请求；创建邀请重试保留原编号，遇到日配额耗尽应持久化待办，不能循环换编号或立即重试。
16. `/v1/me.expires_at` 可为 `null`，表示个人或组织密钥不自动到期；不要把 null 当作无效日期。永久密钥仍受撤销、实时授权与全部限流规则约束；邀请的 `expires_at` 仍是实际到期时间。

## 建议模块

```text
server configuration -> organization credential map
                     -> startup /v1/me validation
authorized command   -> persisted request + idempotency key
                     -> create invitation -> private player link
verified webhook     -> durable inbox -> fetch latest resource
periodic reconcile   -> merge by resource ID -> user-facing status
```

在多租户应用中，每个本地租户必须先匹配到可信的组织配置。不得允许未经授权的请求自由指定密钥引用。接收事件时，不信任未验签的 partner_id 来决定访问哪个组织。

## 最低测试用例

- 密钥缺失、无效、撤销、过期及权限不足。
- 相同账号管理 A/B，但 A 的密钥不能访问 B。
- 同一幂等编号同正文重放成功，改正文返回冲突。
- 玩家并发认领后只有一个正式工单。
- 邀请到期、已使用、撤销和 claiming 中间状态。
- Webhook 原始字节签名、大小写、时间窗口、错误组织、重复投递、重试。
- 记录更新/移出组织/删除后的本地同步。
- 远程密码、邮箱、联系方式和内部备注不出现在 API 结果或应用日志。

## 生成代码时的输出要求

明确列出所需 scopes、环境变量、使用的组织配置、持久化字段、重试策略和日志脱敏方案。引用对应文档页和 OpenAPI operationId。没有已公开字段时，写明需要人工确认或产品扩展，不凭空生成数据关联。