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,46 @@
+# Business Plugin V1 开发指南
+
+## 目录模板
+
+```text
+my-business-plugin/
+├── cmd/plugin/main.go
+├── internal/auth/
+├── internal/coreadapter/
+├── internal/manifest/
+├── internal/domain/
+├── ui/index.html
+├── ui/assets/
+├── business-plugin-manifest.v1.json
+├── deploy/
+├── test/contract/
+└── README.md
+```
+
+入口服务只负责加载配置、启动 HTTP server 和健康端点。鉴权、Core API、领域逻辑、manifest 校验和 UI 不要全部写在入口文件。
+
+## 开发顺序
+
+1. 先复制 manifest 模板，声明唯一 `plugin_id`、capability、Core baseline、服务健康路径、UI 入口和精确 allowlist。
+2. 实现 Core Adapter 的 typed methods；禁止接受浏览器传入的任意 URL。
+3. 实现管理员登录、2FA、HttpOnly session、CSRF、refresh budget、登出撤销和日志脱敏。
+4. 实现领域 API 和 UI；浏览器只调用插件 BFF，不读取 Core token 或宿主存储。
+5. 提供 `healthz`、`readyz`、版本和 request ID；失败时保持 fail-closed。
+6. 由控制面执行签名、哈希、兼容性、启停、升级和回滚；插件服务不自行覆盖其他插件资源。
+7. 用 deployment-managed `custom_menu_items` preview/apply 注入管理员入口。
+
+## UI 约束
+
+业务插件页面遵循 `docs/FRONTEND_DESIGN_GUIDELINES.md` 和 `UI.MD` 的控制高度、无衬线数字、响应式表格、无卡片嵌套和安全错误展示要求。iframe 与新窗口都必须可用；独立 origin 按部署配置 Cookie `SameSite=None; Secure`，同源反代优先使用 `Lax`。
+
+## 测试最小集
+
+- manifest 未知字段、尾随数据、路径穿越、签名和哈希；
+- 管理员、普通用户、2FA、撤销、刷新、登出和 CSRF；
+- Core API allowlist、查询过滤、401 单次 refresh、429/5xx 策略；
+- secret 不出浏览器/日志/错误；
+- health/readiness、启停、drain、升级、回滚和卸载；
+- iframe、新窗口、刷新恢复、425/900/1440px 截图和横向溢出；
+- 清空插件投影后从 Core 重建。
+
+订阅插件的套餐、余额、订阅实例、同档多实例、单独续费和余额事务规则只写在订阅领域文档，不复制到本通用指南。