tmp: API.md country-layered

tmp-rrpp-deploy-20260910/API.md

@@ -0,0 +1,78 @@
+# RRPP 订阅服务 · SSO 认证接入文档
+
+架构：`客户端 → nginx(api.rrrosmontis.icu) → RRPP 后端(127.0.0.1:5010) → SSO(127.0.0.1:4550) → nodes.json(国家分层)`
+
+## 1. 客户端公开端点
+
+### 统一订阅端点
+```
+GET https://api.rrrosmontis.icu/v1/rrpp/subscription?method=<类型>&user=<b64url邮箱>&password=<b64url密码>[&prefer=<协议>]
+```
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `method` | 是 | `clash` / `v2ray` / `rrpp_client` |
+| `user` | 是 | URL-safe base64 编码的邮箱 |
+| `password` | 是 | URL-safe base64 编码的密码 |
+| `prefer` | 否 | `vless` / `ss` / `http`，指定优先协议；缺省 `vless`，无则回退 vless→ss→http |
+
+### 旧端点（兼容）
+```
+GET /v1/rrpp/nodes_update?user=<b64>&password=<b64>
+```
+等价于 `method=rrpp_client`。
+
+## 2. method 说明
+
+| method | Content-Type | 内容 | 适用客户端 |
+|---|---|---|---|
+| `clash` | `text/yaml` | Clash YAML（按 prefer 或默认 vless，备注 `R.R.P.P. - 国家代码`） | Clash/clash.meta/mihomo |
+| `v2ray` | `text/plain` | base64 节点串（`vless://` / `ss://` / `http://`） | v2rayN/Shadowrocket/Quantumult |
+| `rrpp_client` | `application/json` | 旧格式节点 JSON（仅 http，remark = `服务商 流量`） | RRPP 自建客户端 |
+
+## 3. 返回码
+
+| 码 | 场景 |
+|---|---|
+| 200 | 成功 |
+| 401 | 凭据缺失/SSO 认证失败 |
+| 403 | tier=0（RRPP 未开通） |
+| 404 | method 未知 |
+| 502 | SSO 不可达 |
+| 503 | nodes.json 缺失/损坏，或该 tier 无可用节点 |
+
+## 4. nodes.json 格式（国家分层）
+
+`C:/BtSoft/nginx/others/htmlResources/private/RRPP/nodes.json`，顶层为国家数组：
+
+```jsonc
+[
+  {
+    "country": "JP",                    // 国家代码
+    "available_level": [1, 2, 3],       // 可见等级
+    "provider": "Azure",                // 服务商
+    "traffic": "15G",                   // 流量限额
+    "domain": "iam.aeolianchi.me",      // 域名
+    "ipv6_only": false,                 // 可选，true 时备注加 (IPv6)
+    "methods": {                        // 可用协议
+      "http":  { "port": ..., "username": ..., "password": ... },
+      "vless": { "port": ..., "uuid": ..., "flow": ..., "sni": ..., "public_key": ..., "short_id": ... },
+      "ss":    { "port": ..., "method": ..., "password": ... }
+    }
+  },
+  ...
+]
+```
+
+## 5. 协议选择逻辑
+
+- `prefer` 指定则优先用该协议
+- 缺省默认 `vless`（最好用）
+- 该国家无 `prefer` 协议时按 `vless → ss → http` 回退
+- `rrpp_client` 固定只用 `http`（兼容性），备注 = `provider + traffic`（IPv6 加 `(IPv6)`）
+
+## 6. SSO 认证
+
+- 后端调 SSO `POST http://127.0.0.1:4550/v1/sso/service/rrpp/nodes`（带 `X-SSO-Service-Token` + `X-Real-IP`）
+- SSO 返回 `{tier: 0|1|2|3}`，0=未开通
+- 服务密钥读 `sso-rrrosmontis-icu/secrets.json` 的 `service_tokens.rrpp`