85 KiB

Raw Blame History Unescape Escape

查价系统 PRD v0.6

版本	日期	作者	说明
v0.1	2026-06-16	产品	背景与核心功能初稿（第 1–7 章）
v0.2	2026-06-16	产品负责人/架构师/技术PM	可开工版：矛盾收敛、全章节补齐（1–12 章）
v0.3	2026-06-16	QA负责人/SRE/架构师	补齐第 11 章异常韧性设计、第 12 章验收标准（可自动化）
v0.4	2026-06-16	产品/架构	对齐 Mothership 实测：四档报价、地址联想、托盘数、单位换算、嵌入宿主、官方尺寸限制
v0.5	2026-06-17	产品/架构	明确 Mothership 公开报价页匿名查价；RPA 默认真实抓取，Mock 仅 CI/单测
v0.6	2026-06-17	产品/架构/SRE	RPA 入口 URL 多候选探测、Selector 录制规范、匿名 storageState、入口/抓取失败分类
v0.7	2026-07-13	产品/架构	新增 Flock Freight 报价源模块（§14）；扩展点与硬限对齐官网实测

本版业务权威为 v0.7（在 v0.6 基线上增量）。Mothership 相关规则无变更处仍以 v0.6 为准。技术栈与实现细节见查价系统-技术设计.md；界面与交互见查价系统-UI设计.md；RPA 解阻塞参考见参考-Mothership-RPA-开源借鉴与解阻塞.md。异常处理见第 11 章；验收与上线门禁见第 12 章；Flock Freight 见第 14 章。

工程收敛决策（全局生效）

编号	决策	唯一规则
GD-1	RPA 模型	一次询价 = 1 次 RPA；单次会话内抓取 4 档报价（standard/guaranteed × lowest/fastest）；严禁多次 RPA
GD-2	缓存模型	三层固定优先级：L1 `request_id`(24h 幂等) > L2 `cargo_hash`(3min 热缓存) > L3 stale(30min，仅 RPA 失败降级)
GD-3	service_level / rate_option	均不进入 cache key；缓存仅按货物维度；四档一次返回
GD-4	成功率指标	拆分三指标：API success rate（含缓存）/ RPA success rate（真实外呼）/ realtime rate（真实 RPA 占比）；不使用单一 99.5%
GD-5	询价交互模型	异步：`POST /quotes` 立即返回 `quote_id` + 状态；客户端轮询 `GET /quotes/{quote_id}`
GD-6	加价基准	仅对运费 `raw_freight` 按百分比加价；上限 30%；未配置客户按 0%
GD-7	币种	本期仅 USD；多币种字段保留但不启用
GD-8	货物类型	本期枚举固定为 9 项（见 §4.3.6）；不做「实施时再抓」
GD-9	地址校验	Mothership 报价页为地址联想下拉，禁止仅填街道后 Enter；须携带已选联想项（`place_id` 或等效选中快照）方可询价
GD-15	RPA 报价入口	`MOTHERSHIP_QUOTE_URLS` 须为 headed 录制验证的匿名公开报价 URL 列表（逗号分隔、按序探测）；禁止默认或示例使用 `dashboard.mothership.com`、`www.mothership.com/quote`
GD-11	嵌入形态	查价为宿主系统内嵌能力，不自建客户/运营登录；本期仅保留管理端（预警/RPA/开发进度）
GD-12	货物计量	使用托盘数（`pallet_count`），对齐 Mothership `freight[].quantity`（type=Pallet）；禁止「件数」
GD-13	单位换算	前端/API 可接收 kg/cm；落库与 RPA 前强制换算为 lb/in（GD-10 精度不变）
GD-14	尺寸重量上限	仅以 Mothership Help Center 公布值为硬校验；禁止自定义宽范围
GD-10	金额精度	一律 `DECIMAL(12,2)`，四舍五入 `ROUND_HALF_UP`，保留 2 位
GD-16	Flock Freight	第二报价源（Phase 扩展）；入口 `https://app.flockfreight.com/get-a-quote`；硬限与结果档位见 §14；校验口径与 Mothership 分源独立，禁止混用上限

第 1 章背景与目标

1.1 目的

为客户提供卡派（LTL）自助查价能力，以美美与共作为报价中台，通过 RPA 从 Mothership 获取报价，叠加运营加价后返回客户。本章定义业务动机、目标与边界。

1.2 现状与痛点

痛点	表现	影响
人工查价慢	客服手工登录 Mothership 录入并回传	单次 3–10 分钟，高峰排队
报价不一致	操作习惯差异、in/cm 换算错误	预算与实付偏差，客诉
难规模化	无法并发响应	限制业务增长

1.3 建设目标与衡量

目标	定义	衡量指标（见 §10、§12）
提速	客户自助，无需人工	查价响应 P95 < 30s
降本	减少人工查价	RPA 调用次数下降（缓存命中率）
减少偏差	RPA 与人工一致	RPA vs 人工偏差 ≤ 5%

1.4 系统定位

宿主业务系统（美美与共等）
   ├─ 内嵌查价组件 / 调用查价 API（宿主鉴权，透传 customer_id）
   └─ 运营加价由宿主配置或 API 写入（本期无独立运营端）
      │ HTTP
美美与共 报价中台（本期建设主体）
   ├─ 查价编排服务 Quote Orchestrator
   ├─ 缓存层 Redis（L1/L2/L3）
   ├─ RPA 队列 BullMQ + Worker Pool（Playwright）
   ├─ 加价引擎 Pricing Engine
   ├─ 预警模块 Alert
   ├─ 管理端（仅管理员：预警/RPA/开发进度）
   └─ 持久层 MySQL（quote_record / idempotency / markup_config / alert_log / quote_cache_meta）
      │ RPA
Mothership（外部报价源，仅 RPA）

美美与共：报价中台，负责编排/加价/缓存/预警/落库；查价 UI 嵌入宿主，不单独面向终端客户开户。
CC：本期不接，Phase 2 通过 API 对接（接口与字段已预留）。
Mothership：唯一报价源，仅 RPA；报价页地址须从联想列表点选，结果含 standard/guaranteed 各 最低价格 / 最快递送 选项。

1.5 MVP 边界

本期包含：宿主内嵌查价 API/组件、Mothership RPA（四档报价）、运营加价（宿主/API 配置）、询价记录、三层缓存、缓存降级、偏差预警、管理端（预警中心 + RPA/开发进度，无独立客户/运营登录页）。

本期不包含：CC 对接、Mothership API、嵌入私仓预报、Priority1、Flock Freight 实现（口径见 §14，本期仅文档）、下单、对账、多币种、独立客户查价 H5 账号体系、独立运营管理端登录。

交付约束：3 周；团队 = 1 技术 + Cursor + 1 产品经理。

第 2 章用户与场景

2.1 角色与鉴权

角色	来源	鉴权	权限
宿主系统	业务系统内嵌查价或服务端调用	宿主签发 Service Token / API Key（或宿主 JWT 经网关换票）；请求体携带 `customer_id`	代终端用户提交询价、查历史、配置加价（若宿主开放）
管理员	报价中台管理端	JWT + RBAC `alert:read` `rpa:operate`	查看/处理预警、RPA 状态、开发进度指标；本期唯一需登录的角色

鉴权规则：

查价类 API：Authorization: Bearer <宿主 token>；customer_id 由宿主传入，中台校验 token 与租户绑定关系，越权 403。
管理端 API：管理员 JWT；与宿主 token 隔离。
本期不提供 customer_demo / operator_demo 等独立业务账号；Demo/联调使用宿主模拟 customer_id + 管理端 admin 账号。

2.2 场景一：宿主内嵌查价（主路径，异步模型）

前置：用户在宿主业务系统内操作；宿主前端或 BFF 持有 Service Token。

宿主页面加载内嵌查价组件（或跳转宿主路由）。
填写提货/派送地址（须从地址联想列表点选，见 §4.2.1）、单托重量与尺寸（可用 kg/cm 录入）、托盘数、货物类型。
宿主调用 POST /api/quotes（前端生成 request_id）。
服务端换算为 lb/in → 校验 Mothership 官方范围 → 返回 quote_id + processing（或缓存命中 done）。
轮询 GET /api/quotes/{quote_id}（2s，最长 30s）。
status=done：展示 4 档报价（standard/guaranteed × lowest/fastest），默认 standard + lowest；3 分钟倒计时。
3 分钟内同货物重复查价：命中 L2，不触发 RPA。
倒计时归零：宿主弹窗确认后以新 request_id 重询。

示例输入：LA 已选联想地址 → Dallas 已选联想地址，单托 500 lb，48×40×48 in，2 托盘，general_freight。

示例输出（节选 2 档，实际返回 4 档）：

项目	standard · lowest	guaranteed · fastest
rate_option	最低价格	最快递送
运费 raw_freight	$320.00	$410.00
客户价 final_total（加价 10%）	$352.00	$451.00
时效	预计 5–7 天	保障 3 天内

2.3 场景二：宿主配置加价

宿主运营后台或 PUT /api/markup-configs/{customer_id}（Service Token + pricing:markup:write）。
设置运费加价比例 0–30%（步长 0.1）。
仅影响该 customer_id 之后的新询价；历史不重算。
报价中台管理端不提供运营加价 UI（仅管理员查看预警/RPA）。

2.4 场景三：管理员处理预警

「预警中心」列表展示预警（站内）。
查看详情：quote_id、类型、原始价、对比价、偏差%、时间。
操作：标记已处理 / 暂停 RPA Worker / 触发人工兜底录入。

2.5 场景四：RPA 失败降级（异常路径）

失败分类（v0.6）：

类型	典型原因	错误码/告警	是否走 L3
入口错误	URL 错误、404、登录页且无凭据、preCheck 无表单	`STRUCT_CHANGE` / `QUOTE_ENTRY_UNAVAILABLE`	是（若有 stale）；不消耗 RPA 重试配额
抓取错误	超时、验证码、DOM 变更 mid-flow、四档不全、价格 ≤0	`RPA_CAPTCHA` / `RPA_DATA_INVALID` / `QUOTE_TIMEOUT` 等	是
地址未锁定	RPA 补选联想失败	`ADDRESS_SUGGESTION_NOT_FOUND`	宿主路径 400；Worker 路径走 L3

主路径：

RPA 超时 / 验证码 / 封禁 / 入口错误 / 抓取错误。
按 GD-2 读取 L3 stale（≤30min）。
命中：返回该报价，is_realtime=false，写 STALE_FALLBACK 预警。
未命中：status=failed，错误 QUOTE_UNAVAILABLE，写 RPA_FAILED 预警，提示宿主稍后重试。

第 3 章范围与扩展点

3.1 功能范围矩阵

模块	本期	说明
独立查价页	✅	宿主内嵌组件/API，非独立 C 端账号
询价输入校验	✅	§4（含地址联想、托盘数、Mothership 官方尺寸）
四档输出（异步）	✅	§5、GD-1、GD-5
运营加价（按客户、运费%）	✅	§6；由宿主/API 配置
三层缓存 + 生命周期	✅	§7、GD-2
询价历史记录	✅	§9，预留 CC 字段
Mothership RPA（四档）	✅	GD-1
缓存降级	✅	§7.6
偏差/失败预警（站内）	✅	§7.5
管理端预警 + RPA/开发进度	✅	§2.4；无客户/运营登录
Mothership API	❌	不使用
CC 对接	❌	Phase 2
嵌入私仓预报	❌	Phase 3
Priority1	❌	Phase 4，保留 `QuoteProvider`
Flock Freight RPA	✅	§14；默认关，`FLOCK_RPA_ENABLED` / Mock 启用
多币种 / 下单 / 对账	❌	后续

3.2 扩展点

扩展点	预留方式
Priority1	`QuoteProvider` 接口，新增实现类
Flock Freight	`QuoteProvider` → `FlockFreightRPAProvider`；独立校验常量 `FLOCK_LIMITS`（§14.3）；独立队列/env（技术设计 §7.6）
CC 对接	询价 API 契约稳定；`quote_record` 预留 `cc_customer_id`、`forecast_id`
嵌入预报	查价为独立组件，`request_id` 可关联预报单

第 4 章询价输入

4.1 功能点

ID	描述
F4.1	提货/派送地址录入（须完成联想点选，见 §4.2.1）
F4.2	单托重量录入（lb/kg，提交前换算 lb）
F4.3	单托尺寸录入（in/cm，提交前换算 in）
F4.4	托盘数录入（`pallet_count`，非件数）
F4.5	货物类型选择（固定枚举）
F4.6	默认展示档位：`service_level=standard` + `rate_option=lowest`（仅影响 UI 默认 Tab）
F4.7	单位换算：API 可收 kg/cm，服务端与 RPA 统一 lb/in
F4.8	输入校验（Mothership 官方上限，§4.2.8）

4.2 字段规格

4.2.1 地址（pickup_address / delivery_address）

Mothership 报价页行为（实测）：地址输入框为联想搜索，输入 1234 Warehouse Blvd 后按 Enter 不能确认地址；须在输入框上方出现的候选列表中点击一项，表单才锁定为有效地址。

字段结构：

{
  "street": "1234 Warehouse Blvd",
  "city": "Los Angeles",
  "state": "CA",
  "zip": "90001",
  "place_id": "ChIJxxxx",
  "formatted_address": "1234 Warehouse Blvd, Los Angeles, CA 90001, USA",
  "selected_from_suggestions": true
}

字段	必填	说明
street, city, state, zip	是	`state` 2 字母美国州码；`zip` 正则 `^\d{5}(-\d{4})?$`
place_id	是（宿主/API 路径）	Google Place ID 或 Mothership 联想项 ID；对齐 Mothership API 的 `placeId`
formatted_address	是	用户点选后的完整展示串
selected_from_suggestions	是	必须为 `true`；`false` 拒绝询价

解决方案（二选一，宿主择一实现）：

方案	说明	适用
A. 宿主侧地址组件	宿主复用与 Mothership 同源的 Places 联想（或自研等价组件），用户点选后把 `place_id` + 结构化地址传给中台	推荐；嵌入形态默认
B. RPA 侧补选	入参仅有街道文本时，Worker 输入触发联想 → `waitFor` 下拉 → 点击首条/匹配项 → 校验表单已锁定	仅当宿主无法提供 `place_id` 的过渡方案；成功率低于 A

校验失败：400 VALIDATION_FAILED，提示「请从地址列表中选择有效地址」。

4.2.2 重量（weight）— 单托重量

{ value: number, unit: "lb"|"kg" }，必填，默认 lb
表示每一托盘的重量（对齐 Mothership freight[].weight）
换算：lb = kg × 2.20462，ROUND_HALF_UP 保留 2 位
范围：见 §4.2.8（禁止沿用 1–50000 lb 等自定义宽范围）

4.2.3 尺寸（dimensions）— 单托尺寸

{ length, width, height, unit: "in"|"cm" }，必填，默认 in
表示每一托盘外廓尺寸
换算：in = cm ÷ 2.54，保留 2 位
范围：见 §4.2.8

4.2.4 托盘数（pallet_count）

正整数，必填
语义：托盘数量；映射 Mothership freight[].quantity 且 type: "Pallet"
禁止使用「件数」「箱数」等非托盘字段
范围：见 §4.2.8

4.2.5 货物类型（cargo_type）— 固定枚举（GD-8）

枚举值	显示名
general_freight	普通货物
machinery	机械设备
furniture	家具
electronics	电子产品
building_materials	建材
auto_parts	汽车配件
food_nonperishable	食品（非生鲜）
apparel	服装
other	其他

默认 general_freight。

4.2.6 服务等级（service_level）与报价选项（rate_option）

字段	枚举	默认	说明
service_level	`standard` \| `guaranteed`	`standard`	Mothership 结果页两大服务类型
rate_option	`lowest` \| `fastest`	`lowest`	各 service_level 下的子选项：最低价格 / 最快递送

仅决定结果页默认 Tab；一次 RPA 仍返回 4 档（GD-1）
service_level、rate_option 均不进入 cache key（GD-3）

4.2.7 单位偏好（display_unit）

"imperial"|"metric"，非必填，默认 imperial
仅影响宿主 UI 展示；POST /quotes 时服务端按 weight.unit / dimensions.unit 换算，RPA 仅使用 lb/in

4.2.8 Mothership 官方货物限制（硬校验，GD-14）

来源：Will my freight fit? · Getting Rates（freight[].type=Pallet）

本期查价货物详情硬校验口径（National LTL，单次最多 25 托）：

字段	换算后规则（lb/in）	说明
pallet_count	整数 1–25	单次询价托盘数上限
length	1–999 in	单托长度上限 999 in
width	1–99 in	单托宽度上限 99 in
height	1–99 in	单托高度上限 99 in
weight（单托）	0.01–9,999 lb	单托重量上限 9,999 lb
整票总重	`weight_lb × pallet_count` ≤ 249,975 lb	9,999 × 25 硬顶

非本期默认路径（仅文档备案，不扩校验除非产品切换车型）：

车型	托盘上限	总重上限
26-foot box truck（同城）	12	9,500–10,000 lb
53-foot dry van	28	44,000 lb

超限：400 VALIDATION_FAILED，提示「{字段}超出 Mothership 允许范围」。

4.3 请求体（POST /quotes）

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "CUST_001",
  "pickup_address": {
    "street": "1234 Warehouse Blvd",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "place_id": "ChIJxxxx_pickup",
    "formatted_address": "1234 Warehouse Blvd, Los Angeles, CA 90001, USA",
    "selected_from_suggestions": true
  },
  "delivery_address": {
    "street": "5678 Distribution Dr",
    "city": "Dallas",
    "state": "TX",
    "zip": "75201",
    "place_id": "ChIJxxxx_delivery",
    "formatted_address": "5678 Distribution Dr, Dallas, TX 75201, USA",
    "selected_from_suggestions": true
  },
  "weight": { "value": 500, "unit": "lb" },
  "dimensions": { "length": 48, "width": 40, "height": 48, "unit": "in" },
  "pallet_count": 2,
  "cargo_type": "general_freight",
  "service_level": "standard",
  "rate_option": "lowest",
  "display_unit": "imperial"
}

4.4 业务规则

ID	规则
BR-4.1	入参换算为 in/lb 后再生成 cargo_hash 与调用 RPA
BR-4.2	`request_id` 必填、UUID v4；服务端按 GD-2 L1 做 24h 幂等
BR-4.3	地址须 `selected_from_suggestions=true` 且含 `place_id`（方案 A）；或 RPA 补选成功（方案 B）
BR-4.4	`cargo_hash = MD5(pickup+delivery+weight_lb+dims_in+pallet_count+cargo_type)`，不含 `service_level`、`rate_option`
BR-4.5	`pallet_count` 为托盘数；禁止 `quantity` 件数字段
BR-4.6	重量/尺寸为单托值；整票总重 = `weight_lb × pallet_count`

4.5 异常

异常	触发	行为	提示
E4.1	必填缺失	400 拒绝	「请填写{字段}」
E4.2	超范围	400 拒绝	「{字段}超出允许范围」
E4.3	地址未点选联想项 / 缺 place_id	400 拒绝	「请从地址列表中选择有效地址」
E4.4	单位非法	400 拒绝	「请选择有效的单位」
E4.5	request_id 非 UUID	400 拒绝	「请求标识无效」
E4.6	超 Mothership 官方范围（§4.2.8）	400 拒绝	「{字段}超出 Mothership 允许范围」
E4.7	使用 quantity/件数字段	400 拒绝	「请使用托盘数 pallet_count」

第 5 章询价输出

5.1 功能点

ID	描述
F5.1	一次返回 4 档报价（standard/guaranteed × lowest/fastest，GD-1）
F5.2	默认展示 standard + lowest
F5.3	价格明细（运费/附加费/加价/总价）
F5.4	加价后客户价
F5.5	3 分钟有效期与倒计时
F5.6	来源/实时性/可信度标识

5.2 查询响应（GET /quotes/{quote_id}）

{
  "quote_id": "QTE_20260616_0001",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "valid_until": "2026-06-16T14:32:00Z",
  "source_type": "rpa",
  "is_realtime": true,
  "confidence_score": 0.95,
  "currency": "USD",
  "quotes": [
    {
      "service_level": "standard",
      "rate_option": "lowest",
      "carrier": "Mothership",
      "transit_days": "5-7",
      "transit_description": "最低价格 · 预计 5-7 天送达",
      "raw_freight": 320.00,
      "surcharges": 0.00,
      "raw_total": 320.00,
      "markup_percent": 10.0,
      "markup_amount": 32.00,
      "final_total": 352.00,
      "breakdown": [
        { "item": "运费", "amount": 320.00 },
        { "item": "附加费", "amount": 0.00 },
        { "item": "运营加价(10.0%)", "amount": 32.00 }
      ]
    },
    {
      "service_level": "standard",
      "rate_option": "fastest",
      "carrier": "Mothership",
      "transit_days": "3-4",
      "transit_description": "最快递送 · 预计 3-4 天送达",
      "raw_freight": 365.00,
      "surcharges": 0.00,
      "raw_total": 365.00,
      "markup_percent": 10.0,
      "markup_amount": 36.50,
      "final_total": 401.50,
      "breakdown": [
        { "item": "运费", "amount": 365.00 },
        { "item": "附加费", "amount": 0.00 },
        { "item": "运营加价(10.0%)", "amount": 36.50 }
      ]
    },
    {
      "service_level": "guaranteed",
      "rate_option": "lowest",
      "carrier": "Mothership",
      "transit_days": "4-5",
      "transit_description": "保证送达 · 最低价格",
      "raw_freight": 380.00,
      "surcharges": 0.00,
      "raw_total": 380.00,
      "markup_percent": 10.0,
      "markup_amount": 38.00,
      "final_total": 418.00,
      "breakdown": [
        { "item": "运费", "amount": 380.00 },
        { "item": "附加费", "amount": 0.00 },
        { "item": "运营加价(10.0%)", "amount": 38.00 }
      ]
    },
    {
      "service_level": "guaranteed",
      "rate_option": "fastest",
      "carrier": "Mothership",
      "transit_days": "3",
      "transit_description": "保证送达 · 最快递送",
      "raw_freight": 410.00,
      "surcharges": 0.00,
      "raw_total": 410.00,
      "markup_percent": 10.0,
      "markup_amount": 41.00,
      "final_total": 451.00,
      "breakdown": [
        { "item": "运费", "amount": 410.00 },
        { "item": "附加费", "amount": 0.00 },
        { "item": "运营加价(10.0%)", "amount": 41.00 }
      ]
    }
  ]
}

5.3 字段说明

字段	类型	说明
service_level	enum	`standard` / `guaranteed`
rate_option	enum	`lowest`（最低价格）/ `fastest`（最快递送）
status	enum	`processing` / `done` / `failed` / `expired`
valid_until	ISO8601	报价生成时间 + 3 分钟
source_type	enum	`rpa` / `cache`（L2 命中）/ `stale`（L3 降级）
is_realtime	bool	`rpa`/`cache`=true；`stale`=false
confidence_score	decimal	rpa/cache=0.95；stale=0.70
currency	string	固定 `USD`
markup_percent	decimal	应用比例（基于运费）
final_total	decimal	`raw_total + raw_freight × markup%` ，ROUND_HALF_UP

5.4 展示规则

ID	规则
BR-5.1	默认选中 standard + lowest；可切换 guaranteed / fastest
BR-5.2	倒计时剩余 <30s 高亮
BR-5.3	`is_realtime=false` 显示角标「非实时报价，仅供参考」
BR-5.4	仅展示 USD
BR-5.5	`quotes` 数组长度固定为 4（四档齐全才 `done`）

5.5 异常输出

场景	HTTP	响应
处理中	200	`status=processing`
完成	200	`status=done` + quotes
RPA 失败有 stale	200	`status=done` + `source_type=stale` + `is_realtime=false`
RPA 失败无 stale	200	`status=failed` + `error_code=QUOTE_UNAVAILABLE`
超时(>30s 仍处理)	200	`status=failed` + `error_code=QUOTE_TIMEOUT`
quote_id 不存在	404	`error_code=QUOTE_NOT_FOUND`
越权访问	403	`error_code=FORBIDDEN`

5.6 错误码全集

error_code	含义	来源
VALIDATION_FAILED	入参校验失败	输入
QUOTE_UNAVAILABLE	RPA 失败且无 stale	RPA
QUOTE_TIMEOUT	30s 内未完成	RPA
QUOTE_NOT_FOUND	quote_id 不存在	查询
FORBIDDEN	越权/无权限	鉴权
RATE_LIMITED	触发限流	网关
CARRIER_NO_CAPACITY	Mothership 返回无运力	业务
ADDRESS_NOT_SUPPORTED	邮编不支持	业务
ADDRESS_SUGGESTION_NOT_FOUND	RPA 地址联想点选失败	RPA / 输入
QUOTE_ENTRY_UNAVAILABLE	所有报价入口 URL preCheck 失败	RPA
STRUCT_CHANGE	页面结构变更 / 404 / 登录页且无凭据	RPA
INTERNAL_ERROR	系统异常	系统

第 6 章加价规则

6.1 功能点

ID	描述
F6.1	按客户独立配置
F6.2	仅按运费百分比加价（GD-6）
F6.3	上限 30%
F6.4	未配置默认 0%
F6.5	配置审计（操作人、时间）

6.2 配置项

字段	类型	必填	说明
customer_id	string	是	客户唯一标识
markup_percent	decimal(5,1)	是	0–30.0，步长 0.1
operator_id	string	是	操作人
remark	string	否	备注

6.3 计算（唯一公式）

markup_amount = ROUND_HALF_UP(raw_freight × markup_percent / 100, 2)
final_total   = ROUND_HALF_UP(raw_total + markup_amount, 2)

示例：raw_freight=380.00，surcharges=0，raw_total=380.00，markup=10.0% → markup_amount=38.00，final_total=418.00。含附加费示例：raw_freight=320，surcharges=15，raw_total=335，markup=10% → markup_amount=32.00，final_total=367.00。

6.4 业务规则

ID	规则
BR-6.1	仅 `pricing:markup:write` 可写
BR-6.2	`markup_percent ∈ [0, 30.0]`
BR-6.3	未配置客户按 0%
BR-6.4	配置变更仅影响新询价，历史不重算

6.5 异常

异常	处理
比例 >30	400「加价比例不能超过 30%」
客户不存在	400「客户不存在」
无权限	403 FORBIDDEN

第 7 章报价生命周期与缓存

7.1 状态机

[创建 processing]
   → 命中 L1 → [done]（原响应）
   → 命中 L2 → [done]（source=cache）
   → 未命中 → 入 RPA 队列
        → RPA 成功 → 写 L1/L2，落库 → [done source=rpa]
        → RPA 失败 → 查 L3 stale
              → 命中 → [done source=stale, is_realtime=false] + 预警
              → 未命中 → [failed QUOTE_UNAVAILABLE] + 预警
   → 30s 未完成 → [failed QUOTE_TIMEOUT]
[done] --3 分钟到期--> [expired]（客户端提示重询）

7.2 三层缓存（GD-2，唯一规则）

层	Key	存储	TTL	用途	优先级
L1	`idem:{request_id}`	完整响应快照	24h	幂等：相同请求返同一结果	1（最高）
L2	`quote:{cargo_hash}`	四档报价（未加价原始结果）	3min	去重 RPA	2
L3	`stale:{cargo_hash}`	同 L2 内容	30min	仅 RPA 失败时降级只读	3（最低）

写入规则：RPA 成功后同时写 L1（带 request_id）、L2、L3。命中 L2 后仍按当前请求的客户加价比例重算 final_total 并写 L1。

读取顺序固定：L1 → L2 →（RPA）→ 失败时 L3。L3 永不用于正常路径，只在 RPA 失败时读取。

cargo_hash 定义见 BR-4.4，不含 service_level、不含 customer_id（加价在读出后按客户重算）。

7.3 幂等规则

条件	行为
相同 `request_id` 24h 内再次 `POST /quotes`	返回 L1 快照对应的同一 `quote_id`，不触发新 RPA
L1 过期后相同 request_id	视为新请求，重新走流程

7.4 有效期与复用

项	值
报价有效期	3 分钟（`valid_until`）
3min 内同 cargo 再询	命中 L2，无新 RPA
过期	客户端弹「是否重新询价」，确认后新 request_id

7.5 偏差预警

条件	基准	动作
本次 RPA `raw_total` 与 L3 中上一次同 cargo 报价偏差 ≥ 5%	上一次报价	写 `alert_log` 类型 `PRICE_DEVIATION`，站内通知管理员
首次询价（无历史基准）	无	不预警

偏差计算：abs(new - prev) / prev ≥ 0.05；恰好等于 5% 触发（≥）。

7.6 降级

RPA 失败按 §2.5 / §7.1 执行：优先 L3 stale，写 STALE_FALLBACK；无 stale 则 failed 写 RPA_FAILED。

7.7 预警类型

type	触发	通知
PRICE_DEVIATION	偏差 ≥5%	管理员站内
STALE_FALLBACK	使用 L3 降级	管理员站内
RPA_FAILED	RPA 失败无 stale	管理员站内
RPA_CAPTCHA	遇验证码	管理员站内 + 暂停该 Worker

第 8 章技术架构（可部署级）

8.1 架构组件

[客户端/管理端]
     │ REST(JWT)
[API 网关层]  限流(令牌桶) + 鉴权 + 路由
     │
[Quote Orchestrator 查价编排服务]
   ├─ ValidationModule      入参校验 + 单位换算
   ├─ CacheModule           L1/L2/L3 读写(Redis)
   ├─ IdempotencyModule     request_id 幂等
   ├─ PricingEngine         按客户加价
   ├─ AlertModule           预警写入
   └─ QuoteProvider(接口)
         └─ MothershipRPAProvider（本期唯一实现）
     │ 入队
[BullMQ 队列(Redis)] ── [RPA Worker Pool(Playwright)]
     │                         │ 1 Worker = 1 IP + 1 指纹 + 1 Session
[MySQL]                    [Mothership]
 quote_record / idempotency_record
 markup_config / alert_log / quote_cache_meta

8.2 RPA 执行流程（GD-1：单次会话四档报价）

1. Worker 从 BullMQ 取 job(quote_id, cargo 标准化输入)
2. QuotePageAdapter.resolveQuoteEntry()：
   - 读取 env MOTHERSHIP_QUOTE_URLS（逗号分隔，按序）
   - 对每个 URL：goto → preCheck（非 login/captcha、报价表单 selector 可见）
   - 首个通过者写入 activeUrl；全部失败 → QUOTE_ENTRY_UNAVAILABLE / STRUCT_CHANGE
   - **禁止**内置默认 URL；禁止 `dashboard.mothership.com`、`www.mothership.com/quote`（已 404 或跳转登录）
3. 加载 RPA_STORAGE_STATE_PATH（若存在）匿名 Cookie；成功路径写回 storageState
4. 若页面为 login 且已配置 MOTHERSHIP_EMAIL/PASSWORD → 重登 1 次；若 login 且无凭据 → STRUCT_CHANGE（**非** SESSION_EXPIRED）
5. preCheck：404 文案 / 登录页且无凭据 → STRUCT_CHANGE；关键表单元素不可见 → STRUCT_CHANGE
6. 地址：输入街道 → wait 联想下拉 → click 含 zip 项 → 断言下拉消失且地址已锁定（GD-9）；失败 → ADDRESS_SUGGESTION_NOT_FOUND
7. 填表：pickup/delivery、单托 weight(lb)/dims(in)、pallet_count、cargo_type
8. 提交一次；在结果页分别选择 standard/guaranteed，各切换 lowest/fastest，抓取 4 组价格与时效
9. 一致性校验：价格 >0、四档均存在
10. 标准化为 quotes[4]，回写 Orchestrator
11. 异常：超时/验证码/结构变更/地址未锁定 → 抛分类错误 → 进入 fallback（§8.4）
重试：单 job 最多重试 1 次；连续失败 ≥3 触发熔断 10 分钟

8.2.1 RPA 环境变量（GD-15）

变量	必填	说明
`MOTHERSHIP_QUOTE_URLS`	是	逗号分隔匿名报价入口 URL，按序探测
`RPA_STORAGE_STATE_PATH`	否	Playwright storageState 文件路径（默认 `.rpa/mothership-storage.json`）
`RPA_SELECTOR_*`	是	由 Playwright codegen 录制产出，见 §8.2.3
`MOTHERSHIP_EMAIL` / `MOTHERSHIP_PASSWORD`	否	仅当入口跳转 login 且需账号时使用
`RPA_MOCK_MODE`	否	仅 CI/单测为 `true`；验收与生产为 `false`
`RPA_HEADLESS`	否	默认 `true`；probe 失败时可设 `false` 对比

8.2.2 入口 URL 禁止清单

URL	原因
`https://dashboard.mothership.com/`	非公开报价页，跳转 login
`https://www.mothership.com/quote`	2026-06 实测 404

8.2.3 RPA Selector 维护规范

使用 Playwright codegen（headed） 录制人工匿名查价路径（LA→Dallas 标准样例）。
从录制脚本提取 goto URL → 写入 MOTHERSHIP_QUOTE_URLS。
从录制脚本提取 selector → 写入 RPA_SELECTOR_*（见技术设计 §7.2.3 清单）。
每次 Mothership 页面改版后：重新录制 → 更新 env → 运行 scripts/probe-rpa.ts 连续 3 次 exit 0。
禁止手猜 selector 上线；禁止 LLM 运行时自愈替代生产热路径（GD-1 确定性要求）。

验证命令：

RPA_MOCK_MODE=false RPA_HEADLESS=false npx tsx scripts/probe-rpa.ts

8.3 Cache 流程

POST /quotes(request_id, cargo):
  if L1[request_id] 存在: 返回其 quote_id (done)
  cargo_hash = MD5(标准化货物)
  if L2[cargo_hash] 存在:
     按客户加价重算 → 落库 → 写 L1 → 返回 done(source=cache)
  else:
     创建 quote_record(processing) → 入队 RPA → 返回 quote_id(processing)

RPA 成功:
  写 L2(3min)、L3(30min)、L1(24h) → 加价 → 落库 done(source=rpa)
  与 L3 上次比对，偏差≥5% 写 PRICE_DEVIATION

8.4 Fallback 流程

RPA 失败:
  if L3[cargo_hash] 存在:
     读出 → 按客户加价 → done(source=stale,is_realtime=false)
     写 STALE_FALLBACK 预警
  else:
     failed(QUOTE_UNAVAILABLE) + 写 RPA_FAILED 预警
验证码:
  停止该 Worker 重试 → 标记 IP/指纹不可用 → 写 RPA_CAPTCHA → 走上面 L3 分支

8.5 接口清单

方法	路径	权限	说明
POST	/api/quotes	宿主 Service Token	提交询价，返回 quote_id
GET	/api/quotes/{quote_id}	宿主（本人 customer_id）	轮询结果
GET	/api/quotes/history	宿主（本人 customer_id）	分页历史（必传分页）
PUT	/api/markup-configs/{customer_id}	宿主（`pricing:markup:write`）	新增/更新加价
GET	/api/alerts	管理员	预警列表（分页）
POST	/api/alerts/{id}/resolve	管理员	标记处理

统一响应包络：{ "code": 0, "message": "ok", "data": {...} }；错误 code 取 §5.6。

第 9 章数据模型（可建表）

MySQL 8.0，InnoDB，utf8mb4。金额 DECIMAL(12,2)。所有删除为逻辑删除（is_deleted）。DDL 需人工确认后执行 migration。

9.1 quote_record 询价记录

CREATE TABLE quote_record (
  id              BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  quote_id        VARCHAR(32)  NOT NULL,
  request_id      VARCHAR(36)  NOT NULL,
  customer_id     VARCHAR(32)  NOT NULL,
  cargo_hash      CHAR(32)     NOT NULL,
  status          VARCHAR(16)  NOT NULL DEFAULT 'processing',
  source_type     VARCHAR(16)  NULL,
  is_realtime     TINYINT(1)   NOT NULL DEFAULT 1,
  confidence_score DECIMAL(3,2) NULL,
  currency        VARCHAR(8)   NOT NULL DEFAULT 'USD',
  -- 输入快照
  pickup_json     JSON         NOT NULL,
  delivery_json   JSON         NOT NULL,
  weight_lb       DECIMAL(12,2) NOT NULL,
  dim_l_in        DECIMAL(8,2) NOT NULL,
  dim_w_in        DECIMAL(8,2) NOT NULL,
  dim_h_in        DECIMAL(8,2) NOT NULL,
  pallet_count    INT          NOT NULL COMMENT '托盘数，对齐 Mothership freight.quantity',
  cargo_type      VARCHAR(32)  NOT NULL,
  -- 四档结果快照
  quotes_json     JSON         NULL,
  markup_percent  DECIMAL(5,1) NOT NULL DEFAULT 0.0,
  valid_until     DATETIME     NULL,
  error_code      VARCHAR(32)  NULL,
  -- CC 预留
  cc_customer_id  VARCHAR(32)  NULL,
  forecast_id     VARCHAR(32)  NULL,
  is_deleted      TINYINT(1)   NOT NULL DEFAULT 0,
  created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_quote_id (quote_id),
  KEY idx_customer_created (customer_id, created_at),
  KEY idx_cargo_hash (cargo_hash),
  KEY idx_request (request_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

9.2 idempotency_record 幂等表

CREATE TABLE idempotency_record (
  id           BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  request_id   VARCHAR(36) NOT NULL,
  customer_id  VARCHAR(32) NOT NULL,
  quote_id     VARCHAR(32) NOT NULL,
  expire_at    DATETIME    NOT NULL,
  created_at   DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_request_id (request_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

说明：Redis L1 为热路径；本表为持久兜底，保证重启后 24h 内幂等仍成立。request_id 唯一键防并发重复写。

9.3 quote_cache_meta 缓存元数据（偏差比对/审计）

CREATE TABLE quote_cache_meta (
  id           BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  cargo_hash   CHAR(32)     NOT NULL,
  raw_total_standard   DECIMAL(12,2) NOT NULL,
  raw_total_guaranteed DECIMAL(12,2) NOT NULL,
  last_quotes_json     JSON   NOT NULL,
  refreshed_at DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_cargo_hash (cargo_hash)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

用途：持久记录每个 cargo_hash 上一次原始报价，供 §7.5 偏差比对（即使 Redis L3 已过期）。

9.4 markup_config 加价配置

CREATE TABLE markup_config (
  id             BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  customer_id    VARCHAR(32)  NOT NULL,
  markup_percent DECIMAL(5,1) NOT NULL DEFAULT 0.0,
  operator_id    VARCHAR(32)  NOT NULL,
  remark         VARCHAR(255) NULL,
  is_deleted     TINYINT(1)   NOT NULL DEFAULT 0,
  created_at     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_customer (customer_id),
  CONSTRAINT chk_markup CHECK (markup_percent >= 0 AND markup_percent <= 30.0)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

9.5 alert_log 预警日志

CREATE TABLE alert_log (
  id           BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  alert_type   VARCHAR(32)  NOT NULL,
  quote_id     VARCHAR(32)  NULL,
  cargo_hash   CHAR(32)     NULL,
  detail_json  JSON         NULL,
  status       VARCHAR(16)  NOT NULL DEFAULT 'open',
  resolver_id  VARCHAR(32)  NULL,
  resolved_at  DATETIME     NULL,
  created_at   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_type_status (alert_type, status),
  KEY idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

9.6 字段映射（响应 ← 表）

响应字段	来源
quote_id / status / source_type / is_realtime	quote_record
quotes[]	quote_record.quotes_json
markup_percent	markup_config（查询时）
valid_until	quote_record.valid_until

第 10 章非功能需求

10.1 性能

指标	目标
查价完成（done）P95	< 30s（含 RPA）
L1/L2 命中响应 P95	< 300ms
GET 轮询响应 P95	< 200ms
加价配置/预警接口 P95	< 500ms

10.2 成功率指标（GD-4，拆分）

指标	定义	目标
API success rate	`done(含 cache/stale) / 总 POST`	≥ 99.5%
RPA success rate	`RPA done / 触发 RPA 的请求`	≥ 85%
realtime rate	`source∈{rpa,cache} / done`	≥ 90%
缓存命中率	`(L1+L2) 命中 / 总 POST`	≥ 90%（3min 内重复场景）
重询率	`过期后重新询价 / done`	≤ 5%
RPA vs 人工偏差	抽检	≤ 5%

10.3 可用性

项	规则
RPA 熔断	连续失败 ≥3 次熔断 10 分钟，期间全部走 L3/失败
队列	BullMQ 持久化；服务重启 job 不丢
降级	RPA 不可用时 L3 stale 兜底，标记非实时
限流	单客户 60 次/分钟，超限 RATE_LIMITED

10.4 幂等性

场景	保证
重复 POST 相同 request_id	L1 + idempotency_record 双保险，返回同一 quote_id
并发相同 request_id	唯一键冲突 → 读已存在记录返回
RPA 重试	同 quote_id 不重复落库（按 quote_id 更新）

10.5 一致性

项	规则
缓存与 DB	RPA 成功后先落库再写缓存；缓存失效不影响 DB 真值
加价	命中 L2 时按当前客户配置实时重算，不缓存加价后价
金额	全链路 DECIMAL(12,2)，ROUND_HALF_UP
偏差基准	quote_cache_meta 持久记录，避免 Redis 过期丢基准

10.6 安全

项	规则
鉴权	所有接口 JWT；客户仅访问本人资源
RBAC	加价 `pricing:markup:write`；预警 `alert:read`
越权	403 FORBIDDEN
审计	加价变更、预警处理记录操作人与时间
日志	所有 async 必须 log error，不得吞异常

第 11 章异常场景与系统韧性设计

本章定义全链路失败点的唯一系统行为，与第 7 章生命周期、第 8 章 fallback 流程、第 12 章验收用例一一对应。每条均含：异常描述、系统行为、降级策略、告警、用户可见结果。

11.1 输入层异常处理

异常：必填字段为空或半空
系统行为：400 VALIDATION_FAILED，拒绝入队，不生成 quote_id
是否允许降级：否
是否触发告警：否
用户看到的结果：「请填写{字段名}」

异常：重量/尺寸/托盘数超 Mothership 官方范围（§4.2.8）
系统行为：400 VALIDATION_FAILED，拒绝入队
是否允许降级：否
是否触发告警：否
用户看到的结果：「{字段}超出允许范围」

异常：地址未从联想列表点选（selected_from_suggestions=false 或缺 place_id）
系统行为：400 VALIDATION_FAILED，拒绝入队
是否允许降级：否
是否触发告警：否
用户看到的结果：「请从地址列表中选择有效地址」

异常：地址邮编格式非法（非 5 位或 5+4）
系统行为：400 VALIDATION_FAILED，拒绝入队
是否允许降级：否
是否触发告警：否
用户看到的结果：「地址无效，请检查州与邮编」

异常：单位错配（数值与 unit 语义不一致，如 500kg 标为 lb）
系统行为：按 BR-4.1 强制按声明 unit 换算为 in/lb 后处理，不报错
是否允许降级：否
是否触发告警：否
用户看到的结果：正常进入处理流程

异常：地址含 SQL/脚本注入字符
系统行为：400 VALIDATION_FAILED，拒绝入队，记录 audit log
是否允许降级：否
是否触发告警：是（安全类告警）
用户看到的结果：「地址无效，请检查」

异常：货物类型不在 9 项枚举内
系统行为：400 VALIDATION_FAILED，拒绝入队
是否允许降级：否
是否触发告警：否
用户看到的结果：「请选择有效的货物类型」

异常：request_id 非 UUID v4
系统行为：400 VALIDATION_FAILED，拒绝入队
是否允许降级：否
是否触发告警：否
用户看到的结果：「请求标识无效」

11.2 行为与并发控制

异常：重复点击提交按钮
系统行为：前端 button disabled 3000ms；后端 L1 命中直接返回已有 quote_id
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：直接展示已有报价或 processing 状态

异常：同一 request_id 并发 10 次提交
系统行为：Redis L1 SETNX + DB 唯一键冲突，返回首次 quote_id，其余请求丢弃
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：所有请求返回同一 quote_id

异常：页面刷新后重复提交
系统行为：request_id 不变，L1 24h 内幂等生效
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：返回原 quote_id

异常：多标签页同时对同一 request_id 操作
系统行为：按 request_id 隔离，各自独立轮询 GET
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：各标签页状态一致

异常：浏览器前进/后退导致状态错乱
系统行为：客户端以 quote_id 为准，GET /quotes/{id} 实时拉取
是否允许降级：是（L3）
是否触发告警：否
用户看到的结果：显示当前真实状态

11.3 网络与通信容错

异常：客户端网络断开后恢复
系统行为：服务端继续 RPA，客户端重连后轮询 GET 可取结果
是否允许降级：是（L3）
是否触发告警：否
用户看到的结果：轮询恢复后显示 done 或 failed

异常：请求已发送但响应丢失
系统行为：客户端指数退避重试 GET，最多 15 次（30s 内）
是否允许降级：是（L1/L3）
是否触发告警：否
用户看到的结果：最终获得状态或超时提示

异常：CDN 缓存脏数据
系统行为：所有查价接口加 Cache-Control: no-store；API 网关不走 CDN
是否允许降级：否
是否触发告警：否
用户看到的结果：始终获取实时响应

异常：客户端弱网（>500ms RTT）
系统行为：客户端超时 30s 后提示「查询超时，请重试」
是否允许降级：是（L3）
是否触发告警：否
用户看到的结果：提示重试或展示 stale 报价

11.4 后端 API 容错策略

异常：API 处理超时（>30s 仍未 done）
系统行为：定时任务标记 status=failed + QUOTE_TIMEOUT，不阻塞线程
是否允许降级：是（L3）
是否触发告警：是（RPA 超时类）
用户看到的结果：「查询超时，请重试」

异常：HTTP 5xx（数据库/Redis 抖动）
系统行为：网关 retry 1 次，仍失败返回 503 + INTERNAL_ERROR
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：「服务暂时不可用，请稍后重试」

异常：响应字段缺失（quotes 数组为空）
系统行为：按 RPA_DATA_INVALID 处理，走 L3 fallback
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：展示 stale 或「暂时无法获取报价」

异常：响应结构变化（新增/删除关键字段）
系统行为：Provider preCheck 失败，抛 STRUCT_CHANGE，走 L3 或 failed
是否允许降级：是（L3）
是否触发告警：是（STRUCT_CHANGE）
用户看到的结果：按 fallback 处理

异常：幂等冲突（request_id 已存在但 cargo 不同）
系统行为：L1 优先，返回原 quote_id，忽略新 cargo
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：返回原报价

11.5 RPA 外部依赖容错

异常：Mothership DOM 结构变化 / 报价入口不可用
系统行为：preCheck 失败（404、login 且无凭据、表单 selector 不可见），抛 STRUCT_CHANGE 或 QUOTE_ENTRY_UNAVAILABLE，重试 0 次，走 L3 fallback
是否允许降级：是（L3）
是否触发告警：是（STRUCT_CHANGE）
用户看到的结果：展示 stale 报价或「暂时无法获取报价」

异常：storageState 失效（Cookie 过期）
系统行为：删除失效 storageState 文件，重新匿名访问；若仍 login 且无凭据 → STRUCT_CHANGE；若有凭据则重登 1 次
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：按 fallback 处理

异常：地址联想点选失败
系统行为：抛 ADDRESS_SUGGESTION_NOT_FOUND，不重试，Worker 路径走 L3；宿主 API 路径返回 400
是否允许降级：是（L3，Worker）；否（400，宿主直调）
是否触发告警：是
用户看到的结果：提示修正地址或 stale 报价

异常：验证码 / Cloudflare 拦截
系统行为：抛 RPA_CAPTCHA，暂停该 IP+指纹 Worker 10 分钟，写告警，走 L3
是否允许降级：是（L3）
是否触发告警：是（RPA_CAPTCHA）
用户看到的结果：展示 stale 报价或「暂时无法获取报价」

异常：登录失效 / session 过期（已登录账号场景）
系统行为：若页面为 login 且已配置 MOTHERSHIP_EMAIL/PASSWORD，Worker 自动重新登录 1 次，失败后抛 SESSION_EXPIRED，走 L3；若 login 且无凭据 → STRUCT_CHANGE（禁止误报 SESSION_EXPIRED）
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：按 fallback 处理

异常：RPA 返回不完整数据（standard 存在，guaranteed 缺失）
系统行为：一致性校验失败，抛 RPA_DATA_INVALID，走 L3
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：展示 stale 报价

异常：页面加载超时（>15s）
系统行为：超时抛 PAGE_LOAD_TIMEOUT，走 L3
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：按 fallback 处理

异常：RPA 抓取成功但数据错误（价格 ≤0 或负数）
系统行为：一致性校验失败，抛 RPA_DATA_INVALID，走 L3，不落库错误价
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：展示 stale 报价

异常：RPA 连续失败 ≥3 次
系统行为：熔断 10 分钟，期间全部走 L3 或 failed
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：按 fallback 处理或「暂时无法获取报价」

11.6 缓存一致性与防击穿设计

异常：cache 击穿（同一 cargo_hash 同时 100+ miss）
系统行为：L2 写操作加 Redis SETNX + 5s expire 锁，只允许 1 个 RPA，其余等待 2s 后读 L2
是否允许降级：是（L3）
是否触发告警：否
用户看到的结果：最终命中 L2 或 L3

异常：cache 雪崩（3min TTL 同时到期）
系统行为：L2 TTL 写入时加 0–30s 随机 jitter
是否允许降级：是（L3）
是否触发告警：否
用户看到的结果：平滑过渡

异常：cache 不一致（L2 旧报价 vs 新 RPA 结果）
系统行为：L2 3min 固定 TTL，不被新 RPA 覆盖；新 RPA 写新 L2
是否允许降级：是（L2）
是否触发告警：否
用户看到的结果：3min 内看到旧报价，之后看到新报价

异常：stale 数据被错误展示为实时
系统行为：所有 L3 命中必须返回 is_realtime=false + 角标「非实时报价，仅供参考」
是否允许降级：是（L3）
是否触发告警：是（STALE_FALLBACK）
用户看到的结果：带角标展示

异常：request_id 与 cargo_hash 冲突
系统行为：L1 优先级最高，request_id 命中直接返回，不再查 L2
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：返回原 quote_id

11.7 并发一致性与幂等设计

异常：同一用户并发 10 次不同 request_id 询价
系统行为：API 网关令牌桶限流 60 次/分钟，超限 429 RATE_LIMITED
是否允许降级：否
是否触发告警：是（限流）
用户看到的结果：「请求过于频繁，请稍后重试」

异常：多用户同时请求同一货物
系统行为：L2 共享，各自按自己 customer_id 加价重算 final_total，无覆盖写
是否允许降级：是（L2）
是否触发告警：否
用户看到的结果：各自看到自己加价后的价格

异常：价格竞争导致覆盖写
系统行为：quote_record 更新按 quote_id 主键，RPA 成功后先 UPDATE 再写缓存
是否允许降级：是（L2）
是否触发告警：否
用户看到的结果：最终以 DB 为准

异常：幂等失效导致重复 RPA
系统行为：Redis L1 + DB 唯一键双保险，冲突即返回已有 quote_id
是否允许降级：是（L1）
是否触发告警：否
用户看到的结果：不重复执行 RPA

11.8 数据计算安全

异常：浮点精度误差（加价计算）
系统行为：全程使用 DECIMAL(12,2)，加价公式 ROUND_HALF_UP(raw_freight × markup / 100, 2)
是否允许降级：否
是否触发告警：否
用户看到的结果：金额精确到分，无误差

异常：surcharge 缺失
系统行为：按 0 处理，raw_total = raw_freight
是否允许降级：否
是否触发告警：否
用户看到的结果：正常展示

异常：rounding 规则不一致
系统行为：全局唯一 ROUND_HALF_UP，DB/缓存/响应一致
是否允许降级：否
是否触发告警：否
用户看到的结果：各端金额一致

11.9 权限与安全控制

异常：越权访问其他客户 quote_id
系统行为：JWT customer_id 校验失败，403 FORBIDDEN，记录 audit log
是否允许降级：否
是否触发告警：是（安全）
用户看到的结果：403 FORBIDDEN

异常：伪造 customer_id（JWT 无效）
系统行为：JWT 签名校验失败，401 UNAUTHORIZED
是否允许降级：否
是否触发告警：是（安全）
用户看到的结果：401 UNAUTHORIZED

异常：无权限修改加价规则
系统行为：RBAC 校验失败，403 FORBIDDEN
是否允许降级：否
是否触发告警：是（安全）
用户看到的结果：403 FORBIDDEN

异常：API 被批量刷（>60 次/分钟/客户或 >1000 次/分钟/IP）
系统行为：网关限流 + IP 封禁 10 分钟，写安全告警
是否允许降级：否
是否触发告警：是（安全）
用户看到的结果：429 RATE_LIMITED 或封禁提示

11.10 状态机与生命周期保护

异常：询价已过期（valid_until 过去）仍被展示
系统行为：客户端 GET 时检查 valid_until，过期返回 status=expired，不展示价格
是否允许降级：否
是否触发告警：否
用户看到的结果：「报价已过期，是否重新询价？」

异常：cache 未过期但 RPA 更新更高优先级
系统行为：L2 3min 固定 TTL，新 RPA 只写新 L2，不覆盖旧 L2
是否允许降级：是（L2）
是否触发告警：否
用户看到的结果：3min 内看到旧报价

异常：fallback 状态未标识
系统行为：所有 L3 命中强制返回 is_realtime=false + 角标
是否允许降级：是（L3）
是否触发告警：是（STALE_FALLBACK）
用户看到的结果：带角标展示

异常：quote_id 重复使用（生成冲突）
系统行为：DB quote_id 唯一键冲突，拒绝写入，抛 INTERNAL_ERROR
是否允许降级：否
是否触发告警：是
用户看到的结果：服务异常提示

异常：processing 状态超过 30s 未更新
系统行为：定时任务标记为 failed + QUOTE_TIMEOUT
是否允许降级：是（L3）
是否触发告警：是
用户看到的结果：轮询后得到 failed 状态

第 12 章验收标准（Acceptance Criteria）

本章所有 TC 可直接转换为自动化脚本，PASS 条件均为可量化判断。与第 11 章异常场景一一对应。

12.1 功能验收

TC-101 正常询价流程（首次提交）

类型：Functional
前置条件：宿主 Service Token 有效，customer_id=CUST_001 未配置加价；地址含有效 place_id
输入数据：request_id=uuid-v4，pickup/delivery 含 place_id，单托 weight=500lb，dims=48×40×48in，pallet_count=2，cargo_type=general_freight，service_level=standard，rate_option=lowest
操作步骤：POST /quotes → 轮询 GET /quotes/{quote_id} 直至 done
预期结果：
- HTTP状态码：200
- 响应字段：status=done，source_type=rpa，is_realtime=true，quotes 数组长度=4，final_total=raw_total（markup=0）
- 数据库变化：quote_record 新增 1 条，status=done，source_type=rpa；idempotency_record 新增 1 条
- 是否触发告警：否
- 是否命中cache：否
PASS标准：响应 200，status=done，quotes 含 standard/guaranteed × lowest/fastest 共 4 档，DB 写入 1 条 quote_record + 1 条 idempotency_record，耗时 <30s

TC-102 四档报价返回正确性

类型：Functional
前置条件：RPA 已成功抓取
输入数据：同 TC-101
操作步骤：GET /quotes/{quote_id}
预期结果：
- HTTP状态码：200
- 响应字段：quotes 含 4 条；每条含 service_level + rate_option；standard+lowest 的 transit_description 含「最低价格」；guaranteed+fastest 含「最快递送」或「保障」
- 数据库变化：quotes_json 存储四档数据
- 是否触发告警：否
- 是否命中cache：首次不命中
PASS标准：quotes 数组恰好 4 条，service_level × rate_option 组合齐全

TC-103 加价计算正确性（含 surcharge）

类型：Functional
前置条件：markup_config 中 CUST_002 配置 10.0%
输入数据：raw_freight=320.00，surcharges=15.00，markup=10.0%
操作步骤：RPA 返回后 PricingEngine 计算
预期结果：
- HTTP状态码：200
- 响应字段：markup_amount=32.00，final_total=367.00（ROUND_HALF_UP）
- 数据库变化：quote_record.markup_percent=10.0，quotes_json 中 breakdown 含 3 项
- 是否触发告警：否
- 是否命中cache：否
PASS标准：markup_amount=32.00，final_total=367.00，金额精确到分，无浮点误差

TC-104 L2 cache 命中逻辑

类型：Functional
前置条件：同一 cargo_hash 已存在 L2（3min 内）
输入数据：相同货物，不同 request_id
操作步骤：POST /quotes（新 request_id）
预期结果：
- HTTP状态码：200
- 响应字段：status=done，source_type=cache，is_realtime=true
- 数据库变化：quote_record 新增 1 条（source_type=cache），idempotency_record 新增
- 是否触发告警：否
- 是否命中cache：是（L2）
PASS标准：source_type=cache，耗时 <300ms，无新 RPA 调用

TC-105 request_id 幂等（24h 内重复提交）

类型：Functional
前置条件：request_id 已使用过
输入数据：相同 request_id，相同或不同货物
操作步骤：POST /quotes
预期结果：
- HTTP状态码：200
- 响应字段：返回首次 quote_id，status=done
- 数据库变化：quote_record 不新增，idempotency_record 不新增
- 是否触发告警：否
- 是否命中cache：是（L1）
PASS标准：返回原 quote_id，DB 无新写入，24h 内任意次数均返回同一 quote_id

TC-106 单位换算（kg/cm）

类型：Functional
前置条件：无
输入数据：weight=227kg，dims=122×102×122cm
操作步骤：POST /quotes → 轮询至 done
预期结果：
- HTTP状态码：200
- 响应字段：内部 weight_lb≈500.66，dims 换算为 in 后正常询价
- 数据库变化：quote_record 记录换算后 in/lb 值
- 是否触发告警：否
- 是否命中cache：否
PASS标准：200 done，DB weight_lb 与 dims 为换算后 in/lb 值

TC-107 不同 service_level 同货物共享缓存

类型：Functional
前置条件：L2 已存在（四档）
输入数据：相同货物，service_level 分别为 standard / guaranteed 两次提交
操作步骤：两次 POST /quotes（不同 request_id）
预期结果：
- HTTP状态码：200
- 响应字段：两次均返回四档 quotes，第二次 source_type=cache
- 数据库变化：第二次无新 RPA
- 是否触发告警：否
- 是否命中cache：第二次命中 L2
PASS标准：第二次 source_type=cache，quotes 仍含四档

TC-108 L2 过期后触发新 RPA

类型：Functional
前置条件：同 cargo_hash L2 已过期（>3min）
输入数据：相同货物
操作步骤：POST /quotes
预期结果：
- HTTP状态码：200
- 响应字段：status=processing 后 done，source_type=rpa
- 数据库变化：新 quote_record，触发 RPA
- 是否触发告警：否
- 是否命中cache：否
PASS标准：source_type=rpa，RPA 被调用 1 次

12.2 异常场景验收（对齐第 11 章）

TC-201 输入必填缺失

类型：Exception
前置条件：无
输入数据：weight 字段缺失
操作步骤：POST /quotes
预期结果：
- HTTP状态码：400
- 响应字段：error_code=VALIDATION_FAILED
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：400 VALIDATION_FAILED，不生成 quote_id

TC-202 数值超范围（weight=0）

类型：Exception
前置条件：无
输入数据：weight.value=0
操作步骤：POST /quotes
预期结果：
- HTTP状态码：400
- 响应字段：error_code=VALIDATION_FAILED
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：400，提示超范围

TC-203 地址邮编非法

类型：Exception
前置条件：无
输入数据：zip="9001"（4 位）
操作步骤：POST /quotes
预期结果：
- HTTP状态码：400
- 响应字段：error_code=VALIDATION_FAILED
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：400，地址无效

TC-204 request_id 非 UUID

类型：Exception
前置条件：无
输入数据：request_id="not-uuid"
操作步骤：POST /quotes
预期结果：
- HTTP状态码：400
- 响应字段：error_code=VALIDATION_FAILED
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：400 VALIDATION_FAILED

TC-205 RPA 失败 + L3 stale 命中

类型：Exception
前置条件：cargo_hash 存在 L3（≤30min）
输入数据：正常货物
操作步骤：RPA 触发失败（模拟验证码）
预期结果：
- HTTP状态码：200
- 响应字段：status=done，source_type=stale，is_realtime=false，角标「非实时报价，仅供参考」
- 数据库变化：quote_record 新增，source_type=stale
- 是否触发告警：是（STALE_FALLBACK）
- 是否命中cache：是（L3）
PASS标准：200，source_type=stale，is_realtime=false，alert_log 新增 1 条 STALE_FALLBACK

TC-206 RPA 失败 + 无 L3

类型：Exception
前置条件：cargo_hash 无 L3
输入数据：正常货物
操作步骤：RPA 触发失败
预期结果：
- HTTP状态码：200
- 响应字段：status=failed，error_code=QUOTE_UNAVAILABLE
- 数据库变化：quote_record 新增，status=failed
- 是否触发告警：是（RPA_FAILED）
- 是否命中cache：否
PASS标准：200，status=failed，error_code=QUOTE_UNAVAILABLE，alert_log 新增 RPA_FAILED

TC-207 并发重复提交（10 次相同 request_id）

类型：Exception
前置条件：无
输入数据：相同 request_id，10 并发
操作步骤：10 线程同时 POST /quotes
预期结果：
- HTTP状态码：200
- 响应字段：全部返回同一 quote_id
- 数据库变化：quote_record 仅 1 条，idempotency_record 仅 1 条
- 是否触发告警：否
- 是否命中cache：是（L1）
PASS标准：10 次请求返回同一 quote_id，DB 仅写入 1 条

TC-208 网络超时（>30s）

类型：Exception
前置条件：无
输入数据：正常
操作步骤：RPA 模拟 >30s 未完成
预期结果：
- HTTP状态码：200
- 响应字段：status=failed，error_code=QUOTE_TIMEOUT
- 数据库变化：quote_record status=failed
- 是否触发告警：是
- 是否命中cache：否
PASS标准：200，status=failed，error_code=QUOTE_TIMEOUT

TC-209 RPA 连续失败熔断

类型：Exception
前置条件：无
输入数据：连续 3 次 RPA 失败
操作步骤：触发 3 次失败
预期结果：
- HTTP状态码：200
- 响应字段：第 4 次起 10 分钟内走 L3 或 failed
- 数据库变化：alert_log 记录熔断
- 是否触发告警：是
- 是否命中cache：按 L3
PASS标准：连续失败 ≥3 次后 10 分钟内无新 RPA 调用

TC-210 偏差预警（≥5%）

类型：Exception
前置条件：quote_cache_meta 存在上次报价 raw_total_standard=352
输入数据：本次 RPA raw_total_standard=370（偏差 5.1%）
操作步骤：RPA 成功
预期结果：
- HTTP状态码：200
- 响应字段：status=done，正常返回报价
- 数据库变化：alert_log 新增 PRICE_DEVIATION
- 是否触发告警：是
- 是否命中cache：否
PASS标准：200 done，alert_log 新增 PRICE_DEVIATION

TC-211 偏差未达阈值（4.9%）

类型：Exception
前置条件：上次 raw_total=352
输入数据：本次 raw_total=369.25（偏差 4.9%）
操作步骤：RPA 成功
预期结果：
- HTTP状态码：200
- 响应字段：status=done
- 数据库变化：无 PRICE_DEVIATION 告警
- 是否触发告警：否
- 是否命中cache：否
PASS标准：200 done，alert_log 无 PRICE_DEVIATION

TC-212 首次询价不触发偏差预警

类型：Exception
前置条件：cargo_hash 无历史基准
输入数据：正常货物
操作步骤：首次 RPA 成功
预期结果：
- HTTP状态码：200
- 响应字段：status=done
- 数据库变化：quote_cache_meta 写入基准
- 是否触发告警：否
- 是否命中cache：否
PASS标准：200 done，无 PRICE_DEVIATION 告警

12.3 性能验收

TC-301 RPA 路径 P95 响应时间

类型：Performance
前置条件：RPA 正常
输入数据：标准测试货物
操作步骤：100 次连续 POST + 轮询
预期结果：
- HTTP状态码：200
- 响应字段：status=done
- 数据库变化：100 条 quote_record
- 是否触发告警：否
- 是否命中cache：否
PASS标准：P95 完成时间 <30s，P99 <45s

TC-302 L2 cache 命中 P95 响应时间

类型：Performance
前置条件：L2 已存在
输入数据：相同货物
操作步骤：100 次 POST
预期结果：
- HTTP状态码：200
- 响应字段：source_type=cache
- 数据库变化：100 条 quote_record（cache 来源）
- 是否触发告警：否
- 是否命中cache：是
PASS标准：P95 响应 <300ms，P99 <500ms

TC-303 并发 QPS 限流验证

类型：Performance
前置条件：单客户账号
输入数据：不同 request_id
操作步骤：60s 内发送 70 次请求
预期结果：
- HTTP状态码：前 60 次 200，后 10 次 429
- 响应字段：429 响应 error_code=RATE_LIMITED
- 数据库变化：60 条 quote_record
- 是否触发告警：是（限流）
- 是否命中cache：部分命中
PASS标准：令牌桶 60 次/分钟生效，>60 次/分钟返回 429

TC-304 RPA 最大等待时间边界

类型：Performance
前置条件：无
输入数据：正常
操作步骤：RPA 模拟 28s 完成 vs 31s 未完成
预期结果：
- HTTP状态码：200
- 响应字段：28s→done；31s→failed QUOTE_TIMEOUT
- 数据库变化：对应 status
- 是否触发告警：31s 时触发
- 是否命中cache：否
PASS标准：28s 内返回 done，>30s 返回 QUOTE_TIMEOUT

12.4 数据一致性验收

TC-401 cache vs RPA 一致性

类型：Consistency
前置条件：L2 存在
输入数据：相同货物
操作步骤：L2 命中 vs 新 RPA 结果比对
预期结果：
- HTTP状态码：200
- 响应字段：3min 内 L2 raw_total 与生成时 RPA 一致
- 数据库变化：quote_cache_meta 记录最新 RPA
- 是否触发告警：偏差 ≥5% 触发
- 是否命中cache：L2 命中
PASS标准：L2 内容与写入时 RPA 一致；新 RPA 偏差 ≥5% 触发 PRICE_DEVIATION

TC-402 quote_id 唯一性

类型：Consistency
前置条件：无
输入数据：100 次不同 request_id
操作步骤：并发提交
预期结果：
- HTTP状态码：200
- 响应字段：100 个不同 quote_id
- 数据库变化：100 条 quote_record，quote_id 唯一
- 是否触发告警：否
- 是否命中cache：否
PASS标准：DB quote_id 唯一键无冲突

TC-403 加价计算可复算

类型：Consistency
前置条件：DB 已存储 raw_freight 与 markup_percent
输入数据：quote_record 已存在
操作步骤：从 DB 读取并重算 final_total
预期结果：
- HTTP状态码：200
- 响应字段：重算值与 quotes_json.final_total 一致
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：重算值 == 存储值，误差 ≤0.01

TC-404 request_id 幂等一致性（跨重启）

类型：Consistency
前置条件：Redis L1 已过期，DB idempotency_record 仍存在
输入数据：相同 request_id
操作步骤：服务重启后再次 POST
预期结果：
- HTTP状态码：200
- 响应字段：返回原 quote_id
- 数据库变化：无新写入
- 是否触发告警：否
- 是否命中cache：是（DB 兜底）
PASS标准：重启后 24h 内仍返回原 quote_id

12.5 安全与权限验收

TC-501 越权访问（customer_id 伪造）

类型：Security
前置条件：客户 A JWT
输入数据：quote_id 属于客户 B
操作步骤：GET /quotes/{B的quote_id}（带 A 的 JWT）
预期结果：
- HTTP状态码：403
- 响应字段：error_code=FORBIDDEN
- 数据库变化：无
- 是否触发告警：是（安全类）
- 是否命中cache：否
PASS标准：403 FORBIDDEN，audit log 记录越权尝试

TC-502 运营权限控制（加价配置）

类型：Security
前置条件：客户角色 JWT（无 pricing:markup:write）
输入数据：PUT /markup-configs/CUST_001
操作步骤：客户角色调用加价接口
预期结果：
- HTTP状态码：403
- 响应字段：error_code=FORBIDDEN
- 数据库变化：markup_config 不更新
- 是否触发告警：是（安全）
- 是否命中cache：否
PASS标准：403，markup_config 不变

TC-503 批量刷接口限流

类型：Security
前置条件：无
输入数据：单 IP 120 次/分钟
操作步骤：高频 POST /quotes
预期结果：
- HTTP状态码：429
- 响应字段：error_code=RATE_LIMITED
- 数据库变化：仅 60 条
- 是否触发告警：是（安全）
- 是否命中cache：部分
PASS标准：>60 次/分钟返回 429

TC-504 API 非法请求拦截

类型：Security
前置条件：无
输入数据：payload 含 SQL 注入
操作步骤：POST /quotes（恶意 payload）
预期结果：
- HTTP状态码：400
- 响应字段：error_code=VALIDATION_FAILED
- 数据库变化：无
- 是否触发告警：是（安全）
- 是否命中cache：否
PASS标准：400，不执行 RPA，不写入 DB

TC-505 加价上限边界

类型：Security
前置条件：运营角色 JWT
输入数据：markup_percent=30.1
操作步骤：PUT /markup-configs/CUST_001
预期结果：
- HTTP状态码：400
- 响应字段：拒绝保存
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：400，markup_config 不变

TC-506 历史接口强制分页

类型：Security
前置条件：客户 JWT
输入数据：GET /quotes/history 不传 page/size
操作步骤：调用历史接口
预期结果：
- HTTP状态码：400
- 响应字段：VALIDATION_FAILED
- 数据库变化：无
- 是否触发告警：否
- 是否命中cache：否
PASS标准：400，强制分页参数

12.6 RPA 与外部系统验收

TC-601 RPA 成功返回结构完整性

类型：Functional
前置条件：MOTHERSHIP_QUOTE_URLS 已 headed 录制验证；RPA_MOCK_MODE=false
输入数据：标准货物（LA 90001 → Dallas 75201，2 托，500lb/托，48×40×48in）
操作步骤：npx tsx scripts/probe-rpa.ts 连续执行 3 次
预期结果：
- exit code：0（3 次均成功）
- 响应字段：items.length === 4（standard/guaranteed × lowest/fastest），每条 raw_freight>0，transit_description 非空
- 数据库变化（API 路径）：quote_record source_type=rpa
- 是否触发告警：否
- 是否命中cache：否
PASS标准：3 次 probe 均 exit 0；四档齐全且 raw_freight>0

TC-602 RPA 失败 fallback 触发

类型：Exception
前置条件：L3 存在
输入数据：正常
操作步骤：模拟验证码
预期结果：
- HTTP状态码：200
- 响应字段：source_type=stale，is_realtime=false
- 数据库变化：alert_log 新增 STALE_FALLBACK
- 是否触发告警：是
- 是否命中cache：是（L3）
PASS标准：source_type=stale，alert_log 写入，is_realtime=false

TC-603 验证码/封禁场景

类型：Exception
前置条件：Worker 可用
输入数据：正常
操作步骤：RPA 触发验证码
预期结果：
- HTTP状态码：200
- 响应字段：source_type=stale 或 failed
- 数据库变化：alert_log 新增 RPA_CAPTCHA，Worker 暂停 10 分钟
- 是否触发告警：是（RPA_CAPTCHA）
- 是否命中cache：是（L3）
PASS标准：alert_log RPA_CAPTCHA，Worker 10 分钟内不分配新 job

TC-604 页面结构变化容错

类型：Exception
前置条件：Mothership DOM 变更
输入数据：正常
操作步骤：RPA preCheck 失败
预期结果：
- HTTP状态码：200
- 响应字段：source_type=stale 或 failed
- 数据库变化：alert_log 新增 STRUCT_CHANGE
- 是否触发告警：是
- 是否命中cache：是（L3）
PASS标准：alert_log STRUCT_CHANGE，Worker 停止，走 L3

TC-605 RPA 超时降级

类型：Exception
前置条件：无
输入数据：正常
操作步骤：RPA 执行 >30s
预期结果：
- HTTP状态码：200
- 响应字段：status=failed，error_code=QUOTE_TIMEOUT
- 数据库变化：quote_record status=failed
- 是否触发告警：是
- 是否命中cache：否
PASS标准：status=failed，error_code=QUOTE_TIMEOUT，alert_log 写入

12.7 Go/No-Go 上线门禁

指标	目标值	测量方法	Go 条件
API success rate（含 cache）	≥99.5%	1000 次请求统计	1000 次中 ≥995 次 200 done
RPA success rate	≥85%	100 次真实 RPA 统计	100 次中 ≥85 次 source=rpa
RPA probe 门禁	3/3 成功	`RPA_MOCK_MODE=false npx tsx scripts/probe-rpa.ts` 连续 3 次	3 次均 exit 0（TC-601）
realtime rate	≥90%	1000 次 done 统计	1000 次中 ≥900 次 is_realtime=true
cache 命中率（L1+L2）	≥90%	1000 次请求统计	1000 次中 ≥900 次命中 L1 或 L2
RPA vs 人工偏差	≤5%	人工抽检 ≥30 单	30 单中偏差 ≤5% 通过率 ≥95%
P0 级别测试失败	0	全用例执行 §12.1–12.6	无 P0 失败
性能 P95	<30s	Load Test 100 次（TC-301）	P95 <30s
无高危安全漏洞	0	渗透测试 TC-501~506	无高危漏洞

12.8 测试分层策略

层级	范围	工具/框架	覆盖率目标	执行频率
Unit Test	PricingEngine、CacheModule、ValidationModule	Jest / Vitest	80% 行覆盖	每次提交
Integration Test	API + DB + Redis + BullMQ	Supertest + Testcontainers	全部 API 契约	每次构建
E2E Test	客户端轮询 + RPA 模拟	Playwright	核心 5 条用户路径	每日
Load Test	60 QPS + 100 并发	k6 / JMeter	P95 <30s，成功率 ≥99%	每次发布前

12.9 测试数据设计

数据类型	模板/值	用途
标准测试货物	LA(90001)→Dallas(75201)，500lb，48×40×48in，2件，general_freight	功能/性能基线
极端托盘数	25 / 1 pallet	边界校验
极端尺寸	999×99×99 in（上限）	边界校验
超规尺寸	1000×100×100 in	边界校验 400
无效地址	zip=9001，state=XX	异常输入 TC-203
高并发账号	100 个独立 customer_id	Load Test / 并发
缓存命中货物	固定 3min 内重复使用	Cache 命中率 TC-104
RPA 失败模拟	故意触发验证码 / DOM 变更	降级 TC-602~604
加价配置	CUST_001=0%，CUST_002=10.0%，CUST_003=30.0%	加价计算 TC-103/505

12.10 用例与章节映射

PRD 章节	对应用例
§4 询价输入	TC-101~108，TC-201~204
§6 加价规则	TC-103，TC-505
§7 生命周期/缓存	TC-104~105，TC-107~108，TC-401~404
§11 异常场景	TC-205~212，TC-501~506，TC-602~605
§10 性能/安全	TC-301~304，TC-503

第 13 章 3 周交付计划

Week 1 — 基础链路与数据层

任务	产出	验证
DB migration（5 张表）	表结构	空库双跑通过
API 骨架 + 鉴权 + 统一响应	POST/GET/quotes	TC-101，TC-204
输入校验 + 单位换算	ValidationModule	TC-201~203，TC-106
Redis 三层缓存读写	CacheModule	TC-104~105，TC-107
幂等（L1 + 表）	IdempotencyModule	TC-105，TC-207，TC-404

Week 2 — RPA 与加价

任务	产出	验证
MothershipRPAProvider（四档）	RPA Worker	TC-601
BullMQ 队列 + Worker Pool	异步链路	TC-601，TC-605
Fallback（L3 stale）+ 熔断	降级逻辑	TC-205~206，TC-209
验证码处理 + 暂停 Worker	异常处理	TC-603
PricingEngine 加价	加价计算	TC-103，TC-505
加价配置 API + 管理端页	配置功能	TC-502，TC-505

Week 3 — 预警、前端、验收

任务	产出	验证
偏差预警 + alert_log	AlertModule	TC-210~212
预警中心管理端页	预警列表/处理	冒烟
宿主内嵌查价（轮询/倒计时/四档/非实时角标）	前端	TC-601，TC-602 UI
历史记录页（分页）	前端	TC-506
限流 + 越权防护	安全	TC-501，TC-503~506
人工抽检一致性 ≥30 单	报告	§12.7
指标采集（三成功率/命中率）	监控看板	§10.2，§12.7
全量 TC 回归 + Go/No-Go	上线门禁	§12.7

里程碑

时点	交付物
W1 末	缓存+幂等可用，缓存命中路径端到端通
W2 末	RPA 四档 + 加价 + 降级全链路通
W3 末	§12 全用例通过 + §12.7 指标达标 + 可上线

第 14 章 Flock Freight 报价源（GD-16，Phase 扩展）

本章为 第二报价源 产品口径。MVP（Mothership）不实现；实现前须按技术设计 §7.6 录制 + probe 门禁。
实测入口：https://app.flockfreight.com/get-a-quote（2026-07-13）。

14.1 目标与边界

项	规则
产品定位	Flock Freight 共享整车（FlockDirect）/ 标准 LTL 伙伴线路的公开查价
接入方式	仅 Playwright RPA；不使用 Flock 官方 API
与 Mothership 关系	独立 Provider、独立硬限、独立 session；同一编排层经 `QuoteProvider` 扩展
本期实现	✅ 已落地（`FLOCK_RPA_ENABLED` / Mock 联调；真实 RPA 须 probe 3/3）
下单 / 支付	❌ 不在本期；结果页「Complete your order」仅作 RPA 停止边界

14.2 官网流程实测摘要

1. 打开 get-a-quote（可匿名填表，无需先登录）
2. 填写：取货日期、取件/投递 ZIP、托盘数、总重量(lb)、单托尺寸(in)
3. 「下一个」→ 结果页展示两档：FlockDirect® / Standard
4. 「Complete your order」→ 引导「Create your free account」注册后继续

观察点	结论
报价表单	字段少：日期 + ZIP×2 + 托盘数 + 总重 + L/W/H；无街道联想
结果页	两档对比卡；含 Reference #、Quotes generated
免费注册	First/Last name、Company、Phone、Work email、月均干货车次下拉；实测随机邮箱/电话/名称可注册成功，站点无明显实名/邮箱域名校验
注册下拉选项	`I haul or dispatch freight` / `1-25` / `26-100` / `101-500` / `501-1000` / `1000+` / `I'm a logistics provider`

14.3 货物硬限（官网提示，独立于 GD-14）

字段	规则（英制）	宿主提示文案（中文）
托盘数量 `pallet_count`	整数 4–20	托盘数量只能输入 4 到 20
总运输重量 `total_weight_lb`	≤ 45,000 lb（整票总重，非单托）	总重量不能超过 45000 lb
单托长度	≤ 636 in（默认示例 48）	托盘长度不能超过 636 in
单托宽度	≤ 102 in（默认示例 40）	托盘宽度不能超过 102 in
单托高度	≤ 108 in（默认示例 48）	托盘高度不能超过 108 in
取件/投递 ZIP	必填；美国 5 位 ZIP	需要提供取件/投递邮政编码
取货日期	必填；不得早于当日策略以录制为准	请选择取货日期

超限：400 VALIDATION_FAILED，message 用上表中文提示；禁止套用 Mothership §4.2.8 上限。

计量差异（相对 Mothership）：

维度	Mothership	Flock Freight
重量	单托 `weight_lb`，总重 = 单托 × 托盘数	表单直接填整票总重（lb）
地址	街道 + 联想点选 `place_id`	仅 ZIP（取件/投递）
结果档位	4 档（standard/guaranteed × lowest/fastest）	2 档：FlockDirect®、Standard

14.4 结果档位映射

官网卡片	映射 `service_level`	`rate_option`	说明
FlockDirect®	`guaranteed`（语义：premium / hubless）	`fastest`	价格从 $X；含周末时效文案；终端免中转卖点
Standard	`standard`	`lowest`	价格从 $X；工作日时效；走 LTL 伙伴

一次 RPA 须抓齐 2 档（价格 >0、时效文案非空）。不足 2 档 → STRUCT_CHANGE 或 CARRIER_NO_CAPACITY（按页面文案分类）。
宿主展示：两张对比卡即可，不要求补齐 Mothership 四档空位。

14.5 账号与 Session（RPA）

项	规则
匿名查价	get-a-quote → 结果页：优先走匿名路径（与实测一致）
注册页	仅当流程强制登录/下单时触发；可用预置测试账号或按需自动注册
注册字段强度	站点侧弱校验；中台仍须自有测试账号池，禁止把随机生成账号写入生产密钥库明文日志
storageState	独立路径，如 `.rpa/flock-storage.json`；与 Mothership 文件隔离

14.6 功能点与异常

ID	描述
F14.1	按 §14.3 校验 ZIP、托盘、总重、尺寸
F14.2	RPA 填写 get-a-quote 并抓取两档价格/时效/Reference #
F14.3	结果经 PricingEngine 加价后返回宿主（`carrier=Flock Freight`）
F14.4	Selector / URL 改版 → STRUCT_CHANGE；独立 probe

异常	处理
ZIP 缺失/非法	400，中文提示
托盘/重量/尺寸超 §14.3	400，中文提示
入口不可用 / 表单 DOM 变更	`QUOTE_ENTRY_UNAVAILABLE` / `STRUCT_CHANGE`
仅返回 1 档或价格为 0	失败，不写假档

14.7 验收门禁（实现阶段）

项	标准
Probe	`scripts/probe-flock-rpa.ts` 标准样例（如 CA ZIP→TX ZIP）连续 3 次 exit 0
档位	items 含 FlockDirect + Standard 映射各 1 条
校验	托盘 3 / 21、总重 45001、L/W/H 超限均 400
隔离	关闭 Flock 开关时不影响 Mothership 主路径

附录 A：QuoteProvider 接口契约

interface Address {
  street: string; city: string; state: string; zip: string;
  placeId: string; formattedAddress: string; selectedFromSuggestions: boolean;
}
interface QuoteRequest {
  cargoHash: string;
  pickup: Address; delivery: Address;
  weightLb: number; dimsIn: { l: number; w: number; h: number };
  palletCount: number; cargoType: string;
}
interface QuoteItem {
  serviceLevel: 'standard' | 'guaranteed';
  rateOption: 'lowest' | 'fastest';
  carrier: string; transitDays: string; transitDescription: string;
  rawFreight: number; surcharges: number; rawTotal: number;
}
interface QuoteResult {
  items: QuoteItem[];          // 必含 4 档（standard/guaranteed × lowest/fastest）
  sourceType: 'rpa';
  confidenceScore: number;
}
interface QuoteProvider {
  getQuote(req: QuoteRequest): Promise<QuoteResult>; // 一次 RPA 返回四档
  healthCheck(): Promise<boolean>;
}

附录 B：页面与状态清单

页面	状态	关键组件
宿主内嵌查价	idle / submitting / processing / done / stale / failed / expired	地址联想点选、kg/cm 录入、托盘数、pallet_count、四档报价卡、倒计时
管理端预警	list / detail	类型筛选、偏差%、quote_id、处理按钮
管理端 RPA/开发进度	dashboard	Worker 状态、成功率、队列深度

附录 C：状态/枚举字典

枚举	取值
quote.status	processing / done / failed / expired
quote.source_type	rpa / cache / stale
service_level	standard / guaranteed
rate_option	lowest / fastest
alert_type	PRICE_DEVIATION / STALE_FALLBACK / RPA_FAILED / RPA_CAPTCHA / STRUCT_CHANGE / SESSION_EXPIRED / SECURITY
cargo_type	见 §4.2.5（9 项）
currency	USD（本期唯一）

附录 D：v0.5 → v0.6 变更追踪

ID	章节	Before (v0.5)	After (v0.6)
CHG-P01	版本	v0.5	v0.6
CHG-P02	GD	无入口 URL 规范	新增 GD-15：`MOTHERSHIP_QUOTE_URLS` headed 录制；禁止 dashboard / `/quote`
CHG-P03	§2.5	仅「超时/验证码/封禁」	区分入口错误 vs 抓取错误；地址未锁定单独分类
CHG-P04	§5.6	无 `QUOTE_ENTRY_UNAVAILABLE` / `ADDRESS_SUGGESTION_NOT_FOUND`	新增两错误码
CHG-P05	§8.2	默认 `dashboard.mothership.com` 单 URL	`QuotePageAdapter` 多 URL 探测 + storageState + login 无凭据→STRUCT_CHANGE
CHG-P06	§8.2	无 Selector 规范	新增 §8.2.1~§8.2.3（env、禁止清单、codegen 维护）
CHG-P07	§11.5	login 一律 SESSION_EXPIRED	login 无凭据→STRUCT_CHANGE；新增 storageState 失效、地址联想失败
CHG-P08	TC-601	quotes 2 条	items 4 档 + probe-rpa 连续 3 次 exit 0
CHG-P09	§12.7	无 probe 门禁	新增 RPA probe 3/3 Go 条件

附录 E：v0.6 → v0.7 变更追踪

ID	章节	Before (v0.6)	After (v0.7)
CHG-P10	版本	v0.6	v0.7
CHG-P11	GD	GD-1~15	新增 GD-16 Flock Freight 第二报价源
CHG-P12	§3.1/3.2	仅 Priority1 扩展点	增加 Flock Freight 模块行与扩展点
CHG-P13	§14	无	新增 Flock Freight：入口、硬限、两档映射、弱注册、验收

85 KiB Raw Blame History Unescape Escape