From d4de462d44065a90b40ffbe54f4e70884d65953b Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 31 Aug 2026 21:08:32 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E5=8D=8F?= =?UTF-8?q?=E8=B0=83=20E2E=20=E8=BF=90=E8=A1=8C=E4=B8=8E=E6=8E=92=E9=9A=9C?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=20(#171)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/04-local-development-and-verification.md | 45 ++++++++++++++++++- docs/06-troubleshooting.md | 31 ++++++++++++- docs/delivery/deployment-and-operations.md | 24 +++++++++- 3 files changed, 94 insertions(+), 6 deletions(-) diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index d965638..e843ec5 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.- -wiki_revision: 7e5ec44eb0afec0b84010ce6cf82177491272c70 -synchronized_at: 2026-08-31T08:25:49Z +wiki_revision: 889ffccc30a998a5cc8c4a5d91af3c72771c093a +synchronized_at: 2026-08-31T13:00:20Z # 本地开发与验证 @@ -775,3 +775,44 @@ git diff --check 这些测试证明编排和隔离控制，不证明真实产品包、生产 PostgreSQL、客户 PKI、真实摄像头/GPU、供应商服务、容量或长稳表现。真实契约闭环与 Brain/Bell 离线、重启、重复/冲突及证据降级由后续 E2E 工单验证。 + + +## 三项目协调 E2E 验证 + +从仓库根目录执行唯一默认验收入口： + +```powershell +pwsh scripts/e2e/coordination/run-coordination-e2e.ps1 +``` + +可复制的工具参数： + +```powershell +pwsh scripts/e2e/coordination/run-coordination-e2e.ps1 -PostgresBin D:\pgsql17\bin -Python Brain\.venv\Scripts\python.exe +``` + +默认完整运行按以下阶段串行收敛： + +1. 创建动态 loopback 端口的临时 PostgreSQL，为 Sense/Bell 建立不同的随机 owner/database，并执行 Bell 正式迁移。 +2. 在一次性 Python venv 中验证 source-config、runtime-status、machine-identity、events、evidence 五类冻结 v1 契约。 +3. 验证 Sense 配置/状态、Brain 事件接入/证据/Outbox 与 PostgreSQL 并发恢复。 +4. 验证 Brain 配置/状态 connector、匿名事件导出和持久重放。 +5. 串行验证 Bell ingress/evidence、Rule/Alert 投影和 ack/close 生命周期。共享有状态 Bell 数据库的包不得并行运行。 +6. 默认重新运行 Sense isolated E2E、Brain 全套测试和 Bell isolated E2E。 +7. 核对 Sense/Bell database owner/database 不同、随机秘密未进入临时日志、所属端口/进程已停止，并安全清理专属临时目录。 + +#155 的完整通过记录为：source-config 11 项、runtime-status 14 项、machine-identity 10 项、events 7 项、evidence 4 项；Brain connector/event export 25 项、Brain 全套 74 项；Sense/Bell connector 与独立 isolated E2E 均通过。不同提交必须以当次真实输出为准，不复用这些数量冒充新结果。 + +只有默认完整入口退出码为 0、末行出现 `COORDINATION_E2E passed`、三端独立回归均成功并且工作区无计划外改动，才满足协调 E2E 技术验收。`-SkipIndependentProductE2E` 仅供 harness 调试，不能作为 #155/MVP 验收。`-KeepTemporary` 仅用于失败诊断，保留内容不得提交或共享。 + +仓库级闭环继续执行： + +```powershell +python dev_scripts/harness.py check --strict +python -m unittest discover -s tests -v +python dev_scripts/harness.py sync --check +git diff --check +``` + +已验证范围不包含真实 GPU/生产模型、真实摄像头、通知供应商、生产迁移、16 路长稳和客户现场效果；这些项目必须在对应环境和独立工单中验收。 + diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md index c17a37a..d766ff6 100644 --- a/docs/06-troubleshooting.md +++ b/docs/06-troubleshooting.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting -wiki_revision: 0d4a70626b4ab8cc65df3d8a56975376684dd284 -synchronized_at: 2026-08-31T08:26:11Z +wiki_revision: eec4beb8e5b9b8ff18401b272fd249aff7711509 +synchronized_at: 2026-08-31T13:00:41Z # 故障排查 @@ -221,3 +221,30 @@ pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest 日志和状态不得包含环境变量值、密码、JWT、token、私钥、完整 Authorization、摄像头凭据或客户数据。协调层故障时可停止使用根级入口并恢复三个产品各自的已验收启动脚本，不删除数据或共享事实。 + + +## 三项目协调 E2E 排错 + +先从完整输出定位第一个失败阶段，不同时修改多个猜测原因。默认入口是： + +```powershell +pwsh scripts/e2e/coordination/run-coordination-e2e.ps1 +``` + +| 现象 | 检查 | 安全处理 | +|---|---|---| +| 缺少 `initdb.exe`、`pg_ctl.exe`、`createdb.exe` 或 `psql.exe` | 检查 `-PostgresBin` 是否指向同一 PostgreSQL 安装的 `bin` | 修正工具路径；不要改用生产数据库或默认 5432 | +| Python 缺少契约依赖 | 确认所选 Python 可创建 venv 且能安装仓库冻结依赖 | 修复 Python/依赖源后重试；不要把依赖临时装进产品环境充当固定基线 | +| Bell 正式迁移失败 | 查看当轮临时目录的 `bell-migrate.log`，核对首个 SQLSTATE | 修复迁移或工具链；不得跳过迁移、手工补表或连接业务库 | +| Sense/Bell 数据库隔离断言失败 | 检查生成的 owner/database 是否不同 | 停止测试；不得共享数据库、角色、JWT、Cookie 或账户空间 | +| Bell Rule/Alert 评估数偶发增加 | 检查是否把 ingress、rule、lifecycle 多个有状态 Go 包放在同一数据库并行运行 | 恢复 root harness 的串行阶段；不要降低断言或清除不可变事实 | +| `machine_token_*`、duplicate 或 conflict 与预期不符 | 核对 audience/scope/kid、请求绑定、jti 和 producer/source 业务键 | 保持稳定错误和原业务键；不得记录 Authorization、复用网页登录态或为重试改 source ID | +| Outbox 在 Bell 离线后未补投 | 核对 retry/lease/available_at、Bell 恢复和新 relay 进程 | 保留消息和历史，恢复 Bell 后重试；不得清空 Outbox/Receipt/Event | +| evidence timeout/unavailable 导致整条事件失败 | 检查 evidence resolver 与降级状态 | Event/Receipt/Alert 应继续保留；不得把失败伪装为 success | +| 端口仍占用或测试结束后有进程 | 确认进程是否由本轮测试启动，查看所属临时目录和状态 | 只停止能证明归属的进程；不得无条件 taskkill 或终止其他实例 | +| 秘密扫描失败 | 在本轮临时日志中搜索该随机测试值，禁止把值粘贴到工单 | 修复日志输出后重新运行；不得仅关闭扫描 | +| 需要保留失败现场 | 使用 `-KeepTemporary` 并记录明确绝对临时路径 | 目录只用于本机受控诊断，完成后按已核对路径清理；不得提交或共享 | +| 使用 `-SkipIndependentProductE2E` 后通过 | 只证明协调 harness 主体，不证明三端独立回归 | 修复依赖后重新运行默认完整入口，不能据此通过 MVP 验收 | + +若失败发生在 Sense、Brain 或 Bell 的独立 E2E，转到对应产品章节按该端首个错误排查；不得在协调文档工单中顺手修改产品代码。真实 GPU、真机、通知供应商、生产迁移、16 路长稳或客户现场问题不属于该隔离 E2E 的结论。 + diff --git a/docs/delivery/deployment-and-operations.md b/docs/delivery/deployment-and-operations.md index f25d62f..f700454 100644 --- a/docs/delivery/deployment-and-operations.md +++ b/docs/delivery/deployment-and-operations.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.- -wiki_revision: f71d21296bc4d402046a52903e6e9ac0583dbd66 -synchronized_at: 2026-08-31T08:27:50Z +wiki_revision: b254f544fc867f1f9cc91b6c935ca638349e53c3 +synchronized_at: 2026-08-31T13:02:36Z # YoVision 部署与运维 @@ -214,3 +214,23 @@ pwsh -NoProfile -File scripts/runtime/coordination/stop-yovision.ps1 -Manifest C 升级时每次只替换一个独立包并更新精确版本，先备份 Sense/Bell，再按 Bell → Sense → Brain 验证，最后启用 connector。回退时先停用 Brain event export、Sense ingress/relay 与 Bell ingress/evidence connector，再使用各产品独立入口回退包或恢复数据库；不得删除 Outbox、Receipt、Event、运行投影、replay 或审计事实。16 路只是当前交付配额，不是编排器硬上限；真实生产包、PostgreSQL、客户 PKI、真机容量与长稳仍需部署环境验收。 + + +## 三项目协调 E2E 验收入口 + +工单 #155 已于 2026-08-31 验收，并通过 PR #170 合入 `dev@0276bce`。该入口只用于隔离开发/验收，不是生产部署、生产迁移或现场容量测试： + +```powershell +pwsh scripts/e2e/coordination/run-coordination-e2e.ps1 +``` + +入口要求 PowerShell 7、冻结的 Go 1.26.5 工具链、Brain 可用 Python 环境、PostgreSQL 17 命令行工具，以及 Sense/Bell 各自独立 E2E 已记录的本机依赖。PostgreSQL 工具默认从 `D:\pgsql17\bin` 读取，可通过 `-PostgresBin` 指定其他安装目录；Python 默认优先使用 `Brain\.venv\Scripts\python.exe`，也可通过 `-Python` 指定。不得为通过测试而连接生产数据库、客户设备或生产服务。 + +每次运行会在系统临时目录创建专属 PostgreSQL cluster，使用非 5432 动态 loopback 端口，并为 Sense、Bell 创建随机且不同的 database owner 和 database。测试凭据只存在于当前进程和临时测试范围，不进入仓库。入口按顺序执行冻结契约、三端 connector/持久化故障验证，并默认继续执行 Sense、Brain、Bell 各自已有的独立 E2E。 + +`-SkipIndependentProductE2E` 只用于定位协调 harness 自身故障；使用该参数的结果不能作为 #155 或 MVP #156 验收证据。`-KeepTemporary` 只用于受控保留失败诊断，目录可能包含一次性测试数据，排查完成后按明确绝对路径清理，不得提交或共享。 + +入口在 `finally` 中只停止自己启动的临时 PostgreSQL和下游测试拥有的进程，核对端口关闭，并扫描临时日志是否出现本轮随机秘密。成功的最终判据是全部阶段退出码为 0，输出末行包含 `COORDINATION_E2E passed`，且 `git status --short` 没有产品源码或配置改动。 + +该验收证明版本化契约、配置/状态、匿名事件、Sense Outbox、Bell Receipt/Event/Alert/ack/close、离线恢复、身份/重放/冲突/证据降级及三端独立运行；不证明真实 GPU/生产模型、真实摄像头、通知供应商、生产迁移、16 路长稳或客户现场效果。 + -- 2.34.1 From a69ef627c73f0c341337b99f5a21aedb137608ba Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 31 Aug 2026 21:12:33 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=E5=8D=8F?= =?UTF-8?q?=E8=B0=83=20E2E=20=E6=B8=85=E7=90=86=E8=BE=B9=E7=95=8C=E6=8E=AA?= =?UTF-8?q?=E8=BE=9E=20(#171)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/delivery/deployment-and-operations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/delivery/deployment-and-operations.md b/docs/delivery/deployment-and-operations.md index f700454..0829d4e 100644 --- a/docs/delivery/deployment-and-operations.md +++ b/docs/delivery/deployment-and-operations.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.- -wiki_revision: b254f544fc867f1f9cc91b6c935ca638349e53c3 -synchronized_at: 2026-08-31T13:02:36Z +wiki_revision: c376d69227aa159a7839a829f5bfb5a7beaf89e6 +synchronized_at: 2026-08-31T13:12:00Z # YoVision 部署与运维 @@ -230,7 +230,7 @@ pwsh scripts/e2e/coordination/run-coordination-e2e.ps1 `-SkipIndependentProductE2E` 只用于定位协调 harness 自身故障；使用该参数的结果不能作为 #155 或 MVP #156 验收证据。`-KeepTemporary` 只用于受控保留失败诊断，目录可能包含一次性测试数据，排查完成后按明确绝对路径清理，不得提交或共享。 -入口在 `finally` 中只停止自己启动的临时 PostgreSQL和下游测试拥有的进程，核对端口关闭，并扫描临时日志是否出现本轮随机秘密。成功的最终判据是全部阶段退出码为 0，输出末行包含 `COORDINATION_E2E passed`，且 `git status --short` 没有产品源码或配置改动。 +入口在 `finally` 中只停止自己启动的临时 PostgreSQL 和下游测试拥有的进程，核对端口关闭，并扫描临时日志是否出现本轮随机秘密。成功的最终判据是全部阶段退出码为 0，输出末行包含 `COORDINATION_E2E passed`，且 `git status --short` 没有产品源码或配置改动。 该验收证明版本化契约、配置/状态、匿名事件、Sense Outbox、Bell Receipt/Event/Alert/ack/close、离线恢复、身份/重放/冲突/证据降级及三端独立运行；不证明真实 GPU/生产模型、真实摄像头、通知供应商、生产迁移、16 路长稳或客户现场效果。 -- 2.34.1