chore: initialize standalone business plugin repository

2026-08-27 23:36:08 +08:00
commit 5feae3ad41
59 changed files with 8950 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 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 在新版本健康和契约测试通过前保持可用。