# ONLYOFFICE 多插件开发网关

中央注册表位于 `packages/onlyoffice-plugins/registry.yaml`。开发网关为所有插件提供统一公网入口，各插件仍由独立 Vite 服务提供 HMR。

## 启动

```bash
pnpm dev:onlyoffice
```

默认入口：

```text
http://localhost:4173/onlyoffice-plugins/0.1.0-dev/eln-template-annotator/config.json
http://localhost:4173/onlyoffice-plugins/0.1.0-dev/eln-record-filler/config.json
```

内部端口只监听本机：annotator 使用 `4181`，filler 使用 `4182`。Vite 将每个插件的 HMR path 追加到插件 base，实际 WebSocket 路径为 `/onlyoffice-plugins/<release>/<plugin-code>/__hmr/<plugin-code>`，由同一插件代理转发。

## 生成后端配置

```bash
mkdir -p /absolute/release-root /absolute/backend-config
ONLYOFFICE_PLUGIN_PUBLIC_BASE_URL=http://localhost:4173/onlyoffice-plugins \
ONLYOFFICE_PLUGIN_API_BASE_URL=http://localhost:30000 \
ONLYOFFICE_PLUGIN_RELEASE=0.1.0-dev \
ONLYOFFICE_RELEASE_ROOT=/absolute/release-root \
ONLYOFFICE_PLUGIN_CONFIG_OUTPUT=/absolute/backend-config/onlyoffice-plugins.yaml \
pnpm generate:onlyoffice-backend-config
```

输出文件包含注册表内全部 `definitions` 和 `scenes`，应交给配置中心或后端部署流程加载，不能写入插件公网 release 根目录。

## 新增插件

1. 在 `packages/onlyoffice-plugins/` 下创建独立插件包。
2. 在 `registry.yaml` 添加唯一的 code、package、directory、GUID、内部端口和业务场景。
3. 保持插件版本 `0.1.0`，开发 release 使用 `0.1.0-dev`。
4. 运行网关测试和配置生成器，后端同步增加对应业务场景契约测试。

单插件开发命令继续可用，生产构建和不可变 release 不经过开发网关。

## 生产发布（测试 / 正式环境）

生产环境**不启动** `pnpm dev:onlyoffice`。插件是静态文件，随后端仓库的 cx-web 镜像一起发布：

- 后端仓库 `make web-dist`（`docker/frontend/sync-dist.sh`）读本目录 `registry.yaml`，对每个插件执行
  `pnpm --filter <package> build`，把 `<directory>/dist/` 拷到 cx-web 的 `/onlyoffice-plugins/0.1.0/<code>/`。
- cx-web 的 nginx 提供该路径，并把插件 `../v1/plugins.js|css` 转发到 Document Server 的 `/sdkjs-plugins/v1/`。
- 后端 cx-biz-common 按部署环境的 `ONLYOFFICE_PLUGIN_PUBLIC_BASE_URL`（如 `http://<站点>/onlyoffice-plugins`）、
  `ONLYOFFICE_PLUGIN_RELEASE=0.1.0`、`ONLYOFFICE_PLUGIN_API_BASE_URL`（如 `http://<站点>`）签发插件地址。

因此新增插件只要：① 在 `registry.yaml` 登记；② 保证 `build` 产出 `dist/config.json` 与 `dist/index.html`；
③ 后端 `config/shared/jnpf-biz-common.yaml` 增加对应 definition 与 scene。发布脚本与 nginx 无需改动。