# 真人录证：定位 place commit 瞬间

> **当前 P0 必做任务**。在修复 RPA 之前，必须先完成本录证。  
> **冻结**：录证完成并分析前，禁止新增 `fix-place/*`、`place-commit-strategy`、`selection-trace`、新回退策略、新点击方式。

---

## 目标

找到 MotherShip widget 在**真人操作**下，`GET axel/location/place/{placeId}` 真正发生的瞬间，并与 RPA 失败路径对比。

成功判据（录证侧）：

- HAR + Trace + 录像 + Console + Network 五类产物齐全
- `commit-moments.json` 中至少有 **2 次** `GET place` 200（提货 + 派送）
- 能说明：点选联想后多少毫秒内触发 place commit、伴随哪些 DOM/网络事件

---

## 一键启动

```powershell
cd x:\work\chajia
npm run record:human-commit-baseline
```

非 TTY / Enter 无效时：

```powershell
$env:HUMAN_RECORD_FILE_TRIGGER="1"
npm run record:human-commit-baseline
```

脚本会打印 `runId` 和产物目录，例如：

```
.rpa/human-commit-baseline/a1b2c3d4/
```

---

## 人工操作顺序

1. 浏览器打开 MotherShip 报价 widget
2. **提货**：键入街道 → 点选联想 → 确认 widget 显示已锁定
3. 触发检查点 1（Enter 或触发文件 `triggers/after-pickup`）
4. **派送**：同上
5. 触发检查点 2（`triggers/after-delivery`）
6. 填货物 → 点 Get Quote → 等待报价档位出现
7. 触发检查点 3（`triggers/after-quote`）
8. 触发结束（`triggers/finish`）

### 文件触发（推荐 Windows）

```powershell
# 将 {runId} 替换为脚本启动时打印的 ID
New-Item -Force ".rpa\human-commit-baseline\{runId}\triggers\after-pickup"
New-Item -Force ".rpa\human-commit-baseline\{runId}\triggers\after-delivery"
New-Item -Force ".rpa\human-commit-baseline\{runId}\triggers\after-quote"
New-Item -Force ".rpa\human-commit-baseline\{runId}\triggers\finish"
```

---

## 产物说明

| 文件 | 用途 |
|------|------|
| `baseline.har` | 全量 HAR，DevTools 导入分析 |
| `trace.zip` | Playwright Trace（含 CDP、截图、DOM 快照） |
| `video/*.webm` | 屏幕录像，对照时间轴 |
| `console.ndjson` | 浏览器 Console 逐行 |
| `network.ndjson` | axel/location、axel/quote、Google Places 请求 |
| `checkpoints.json` | 四个检查点时间戳 |
| `commit-moments.json` | 自动捕获的 `GET place/{id} 200` |
| `summary.json` | 录证摘要与分析提示 |

---

## 分析 commit 瞬间

### 1. 自动摘要

```powershell
Get-Content .rpa\human-commit-baseline\{runId}\commit-moments.json
Get-Content .rpa\human-commit-baseline\{runId}\summary.json
```

终端在录证过程中会打印：

```
[录证] ★ place commit 200 @ +12345ms phase=after_pickup
```

### 2. Playwright Trace（CDP）

```powershell
npx playwright show-trace .rpa\human-commit-baseline\{runId}\trace.zip
```

在 Trace 中：

- 时间轴对齐 **Network** 面板，过滤 `place/`
- 查看点选联想**前一帧 / 后一帧**的 DOM 与鼠标事件
- 记录：是 `click`、`keydown`、`place_changed` 还是 blur 之后触发

### 3. HAR

用 Chrome DevTools → Import HAR → 过滤 `axel/location/place`

对比：

- `search` 响应中的 `placeId`
- 随后 `GET place/{id}` 的 initiator / timing

### 4. 与 RPA 对比

| 维度 | 真人录证 | RPA worker 日志 |
|------|----------|-----------------|
| place 200 次数 | commit-moments.json | `placeRequestObserved` |
| 触发阶段 | checkpointPhase | `selection-trace` / adapter events |
| 点选方式 | trace 录像 | mothership-styled-click / keyboard |

**若真人稳定 2 次 place 200，RPA 为 0** → 停止改 timeout/stealth，只复刻真人事件序列。

---

## 推荐测试地址（与 prove 一致）

| 侧 | 地址 |
|----|------|
| 提货 | 1234 Warehouse Street, Los Angeles, CA |
| 派送 | 5678 Distribution Way, Farmers Branch, TX |
| 货物 | 2 托 × 500 lb，48×40×48 in |

也可用 POI 难例（Convention Center → Ocean Drive）做第二遍录证。

---

## 冻结范围（录证期间）

禁止新增或扩展：

- `workers/rpa/fix-place/*`
- `place-commit-strategy.ts`
- `selection-trace.ts`
- 新的 commit 回退链 / CDP 点击路径

允许：

- 本录证脚本与文档
- 基于录证结论的**单一**最小复刻（需先写分析结论）

---

## 完成标准

- [ ] 至少 1 次完整录证（双地址 + 报价）
- [ ] `commit-moments.json` ≥ 2 条 place 200
- [ ] 输出 1 页分析：`docs/mothership-commit-瞬间分析.md`（人工或 AI 根据 trace 填写）
- [ ] 团队评审：确认 RPA 下一步只复刻真人事件，不继续堆策略