# Sub2API Subscription Admin Business Plugin V1

这是一个可独立运行后端的管理员只读订阅业务模块，不是现有 `.s2plugin` transport 插件，也不是插件管理控制面。它不导入 Sub2API `internal` 包，不连接 Core 数据库，也不修改 Core Go/Vue、迁移、路由或 `.s2plugin` ABI。浏览器前端由 `plugin-admin` 统一 TDesign 控制面承载，订阅模块不提供第二个登录页或 Cookie。

生产/集成环境由通用 `plugins/plugin-admin` 控制面安装、启用和升级本插件；本插件不会预装，也不会成为控制面首页。只有健康检查通过并由管理员执行菜单预览/应用后，Core 管理员菜单才会出现“订阅管理”入口。直接运行本目录仅用于本地开发和契约测试。

## 本地启动

```sh
CORE_BASE_URL=http://127.0.0.1:8080 \
PLUGIN_HOST=127.0.0.1 \
PLUGIN_PORT=8091 \
go run .
```

本地后端可打开 `http://127.0.0.1:8091/healthz` 进行服务契约调试；生产浏览器入口应从 Plugin Admin 的订阅模块路由进入。生产环境应通过 HTTPS 反向代理，并设置 `PLUGIN_COOKIE_SECURE=true`。默认情况下本服务只暴露健康检查、就绪检查和交接页，不暴露第二套登录、Cookie 或 Core 数据 API。`PLUGIN_STANDALONE_AUTH=true` 仅在 `PLUGIN_ENV=development` 且监听地址为 loopback 时生效；该开发兼容模式会创建模块 Cookie，生产必须保持关闭。

## V1 范围

- 由 Plugin Admin 统一完成 Core 管理员账号登录和 Core 2FA；普通账号统一拒绝。
- 订阅模块复用控制面的 HttpOnly、SameSite 会话和写请求 CSRF 校验，不创建模块级登录会话。
- Core token 只保存在插件服务端内存会话中，不进入浏览器、URL、HTML、LocalStorage、响应或日志。
- 只读套餐、订阅列表、订阅详情和插件操作记录。
- Core access token 失效时最多刷新一次；刷新失败会销毁插件会话。
- 页面刷新会从插件会话恢复，并重新取得短期 CSRF token；服务端不会把 Core token 返回浏览器。
- 登录会读取 Core 公开验证码配置并透传 Turnstile、腾讯、阿里云或 GeeTest 的验证结果；验证码本身仍由 Core 校验。
- 余额购买、续费、撤销、退款和外部支付不在 V1，页面不渲染提交按钮。

## Core API allowlist

插件服务端在 `PLUGIN_STANDALONE_AUTH=true`、`PLUGIN_ENV=development` 且 loopback 的本地兼容模式下仅调用这些明确路径；生产数据访问由 Plugin Admin 同源 BFF 完成：

```text
POST /api/v1/auth/login
POST /api/v1/auth/login/2fa
POST /api/v1/auth/refresh
POST /api/v1/auth/logout
GET  /api/v1/auth/me
GET  /api/v1/settings/public
GET  /api/v1/admin/payment/plans
GET  /api/v1/admin/subscriptions
GET  /api/v1/admin/subscriptions/{id}
GET  /api/v1/admin/users/{id}
GET  /api/v1/admin/users/{id}/subscriptions
```

列表请求只接受 `page`、`page_size`、`limit`、`user_id`、`group_id`、`status`、`platform`、`sort_by`、`sort_order` 参数。插件不会代理任意 URL，也不会调用尚不存在的 `/api/v1/plugin-host/*`。

## Core 菜单与反向代理

控制面会依据清单中的菜单声明生成下面的 `custom_menu_items` 项；部署时无需手工写入订阅菜单：

```json
{
  "id": "qiu.subscription-admin",
  "label": "订阅管理",
  "url": "https://CORE_ORIGIN/extensions/qiu.plugin-admin/admin/#/modules/subscription/overview",
  "visibility": "admin",
  "sort_order": 200
}
```

Core 自定义页面的 sandbox iframe 不会继承 Core `localStorage` 登录态，因此菜单应指向 Plugin Admin 的统一控制面入口；订阅模块本身不显示登录页、不创建 Cookie。不要把 JWT 放进 URL。

## 测试

```sh
go test ./... -count=1
node --check ui/app.js
```

`main_test.go` 覆盖 Core 路径 allowlist、查询参数过滤、管理员角色拒绝、插件 Cookie、Core token 不泄露、会话过期、请求 ID、登录限流和 2FA pending 一次性消费。浏览器验收脚本位于 `test/browser-check.mjs`，可使用本地 Mock Core 验证直连、子路径反代和三种视口。

## 生成可安装包

```sh
./package.sh
```

脚本生成 `dist/qiu.subscription-admin.s2plugin`，包内根文件名为
`manifest.json`，并包含清单声明哈希的 UI 文件。该模块采用外部服务模式；
归档只携带清单和 UI 资源，不会替部署者启动后端。安装后先独立启动
`subscription-admin`（或由 systemd 持续运行），再在 `plugin-admin` 的配置中填写
`service_url`（插件 loopback 地址），并为 Plugin Admin 设置
`PLUGIN_PUBLIC_URL`（例如 `https://CORE_ORIGIN/extensions/qiu.plugin-admin`）。
然后执行启用、健康检查和菜单应用。浏览器前端由 `plugin-admin` 统一挂载并共享
控制面会话，菜单固定跳转到 `#/modules/subscription/overview`，不会跳转到本服务
的登录页。生产环境必须把签名文件通过
`SIGNATURE_FILE=/path/to/signature.json ./package.sh` 放入包内，并将对应公钥
加入控制面受信发布者配置；未签名包仅限 development + loopback。

## 清单和发布

`business-plugin-manifest.v1.json` 是部署层清单，不由 Core 读取。生产发布应由独立 CI 签名并校验清单、版本、健康路径和兼容的 Core 版本；不要把发布私钥放入仓库或插件包。插件版本独立于 `backend/cmd/server/VERSION`。

发布构建必须显式启用签名门禁：

```sh
RELEASE_BUILD=true SIGNATURE_FILE=/secure/signature.json ./package.sh
```

脚本会把 `signature.json` 放入归档并生成同名 `.sha256` 校验文件；未签名包
仅用于 development + loopback。

## 已知限制

- 模块后端是常驻服务，不需要每次使用后重启。Core access token 过期时，后端会
  按需 refresh 并继续当前请求；只有 refresh 失效、Core 撤销管理员、会话
  空闲超过 30 分钟或达到 8 小时绝对上限时才需要重新登录。
- V1 控制面使用内存会话，控制面服务重启会要求重新登录一次；订阅模块不会
  单独要求登录。多实例或跨重启免登录需将控制面会话存储替换为插件自有的
  加密 Redis/共享会话服务。
- 现有 Core 自定义 iframe 没有 token handoff，V1 不提供无感 SSO；真正 SSO 需要单独的 V1.1 Core 交接接口。
- Core 当前套餐响应中的 `features` 可能是 JSON 字符串，UI 会兼容字符串和数组。
- Core 开启验证码时，管理员必须先完成对应提供商的挑战并将结果填入登录表单；插件不保存验证码票据。