sub2api-add/docs/BUSINESS_PLUGIN_DEVELOPMENT.md

Business Plugin V1 开发指南

目录模板

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 重建。

订阅插件的套餐、余额、订阅实例、同档多实例、单独续费和余额事务规则只写在订阅领域文档，不复制到本通用指南。