# Business Plugin Manifest V1

状态：Accepted Contract

业务插件清单由独立控制面读取和校验，Core 当前不会读取它。清单只声明插件身份、版本、能力、服务、UI、兼容性、发布者和 Core API 权限，不授予数据库、路由或 secret 权限。

## 1. 最小清单

```json
{
  "schema_version": 1,
  "plugin_id": "DOMAIN_PLUGIN_ID",
  "name": "DOMAIN_PLUGIN_NAME",
  "version": "1.0.0",
  "core_api_baseline": "sub2api-0.1.183",
  "tested_core_versions": ["0.1.183"],
  "capabilities": ["DOMAIN_CAPABILITY_V1"],
  "backend": {
    "listen_env": "PLUGIN_PORT",
    "health_path": "/healthz",
    "readiness_path": "/readyz"
  },
  "ui": {
    "entrypoint": "/admin/",
    "menu": {
      "id": "DOMAIN_PLUGIN_ID",
      "label": "DOMAIN_PLUGIN_LABEL",
      "visibility": "admin",
      "sort_order": 200
    }
  },
  "publisher": {
    "key_id": "PUBLISHER_KEY_ID"
  },
  "core_api_allowlist": [
    "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/DOMAIN_READ_ENDPOINT"
  ]
}
```

## 2. 字段规则

- `plugin_id`：小写、稳定、全局唯一；不得包含 `/`、空格或路径跳转。
- `version`：插件自身 SemVer，与 Core 版本和发行标签分离。
- `core_api_baseline`：插件编译和契约测试所针对的 Core 版本。
- `tested_core_versions`：只填写真实执行过契约测试的版本。
- `capabilities`：一个或多个业务能力 ID；控制面不为未实现的能力自动创建路由。
- `backend.health_path`、`readiness_path`：只能是插件服务根下的绝对 HTTP 路径（例如 `/healthz`、`/readyz`），不得包含主机、查询、片段或路径跳转。
- `ui.entrypoint`：只能指向包内 UI 资源。
- `ui.menu`：管理员菜单声明；控制面必须校验 ID 与插件 ID 绑定，`visibility` 只能是 `admin`。
- `publisher.key_id`：必须匹配受信任发布者配置。
- `core_api_allowlist`：方法和路径必须逐项列出，不允许通配符、任意 URL 或未声明查询参数。

## 3. 签名和哈希

```json
{
  "algorithm": "ed25519",
  "key_id": "PUBLISHER_KEY_ID",
  "signature": "BASE64_SIGNATURE"
}
```

签名覆盖 `manifest.json` 原始字节。包内每个服务文件和 UI 文件的 SHA-256 由清单声明。验证器必须拒绝尾随 JSON、重复字段、未知字段、无效 Base64、大小写错误的哈希和不匹配的 key ID。

## 4. 兼容性门禁

1. 清单 schema 版本不匹配：`incompatible`。
2. Core 不在 `requires` 范围：`incompatible`。
3. Core 在范围内但未列入 `tested_core_versions`：安装后保持 disabled，要求管理员确认。
4. 业务能力、服务协议或 UI 版本不支持：禁止启用。
5. 升级只产生新 revision；旧 active revision 在新版本健康和契约测试通过前保持可用。