# YoVision 可选协调部署

本目录只组合已经验收的 Sense、Brain、Bell 交付入口，不复制产品实现，也不成为业务事实源。三个产品仍使用独立包、进程、端口、数据目录、日志、数据库角色、账户空间、浏览器 Cookie 和机器身份。

## 准备

1. 将 `coordination.example.json` 复制到仓库外受控配置目录，填写三个已审核交付包的精确版本与绝对路径。
2. 分别准备仓库外 `sense.env`、`brain.env`、`bell.env`。Sense 至少提供 `SENSE_DATABASE_URL`、`SENSE_JWT_SECRET`、`SENSE_PORT`，Bell 至少提供 `BELL_DATABASE_URL`、`BELL_JWT_SECRET`、`BELL_PORT`、`BELL_WEB_PORT`；其余配置（包括 connector 开关）仍遵循各产品自己的环境文件说明。不得在清单或仓库中填写密码、JWT、token 或私钥内容。
3. 为每个调用实例创建独立 Ed25519 私钥和消费者公钥注册表；清单只引用私钥路径。
4. 为 Sense、Bell 创建不同 PostgreSQL 数据库和角色；先使用各自迁移入口完成备份与迁移。
5. 确认清单声明的所有端口、包目录、数据目录和日志目录互不重叠。

编排器会创建并隔离清单中的数据、日志目录；各产品环境文件或产品配置还必须把自身持久化与业务日志指向对应目录。编排器不会猜测或改写产品内部配置。

示例清单中的地址、版本和标识都是不可直接投产的占位值。默认 16 路只是当前交付配额，不是编排器容量上限。

## 命令

从仓库根目录运行；不需要修改 PowerShell 执行策略：

```powershell
pwsh -NoProfile -File scripts/runtime/coordination/start-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -ValidateOnly
pwsh -NoProfile -File scripts/runtime/coordination/start-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product bell,sense,brain
pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product all
pwsh -NoProfile -File scripts/runtime/coordination/stop-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product brain
```

`.bat` 包装器接受相同参数。启动时，`all` 只包含清单中 `enabled=true` 的产品；停止和查看状态时，`all` 会覆盖三个产品，避免产品被停用后遗留进程。启动顺序固定为 Bell → Sense → Brain，停止顺序固定为 Brain → Sense → Bell。单端失败只返回非零并清理该端新进程，不自动停止已经运行的其他端。

## 状态与日志

编排状态写入清单的 `runtime_root\state`，每端只保存 PID、启动时间、版本、命令路径和清单摘要，不保存环境变量值。协调启动日志分别写入各产品独立 `log_directory`。产品自己的日志仍由产品入口管理。

`status` 返回 `running`、`unhealthy`、`stopped` 或 `stale`；仅当所选产品全部健康运行时退出码为 0。PID 与命令归属不匹配时不停止进程，必须人工核对。

## 升级与回退

升级顺序为：备份 Sense/Bell → 迁移 Bell → 启动/检查 Bell → 迁移 Sense → 启动/检查 Sense → 更新 Brain → 启用 connector。每次只替换一个独立包并更新清单版本。

回退时先停用 Brain event export、Sense ingress/relay 与 Bell ingress/evidence connector，再按产品独立入口回退包或恢复各自数据库。不得删除 Sense Outbox、运行投影、Bell Receipt/Event、replay 或审计事实。根级编排故障时直接恢复三个产品原有独立入口。