# PRD — Intelligent Document Assembly & Auto-Validation for Freight Forwarders

> **版本：** v1（首次生成）
> **生成时间：** 2026-05-09 11:38
> **来源：** ScoredDemands/freight-forwarder-doc-cutoff-challenges__scored-demand__20260405-2142.md
> **评分：** 33/40 | **决策：** BUILD
> **战略定位：** Card #1（截关追踪）的扩展层，可合并为货代一站式指挥中心

---

## 1. Problem & User

**目标用户：** SMB 货代（1–100人）的单证员和运营人员，每月处理 100–500 票海运/空运货物的单据。

**核心痛点：** 每份货运单据（提单、商业发票、装箱单、SI）需在多个系统（TMS、船司门户、海关申报平台）间手动重复录入相同数据，每份单据耗时 10–60 分钟，每票货隐形人力成本 $6–12。重复录入引发的HS编码错误、重量不一致等问题导致海关查验和罚款，且这些错误往往在截关前最后一刻才被发现。

**用户原话：** "手工录入一份大单据要60分钟，同样的数据要在3个系统各输一遍。"

---

## 2. Target Outcome & KPIs

| KPI | 目标（上线后 90 天） |
|-----|---------------------|
| 付费用户数 | 30 家 SMB 货代 |
| MRR | $2,370（30 × $79） |
| 单据处理时间（用户反馈） | 从平均 25 分钟降至 ≤5 分钟 |
| OCR 字段准确率 | ≥90%（需人工确认剩余 10%） |
| 14 天免费转付费率 | ≥20% |

---

## 3. MVP Scope（In）

- 文件上传：支持 PDF / JPG / PNG（商业发票 CI、装箱单 PL）
- AI 字段提取：自动识别发货人、收货人、HS 编码、品名、数量、重量、件数、货值
- 人工审核界面：逐字段对照原始文档确认/修正，异常字段高亮
- 交叉校验规则：总重量 vs 分项重量之和、HS 编码格式、必填字段完整性
- 导出格式：CSV（通用）、结构化 JSON（供后续 API 推送）、COSCO/ONE/Evergreen SI 表格复制格式
- 历史记录：已处理单据列表，支持重新编辑/导出
- 免费额度：每月 20 份单据（体验核心价值）

---

## 4. Out of Scope

- 直接推送到船司 SI 门户（需各船司 API 授权，v2）
- 空运单（AWB）处理（v2）
- 海关申报电子化直报（政策复杂，v3）
- 多语言单据（中文以外语种 OCR，v2）
- 与 TMS 系统双向集成
- 截关时间管理（Card #1 范围）

---

## 5. User Flow（Happy Path）

**注册后 5 分钟内的 Aha Moment：**

1. 用户访问 `/signup` → 邮箱注册 → 进入 workspace
2. 首页展示「上传你的第一份单据」大号 CTA（拖拽区域 + 示例单据预览）
3. 用户上传一份商业发票 PDF → 系统显示「AI 处理中…」（约 8–15 秒）
4. **Aha Moment：** 出现结构化字段表单，发货人/品名/重量已自动填好，异常字段（如 HS 编码格式错误）用红色高亮
5. 用户点击确认/修正各字段 → 点击「导出 CSV」→ 文件即刻下载
6. 系统提示「您已节省约 20 分钟，已处理 1/20 份免费额度」

---

## 6. Functional Requirements（P0）

### 6.1 Onboarding Flow（零人工介入）
- 注册后直接进入上传界面，无中间步骤
- 上传区有「示例单据」一键预填演示（无需真实文件即可体验 Aha Moment）
- 处理完成后弹出「分享给同事」邀请入口（病毒式增长触点）

### 6.2 文件处理 Pipeline
- `POST /api/documents/upload` — 接收文件，存入 S3/R2，返回 document_id
- `POST /api/documents/:id/extract` — 调用 Claude Vision API 提取字段，返回结构化 JSON
- `PATCH /api/documents/:id/fields` — 保存人工修正结果
- `GET /api/documents/:id/export?format=csv|json|cosco_si` — 导出

### 6.3 AI 提取规格
- 调用 Claude claude-sonnet-4-6（Vision）解析单据图像/PDF 转图
- Prompt 指定字段清单：shipper, consignee, notify_party, hs_code, description, quantity, unit, gross_weight, net_weight, measurement, cargo_value, currency, po_number
- 返回每个字段的 `value` + `confidence`（高/中/低）+ `source_bbox`（原文档位置）
- 低置信度字段自动标红，要求用户确认

### 6.4 校验规则引擎
- 总重 = Σ分项重量（误差 > 0.5kg 告警）
- HS 编码：6位数字格式校验
- 必填字段：shipper/consignee/hs_code/gross_weight 不得为空
- 货值 × 汇率跨货币一致性（如有多行不同货币）

### 6.5 付费墙设计
- **触发事件：** 用户处理第 **21 份**单据时（免费额度 20 份/月）
- in-app 模态框「本月免费额度已用完，升级后立即继续处理」
- **自动转化序列：**
  - T+0：模态框 + 「$79/月 · 14天免费试用」CTA
  - T+12h：邮件「您有 X 份单据等待处理，平均节省 20 分钟/份」
  - T+48h：邮件「对比：$79/月 vs 雇一个兼职录单员 $800/月」
  - T+7d：「月底前升级享 9 折」限时优惠

---

## 7. Data Model（精简）

```
User { id, email, password_hash, workspace_id, created_at }
Workspace { id, name, plan(free|pro), docs_this_month, trial_ends_at }
Document { id, workspace_id, filename, file_url, status(processing|review|done), created_at }
ExtractedField { id, document_id, field_name, value, confidence(high|medium|low), corrected_value, is_confirmed }
ExportLog { id, document_id, format, exported_at }
```

---

## 8. API / Integration Notes

- **AI 提取：** Anthropic Claude API（claude-sonnet-4-6，Vision 模式，PDF 先转 PNG）
- **文件存储：** Cloudflare R2（已有基础设施）
- **PDF 转图：** `pdf2pic` npm 包（服务端，无需外部 API）
- **邮件：** Resend（与 Card #1 共用）
- **支付：** Paddle（与 Card #1 共用，不同 Plan ID）
- **导出格式：** CSV（papaparse）、COSCO SI 格式（固定列映射 JSON 模板）

---

## 9. Acceptance Criteria

- [ ] 上传 PDF 商业发票后 20 秒内返回提取结果，主要字段（发货人/品名/重量）准确率 ≥90%
- [ ] 低置信度字段在 UI 中红色标注，用户确认前不可导出
- [ ] 总重与分项重量不符时，保存时弹出警告（用户可强制覆盖）
- [ ] HS 编码格式错误时，字段边框变红并显示提示文案
- [ ] 导出 CSV 包含所有确认字段，文件名格式为 `{document_id}_{timestamp}.csv`
- [ ] 第 21 份单据处理完成时，付费模态框出现，T+12h 邮件触发
- [ ] 示例单据演示流程无需真实上传文件即可完整体验

---

## 10. Delivery Plan

### Milestone 1 — 文件上传 + AI 提取 + 审核 UI（9h）

**目标：** 用户能上传单据并看到 AI 提取的结构化字段。

**文件：**
- `app/api/documents/upload/route.ts` — 文件接收 + R2 上传 + Document 记录创建
- `lib/pdf-to-image.ts` — PDF 转 PNG（pdf2pic 封装）
- `lib/claude-extract.ts` — Claude Vision API 调用 + 字段解析
- `app/api/documents/[id]/extract/route.ts` — 触发提取，轮询状态
- `app/(dashboard)/documents/[id]/review/page.tsx` — 字段审核界面（原文预览 + 表单并排）
- `components/FieldRow.tsx` — 单字段组件（置信度徽章 + 编辑态）

**Exit Criteria：**
- `POST /api/documents/upload` 返回 201 含 document_id
- `POST /api/documents/:id/extract` 在 20s 内返回含 ≥10 个字段的 JSON
- 审核页面正确渲染字段，低置信度字段标红

### Milestone 2 — 校验引擎 + 导出（5h）

**目标：** 校验通过后支持多格式导出。

**文件：**
- `lib/validation-rules.ts` — 重量加总、HS格式、必填项校验
- `app/api/documents/[id]/export/route.ts` — format 参数路由 CSV/JSON/cosco_si
- `lib/export-formats/csv.ts` — papaparse 导出
- `lib/export-formats/cosco-si.ts` — COSCO SI 格式映射
- `components/ExportButton.tsx` — 导出按钮 + 格式选择下拉

**Exit Criteria：**
- 保存时总重与分项重不符，UI 弹出警告
- `GET /api/documents/:id/export?format=csv` 返回正确 CSV 文件
- HS 编码非6位数字时，字段标红

### Milestone 3 — 付费墙 + 转化序列 + 示例演示（6h）

**目标：** PLG 漏斗完整闭环。

**文件：**
- `components/PaywallModal.tsx` — 第 21 份触发模态框
- `app/api/billing/upgrade/route.ts` — Paddle checkout（复用 Card #1 基础）
- `lib/email/sequences/doc-conversion.ts` — T+12h / T+48h / T+7d 邮件
- `app/api/cron/doc-conversion/route.ts` — 转化序列 Cron
- `app/(dashboard)/demo/page.tsx` — 示例单据演示页（内嵌预设数据，无需上传）

**Exit Criteria：**
- 处理第 21 份单据后，PaywallModal 出现
- T+12h（测试用 5 分钟）转化邮件触发
- 示例演示页可完整走通上传→提取→审核→导出流程

---

## 11. Risks & Mitigations

| 风险 | 缓解方案 |
|------|---------|
| Claude Vision 对低质扫描件准确率差 | 提示用户上传清晰文件 + 手动填写兜底 |
| Claude API 延迟高（>20s） | 异步处理 + 进度条 + WebSocket 推送结果 |
| COSCO/ONE SI 格式频繁变更 | 导出模板独立维护，用 JSON 配置化映射 |
| 免费额度 20 份不够体验价值 | 监控 Day-14 转化率，若 <15% 提升至 30 份 |
| Claude API 成本（每次调用 ~$0.01–0.03） | 免费用户按量限制，付费用户成本 < MRR 的 5% |

---

## 12. Chargeability Rationale

**免费版（20份/月）：** 用户在处理真实货物单据中亲身体验「60 分钟 → 5 分钟」的效率跃迁，建立强依赖后触碰付费墙。

**付费版（$79/月，无限单据）：** 每月 $79 对应每票货节省 20 分钟，100 票/月即节省 33 小时，ROI 是付费成本的 **8–15 倍**——用户自己就能算清这笔账，无需说服。

**付费墙触发时机：** 用户处理第 21 份单据——已建立工作流依赖，切换回手动录入的心理成本极高，升级决策最自然。