# 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`