# PRD — Multi-Carrier Cutoff Tracker & Alert System

> **版本：** v1（首次生成）
> **生成时间：** 2026-05-09 11:38
> **来源：** ScoredDemands/freight-forwarder-doc-cutoff-challenges__scored-demand__20260405-2142.md
> **评分：** 35/40 | **决策：** BUILD

---

## 1. Problem & User

**目标用户：** SMB 货代公司（1–100人）的出口协调员和运营经理，每月管理 50–500 票货物，涉及多家船司。

**核心痛点：** 货代需手动追踪多家船司（MSC、COSCO、Evergreen 等）的 CY/SI/VGM/海关放行截关时间，依赖电子表格和日历提醒，完全无自动化。一旦错过截关，每个集装箱每天罚款 $100–300 压港费 + $150–500 滚船费。"差一小时，货物多等一周。"

**现有竞品缺口：** CargoWise/Magaya 要 $1,000+/月且需全系统迁移；免费方案（表格+日历）无法感知船司时间变动。

---

## 2. Target Outcome & KPIs

| KPI | 目标（上线后 90 天） |
|-----|---------------------|
| 付费用户数 | 50 家 SMB 货代 |
| MRR | $2,450（50 × $49） |
| 每用户追踪货量 | 平均 80 票/月 |
| 截关遗漏率 | 用户反馈降低 ≥80% |
| 14 天免费转付费率 | ≥25% |

---

## 3. MVP Scope（In）

- 货物管理：添加/编辑/删除货物（船司、船名、起运港、截关类型）
- 多截关类型支持：CY Cut、SI Cut、VGM Cut、Customs Release
- 手动录入截关时间（MVP 阶段，后续接 API）
- 统一 Timeline 看板：所有货物的截关倒计时，按紧迫度排序
- 文件状态标记：每票货标注 SI/VGM/商业发票是否就绪
- 三级告警邮件：72h / 24h / 4h 前自动发送
- 船司时间变动手动更新 + 重新触发告警
- 团队多账号：同公司最多 5 个协调员共用一个 workspace

---

## 4. Out of Scope

- 船司 API 实时抓取（v2 功能）
- SMS 告警（v2，MVP 只做邮件）
- TMS 系统集成/导入
- 单据自动生成/OCR（Card #2 范围）
- 移动端 App
- 多货币计费

---

## 5. User Flow（Happy Path）

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

1. 用户访问 `/signup` → 输入邮箱密码 → 进入 workspace
2. 系统展示「添加你的第一票货」引导卡（无需看文档）
3. 用户填写：船司（下拉）、船名、起运港、ETD → 系统展示默认截关类型模板
4. 用户确认/调整 CY/SI/VGM 截关时间 → 点击「保存」
5. **Aha Moment：** Dashboard 立即出现倒计时卡片，显示「距 CY Cut 还有 2 天 14 小时」，状态为 🔴 紧急
6. 系统提示「开启邮件告警」→ 用户确认邮箱 → 告警激活
7. 用户批量添加剩余货物（支持复制上一票的船司模板）

---

## 6. Functional Requirements（P0）

### 6.1 Onboarding Flow（零人工介入）
- 注册后自动进入引导向导（3 步：添加货物 → 确认截关 → 开启告警）
- 引导完成前不展示空白 Dashboard
- 支持「跳过向导」但保留提醒入口

### 6.2 货物与截关管理
- `POST /api/shipments` — 创建货物，自动生成 4 种截关记录
- `PATCH /api/shipments/:id/cutoffs` — 更新截关时间，触发告警重计算
- `GET /api/dashboard` — 返回按紧迫度排序的货物+截关列表（缓存 60s）

### 6.3 告警引擎
- Cron 每小时扫描所有激活货物
- 72h / 24h / 4h 三个触发点各发一封邮件，不重复发送
- 邮件包含：货物名、截关类型、剩余时间、Dashboard 直链
- **付费墙触发事件：** 当用户追踪货物数量达到 **第 11 票**（免费额度 10 票）时，Dashboard 顶部出现付费提示横幅

### 6.4 自动转化序列（触碰付费墙后）
- **T+0：** in-app 横幅「您已追踪 10 票货物，升级解锁无限额度」+ 「14 天免费试用」CTA
- **T+24h：** 邮件「您有 X 票货物正在等待告警，试用 Pro 确保不漏截」
- **T+72h：** 邮件「错过一个截关的代价是 $250–800，$49/月保护您的每票货」
- **T+7d：** 如未转化，发送「最后提醒」+ 提供 1 个月 9 折优惠码

### 6.5 团队协作
- workspace 邀请链接，同公司最多 5 人
- 所有成员共享同一个货物列表和告警设置

---

## 7. Data Model（精简）

```
User { id, email, password_hash, workspace_id, role, created_at }
Workspace { id, name, plan(free|pro), shipment_count, trial_ends_at }
Shipment { id, workspace_id, carrier, vessel_name, origin_port, etd, status(active|completed) }
Cutoff { id, shipment_id, type(CY|SI|VGM|customs), deadline_at, doc_ready(bool) }
AlertLog { id, cutoff_id, trigger_type(72h|24h|4h), sent_at }
```

---

## 8. API / Integration Notes

- **邮件发送：** Resend（$0 开始，API 简洁）
- **Cron：** Vercel Cron Jobs 或 node-cron（自托管）
- **支付：** Paddle（已有集成经验）
- **MVP 阶段：** 船司截关数据全部手动录入，系统提供主流船司默认模板（MSC/COSCO/Evergreen/ONE/Yang Ming）

---

## 9. Acceptance Criteria

- [ ] 用户注册后 5 分钟内完成第一票货物添加，无需查阅文档
- [ ] Dashboard 正确展示所有货物的截关倒计时，按紧迫度（最近截关在顶）排序
- [ ] 距截关 72h / 24h / 4h 时，对应邮件准时发送，同一触发点不重复发送
- [ ] 截关时间更新后，告警重新计算，已发送的告警不重发
- [ ] 第 11 票货物添加时，付费横幅出现，T+24h 转化邮件触发
- [ ] `GET /api/dashboard` 响应时间 < 500ms（含缓存）
- [ ] 多用户同一 workspace 可看到实时一致的货物状态

---

## 10. Delivery Plan

### Milestone 1 — 核心数据层 + 基础 UI（8h）

**目标：** 用户能添加货物并在 Dashboard 看到截关倒计时。

**文件：**
- `prisma/schema.prisma` — User/Workspace/Shipment/Cutoff 模型
- `app/api/shipments/route.ts` — POST（创建货物+自动生成4条Cutoff）
- `app/api/dashboard/route.ts` — GET（聚合货物+截关，按紧迫度排序）
- `app/(dashboard)/page.tsx` — 截关倒计时卡片列表
- `components/ShipmentForm.tsx` — 添加货物表单（船司下拉+截关预填）

**Exit Criteria：**
- `POST /api/shipments` 返回 201，含 4 条 Cutoff 记录
- `GET /api/dashboard` 返回货物列表，按 `nearest_cutoff ASC` 排序
- Dashboard 页面渲染货物卡片，显示剩余小时数

### Milestone 2 — 告警引擎 + 邮件（6h）

**目标：** 截关前自动发送告警邮件，不重复发送。

**文件：**
- `lib/alert-engine.ts` — 扫描 Cutoff，计算触发条件，去重逻辑
- `app/api/cron/alert/route.ts` — Vercel Cron 入口（每小时触发）
- `lib/email/templates/cutoff-alert.tsx` — 邮件模板（React Email）
- `lib/resend.ts` — Resend 客户端封装
- `prisma/migrations/` — AlertLog 表

**Exit Criteria：**
- 手动调用 `/api/cron/alert`，距截关 < 72h 的货物收到邮件
- 重复调用不发重复邮件（AlertLog 去重）
- 截关更新后，旧 AlertLog 清除，重新计算

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

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

**文件：**
- `app/onboarding/page.tsx` — 3 步引导向导
- `components/PaywallBanner.tsx` — 第 11 票触发横幅
- `app/api/billing/upgrade/route.ts` — Paddle 付费跳转
- `lib/email/sequences/conversion.ts` — T+24h / T+72h / T+7d 邮件队列
- `app/api/cron/conversion/route.ts` — 转化序列 Cron

**Exit Criteria：**
- 新用户注册后自动进入 Onboarding，完成后进入 Dashboard
- 添加第 11 票货物时，PaywallBanner 出现
- T+24h 后（测试用 5 分钟替代），触碰付费墙用户收到转化邮件

---

## 11. Risks & Mitigations

| 风险 | 缓解方案 |
|------|---------|
| 船司截关数据不准确（手动录入误差） | 提供主流船司默认模板 + 用户可编辑修正 |
| 告警漏发（Cron 失败） | AlertLog 幂等设计 + Vercel Cron 失败重试 |
| 免费额度太高（10票）导致不付费 | 监控 Day-14 转化率，若 <15% 降至 5 票 |
| SMB 货代不信任新工具 | 14 天无需信用卡试用，降低采用门槛 |

---

## 12. Chargeability Rationale

**免费版（≤10票）：** 用户真实感受到截关倒计时和邮件告警的价值，在处理小批量货物时完全够用——让用户"上瘾"于零漏截的安全感。

**付费版（$49/月，无限票数）：** 扩展到日常全量货物管理；$49/月相当于防止 **0.2个** 滚船事故的成本，ROI 在第一个月即可验证。

**付费墙触发时机：** 用户追踪第 11 票货物时——此时用户已体验到核心价值、建立使用习惯，升级决策阻力最低。