47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# 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 重建。
|
|
|
|
订阅插件的套餐、余额、订阅实例、同档多实例、单独续费和余额事务规则只写在订阅领域文档，不复制到本通用指南。
|