|
|
# 查价项目
|
|
|
|
|
|
> **新人入口文档**：5 分钟了解项目、跑起来、别踩红线。
|
|
|
> 权威细节以 PRD / 技术设计 / 工程任务拆解为准；本文是索引与速查。
|
|
|
|
|
|
| 项 | 值 |
|
|
|
|----|-----|
|
|
|
| 文档版本 | v1.3 |
|
|
|
| 更新日期 | 2026-06-30 |
|
|
|
| 产品名 | 美美与共报价中台（查价系统） |
|
|
|
| 代码仓库 | `chajia` |
|
|
|
|
|
|
---
|
|
|
|
|
|
## AI 项目交接文档
|
|
|
|
|
|
> 供下一 AI 会话快速接手。执行日志：`cursor_project_rules/implementation-plan.mdc`（Step 11.75~11.86）。
|
|
|
|
|
|
### 1. 项目核心身份 (Project Identity)
|
|
|
|
|
|
**项目名称与一句话定义**
|
|
|
|
|
|
**美美与共报价中台（chajia）** — 通过 Playwright RPA 抓取 MotherShip 公开报价页，一次询价返回多档 LTL 报价，经加价引擎输出给宿主系统内嵌查价组件；中台自身提供 admin 管理端（预警、RPA 运维、队列监控）。
|
|
|
|
|
|
**技术栈清单**（来源：`package.json` / `docker-compose.yml`）
|
|
|
|
|
|
| 类别 | 技术 | 版本 |
|
|
|
|------|------|------|
|
|
|
| 语言 | TypeScript | ^5.9.2 |
|
|
|
| 运行时 | Node.js | [需人工补充: 最低 Node 版本] |
|
|
|
| Web 框架 | Next.js (App Router) | ^15.5.6 |
|
|
|
| UI | React | ^19.1.1 |
|
|
|
| 样式 | Tailwind CSS | ^3.4.19 |
|
|
|
| 组件 | shadcn/ui 风格 + Geist 字体 + @phosphor-icons/react ^2.1.10 | — |
|
|
|
| 表单 | react-hook-form ^7.79.0 + zod ^3.25.76 | — |
|
|
|
| API | Next.js Route Handlers | — |
|
|
|
| ORM | Prisma | ^6.19.0 |
|
|
|
| 数据库 | MySQL | 8.0（docker image `mysql:8.0`） |
|
|
|
| 缓存/队列 | Redis 7-alpine + ioredis ^5.8.1 + BullMQ ^5.78.1 | 本机 WSL 实测 6.0.16 有警告 |
|
|
|
| RPA | Playwright ^1.61.0；可选 playwright-extra + stealth | — |
|
|
|
| 队列 UI | Bull Board (@bull-board/* ^8.0.0) + Hono ^4.12.25 | — |
|
|
|
| 鉴权 | jose ^5.10.0 + bcryptjs ^3.0.2 | — |
|
|
|
| 测试 | Vitest ^3.2.4 + @playwright/test ^1.61.0 | — |
|
|
|
| 构建/脚本 | tsx ^4.20.5 | — |
|
|
|
| 部署 | Docker Compose（全栈或宝塔宿主机 MySQL + Docker 应用） | 见 `deploy/` |
|
|
|
|
|
|
**目录结构语义化说明**
|
|
|
|
|
|
| 路径 | 职责 | 数据流向 |
|
|
|
|------|------|----------|
|
|
|
| `app/` | Next.js 页面与 API Routes（薄路由层） | 宿主/Admin HTTP → `modules/*` |
|
|
|
| `app/api/quotes/` | 询价创建与轮询（方式 B） | → `modules/quote/orchestrator` → BullMQ |
|
|
|
| `app/api/host/quote/` | 宿主两步公开接口（方式 A，免 Token） | candidates → submit（服务端内部轮询） |
|
|
|
| `app/api/addresses/mothership-candidates/` | 地址候选（方式 B 第 1 步） | → BullMQ `address-candidates` job |
|
|
|
| `lib/axel/` | MotherShip axel HTTP 直连（search/place/quote） | `buildAxelCargo` 整数磅/英寸 |
|
|
|
| `lib/constants/host-service.ts` | 默认 Service Token / customer_id | embed-demo 与内网对接 |
|
|
|
| `components/` | 宿主内嵌查价 UI、管理端组件 | hooks → API |
|
|
|
| `modules/quote/` | 询价编排、校验、幂等、fallback | L1→L2→RPA→L3 状态机 |
|
|
|
| `modules/pricing/` | 加价引擎（仅 raw_freight，0~30%） | 读 MarkupConfig → 写 QuoteRecord |
|
|
|
| `modules/cache/` | Redis L1/L2/L3、限流、熔断 | 读写 Redis |
|
|
|
| `workers/rpa/` | BullMQ Consumer + Playwright 填表/抓价 | 消费 queue → 写 MySQL/Redis |
|
|
|
| `workers/rpa/quote-capture/` | Network-First 报价捕获（axel/quote 契约解析） | submit 后监听 network → normalize |
|
|
|
| `workers/rpa/address-adapter/` | 地址选择抽象（real/mock） | DOM + axel search/place API |
|
|
|
| `workers/rpa/kernel/` | RPA 步骤编排（address/cargo/quote steps） | 内部状态机 |
|
|
|
| `lib/` | prisma/redis/response/rpa env 等基础设施 | 被 app/modules/workers 引用 |
|
|
|
| `prisma/` | Schema、migrations、seed | MySQL 持久化 |
|
|
|
| `scripts/` | probe、prove、smoke、录证、准确度测试 | CLI 验收/排障 |
|
|
|
| `cursor_project_rules/` | AI 编码规则 + implementation-plan 逐步日志 | 必读 |
|
|
|
| `.rpa/` | storageState、session、chain-proof 产物 | 勿提交敏感态（gitignore） |
|
|
|
| `.dev/logs/` | worker/next 运行日志、失败截图 | 排障 |
|
|
|
|
|
|
**端到端数据流**
|
|
|
|
|
|
```
|
|
|
【方式 A — 宿主公开接口，推荐】
|
|
|
宿主前端
|
|
|
→ POST /api/host/quote/candidates（地址+货物 → RPA 枚举候选 + host_session_id）
|
|
|
→ 用户选候选
|
|
|
→ POST /api/host/quote/submit（服务端内部轮询，同步返回最终报价）
|
|
|
|
|
|
【方式 B — Token 三步，embed-demo / 后期鉴权】
|
|
|
EmbeddedQuoteWidget
|
|
|
→ POST /api/addresses/mothership-candidates
|
|
|
→ 用户确认弹窗
|
|
|
→ POST /api/quotes → L1/L2 未命中 → BullMQ quote-rpa
|
|
|
→ workers/rpa：Direct 优先 node fetchAxelQuoteItems → 失败可 Widget fallback（生产建议关闭）
|
|
|
→ 写 L2/L3 + quote_record → GET /api/quotes/{id} 轮询
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2. 当前开发状态快照 (Current State Snapshot)
|
|
|
|
|
|
**已完成模块**（单测/集成/E2E 在 Mock 或隔离路径下通过）
|
|
|
|
|
|
| 模块 | 验收依据 |
|
|
|
|------|----------|
|
|
|
| Phase 0~4 底座 | M1：POST /quotes、L2 缓存、幂等、校验 400 |
|
|
|
| 鉴权 RBAC + Service Token | middleware + 单测 |
|
|
|
| 三级缓存 + 限流 + 熔断 | redis-cache / rate-limiter 单测 |
|
|
|
| 加价引擎 | engine.test.ts TC-103 |
|
|
|
| 询价编排 + fallback + 超时 sweeper | orchestrator / timeout-sweeper 单测 |
|
|
|
| BullMQ 队列 + Worker 管理 API | rpa status/pause |
|
|
|
| 宿主内嵌查价 UI + 地址确认弹窗 | embed-demo + E2E |
|
|
|
| 管理端（预警/RPA/队列/指标/客户加价） | admin 路由 |
|
|
|
| 宿主公开 API（方式 A） | `app/api/host/quote/*` + `deploy/第三方对接指南.md` |
|
|
|
| 内网生产部署（宝塔 MySQL） | `deploy/docker-compose.bt-host-mysql.yml` + `install-bt-host-mysql.sh` |
|
|
|
| axel 公制取整 | `toAxelWholeInches` / `toAxelWholePounds`（直连 API 边界） |
|
|
|
| CI lint + test:unit + test:integration + build | `.github/workflows/ci.yml` |
|
|
|
| RPA v1.2 骨架 | QuotePageAdapter、selector env、Network-First capture、contract guard |
|
|
|
| 阶段 0 录证 | `.rpa/phase0/quote-contract-summary.json`：headed 人工可拿到 axel/quote |
|
|
|
| 货物填表（mock 路径） | fillCargoInDrawer + cargo-reset 单测 |
|
|
|
|
|
|
**进行中任务**
|
|
|
|
|
|
| 任务 | 进度 | 说明 |
|
|
|
|------|------|------|
|
|
|
| **M2-v1.2** 真实 RPA probe 3/3 | **待跑** | `npm run probe:rpa:3x` |
|
|
|
| **内网生产验收** | **进行中** | 宝塔 MySQL + `192.168.2.14:30325`；公制货物 + Direct 模式 |
|
|
|
| task-133~135 CI probe 门禁 | 待执行 | TC-601 |
|
|
|
| Priority1 FTL/LTL 录制与 benchmark | **实验** | 非 MVP；`visual:priority1-*` / `record:priority1-*` |
|
|
|
|
|
|
**最近 3 次关键变更**
|
|
|
|
|
|
| 次序 | 变更 | 原因 | 影响模块 |
|
|
|
|------|------|------|----------|
|
|
|
| 1 | **宿主公开 API**（`/api/host/quote/candidates` + `submit`） | 美美与共等宿主免 Token、服务端同步返回报价 | `app/api/host/`、`deploy/API.md` |
|
|
|
| 2 | **生产 Direct 报价 + 关闭 Widget fallback** | 避免浏览器回退卡 6~12 分钟；内网快速失败 | `quote-strategy.ts`、`RPA_QUOTE_MODE=direct`、`RPA_DISABLE_WIDGET_QUOTE_FALLBACK=true` |
|
|
|
| 3 | **axel 公制取整**（磅/英寸 `Math.ceil`） | MotherShip `axel/quote` 要求整数；公制 API 会算出小数 | `unit-converter.ts`、`lib/axel/shipment.ts` |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 3. 问题与阻塞项登记 (Issues & Blockers Registry)
|
|
|
|
|
|
> **2026-06-30 状态**：人工 docx 10 组 `probe:human-doc-system` **10/10 PASS**。内网已部署宝塔 MySQL + Docker 应用（`30325`）；生产模板默认 Direct + 禁 Widget fallback。公制 API 须走 `toAxelWhole*` 取整后发 axel。
|
|
|
|
|
|
| 问题ID | 状态 | 问题描述 | 复现路径/报错信息 | 已尝试的解决方案(含失败原因) | 下一步建议方案 | 相关文件路径 |
|
|
|
|--------|------|----------|-------------------|------------------------------|----------------|--------------|
|
|
|
| **BLK-012** | 已修复 | **P0** 公制货物直连 axel HTTP 400（磅/英寸须整数） | API 传 500kg / 120cm → `Weight/Length must be a whole number` | 内部 GD-13 保留 2 位小数；边界 `toAxelWholePounds/Inches` 向上取整 | 验收公制样例 + 英制默认样例均 PASS | `unit-converter.ts`、`lib/axel/shipment.ts` |
|
|
|
| **BLK-013** | 已修复 | 打包后 `GET /api/quotes/{id}` 返回 HTML 404 | Windows 打包脚本 `[quote_id]` 被当通配符 | `pack-server-upload.ps1` 使用 `-LiteralPath`；安装脚本预检路由 | 上传后 `curl` 确认 JSON 非 HTML | `deploy/pack-server-upload.ps1` |
|
|
|
| **BLK-014** | 已缓解 | Docker 部署 next-app 缺 Playwright / storageState | 503 或 bootstrap 失败 | `rpa_state` 卷共享；next-app `RPA_AUTO_BOOTSTRAP_STORAGE=false` | worker 负责 bootstrap；两容器共享 `.rpa` | `docker-compose.bt-host-mysql.yml` |
|
|
|
| **BLK-001** | 已缓解 | **P0** 地址 DOM 点选不触发 `GET place/{placeId}`，commit 失败 | 历史：embed-demo → worker `no_place_request` | description-click / keyboard / pac-dispatch 等；**11.77** preknown 跳过 legacy 点选、走 synthetic | 新地址回归 `probe:human-doc-system`；headed 录证见 `docs/真人录证-commit时刻.md` | `mothership-address-adapter.ts`、`address-commit.ts` |
|
|
|
| **BLK-002** | 已缓解 | **P0** 填 delivery 后 pickup 丢失（widget 互斥） | 历史：dual-address `pickupLostAfterDelivery=true` | 交替 refill（11.48）；preknown synthetic（11.77） | 同上 | `address-side.ts`、`address-commit.ts` |
|
|
|
| **BLK-003** | 已缓解 | submit 后无 `axel/quote`（contract=0） | 历史：commit 失败导致无 quote | 根因是地址未 commit；Direct-first + Widget fallback（11.75） | 监控 worker 日志 `axel/quote`；勿在 commit 通前改 contract 层 | `quote-capture/pipeline.ts`、`quote-strategy.ts` |
|
|
|
| **BLK-004** | 已关闭 | mock/fixture 假通过误导验收 | `prove:rpa-chain` PASS 但价非 MotherShip | mock-chain-fixture **已删除（11.45）** | 验收 `RPA_ADDRESS_MODE=real` + 无 fixture | `.rpa/chain-proof-72b4e980.json`（历史样例） |
|
|
|
| **BLK-005** | 已更新 | direct POST axel/quote 价与 UI 不一致 | 历史：direct 价偏低 | **11.75** Direct 优先、失败再 Widget fallback | 勿单独启用 Widget 并行/预热 | `quote-strategy.ts`、`axel-quote-direct.ts` |
|
|
|
| **BLK-006** | 开放 | L2 缓存假阳性 | `创建即 done + source_type=cache` | 探针用 `uniqueWeight` 防命中空 cache | 验收前换 cargo 或 `FLUSHDB` | `modules/cache/redis-cache.ts` |
|
|
|
| **BLK-007** | 开放 | 端到端超时 420s | commit 失败时前端超时 | 提 timeout 不能解决 commit；commit 通后约 2–3 分钟/单 | commit 稳定后评估 browser warm/session | `lib/constants/quote.ts` |
|
|
|
| **BLK-008** | 开放 | WSL Redis/MySQL 间歇断连 | worker `ECONNREFUSED 6379/3307` | keepalive + orphan 回收 | 长跑前 `npm run dev:infra:start` | `lib/redis.ts`、`queue-recovery.ts` |
|
|
|
| **BLK-009** | 开放 | 候选 API 60~180s 慢 | POST `/api/addresses/mothership-candidates` | 枚举优化、Worker 队列 | 候选慢可接受；`pickBestMothershipCandidate` 降权 Bridge | `address-candidates.ts`、`pick-mothership-candidate.ts` |
|
|
|
| **BLK-010** | 开放 | storageState 货物残留 | 摘要 2296Lbs vs 期望 500Lbs | freshCargoContext + cargo-reset | real 路径验证 `assertWidgetCargoSummary` | `cargo-reset.ts`、`session-manager.ts` |
|
|
|
| **BLK-011** | 冻结 | 架构过度重构拖慢排障 | kernel/驻留页多轮 | 11.30 放弃驻留页默认路径 | **冻结架构**；仅改 adapter + commit | `workers/rpa/kernel/` |
|
|
|
|
|
|
**根因链（历史 → 当前）**
|
|
|
|
|
|
```
|
|
|
[历史] placeApiHitCount=0 → commit FAILED → 无 axel/quote → 420s 超时
|
|
|
[当前] Direct-first + 系统探针 10/10；内网宝塔部署 + 公制取整；宿主方式 A 两步 API
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 4. 架构决策记录 (ADR)
|
|
|
|
|
|
**ADR-1：Network-First 报价捕获（禁止 DOM 刮价）**
|
|
|
|
|
|
- **决策**：报价仅来自 `services.mothership.com/axel/quote` 网络响应，经 `quote-contract-guard` + `payload-decode` 解析；禁止 DOM price extraction。
|
|
|
- **原因**：MotherShip SPA 档位与 DOM 不同步；阶段 0 HAR 已验证 API 契约稳定。
|
|
|
- **权衡**：放弃 DOM fallback；submit 后必须触发真实 quote 请求，**强依赖地址/货物 commit 成功**。
|
|
|
|
|
|
**ADR-2：BullMQ 统一 RPA Worker（候选 + 询价同进程）**
|
|
|
|
|
|
- **决策**：地址候选与询价均入 BullMQ，同一 `workers/rpa/index.ts` 消费；`withRpaSessionLock` 串行。
|
|
|
- **原因**：spawn 子进程与 worker 双浏览器争用 `.rpa/mothership-storage.json`，行为不一致。
|
|
|
- **权衡**：单 worker 吞吐低；Worker 不可用时才 spawn 回退（stall 60s）。
|
|
|
|
|
|
**ADR-3：MotherShip 地址须用户确认 + place API commit**
|
|
|
|
|
|
- **决策**：RPA 枚举候选 → 前端弹窗确认 → 询价时按 `display_label` 点选；commit 以 `GET place/{placeId}` 网络证据为准。
|
|
|
- **原因**：PRD GD 要求点选；仅 DOM 填值不满足 MotherShip widget 状态机。
|
|
|
- **权衡**：端到端 180~360s；**当前 place commit 未打通即全链路失败**。
|
|
|
|
|
|
**ADR-4：Next.js Route Handlers 薄层 + modules 业务编排**
|
|
|
|
|
|
- **决策**：API Route 只鉴权/校验/调 orchestrator；禁止 Route 内写复杂业务。
|
|
|
- **原因**：可测试性、分层清晰、Worker 与 API 共享 modules。
|
|
|
- **权衡**：无 Server Actions；宿主必须 HTTP 集成。
|
|
|
|
|
|
**ADR-5：放弃驻留页默认路径（`RPA_PARKED_SESSION=false`）**
|
|
|
|
|
|
- **决策**：候选完成后不默认 park page；询价 job 独立开页 + storageState；browser warm 保留。
|
|
|
- **原因**：驻留页需 worker+confirm+同进程，验证周期 >5min 且 fetch failed 频发；网络等待占 80%+。
|
|
|
- **权衡**：候选→询价无法零重开；性能优化有限。
|
|
|
|
|
|
**ADR-6：生产环境 Direct 优先、默认关闭 Widget fallback**
|
|
|
|
|
|
- **决策**：`RPA_QUOTE_MODE=direct`；`RPA_DISABLE_WIDGET_QUOTE_FALLBACK=true`（生产模板）；node `fetchAxelQuoteItems` 为主路径。
|
|
|
- **原因**：Widget 浏览器填表回退单次 6~12 分钟且 worker 并发为 1，易阻塞队列。
|
|
|
- **权衡**：直连对 payload 更严格（整数磅/英寸、有效 placeId）；失败须快速报错而非长时间挂起。
|
|
|
|
|
|
**ADR-7：内部精度与 axel API 边界分离**
|
|
|
|
|
|
- **决策**：`kgToLb` / `cmToIn` 内部保留 2 位小数（GD-13 哈希/展示）；调用 MotherShip `axel/quote` 前 `toAxelWholePounds` / `toAxelWholeInches` 向上取整。
|
|
|
- **原因**：embed-demo 默认英制整数不易暴露；公制 API / 宿主对接会触发小数。
|
|
|
- **权衡**：取整仅影响 MotherShip 边界，不改变 L2 cache key 算法（仍用内部精度）。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 5. 新 AI 接手指令 (Onboarding Instructions)
|
|
|
|
|
|
**启动/运行命令**
|
|
|
|
|
|
```bash
|
|
|
cp .env.example .env # 首次
|
|
|
npm run dev:infra:setup # WSL MySQL+Redis（Windows 推荐）
|
|
|
npm run dev:start # infra + migrate + seed + next + worker + scheduler
|
|
|
|
|
|
# 分项
|
|
|
npm run dev # Next.js :3000
|
|
|
npm run worker:rpa # RPA Worker（另开终端）
|
|
|
npm run worker:scheduler # 超时清扫
|
|
|
|
|
|
# 验证
|
|
|
npm run smoke:connect # MySQL/Redis
|
|
|
npm run verify:rpa-stack # 四步全栈验收
|
|
|
npm run prove:rpa-chain # 端到端 → .rpa/chain-proof-*.json
|
|
|
RPA_HEADLESS=false npm run probe:rpa # headed RPA 调试
|
|
|
|
|
|
# 测试
|
|
|
npm run lint
|
|
|
npm run test:unit
|
|
|
npm run test:integration
|
|
|
npm run test:e2e
|
|
|
npm run go-no-go -- --mock
|
|
|
|
|
|
# 停止
|
|
|
npm run dev:stop
|
|
|
```
|
|
|
|
|
|
**环境变量依赖**（名称为准，勿写值）
|
|
|
|
|
|
| 变量 | 用途 |
|
|
|
|------|------|
|
|
|
| `DATABASE_URL` | MySQL 连接（本地通常端口 3307） |
|
|
|
| `REDIS_URL` | Redis 连接 |
|
|
|
| `JWT_SECRET` | 管理端 JWT |
|
|
|
| `HOST_SERVICE_TOKENS` | 宿主 Service Token → customer_id（内网默认 `chajia-neibu-2026`） |
|
|
|
| `HOST_PUBLIC_API_ENABLED` | `true` 启用方式 A 公开接口（免 Token） |
|
|
|
| `HOST_PUBLIC_DEFAULT_CUSTOMER_ID` | 方式 A 默认客户 ID |
|
|
|
| `RPA_QUOTE_MODE` | `direct`（生产）/ `widget`（调试） |
|
|
|
| `RPA_DISABLE_WIDGET_QUOTE_FALLBACK` | 生产建议 `true`，直连失败不浏览器回退 |
|
|
|
| `RPA_AUTO_BOOTSTRAP_STORAGE` | worker `true`；next-app 容器建议 `false` |
|
|
|
| `MOTHERSHIP_QUOTE_URLS` | RPA 入口 URL 列表（必填，禁止 dashboard） |
|
|
|
| `RPA_SELECTOR_*` | 8 项 Playwright selector（PICKUP/DELIVERY/WIDGET/STREET/SUGGESTION/CARGO/SUBMIT 等） |
|
|
|
| `RPA_STORAGE_STATE_PATH` | Playwright storageState 路径 |
|
|
|
| `RPA_MOCK_MODE` | `false`=真实 RPA；`true` 仅 CI/单测 |
|
|
|
| `RPA_ADDRESS_MODE` | `real` / `mock`（mock 不能用于验收） |
|
|
|
| `RPA_HEADLESS` / `RPA_HEADED` | 有头调试 |
|
|
|
| `RPA_BROWSER_LOCALE` | 推荐 `en-US` |
|
|
|
| `RPA_BROWSER_CHANNEL` | 推荐 `chrome` |
|
|
|
| `RPA_USE_STEALTH` | 默认 `false`（曾破坏 widget） |
|
|
|
| `RPA_PARKED_SESSION` | 默认 `false` |
|
|
|
| `RPA_QUEUE_ENABLED` | Worker 是否消费队列 |
|
|
|
| `RPA_WORKER_ID` | Worker 标识（空则自动生成） |
|
|
|
| `MOTHERSHIP_QUOTE_API_URL_PATTERNS` | axel/quote telemetry 白名单 |
|
|
|
| `MOTHERSHIP_EMAIL` / `MOTHERSHIP_PASSWORD` | 仅 login 页时需要 |
|
|
|
| `DEV_INFRA_MODE` | `native` / `docker` / `auto` |
|
|
|
| `MYSQL_HOST_PORT` / `MYSQL_ROOT_PASSWORD` | Docker/WSL MySQL |
|
|
|
|
|
|
**首要任务优先级**
|
|
|
|
|
|
1. **P0** 回归门禁：`npm run probe:human-doc-system` 10/10（改地址/RPA 后必跑；worker 需 `dev:stop` + `dev:start` 重载）
|
|
|
2. **P0** 实网验收：`npm run prove:rpa-chain` 在 `RPA_ADDRESS_MODE=real` 下 PASS（非 cache、非 fixture）
|
|
|
3. **P1** embed-demo 标准样例（LA 90001 → Dallas 75201，2 托 500lb）返回 `source_type=rpa` 且价与 MotherShip 页面一致
|
|
|
4. **P2** M2 门禁：`npm run probe:rpa:3x` 连续 exit 0
|
|
|
5. **禁止**：在 commit 未通前改 timeout/stealth/contract/kernel/驻留页；禁止 Widget 并行/预热/默认路径
|
|
|
|
|
|
**项目特殊约定**
|
|
|
|
|
|
| 类别 | 约定 |
|
|
|
|------|------|
|
|
|
| 编码前必读 | `cursor_project_rules/global-rules.mdc`、`implementation-plan.mdc`、`domain-rules.mdc` |
|
|
|
| 分层 | `app/api` 薄路由 → `modules` 业务 → `workers/rpa` 长任务 |
|
|
|
| 命名 | DB snake_case；TS camelCase/PascalCase；env UPPER_SNAKE |
|
|
|
| 金额 | DECIMAL(12,2)；`ROUND_HALF_UP`；禁止 float 运算 |
|
|
|
| 界面文案 | **全部中文**（MotherShip 抓取字段除外） |
|
|
|
| 红线 | 一次询价=1 次 RPA；cache key 不含 service_level；禁止 dashboard URL；禁止 RPA mock 上线 |
|
|
|
| Git | 禁止 main 直推；不提交 `.env`/`.rpa/` 敏感态 |
|
|
|
| 完成步骤 | 在 `implementation-plan.mdc` 写 `Done` + 两行执行记录 |
|
|
|
| 禁止库/模式 | 禁止 DOM 刮价；禁止 mock-chain-fixture；禁止 default dashboard URL；禁止空 catch |
|
|
|
| Windows 开发 | 优先 `npm run dev:start`（PowerShell）；WSL native infra 优于 Docker Desktop |
|
|
|
|
|
|
**关键产物路径**
|
|
|
|
|
|
| 路径 | 内容 |
|
|
|
|------|------|
|
|
|
| `.dev/logs/worker-rpa.log` | Worker 实网日志 |
|
|
|
| `.dev/logs/rpa-failure-*.png` | RPA 失败截图 |
|
|
|
| `.rpa/chain-proof-*.json` | prove 链路报告 |
|
|
|
| `.rpa/dual-address-compare-*.json` | 双地址 network 对比 |
|
|
|
| `.rpa/phase0/quote-contract-summary.json` | axel/quote API 契约 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 项目信息
|
|
|
|
|
|
### 做什么
|
|
|
|
|
|
通过 **Playwright RPA** 抓取 Mothership 公开报价页，一次询价返回 **4 档**报价（standard/guaranteed × lowest/fastest），经加价引擎输出给**宿主系统**内嵌查价组件。中台自身仅提供 **admin 管理端**（预警、RPA 状态、队列监控）。
|
|
|
|
|
|
### 不做什么（MVP 边界）
|
|
|
|
|
|
- 不使用 Mothership 官方 API
|
|
|
- 无独立客户/运营登录、无运营加价 UI
|
|
|
- 无 CC 对接、多币种、下单、对账、Priority1
|
|
|
|
|
|
### 技术栈
|
|
|
|
|
|
| 层 | 选型 |
|
|
|
|----|------|
|
|
|
| Web | Next.js 15（App Router）+ React 19 + Tailwind + shadcn/ui |
|
|
|
| API | Next.js Route Handlers |
|
|
|
| 数据 | MySQL 8 + Prisma |
|
|
|
| 缓存/队列 | Redis 7 + BullMQ |
|
|
|
| RPA | Playwright（可选 Patchright） |
|
|
|
| 测试 | Vitest + Playwright E2E |
|
|
|
| 部署 | Docker Compose（全栈 / 宝塔宿主机 MySQL） |
|
|
|
|
|
|
### 核心文档（按阅读顺序）
|
|
|
|
|
|
| 文档 | 用途 |
|
|
|
|------|------|
|
|
|
| [查价系统-PRD.md](./查价系统-PRD.md) v0.6 | 业务规则、GD 决策、验收标准（**最高业务权威**） |
|
|
|
| [查价系统-技术设计.md](./查价系统-技术设计.md) v1.2 | 架构、目录、API、RPA 规格（**实现权威**） |
|
|
|
| [查价系统-工程任务拆解-v1.2.md](./查价系统-工程任务拆解-v1.2.md) | 原子任务与开发顺序 |
|
|
|
| [查价系统-UI设计.md](./查价系统-UI设计.md) | 页面、交互、状态机 |
|
|
|
| [参考-Mothership-RPA-开源借鉴与解阻塞.md](./参考-Mothership-RPA-开源借鉴与解阻塞.md) | RPA 排障参考 |
|
|
|
| [deploy/README.md](../deploy/README.md) | 全 Docker 生产部署 |
|
|
|
| [deploy/宝塔部署说明.md](../deploy/宝塔部署说明.md) | 宝塔 MySQL + Docker 应用（内网 30325） |
|
|
|
| [deploy/API.md](../deploy/API.md) | 外部系统接口速查 |
|
|
|
| [deploy/第三方对接指南.md](../deploy/第三方对接指南.md) | 宿主对接完整指南（方式 A/B） |
|
|
|
| [报价提速与稳定性-改动清单.md](./报价提速与稳定性-改动清单.md) | 提速/稳定性分批实施清单（Phase 12） |
|
|
|
| [AI 项目交接文档](./查价项目.md#ai-项目交接文档) | 完整 handoff：身份/状态/阻塞/ADR/接手指令 | **切换 AI 必读** |
|
|
|
| `cursor_project_rules/` | AI/人工编码规则与实施日志 | implementation-plan 逐步记录 |
|
|
|
|
|
|
### 目录结构（关键路径）
|
|
|
|
|
|
```
|
|
|
chajia/
|
|
|
├── app/ # Next.js 页面 + API Routes
|
|
|
├── components/ # 前端组件（含宿主内嵌查价）
|
|
|
├── modules/ # 业务逻辑（quote/cache/pricing/alert）
|
|
|
├── workers/rpa/ # BullMQ Consumer + Playwright
|
|
|
├── lib/ # prisma/redis/response/rpa
|
|
|
├── prisma/ # schema + migrations + seed
|
|
|
├── scripts/ # probe、smoke、go-no-go、录制
|
|
|
├── __tests__/ # unit / integration / e2e
|
|
|
├── docs/ # 产品与工程文档
|
|
|
└── cursor_project_rules/ # 项目规则 + implementation-plan
|
|
|
```
|
|
|
|
|
|
### 角色与鉴权
|
|
|
|
|
|
| 角色 | 方式 | 能力 |
|
|
|
|------|------|------|
|
|
|
| 宿主系统 | `Authorization: Bearer <HOST_SERVICE_TOKEN>` | 代 `customer_id` 询价、历史、加价配置 |
|
|
|
| 管理员 | JWT + RBAC | 预警、RPA 运维、`/admin/*` |
|
|
|
|
|
|
联调样例：
|
|
|
|
|
|
- 内网宿主 token：`chajia-neibu-2026` → `CUST_001`（见 `lib/constants/host-service.ts`）
|
|
|
- embed-demo 亦使用上述 token（构建时 `NEXT_PUBLIC_EMBED_DEMO_*` 可覆盖）
|
|
|
- 管理端：`admin_demo` / `Demo@123`（仅开发环境）
|
|
|
|
|
|
**宿主对接方式**
|
|
|
|
|
|
| 方式 | 条件 | 接口 |
|
|
|
|------|------|------|
|
|
|
| **A（推荐）** | `HOST_PUBLIC_API_ENABLED=true` | `POST /api/host/quote/candidates` → `POST /api/host/quote/submit`（免 Token，服务端同步返回） |
|
|
|
| **B** | `HOST_PUBLIC_API_ENABLED=false` + Bearer Token | 候选 → `POST /api/quotes` → `GET /api/quotes/{id}` 轮询 |
|
|
|
|
|
|
详见 [deploy/第三方对接指南.md](../deploy/第三方对接指南.md)。
|
|
|
|
|
|
### 联调标准样例
|
|
|
|
|
|
**embed-demo 默认（英制，不易触发 axel 整数校验）**
|
|
|
|
|
|
| 字段 | 值 |
|
|
|
|------|-----|
|
|
|
| 路线 | LA(90001) → Dallas(75201) |
|
|
|
| 单托重量 | 500 lb |
|
|
|
| 单托尺寸 | 48×40×48 in |
|
|
|
| 托盘数 | 2 |
|
|
|
| 货物类型 | `general_freight` |
|
|
|
|
|
|
**宿主 API / 公制验收样例（须走取整后发 axel）**
|
|
|
|
|
|
| 字段 | 值 |
|
|
|
|------|-----|
|
|
|
| 单托重量 | 500 kg → 1103 lb（向上取整） |
|
|
|
| 单托尺寸 | 120×100×150 cm → 48×40×60 in（各边向上取整） |
|
|
|
| 托盘数 | 2 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 常用命令
|
|
|
|
|
|
### 环境准备
|
|
|
|
|
|
```bash
|
|
|
# 复制环境变量（勿提交 .env）
|
|
|
cp .env.example .env
|
|
|
|
|
|
# 一键启动（推荐，含 infra + app + worker）
|
|
|
npm run dev:start
|
|
|
|
|
|
# 仅 Docker infra（MySQL + Redis）
|
|
|
docker compose up -d mysql redis
|
|
|
|
|
|
# WSL/native infra 引导（Windows 开发机）
|
|
|
npm run dev:infra:setup
|
|
|
```
|
|
|
|
|
|
### 数据库
|
|
|
|
|
|
```bash
|
|
|
npm run db:validate # Prisma schema 校验
|
|
|
npm run db:migrate # 本地迁移（开发）
|
|
|
npm run db:deploy # 生产迁移
|
|
|
npm run db:seed # 种子数据
|
|
|
```
|
|
|
|
|
|
### 开发运行
|
|
|
|
|
|
```bash
|
|
|
npm run dev # Next.js :3000
|
|
|
npm run worker:rpa # RPA Worker（另开终端）
|
|
|
npm run worker:scheduler # 超时清扫 Worker
|
|
|
npm run dev:stop # 停止本地进程
|
|
|
npm run dev:clean # 清理临时产物
|
|
|
```
|
|
|
|
|
|
### 测试与门禁
|
|
|
|
|
|
```bash
|
|
|
npm run lint # TypeScript 类型检查
|
|
|
npm run test:unit # 单元测试
|
|
|
npm run test:integration # 集成测试
|
|
|
npm run test:e2e # Playwright E2E
|
|
|
npm run test # 全量 Vitest
|
|
|
|
|
|
npm run smoke:connect # MySQL/Redis 连通
|
|
|
npm run smoke:api # API 冒烟
|
|
|
npm run smoke:rpa # 真实 RPA 冒烟（需 env 配齐）
|
|
|
|
|
|
# RPA 探针（Go/No-Go 门禁：连续 3 次 exit 0）
|
|
|
npm run probe:rpa
|
|
|
npm run probe:rpa:3x
|
|
|
npm run probe:human-doc-system # 人工 docx 10 组，系统 API 全链路
|
|
|
npm run probe:random-address-quote
|
|
|
npm run go-no-go # 上线前指标检查
|
|
|
```
|
|
|
|
|
|
### RPA 录制与排障
|
|
|
|
|
|
```bash
|
|
|
# P0 真人完整链路录证（HAR+录像+Trace+Console+Network，定位 place commit 瞬间）
|
|
|
npm run record:human-commit-baseline
|
|
|
# 详见 docs/真人录证-commit时刻.md
|
|
|
|
|
|
# headed 录制 Mothership 报价流程 → 更新 MOTHERSHIP_QUOTE_URLS / RPA_SELECTOR_*
|
|
|
npm run record:mothership
|
|
|
|
|
|
# P0 真人 vs RPA 网络差分
|
|
|
$env:RPA_HEADLESS="false"
|
|
|
npm run compare:human-rpa-network
|
|
|
```
|
|
|
|
|
|
### Docker 全栈
|
|
|
|
|
|
**方式 1 — 全 Docker（MySQL 在容器内）**：见 [`deploy/README.md`](../deploy/README.md)
|
|
|
|
|
|
```bash
|
|
|
cp deploy/.env.production.example .env # 编辑必填项
|
|
|
bash deploy/install.sh
|
|
|
bash deploy/install.sh --nginx-http # 可选：Nginx 反代
|
|
|
```
|
|
|
|
|
|
**方式 2 — 宝塔宿主机 MySQL + Docker 应用（内网推荐）**：见 [`deploy/宝塔部署说明.md`](../deploy/宝塔部署说明.md)
|
|
|
|
|
|
```bash
|
|
|
# 代码目录示例：/home/project/chajia
|
|
|
cp deploy/.env.bt-host-mysql.example .env # 编辑 DATABASE_URL、HOST_SERVICE_TOKENS 等
|
|
|
bash deploy/install-bt-host-mysql.sh
|
|
|
# 访问 http://<内网IP>:30325
|
|
|
```
|
|
|
|
|
|
上传更新：`deploy/pack-server-upload.ps1` 生成 `上传到服务器/代码/`；**勿覆盖服务器已有 `.env`**。
|
|
|
|
|
|
**本地开发 Compose**：
|
|
|
|
|
|
```bash
|
|
|
docker compose up -d --build
|
|
|
docker compose exec next-app npx prisma migrate deploy
|
|
|
docker compose exec next-app npx prisma db seed
|
|
|
```
|
|
|
|
|
|
### 访问地址
|
|
|
|
|
|
| 入口 | URL |
|
|
|
|------|-----|
|
|
|
| 宿主内嵌演示 | http://localhost:3000/embed-demo |
|
|
|
| 管理端预警 | http://localhost:3000/admin/alerts |
|
|
|
| 管理端 RPA | http://localhost:3000/admin/rpa |
|
|
|
| 队列监控 | http://localhost:3000/admin/queues |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 编码规范
|
|
|
|
|
|
### 分层（禁止跨层）
|
|
|
|
|
|
```
|
|
|
app/api/* → 薄路由，只调 modules
|
|
|
modules/* → 业务编排（orchestrator、pricing、cache）
|
|
|
workers/rpa/* → 长任务 RPA，不经 HTTP 直调 DB 以外层
|
|
|
lib/* → 基础设施封装
|
|
|
components/* → UI，经 hooks/api 调后端
|
|
|
```
|
|
|
|
|
|
- API Route **不得**写复杂业务逻辑
|
|
|
- RPA Worker **不得**绕过 `QuoteProvider` 接口直接返回假数据（CI 除外 `RPA_MOCK_MODE=true`）
|
|
|
|
|
|
### 命名
|
|
|
|
|
|
| 范围 | 规范 | 示例 |
|
|
|
|------|------|------|
|
|
|
| DB 字段 | snake_case | `pallet_count`, `raw_freight` |
|
|
|
| TS 变量/函数 | camelCase | `cargoHash`, `getQuote` |
|
|
|
| TS 类型/组件 | PascalCase | `QuoteRecord`, `QuoteForm` |
|
|
|
| 环境变量 | UPPER_SNAKE | `MOTHERSHIP_QUOTE_URLS` |
|
|
|
| API 路径 | kebab/REST | `/api/quotes/{quote_id}` |
|
|
|
|
|
|
### 金额与精度
|
|
|
|
|
|
- 存储与计算：`DECIMAL(12,2)`
|
|
|
- 舍入：`ROUND_HALF_UP`，保留 2 位
|
|
|
- **禁止**用 `float` / `number` 做金额运算
|
|
|
- **单位换算**：内部 `kgToLb` / `cmToIn` 保留 2 位（GD-13）；调用 MotherShip `axel/quote` 前须 `toAxelWholePounds` / `toAxelWholeInches` 向上取整
|
|
|
|
|
|
### API 响应
|
|
|
|
|
|
统一包络：
|
|
|
|
|
|
```json
|
|
|
{ "code": 0, "message": "ok", "data": { } }
|
|
|
```
|
|
|
|
|
|
错误使用标准 `error_code`（见 PRD §5.6 / `domain-rules.mdc` §10）。
|
|
|
|
|
|
### 异步与错误
|
|
|
|
|
|
- 所有 `async` 必须 `catch` 并 `log`（禁止空 catch）
|
|
|
- 用户可见操作必须有 loading + 防重复提交 + 成功/失败反馈
|
|
|
- 外部调用（RPA/Redis/MySQL）须处理超时与失败分类
|
|
|
|
|
|
### 前端
|
|
|
|
|
|
- **界面文案一律中文**（除 Mothership 原文抓取字段）
|
|
|
- 查价表单须支持地址联想点选、`pallet_count`、kg/cm 展示与 lb/in 换算
|
|
|
- 轮询：`GET /quotes/{id}`，间隔 2s，最长 30s
|
|
|
|
|
|
### Git
|
|
|
|
|
|
- 禁止在 `main` 直接开发；使用 feature 分支
|
|
|
- Commit：`feat|fix|docs|refactor(module): 描述`（可附 PRD/任务编号）
|
|
|
- 不提交 `.env`、`.rpa/` 敏感状态（除示例模板）
|
|
|
|
|
|
### 变更流程
|
|
|
|
|
|
1. 先查 PRD / 技术设计 / `implementation-plan.mdc` 是否已有规则
|
|
|
2. 数据结构变更 → Prisma migration → 再改代码
|
|
|
3. 改逻辑 → 补/跑对应测试
|
|
|
4. 完成一步 → 在 `implementation-plan.mdc` 标记 `Done` + 两行执行记录
|
|
|
|
|
|
---
|
|
|
|
|
|
## 红线（绝对不能违反）
|
|
|
|
|
|
### 业务红线
|
|
|
|
|
|
| # | 规则 | 违反后果 |
|
|
|
|---|------|----------|
|
|
|
| R1 | **一次询价 = 1 次 RPA**，单次必须返回 **4 档** | 成本翻倍、验收失败 |
|
|
|
| R2 | `service_level` / `rate_option` **不得进入** cache key | 缓存串档、价格错误 |
|
|
|
| R3 | 地址必须联想**点选**，须 `place_id` + `selected_from_suggestions=true` | Mothership 拒单或 RPA 失败 |
|
|
|
| R4 | 使用 `pallet_count`（托盘数），**禁止**件数/箱数字段 | 与 Mothership 口径不一致 |
|
|
|
| R5 | 加价仅对 `raw_freight`，上限 30%；未配置客户 0% | 财务口径错误 |
|
|
|
| R6 | L3 stale **仅** RPA 失败降级只读，正常路径不得读 L3 | 展示过期价 |
|
|
|
| R7 | `MOTHERSHIP_QUOTE_URLS` 必填且 headed 录制验证；**禁止**默认 `dashboard.mothership.com` 或 `/quote` | RPA 100% 失败 |
|
|
|
| R8 | login 页且无凭据 → `STRUCT_CHANGE`，**禁止**误报 `SESSION_EXPIRED` | 排障误导、错误重试 |
|
|
|
| R9 | RPA selector **禁止**硬编码上线；必须 `RPA_SELECTOR_*` env 或 `lib/rpa/selector-specs.ts` 统一管理 | 页面改版即挂 |
|
|
|
| R10 | `RPA_MOCK_MODE=false` 为验收/生产默认；Mock 仅 CI/单测 | 假数据上线 |
|
|
|
|
|
|
### 工程红线
|
|
|
|
|
|
| # | 规则 |
|
|
|
|---|------|
|
|
|
| E1 | PRD 与代码冲突时 **以 PRD 为准**；实现细节以技术设计为准 |
|
|
|
| E2 | 禁止擅自新增/修改 API 字段、错误码、表字段（须先改 PRD + migration） |
|
|
|
| E3 | 禁止空 catch、静默失败、吞异常 |
|
|
|
| E4 | 禁止占位 UI / 假按钮 / 「敬请期待」入口 |
|
|
|
| E5 | 禁止物理删除业务数据；使用逻辑删除 `is_deleted` |
|
|
|
| E6 | 禁止跳过 migration 直接改库；禁止代码引用未迁移字段 |
|
|
|
| E7 | 禁止在 main 分支直接提交；禁止 `git push -f` 到 main |
|
|
|
| E8 | 禁止提交密钥（`.env`、storageState、真实 token） |
|
|
|
| E9 | 禁止未授权升级依赖或引入未评审大包 |
|
|
|
| E10 | 多租户：`customer_id` 必须校验归属，禁止越权查历史/报价 |
|
|
|
|
|
|
### 安全红线
|
|
|
|
|
|
| # | 规则 |
|
|
|
|---|------|
|
|
|
| S1 | 查价 API 必须校验宿主 Service Token |
|
|
|
| S2 | 管理端 API 必须 JWT + RBAC |
|
|
|
| S3 | 高危操作须审计日志（`AuditLog`） |
|
|
|
| S4 | 限流：单客户 60 次/分钟（见 PRD） |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 技术方案
|
|
|
|
|
|
### 架构总览
|
|
|
|
|
|
```
|
|
|
宿主系统（内嵌查价 UI）
|
|
|
│ Bearer Token + customer_id
|
|
|
▼
|
|
|
Next.js API（QuoteOrchestrator）
|
|
|
├─ L1 idem:{request_id} ──命中──► 直接返回
|
|
|
├─ L2 quote:{cargo_hash} ──命中──► 加价后返回
|
|
|
└─ 未命中 ──► BullMQ(quote-rpa) ──► RPA Worker
|
|
|
│ │
|
|
|
│ ├─ QuotePageAdapter（多 URL 探测）
|
|
|
│ ├─ session-manager（storageState）
|
|
|
│ └─ mothership.ts（填表+四档抓取）
|
|
|
▼
|
|
|
MySQL quote_record / Redis L2/L3
|
|
|
```
|
|
|
|
|
|
### 缓存策略（GD-2）
|
|
|
|
|
|
| 层 | Key | TTL | 用途 |
|
|
|
|----|-----|-----|------|
|
|
|
| L1 | `idem:{request_id}` | 24h | 幂等完整响应 |
|
|
|
| L2 | `quote:{cargo_hash}` | 3min | 四档原始价（未加价） |
|
|
|
| L3 | `stale:{cargo_hash}` | 30min | RPA 失败降级 |
|
|
|
|
|
|
读取顺序：**L1 → L2 → RPA →（失败）L3**。
|
|
|
|
|
|
### 询价状态机
|
|
|
|
|
|
```
|
|
|
processing → done (cache|rpa|stale) | failed (QUOTE_UNAVAILABLE|QUOTE_TIMEOUT)
|
|
|
done --3min--> expired
|
|
|
```
|
|
|
|
|
|
### RPA 方案（v1.2 + 生产直连）
|
|
|
|
|
|
1. `QuotePageAdapter` 按 `MOTHERSHIP_QUOTE_URLS` 顺序探测可用入口
|
|
|
2. `session-manager` 加载/写回 `RPA_STORAGE_STATE_PATH`；`ensureMothershipStorageState` 可自动 bootstrap
|
|
|
3. **报价主路径（生产）**：`RPA_QUOTE_MODE=direct` → node `fetchAxelQuoteItems`（axel HTTP）
|
|
|
4. **兜底（开发/可关）**：Direct 失败后 Widget 浏览器填表；生产设 `RPA_DISABLE_WIDGET_QUOTE_FALLBACK=true`
|
|
|
5. 地址：RPA 枚举候选 → 用户确认 → placeId commit
|
|
|
6. 失败分类：入口错误 / 地址未锁定 / 验证码 / 结构变更 / 数据无效 / axel 400（整数校验）
|
|
|
|
|
|
上线门禁：`probe-rpa` **连续 3 次 exit 0**（TC-601 + §12.7）；系统链路 `probe:human-doc-system` 10/10。
|
|
|
|
|
|
### 加价公式
|
|
|
|
|
|
```
|
|
|
markup_amount = ROUND_HALF_UP(raw_freight × markup_percent / 100, 2)
|
|
|
final_total = ROUND_HALF_UP(raw_total + markup_amount, 2)
|
|
|
```
|
|
|
|
|
|
### 关键 API
|
|
|
|
|
|
| 方法 | 路径 | 调用方 |
|
|
|
|------|------|--------|
|
|
|
| POST | `/api/host/quote/candidates` | 宿主（方式 A，免 Token） |
|
|
|
| POST | `/api/host/quote/submit` | 宿主（方式 A，同步返回报价） |
|
|
|
| POST | `/api/quotes` | 宿主（方式 B） |
|
|
|
| GET | `/api/quotes/{quote_id}` | 宿主（方式 B 轮询） |
|
|
|
| POST | `/api/addresses/mothership-candidates` | 宿主（方式 B 地址候选） |
|
|
|
| GET | `/api/quotes/history` | 宿主 |
|
|
|
| PUT | `/api/markup-configs/{customer_id}` | 宿主 |
|
|
|
| GET | `/api/alerts` | 管理员 |
|
|
|
|
|
|
### 环境变量（RPA 最小集）
|
|
|
|
|
|
| 变量 | 必填 | 说明 |
|
|
|
|------|------|------|
|
|
|
| `MOTHERSHIP_QUOTE_URLS` | 是 | 逗号分隔匿名报价 URL |
|
|
|
| `RPA_SELECTOR_*` | 是 | 录制产出 selector |
|
|
|
| `RPA_STORAGE_STATE_PATH` | 否 | 默认 `.rpa/mothership-storage.json` |
|
|
|
| `RPA_MOCK_MODE` | 否 | 默认 `false` |
|
|
|
| `RPA_HEADLESS` | 否 | 调试设 `false` |
|
|
|
| `RPA_QUOTE_MODE` | 否 | 生产 `direct` |
|
|
|
| `RPA_DISABLE_WIDGET_QUOTE_FALLBACK` | 否 | 生产建议 `true` |
|
|
|
| `HOST_PUBLIC_API_ENABLED` | 否 | 宿主方式 A 开关 |
|
|
|
| `DATABASE_URL` / `REDIS_URL` | 是 | 基础设施 |
|
|
|
|
|
|
完整列表见 `.env.example` 与技术设计 §6.2。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 新人上手路径
|
|
|
|
|
|
1. **先读本文「AI 项目交接文档」** → PRD §1–3 → 技术设计 §1、§7
|
|
|
2. `cp .env.example .env`，配 `DATABASE_URL` / `REDIS_URL` / `HOST_SERVICE_TOKENS`
|
|
|
3. `npm run dev:start` 或 `docker compose up -d` + `npm run dev`
|
|
|
4. 打开 http://localhost:3000/embed-demo 走通查价
|
|
|
5. RPA 开发：先 `npm run record:mothership`，再 `npm run probe:rpa`
|
|
|
6. 接任务前查 [工程任务拆解 v1.2](./查价系统-工程任务拆解-v1.2.md) 当前 Phase
|
|
|
|
|
|
---
|
|
|
|
|
|
## 排障速查
|
|
|
|
|
|
| 现象 | 优先检查 |
|
|
|
|------|----------|
|
|
|
| **axel/quote HTTP 400 整数** | 公制货物是否经 `toAxelWhole*`；worker 日志 `Weight/Length must be a whole number` |
|
|
|
| **GET /quotes/{id} 返回 HTML** | 动态路由是否打包进镜像；`deploy/pack-server-upload.ps1` 预检 |
|
|
|
| **embed 询价超时/failed** | **先看「AI 项目交接文档」§3 BLK-001~003**；worker 日志 `no_place_request` |
|
|
|
| **直连失败且极慢** | 是否未关 Widget fallback；查 `RPA_DISABLE_WIDGET_QUOTE_FALLBACK` |
|
|
|
| **Service Token 无效** | token 是否在 `HOST_SERVICE_TOKENS`；embed-demo 与 `NEXT_PUBLIC_EMBED_DEMO_*` 一致 |
|
|
|
| 创建即 done + cache | L2 假阳性；换 cargo 或清 Redis `quote:*` |
|
|
|
| place commit 失败 | headed 对比 network：`GET place/{id}` 是否触发 |
|
|
|
| RPA 进登录页 | `MOTHERSHIP_QUOTE_URLS` 是否 dashboard；storageState 是否失效 |
|
|
|
| preCheck 失败 | `RPA_SELECTOR_*` 是否过期；headed 重录 |
|
|
|
| 地址填不进去 | 是否缺少 `place_id`；联想是否 click 而非 Enter |
|
|
|
| 只返回 2 档 | 违反 GD-1，检查四档抓取逻辑 |
|
|
|
| 429 | 限流；检查 `customer_id` 请求频率 |
|
|
|
| Worker 不消费 | Redis 连通、`RPA_QUEUE_ENABLED`、BullMQ 队列 |
|
|
|
|
|
|
失败截图目录：`.dev/logs/`（如 `rpa-failure-*.png`）。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 文档维护
|
|
|
|
|
|
- 业务变更 → 先改 PRD → 同步技术设计 → 更新本文「项目信息/红线/技术方案」摘要
|
|
|
- 命令变更 → 以 `package.json` `scripts` 为准，同步本文「常用命令」
|
|
|
- 规则变更 → 同步 `cursor_project_rules/domain-rules.mdc`
|
