open-design/specs/current/touchpoint-realtime-vela-handoff.md

# Vela Touchpoint「真实时间活动」测试交接

> 写于 2026-09-14。本文是 OpenDesign 对 Vela 的待实现依赖交接，不是上线记录。
>
> 后续用户已批准本地客户端开发：OpenDesign worktree 已接入共享展示生命周期和 Test 授权字段；本文同步记录客户端实现与验证边界。不执行 Vela 远程部署或数据库操作，既有生产服务端协议、不可变发布快照及 deployments/acceptances 历史不因此改变。Vela 客户端与服务端的待交付要求仍保留。

## 已决定的产品语义

活动 Test 不再由客户端选择「模拟前/中/后/唤醒」时间。测试者选择一份 Test deployment，Vela 以每次 GET 的服务器当前时间重新判定状态；只有服务端确认 active 且授权在实际挂载时仍有效，客户端才能渲染、挂载并回执。

**用户已决定：测试入口以真实时间替换模拟场景，不再默认 `active`。** 这不是把旧 `active` 改名为 `wake`，也不是给任一模拟分支保留别名。唯一合法选择是 `realtime`，状态完全由 Vela 当前时钟计算。

不变量：

1. context 的唯一 scenario 是 `"realtime"`；旧 `before`、`active`、`after`、`wake` 一律拒绝，不兼容映射或静默降级。
2. `GET` 带 UTC ISO-8601 的 `serverTime`、`startsAt`、`endsAt`、`authorizationExpiresAt`；均由服务端生成，客户端不得模拟时间或自行签发展示授权。
3. 每次 runtime `GET` 用同一个 `serverTime` 计算状态：`serverTime < startsAt` 为 `before`；`startsAt <= serverTime < endsAt` 为 `active`；否则为 `ended`。三个状态均返回完整 metadata 与 identity 的 HTTP 200，不能由 POST、旧 context 或 `wake` 决定。
4. acceptance 的 `scenario` 也只能是 `"realtime"`；Vela 在写入事务中以服务器当前时间和 Test deployment snapshot 再次核对窗口 active，客户端不能传入/控制判定时间。
5. deployment 的 `snapshotHash`、`artifactHash`、`manifestHash`、内容和既有 acceptance/audit 历史仍是不可变证据。时钟是 runtime 投影，不得重写 snapshot 或历史审计。

### 全球统一时间：北京时间配置，服务端判定

Admin 排期输入和展示固定使用北京时间 `Asia/Shanghai`（UTC+08:00），不随配置人员电脑时区变化。保存时将北京时间转换为明确的 UTC instant；接口使用带时区的时间，runtime 统一返回 UTC ISO-8601。不能仅填写 timeZone 字段却把无偏移的日期字符串按浏览器本地时区解析。

开始、结束与展示授权均由服务端控制，Test/Production 使用同一全球时间点；客户端所在地、系统时区及夏令时不改变排期，不实现“当地时间到几点才展示”。例如北京时间 `2026-09-14 16:00` 对应 `2026-09-14T08:00:00.000Z`，全球客户端都以这一 instant 为开始边界。本地计时仅用于保守撤载和刷新，不自行决定 active。统一时间边界不承诺网络与 polling 下所有设备同一毫秒挂载。

此处明确目标契约；Admin 输入转换与固定北京时间展示仍需按下方清单验证，不视为已完成的实现证明。

## 已知活动证据（复现材料，不等于上线）

- 活动：`活动A-HYT测试`
- activity ID：`yl5cga2linv5ntp4sz0oc7oo`
- 活动修订：`r5`
- Test deployment：`odquc46ptdedpba1c42w5a49`
- 排期：2026-09-14 北京时间 15:47–16:00
- 16:01:06 创建 Test；16:15:35 context 仍投影为 `active`，模拟时间为 15:53:30；16:15:37–16:15:45 有四个 OD 触点回执。

这证明旧模拟 context 可在真实窗口结束后继续生成 `active` 与回执，正是本次要切断的路径。它不是一次真实时间验收成功的证据，不能据此 promotion 或宣称上线。

## OpenDesign 本地验证（非 live Vela 联调）

本轮在实际 Chromium 中使用本地 HTTP 协议 fixture 和正式桌面宿主桥协议 fixture，经过真实客户端入口验证：Test before 零挂载，active 四触点挂载；活动仍 active 时，断网后短期授权到期使四触点全部撤下，deployment 选择保留，界面不把授权过期误报为活动 ended。生产弹窗也经过真实获取入口验证短期授权先于活动结束时撤下。缺少 Test 授权字段的 fixture 零挂载、零回执。共享 owner 的虚拟时钟测试另覆盖续期、响应耗时、本地钟后退、恢复、请求超时与迟到响应。上述是本地客户端证明，**不是** live Vela 联调、原生桌面功能或部署证明。

## 客户端核心要求：Test 与 Production 必须共用一个展示生命周期

**OpenDesign worktree 已合并展示生命周期实现。** `TestCampaignModal`、`ProductionCampaignModal`、`ProductionCampaignBadge`、`ProductionCampaignHover` 均调用 `touchpoint-lifecycle.ts` 的 `useTouchpointLifecycle`；旧的各宿主 polling/lease/wake effects 已移除。独立展示组各自持有实例，但调度、授权和代际隔离只有这一套实现，Test 不再绕开它。Test 选择/验收、生产展示频控和布局留在外层。下表保留重构前审计，不能当作当前代码状态。

### 重构前调用链与差异（历史基线）

下列行号仅定位重构前版本，符号名便于追溯；不是当前行号或 Vela 客户端的实现证明。

| 职责 | Test 重构前实现 | Production 重构前实现 | 基线判断 |
| --- | --- | --- | --- |
| 生命周期 owner | `apps/web/src/components/TestCampaignModal.tsx:583–832` 的 effect | `ProductionCampaignModal.tsx:182–353`、`ProductionCampaignBadge.tsx:63–204`、`ProductionCampaignHover.tsx:35–98`（均在同一 components 目录） | 独立；生产三个宿主也分别维护控制逻辑。 |
| 获取/刷新 | Test effect 建 context、逐 placement GET，30 秒 polling（:817–821） | `production-touchpoint-loader.ts:23` 的 `loadProductionTouchpointDecision`；modal 初始及 focus/online 获取（:238–344），badge:196、hover:96 另有 RECHECK_MS 周期 | 没有统一刷新 owner；生产 loader 只是获取复用，连生产宿主的调度也不统一。 |
| 时间与到期 | `realtimeTiming`（TestCampaignModal.tsx:484–513）按 serverTime/window 与请求单调时钟计算边界，effect 自己设 timer | 生产宿主各自计算授权截止并设 timer；modal:267–270、322–326 | Test 仅活动窗口不能替代生产授权 lease。 |
| 恢复/断网/迟到响应 | Test effect 自有 generation、AbortController、10 秒超时及 focus/pageshow/visibilitychange fence（:615–723、800–831） | 生产宿主自有 request/authorization/lease generation；modal focus/online 触发获取，加载异常 clear（:328–351） | 恢复策略和请求失效机制尚未合并。 |
| 已共享的宿主/渲染 | `useTestRuntime`、`TestTouchpointMount`、`recordVisibleTestTouchpoint` | modal/badge/hover 读取 Test store；modal/badge 调 TestTouchpointMount，hover 也调用可见性回执入口 | 仅部分宿主、store 和渲染/回执工具共用。 |

重构前，App 同时接入 Test/Production 组件，生产 modal 在存在 Test session 时退出独立生产获取 effect；这是 Test 接管宿主而非共享生命周期。重构后仍由 Test 选择接管展示，但 Test 的数据适配器与生产适配器均进入 `useTouchpointLifecycle`；共享 hook 的 references 已覆盖四个入口。

### 合并目标与准确职责

目标是**同一客户端内一个 lifecycle owner + 两个数据适配器**，不是跨 Vela/OD 仓库共享源码。Vela 客户端也需满足同一约束，但本次未重新核查其当前调用链，不能宣称它已完成共享。

- **数据获取/适配层**：分别处理 Test/Production endpoint、认证、locale、deployment/context 选择及响应验证/适配。输出给同一 controller 的是经过身份与能力校验的 decision、服务器时间/活动窗口、展示授权限制或明确的 no-decision/revocation/error 结果。适配器不得拥有 polling、到期 timer、页面事件 listener 或另一个挂载状态机。
- **唯一共享生命周期**：统一拥有 polling/重新获取调度、服务器时间边界、当前授权/可挂载状态、挂载与到期撤载、断网处理、页面恢复、请求取消和迟到响应隔离。Test 的开始边界也必须移入这里，不能继续由 TestCampaignModal 自己驱动，仅抽取一个“共同卸载计时器”仍不合格。
- **展示宿主**：modal/badge/hover 保留各自布局、交互与展示频控，但消费同一 controller 的当前授权和挂载结果；不得保留平行的取数/lease effect。授权失效时所有宿主和异步 mount 回调都受同一代际失效约束，不能重新挂回旧内容。
- **生命周期之外**：Test 选择面板只改变适配器输入；Test context 创建由 Test 适配器处理。`recordTestAcceptance`（TestCampaignModal.tsx:249–297）及 `recordVisibleTestTouchpoint`（:300–332）的验收业务留在外层，仅观察共享生命周期已授权且实际可见的结果；轮询、恢复和无效/过期响应不得产生新验收。外层不得反向维持另一套展示时钟。

OpenDesign 实施位置：`touchpoint-lifecycle.ts` 统一拥有 30 秒 polling、请求超时、服务器相对授权期限、开始边界重新 GET、页面恢复/可见性、请求取消及代际隔离。各宿主的数据适配器只获取和验证响应；生产继续调用 `loadProductionTouchpointDecision`，Test 在选择作用域创建 context 并获取 placements。相同 immutable decision 的正常 polling 续期保留挂载身份，不重复展示/验收。授权到期撤下内容，不自行将服务器 active 状态改为 ended。

### Test deployment 目录发现（OPEND-3172）

“唯一共享生命周期”指展示授权与挂载的 owner，不代表 deployment 目录只能在初始化读取。目录发现由 `test-deployment-selection.ts` 独立拥有：前台每 30 秒读取目录，focus、online、pageshow 和恢复可见时立即刷新；单次请求 10 秒超时，单飞并取消过期请求。空目录、未开始和已结束的选中活动均不能终止目录发现。

- 普通客户端沿用服务端最新优先的目录顺序选择第一个受支持 deployment；调试模式保留人工选择，不自动抢选。目录不提供排期授权，未来活动只能在 realtime decision 验证后展示。
- 相同 deployment 与快照保留原 selection 对象，不能因新 JSON 对象重建 adapter、context 或挂载。替换、快照变化和成功目录确认移除才改变选择；目录请求失败、超时、格式错误不能被当成空目录，也不能延长原展示授权。
- 账号变化、卸载和页面隐藏取消旧目录请求，迟到结果不得覆盖新选择。目录选择只输入现有 Test adapter；context、decision、开始边界、续期和到期仍由原共享生命周期负责，不在目录层复制展示时钟。
- 目录刷新不发布临时空 Test session；切换期间由现有未授权 Test session 保持 Test/Production 隔离。旧授权不能随着目录发现或重试被恢复。

### 生产展示授权约束：必须原样保留上限

生产不是“活动未结束就能一直展示”。共享的 `resolveAuthorizationDeadline` 为生产保留有效截止：

`min(authorizationExpiresAt, endsAt, serverTime + 5 分钟)`

- 三个上限都必须进入共享生命周期；不能只取 `endsAt`，不能因 polling、Test 切换、重新挂载或页面恢复重新起算并延長旧授权。活动尚 active 但授权先到期时，也必须撤载。
- 按服务器时间和请求耗时保守换算本地调度；本地时钟变化、网络延迟或页面挂起不能延长已发授权。恢复时先阻止旧授权继续挂载，再重新验证；旧响应和旧 timer 不能复活已失效 decision。
- 普通窗口 `focus` 不等同于页面恢复：页面仍可见且当前 lease 尚未到期时，立即后台验证并保留原挂载，不改变原授权截止；同一内容的有效响应只续期。`visibilitychange`、`pageshow`、`online` 仍走暂停展示的恢复路径，focus 时已过期的 lease 也先撤下。请求失败、超时、匹配撤销及到期的清理规则不变。
- Test 弹窗与 Production 使用同一展示频控：弹窗实际可见即写入 localStorage `touchpoint-displayed:v1:<账号>:<活动ID>`，同一账号、活动在本设备只自动弹出一次，跨刷新、重新挂载与客户端重启保持；Test 与 Production 共用该记录。已打开的弹窗可在续期、验证与语言切换中保持；此后同一活动的新 deployment、临时空 decision 或关闭后的重新下发均不再自动弹出。账号角标与 hover 不受该频控影响。
- 生产 loader 的 404 是 no-decision，并不自行撤销有效 lease；只有有效且绑定当前 touchpointDecisionId/deploymentId/activityId/contentVersionId 的 410 receipt 才构成服务端撤销。匹配的撤销清除当前展示，但不停止后续发现新活动。非 Abort 的当前请求失败仍诊断后 clear。恢复期间先暂停旧展示；no-decision 或不匹配撤销只能保留尚未到期的原授权及原截止，不能续期或复活过期授权。
- **用户已确认：Test 也由服务端返回 authorizationExpiresAt，与 Production 使用相同的短期展示授权规则。** OpenDesign Test DTO 已将此字段设为必填；适配器不得伪造授权或 fallback 到仅受 endsAt 限制。Vela 新响应仍待交付验证。
- Vela 当前生产服务端最长授权 60 秒（`services/api/src/touchpoints/persistence.ts`：`resolveProductionRuntime`）；Test 每 GET 使用同一 serverTime 生成 `authorizationExpiresAt = min(endsAt, serverTime + 60 秒)`。before/ended 也返回该字段及完整 metadata，但不可挂载；ended 的授权时间可早于 serverTime。客户端 5 分钟安全上限不是服务端授权时长，不能延长 60 秒授权。
- 两种数据源进入同一授权与展示算法：服务器确认 active 且授权有效才能挂载；授权或活动到期取较早者撤载，断网也不续期。只有新的有效服务端响应可以续期；本地计时只能使展示失效，不能自行将 before 激活。

### 两层契约：API 可不同，展示生命周期相同

Test/Production 保留各自 endpoint、认证、选择方式和响应形状，不要求生产接口改为 Test 三态 200。两个适配器统一输出已验证的 identity/content、服务器窗口及授权限制，交给同一 lifecycle owner；统一 polling、挂载、撤载、恢复和迟到响应隔离。Test 选择与验收外置。生产既有 no-decision、撤销和失败语义按前文保留，不把不同响应混为相同撤销信号。

OpenDesign 本地 DTO 与客户端已按上述分层实现；Vela 侧 DTO、服务端、适配器及 fixtures 仍需迁移并完成真实联调，不能因本地实现完成而宣称两仓已交付。

### 共享完成的验收要求（两仓整体仍待验收）

1. 从 Test 和 Production 真实入口分别追踪到同一 lifecycle owner；旧平行 effects/timers/listeners 已移除，适配器仅取数与适配。代码调用链证据与行为验证都要有。
2. 在同一生命周期的验证入口替换两个实际适配器，覆盖 polling、before→active→ended、离线到期、页面恢复和迟到响应；再分别通过两种环境的实际宿主验证挂载/撤载。
3. 生产额外覆盖 authorizationExpiresAt 早于 endsAt、5 分钟上限、窗口仍 active 但 lease 已过期、匹配/不匹配 410 receipt、404 不等于撤销；确认 Test 切换和恢复不会延长生产授权。
4. Test 面板与验收回执外置；非 active/未授权/未实际挂载不验收，polling 不重复回执。生产原有展示频控与交互也必须保留。

此前 27 个相关 Test/host 测试和本地 Chromium Test fixture 的结果，只证明先前 Test 改动的已验证行为；**既不证明 Production 已走同一逻辑，也不证明本节共享目标完成**。

## Wire 契约

OpenDesign 客户端 DTO 位于 `@open-design/contracts/api/touchpointTestRuntime`。Vela 与 OpenDesign 按下列 wire 契约对齐，但两个仓库**不得互相 import**对方的 contracts/package；Vela 应用等价的本地 type/schema，不能另造不同字段或语义。

```ts
import type {
  TestRuntimeAcceptanceRequest,
  TestRuntimeContext,
  TestRuntimeContextRequest,
  TestRuntimeDecision,
  TestRuntimeScenario,
  TestRuntimeScheduleState,
  TestRuntimeTiming,
} from "@open-design/contracts/api/touchpointTestRuntime";

// TestRuntimeScenario = "realtime"
// TestRuntimeScheduleState = "before" | "active" | "ended"
// TestRuntimeContextRequest = { deploymentId: string; scenario: TestRuntimeScenario }
// TestRuntimeContext = TestRuntimeContextRequest & {
//   testerMemberId?: string; updatedAt: string // ISO-8601
// }
// OpenDesign DTO 已同步授权字段；Vela 等价类型与响应仍需实现/验证。
// TestRuntimeTiming = { serverTime: string; startsAt: string; endsAt: string; authorizationExpiresAt: string } // UTC ISO-8601
// TestRuntimeDecision<Content, StaticActions> = {
//   deploymentId: string; activityId?: string; snapshotHash?: string;
//   artifactHash?: string; manifestHash?: string; placementKey: string;
//   requiredCapabilities: string[]; content: Content; staticActions: StaticActions;
//   testContext: TestRuntimeContext & { scheduleState: TestRuntimeScheduleState }
// } & TestRuntimeTiming
// TestRuntimeAcceptanceRequest = {
//   placementKey: string; hostVersion: string; locale: string;
//   scenario: TestRuntimeScenario; evidence: string
// }
```

`simulatedAt` 已删除，不得出现在 context、decision、数据库新写入、客户端校验或 acceptance 依据。`testerMemberId` 由服务端认证得到；客户端不得伪造它。`TestRuntimeDecision<Content, StaticActions>` 在顶层保留 deployment/activity/snapshot/artifact/manifest identity、placement、`requiredCapabilities`、content 和 staticActions，并附 timing/context；它是统一 shape，不得将 non-active 做成缺 metadata/content 的变体。

### 请求与响应范例

继续使用既有 endpoints。

```http
POST /api/v1/touchpoints/runtime/test-context
Content-Type: application/json

{"deploymentId":"odquc46ptdedpba1c42w5a49","scenario":"realtime"}
```

```http
201 Created
Content-Type: application/json

{
  "deploymentId":"odquc46ptdedpba1c42w5a49",
  "testerMemberId":"<authenticated-member-id>",
  "scenario":"realtime",
  "updatedAt":"2026-09-14T08:15:35.000Z"
}
```

```http
GET /api/v1/touchpoints/runtime/test?deploymentId=odquc46ptdedpba1c42w5a49&placementKey=vela.web.console-overlay&locale=zh-CN
```

以下是**局部说明性响应**，只展开本次新增/关键字段；`content` 保持既有完整 payload shape，不是此处省略字段的替代协议。

```http
200 OK
Content-Type: application/json

{
  "deploymentId":"odquc46ptdedpba1c42w5a49",
  "activityId":"<existing-activity-id>",
  "snapshotHash":"sha256:<existing-64-hex-snapshot-hash>",
  "artifactHash":"sha256:<existing-64-hex-artifact-hash>",
  "manifestHash":"sha256:<existing-64-hex-manifest-hash>",
  "placementKey":"vela.web.console-overlay",
  "requiredCapabilities":["hover","static-action"],
  "staticActions":[],
  "content":{"id":"<existing-content-version-id>","placementKey":"vela.web.console-overlay","...":"existing payload unchanged"},
  "testContext":{
    "deploymentId":"odquc46ptdedpba1c42w5a49",
    "testerMemberId":"<authenticated-member-id>",
    "scenario":"realtime",
    "updatedAt":"2026-09-14T08:15:35.000Z",
    "scheduleState":"ended"
  },
  "serverTime":"2026-09-14T08:15:45.000Z",
  "startsAt":"2026-09-14T07:47:00.000Z",
  "endsAt":"2026-09-14T08:00:00.000Z",
  "authorizationExpiresAt":"2026-09-14T08:00:00.000Z"
}
```

`startsAt < endsAt` 必须成立；`serverTime` 可以在窗口外。临界点 start 包含、end 排除。Vela 用单一 `serverTime` 同时生成 response 与 `scheduleState`，避免同一响应自相矛盾。

同一 serverTime 还用于生成最长 60 秒的 authorizationExpiresAt。active 响应必须满足 `serverTime < authorizationExpiresAt <= min(endsAt, serverTime + 60 秒)`。缺少/非法授权时间或超出上限不得挂载、回执或续期；before/ended 带完整字段不代表授权展示。before 必须重新 GET 得到 active 且有效的新授权，不能按本地计时启用旧响应。

```http
POST /api/v1/touchpoints/test-deployments/odquc46ptdedpba1c42w5a49/acceptances
Content-Type: application/json

{
  "placementKey":"vela.web.console-overlay",
  "hostVersion":"<existing-host-version>",
  "locale":"zh-CN",
  "scenario":"realtime",
  "evidence":"https://<existing-approved-evidence-location>",
  "hostCompatibility":{"...":"existing optional report shape"}
}
```

窗口不是 active 时，服务端必须拒绝写入（保持项目现有错误风格；可用明确码 `test_schedule_not_active`），不创建 acceptance，避免 promotion 将其误认为验收齐全。

## Vela 实施定位与改法

以下位置来自 `powerformer/vela` 检索到的当前实现（commit `7cbaeb015196c8ed4bdd669905b3811250335b59`），是待迁移引用，不代表已修改。

| 位置 | 当前职责/旧行为 | Vela 必须改动 |
| --- | --- | --- |
| `services/api/src/touchpoints/routes.ts`：`testContextSchema`、`POST /api/v1/touchpoints/runtime/test-context` | schema 接受 `before/active/after/wake`，再调 `repository.selectTestContext` | 改为严格 `{ deploymentId, scenario: z.literal("realtime") }`；继续从认证 principal 填 tester；旧值或额外 `simulatedAt` 返回既有 `invalid_test_context` 400。 |
| 同文件：`GET /api/v1/touchpoints/runtime/test` | 调 `repository.resolveTestRuntime({ deploymentId, placementKey, locale, testerMemberId })` 后直接返回 decision | 保留认证、查询、404、413；repository 每 GET 取一次 now，返回完整 decision、顶层 timing 及重算 state。route 不缓存 decision。before/ended 仍 200。 |
| 同文件：`POST /api/v1/touchpoints/test-deployments/:id/acceptances` | 接受任意非空 scenario 后调 `recordTestAcceptance` | schema 收紧为 `z.literal("realtime")`；repository 写入事务内再判真实 active，不能只作 route 前置检查。 |
| `services/api/src/touchpoints/persistence.ts`：`TestScenario`、`TestContext`、`TestContextRow`、`toTestContext`、`simulatedTimeForScenario`、`scheduleStateAt`、`TestRuntimeDecision` | 四种模拟场景；context 有 `simulated_at`；模拟函数生成时刻；decision 无顶层 timing | scenario 只留 realtime；删 `simulatedAt`/`simulated_at` 投影和 `simulatedTimeForScenario`；`scheduleStateAt` 可保留为纯函数但输入必须是本次 server instant；decision 顶层加 `serverTime/startsAt/endsAt/authorizationExpiresAt`。 |
| 同文件：`PostgresTouchpointRepository.selectTestContext`、`resolveTestRuntime`、`recordTestAcceptance` | context 写入/更新；resolve 拼 Test snapshot/context；acceptance 写证据 | select 只持久化 realtime 与 `updated_at`；resolve 每 GET 用 now + snapshot window 构建完整 timing/state 及最长 60 秒授权；acceptance 的 active 判定与写入在同一事务。 |
| touchpoints 的 test-context schema migration（路径/命名遵从 Vela 现有 migration 约定） | 当前 `touchpoints.test_contexts` 含 `scenario` 与 `simulated_at`；API SQL mock 也引用它 | context 是可重选临时状态，不是 deployment/acceptance 审计。clean cutover 下：停写旧服务后令旧 contexts 失效并清理，DB owner 批准后收紧 schema 到 realtime 并移除 `simulated_at`。若不能安全清理，可保留 legacy 存储但 runtime 必须拒绝读取/解释它；不得改 deployments、acceptances 或其历史。 |
| `apps/web/src/components/test-campaign-contract.ts` | `TestScenario`、`VelaTestContext`、`VelaTestDecision` 和 `velaTestDecisionMatchesSelection` 比较 `simulatedAt`，并要求 active | 切到 realtime DTO：删旧 scenario/simulatedAt；校验完整授权字段、最长 60 秒上限、ISO timing、`startsAt < endsAt`、state 与 serverTime/window 一致；保留 snapshot、placement、capabilities、staticActions 绑定。non-active 保留同形 content，但不挂载。 |
| `apps/web/src/components/test-campaign-console.tsx`、`apps/web/src/components/production-campaign-float.tsx` | 历史检索入口，非本次 Vela 调用链核查结果 | 在 Vela 客户端内核查并合并到同一生命周期；console 保留选择/验收外层，Test/Production 获取适配器负责协议差异。不能仅迁移 realtime DTO 或复用 float 就声称共享，必须提交实际调用链与两环境验收证据。 |

## 需迁移引用与验证

已检索到的引用：

- `services/api/test/touchpoints-test-context.test.ts`：mock `touchpoints.test_contexts` SQL 与 context persistence。
- `services/api/test/touchpoints-browser-runtime-routes.test.ts`：runtime routes/依赖注入。
- `services/api/test/touchpoints-activities.test.ts`：活动/Test runtime 行为。
- `services/api/test/e2e/touchpoints-restore-lifecycle.test.ts`：Test deployment 生命周期与 promotion/restore 边界。
- `apps/web/tests/unit/production-campaign-float.test.ts`、`apps/web/tests/browser-agent/production-campaign-float.spec.ts`：Web 浮层 fixture/消费。
- `apps/web/src/components/test-campaign-console.tsx`、`apps/web/src/components/production-campaign-float.tsx`、`apps/web/src/components/test-campaign-contract.ts`：Admin/Vela Web 类型、选择校验、渲染入口。
- `services/api/src/touchpoints/promotion.ts` 与 `routes.ts` promotion path：`acceptance_incomplete` 阻断仍必须只承认真实 active 窗口形成的 acceptance。

实现时对上述导出类型/方法先跑 references，再全量迁移实际命中处；不要臆测或改动未检索到的消费者。

## 历史 acceptance 有效性：同库与跨库必须同时过滤

Vela review 补充的交付要求：同库 promotion 和跨库 `getPromotionEvidence` 必须消费同一份有效性判定；仅收紧新 acceptance 写入不能隔离旧证据。本次不声称远程 Vela 已实现该过滤。

- 先过滤，再计算必需 placement 的完整性。有效记录必须为 `scenario === "realtime"`，绑定目标 Test deployment、不可变 snapshot/hash、placement 及既有身份/兼容性要求；可信服务端验收时刻必须位于 `[startsAt, endsAt)`。只有 scenario 字符串不够，缺失可信时间/绑定信息的记录不得计入。
- 旧 before/active/after/wake 或未知 scenario 保留审计但不计入；不得改名 realtime、补造时间或重写历史。判断的是验收发生时刻，不是 promotion 当前时刻；已结束活动中的有效历史 realtime 验收不会仅因现在过期而失效。
- **同库 promotion**：过滤后未覆盖所有必需 placement，沿用 `acceptance_incomplete` 阻断。
- **跨库 `getPromotionEvidence`**：导出/聚合前应用同一过滤，不得把原始记录 count 或未过滤的“齐全”布尔值作为证据。跨库消费侧须验证证据来源、绑定和有效性契约，拒绝旧导出或不可验证记录，不能绕过源侧过滤。格式按 Vela 现有跨库协议落地，不在本文臆造字段。
- 两条路径均须验收：仅旧模拟记录失败；旧新混合但有效覆盖不足失败；完整有效 realtime 证据通过；错 snapshot/placement、窗口外或缺少可信时间不计入；跨库导出/消费后结论一致。原始审计记录保持不变。

## 严格协议切换：Test 维护窗口与旧页面刷新

以下为待另行批准的操作方案，本文不执行。严格协议切换没有新旧兼容期；仅写“先 Vela、后 OD”不足以保护两仓发布之间的 Test 使用者。

1. 维护前准备好两仓新协议、各客户端共享生命周期、两条 promotion 证据过滤及可分发构建。确认能暂停 Test 而不影响 Production；若没有现成暂停/版本识别设施，须先补齐，不能假定已有开关。
2. **进入 Test 维护窗口**：通知测试者关闭旧 Test 页面，暂停选择、展示和验收；服务端受控暂停 Test context/runtime/acceptance 入口及相关 promotion 证据导出/消费。仅隐藏选择面板不够，未刷新的旧页面也必须被拒绝。Production runtime 保持服务。
3. 停止旧服务写入后，再由 DB owner 单独批准 migration；Vela schema、persistence、routes、active-only acceptance 和两条证据过滤作为同一发布单元切换。令旧临时 contexts 失效，不允许新旧实例同时按不同语义服务 Test；不重写 deployment、acceptance 历史或 snapshot。
4. **升级并刷新客户端**：Vela Web 和 OD Web 刷新至新 bundle；OD 打包客户端升级并重启至新构建，仅刷新旧版本不能代替升级。测试者重新选择 deployment，创建 realtime context，不恢复旧模拟 context。未升级/未刷新的页面继续被服务端拒绝，并有明确维护/升级/刷新提示；提示和版本识别是发布前提，不是本文声称已实现的功能。不得静默兼容旧 scenario。
5. 维护期间先走受控验收：新链路 before/active/ended、离线到期、页面恢复、迟到响应、生产授权早于活动结束、同库/跨库证据过滤，以及旧页面实际被拒绝。确认每个客户端两条入口进入同一 lifecycle owner 后，再开放 Test。维护窗口结束取决于完整链路验收，不取决于某一个仓库部署完成。

失败时保持 Test 不可用；不得通过恢复模拟 active、重放旧 context 或放松历史证据过滤回滚。以上是操作交接，不构成远程部署或数据库修改授权。

## 边界

- 未选择 context、deployment 不存在、placement 不匹配、无 runtime 授权保持现有 404/认证失败语义；不得以虚假 active 掩盖。
- `before`/`ended` **不是 404**：必须 HTTP 200，含完整既有 identity、snapshot hashes、placement、capabilities、staticActions、context、timing 和同形 `content`。它们供客户端等待开始/停用；客户端/host 非 active 时禁止挂载 content、发 runtime event 或 acceptance，并必须撤下已显示触点。
- `updatedAt` 是 context 选择更新时间，不替代 `serverTime`，不能判排期。客户端本地钟只可用于刷新/展示，不决定 active。
- 本轮仅修改 OpenDesign 本地客户端、契约、构建入口和相关测试/交接记录，不修改 Vela 运行时代码或远程环境。“不改生产”指不借此改变生产服务端协议、展示授权上限及既有推广门槛。历史证据过滤仍由 Vela 补齐；不重写 deployment/acceptance 审计或内容快照，不更改凭证和数据库连接。

## Vela 与客户端后续验收清单

- [ ] Admin 在不同电脑时区下配置/回显同一北京时间，保存的 UTC startsAt/endsAt 不变；Test/Production 客户端切换 Asia/Shanghai、UTC、America/Los_Angeles 后，对同一服务器 instant 的开始、结束和授权判定一致，覆盖开始包含、结束排除以及当地夏令时切换。
- [ ] 各客户端内 Test/Production 实际入口进入同一生命周期；旧平行调度/lease effects 移除；适配器仅取数、认证、选择和响应适配。
- [ ] 生产 authorizationExpiresAt、endsAt、serverTime + 5 分钟上限与 404/410/加载失败语义保留；两环境分别验证 polling、挂载、离线、恢复和迟到响应。
- [ ] Test DTO、服务端、两仓适配器和 fixtures 同步 authorizationExpiresAt；两种数据源均验证活动仍 active 但授权先过期、断网不续期、恢复获取新授权、before 不被本地激活、缺失授权字段严格拒绝。
- [ ] Test 面板与 acceptance 留在生命周期之外；Test fixture 不被当作 Production 共享证据。
- [ ] 同库 promotion 与跨库 getPromotionEvidence 使用同一历史验收有效性规则，混合/无效证据不能满足完整性。
- [ ] Test 维护窗口、旧页面刷新/旧版本升级、未升级请求拒绝、失败保持 Test 不可用均已受控演练；Production 不因 Test 切换停服。

- [ ] POST context 只接受严格 body `{deploymentId,scenario:"realtime"}`；四种旧值、额外 `simulatedAt`、畸形 body 均 400。
- [ ] 201 context 无 `simulatedAt`，仅有 realtime scenario、deployment、认证得到的 tester、`updatedAt`。
- [ ] 同一 deployment 在真实 starts 前、窗口内、ends 后的 GET 都是 HTTP 200，含合法 timing 与完整 metadata/identity，并依次为 before/active/ended；不重 POST context；只有 active 且授权有效才挂载 content。
- [ ] GET 每次由 server clock 判定；旧 context updatedAt/历史模拟时刻不能让结束窗口变 active。
- [ ] decision 的 identity/content/manifest/artifact/snapshot hashes、placement、capabilities、staticActions 保持精确绑定 immutable snapshot。
- [ ] acceptance 只接受 realtime，before/ended 由服务器拒绝且不落库；active 成功写入仍可走既有 promotion。
- [ ] migration 仅在 DB owner 批准后清理临时旧 contexts，或保留 legacy 但让 runtime 拒绝它；不 mutation deployments、acceptances、历史审计或发布 snapshot hash。
- [ ] Vela Web console/float/fixtures 无 simulated fallback；无效时间 response 不展示/不回执，non-active 200 仅等待/停用。
- [ ] 运行 Vela API scoped tests（test-context、browser runtime routes、activities、promotion/restore lifecycle）、Vela Web consumer tests，并做真实时钟本地 API smoke。

## 部署阻碍与交付状态

| 交付面 | 状态 | 可宣称的范围 |
| --- | --- | --- |
| OpenDesign 当前 worktree 客户端与 contracts | 已接入共享生命周期及必填 Test 授权；本地测试与浏览器协议 fixture 验证 | 覆盖本地客户端，不代表 Vela 新协议已部署；真实联调与正式发布仍待完成。 |
| Vela runtime、persistence、migration、acceptance 与 Vela Web 消费者 | 待实现、待部署、待真实窗口验证 | 不能将本文协议、OpenDesign worktree 代码或 A-HYT 的旧模拟回执表述为 Vela 已部署或真实时间活动已上线。 |

剩余上线阻碍：Vela 客户端共享生命周期与服务端授权响应；migration、每 GET realtime、active-only acceptance、同库 promotion 与跨库 getPromotionEvidence 历史过滤；维护窗口、旧页面策略与两仓真实窗口联调。OpenDesign 本地实现不替代这些交付，也不构成部署或数据库修改授权。