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

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