# 技术设计方案 v1.0（邮件自动预报系统）

> 状态：可直接开发（**2026-07-23 现行口径回写**；**2026-08-03 指令拆分产品规则锁定**）  
> 依据：`docx/需求规格-邮件自动预报-v0.2.md`、`docx/异常场景与系统韧性设计.md`、**`docx/产品规则-邮件指令识别与拆分.md`**  
> 栈锁定：Next.js App Router + MySQL 8 + docker-compose（`web` / `worker` / `mysql`）  
> **回写要点**：`src/worker`；IMAP lookback N 天；无 audit_log；路由 `/confirm` `/logs` `/settings`；本地 MySQL **7023**；seed 仅账号；详见 `docx/现行口径-修订说明-v1.md`  
> **指令口径**：主题/正文/附件分工、仅最新段可确认、软词→客户指令 — 见产品规则页；实现见 `instruction-lexicon.ts` / `split-instructions.ts`（**无 LLM**）

---

## 1. 细化技术选型

### 1.1 ORM

| 维度 | Prisma | Drizzle | TypeORM |
|---|---|---|---|
| AI 生成 Schema | 高（schema 声明式） | 高（TS 表定义） | 中 |
| 类型安全 | 生成客户端强类型 | 推断强 | 装饰器弱于前两者 |
| 迁移 | `prisma migrate` 成熟 | `drizzle-kit` 可用 | 易踩坑 |
| JSON 字段 | 原生支持 | 原生支持 | 一般 |

**唯一推荐：Prisma 5.x**  
理由：Cursor 生成/改 schema 成功率最高；迁移命令固定；与 Next.js 官方示例一致；`Json` 字段直接对应 `type_evidence` / `shipments`。

### 1.2 UI 组件库

| 维度 | shadcn/ui | Ant Design | MUI |
|---|---|---|---|
| 客服后台 | 中（需自拼表格） | 高（Table/Form 开箱） | 高 |
| 虚拟滚动 327+ | `@tanstack/react-virtual` 自接 | `Table virtual` 文档成熟 | 需 DataGrid Pro 或自接 |
| 定制 | 最高 | 中 | 中 |
| 包体/样式冲突 | 低 | 中 | 中 |

**唯一推荐：Ant Design 5.x + `@tanstack/react-virtual`（仅确认页货件表）**  
理由：列表/筛选/Form/Modal 一次齐；确认页用 TanStack Virtual 包 Antd Table 行，避免 Pro 授权；后台信息密度匹配运营场景。

### 1.3 Worker

| 维度 | setInterval 脚本 | BullMQ | PM2 only |
|---|---|---|---|
| 对齐 60s 轮询 | 直接 | 过重 | 仅进程管理 |
| `GET_LOCK` 互斥 | 业务内实现 | 队列锁重复 | 不解决业务锁 |
| compose 复杂度 | 低（第二容器） | 需 Redis | 需宿主机 PM2 |

**唯一推荐：独立 Node 入口 `worker/index.ts` + `setInterval(POLL_INTERVAL_MS)` + MySQL `GET_LOCK('imap_poll', 0)`**  
理由：PRD 明确单连接轮询，无任务扇出；不加 Redis；docker 内 `node dist/worker.js` 常驻即可。Compose 用 `restart: unless-stopped`，不用 PM2。

### 1.4 其余锁定

| 项 | 选型 |
|---|---|
| 语言 | TypeScript 5.x strict |
| 运行时 | Node.js 20 LTS |
| Next | 15.x App Router |
| 鉴权（一期） | 自建 session：`iron-session` + 环境变量账号；Cookie HttpOnly |
| HTTP（CC） | `undici`（Node 原生 fetch 封装层 `CcHttpClient`） |
| IMAP | `imapflow` |
| 邮件解析 | `mailparser` |
| xlsx | `exceljs` |
| zip | `adm-zip`（只解一层） |
| 密码 MD5 | `crypto.createHash('md5')` |
| 校验 | `zod`（API 入参 + 解析中间态） |
| 日志 | `pino` |
| 包管理 | `pnpm` |
| 测试 | `vitest`（单元）+ `playwright`（E2E，M4+） |

---

## 2. 系统架构设计

### 2.1 总体架构（文字）

```
imap.qq.com:993
       │ SINCE N天(已读+未读) / STORE \Seen
       ▼
┌────────────────── worker 容器 ──────────────────┐
│  ImapPoller → SnapshotStore → ParsePipeline     │
│       │              │              │           │
│       └──────────────┴──────────────┘           │
│                      ▼                          │
│              Prisma → MySQL                     │
│   (FETCHED→PARSING→PARSED|PENDING_CONFIRM|…)    │
└─────────────────────────────────────────────────┘
                       ▲
                       │ 读写同一库
┌────────────────── web 容器 ─────────────────────┐
│  Next.js App Router                             │
│  UI: 列表/详情/确认导入/日志                     │
│  Route Handlers: /api/*                         │
│  ImportService → ConflictCheck → CcAdapter      │
│       │                              │          │
│       │                              ▼          │
│       │             test.saas.carriercentral.vip│
│       │            customerLogin / SaveContainer│
│       │            GetContainerList / ShipLine  │
│       └────────── MySQL (status/import/audit) ──┘
└─────────────────────────────────────────────────┘
```

**硬边界：**
- **人工确认路径**（`NEW_CONTAINER`）：仅 Web API 在用户点击确认后调用 `SaveContainer`。
- **自动执行路径**（`TRANSFER` / `INSTRUCTION_HOLD_SPLIT` / `INSTRUCTION_LABEL`）：允许 worker/executor 调用对应 CC 写接口，受 `ENABLE_AUTO_EXEC_*` + `cc_write_capability`（live|mock|off）+ 审计约束；mock ≠ TEST 验收。
- 禁止对超时/未知态盲重放写接口。

### 2.2 模块划分

| 模块 | 路径 | 输入 | 输出 |
|---|---|---|---|
| IMAP 拉取 | `src/worker` + `src/services/imap` | 设置页 mailbox + IMAP_LOOKBACK_DAYS | `mail_message` FETCHED + 快照/附件 | `mail_message` FETCHED + 快照/附件 |
| 解析引擎 | `src/services/parse` | mail_id | `mail_type` + `parse_result` + 新 status |
| 类型判定 | `src/services/parse/classify.ts` | subject/body/filenames | `MailType` + `type_evidence` |
| 卡派解析 | `src/services/parse/packing-list.ts` | xlsx/csv buffer | header + shipments[] |
| 状态机 | `src/services/state-machine.ts` | from/to/guard | 合法迁移或抛 `IllegalTransition` |
| CC Adapter | `src/services/cc` | 业务 DTO | CC 响应；token 缓存 |
| 确认导入 | `src/services/import` | mail_id + 勾选行 + 柜头 | `container_import` + 终态 |
| 补偿重试 | `src/services/compensation` | compensation id | 重试 SaveContainer |
| 前端 | `src/app/(ops)/*` | — | 运营 UI |

### 2.3 数据流

```
1. ImapPoller.GET_LOCK('imap_poll')
2. SEARCH SINCE N天 → 过滤已入库 UID → FETCH → 写 data/mails/{id}/raw.eml + attachments
3. INSERT mail_message status=FETCHED（幂等：message_id / folder+uid / raw_hash）
4. STORE \Seen（失败仅记日志，下轮补 Seen）
5. status→PARSING → classify + packing-list
6. NEW + valid rows≥1 → PENDING_CONFIRM；否则 PARSED / PARSE_FAILED / REJECTED_VALIDATION
7. 用户 POST /api/mails/:id/import
8. CAS: PENDING_CONFIRM→IMPORTING（version 校验）
9. GetContainerList 冲突检测 → 失败则回滚可编辑态并返回 CONFLICT
10. 按柜 SaveContainer（一柜一请求；货件=勾选行）
11. 全成功 SUCCESS；多柜部分 PARTIAL_SUCCESS；失败 FAILED + import_compensation
```

### 2.4 第三方依赖

| 依赖 | 用途 | 超时 |
|---|---|---|
| `imap.qq.com:993` | 拉取/标已读 | connect 30s / read 60s |
| `https://test.saas.carriercentral.vip/api` | CC | HTTP 60s |
| 本地 `./data` | 快照与附件 | — |
| exceljs / adm-zip | 清单解析 | 单附件 ≤20MB |

---

## 3. 数据库设计

Prisma schema 落地；下列 SQL 语义等同。字符集 `utf8mb4`，引擎 InnoDB。

### 3.1 `mail_message`

```sql
CREATE TABLE mail_message (
  id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  message_id      VARCHAR(998) NULL,
  imap_uid        BIGINT UNSIGNED NULL,
  folder          VARCHAR(64) NOT NULL DEFAULT 'INBOX',
  subject         VARCHAR(998) NOT NULL DEFAULT '(无主题)',
  from_addr       VARCHAR(320) NOT NULL DEFAULT '',
  received_at     DATETIME(3) NULL,
  body_text       MEDIUMTEXT NULL,
  mail_type       VARCHAR(32) NOT NULL DEFAULT 'UNKNOWN',
  status          VARCHAR(32) NOT NULL DEFAULT 'FETCHED',
  type_evidence   JSON NULL,
  snapshot_path   VARCHAR(512) NULL,
  raw_hash        CHAR(64) NULL,
  last_error      VARCHAR(1000) NULL,
  version         INT UNSIGNED NOT NULL DEFAULT 1,
  created_at      DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at      DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_message_id (message_id),
  UNIQUE KEY uk_folder_uid (folder, imap_uid),
  UNIQUE KEY uk_raw_hash (raw_hash),
  KEY idx_status_received (status, received_at),
  KEY idx_mail_type (mail_type)
);
```

`mail_type` 枚举值：`NEW_CONTAINER|TRANSFER|INSTRUCTION_HOLD_SPLIT|INSTRUCTION_LABEL|WORK_ORDER|UNKNOWN`  
工单关键词（贴标/拦截/拍照/转仓/快递单号）覆盖为 `WORK_ORDER`；解析产出 `parse_result.mail_record`（提单 `BL_FORECAST` / 工单表）；**本期工单不 auto-exec**。  
`status` 枚举值：PRD §6.3 全量。

### 3.2 `mail_attachment`

```sql
CREATE TABLE mail_attachment (
  id           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  mail_id      BIGINT UNSIGNED NOT NULL,
  filename     VARCHAR(512) NOT NULL,
  content_type VARCHAR(128) NULL,
  sha256       CHAR(64) NOT NULL,
  path         VARCHAR(512) NOT NULL,
  size         INT UNSIGNED NOT NULL,
  rejected     TINYINT(1) NOT NULL DEFAULT 0,
  template_id  VARCHAR(64) NULL,
  created_at   DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  KEY idx_mail (mail_id),
  CONSTRAINT fk_att_mail FOREIGN KEY (mail_id) REFERENCES mail_message(id)
);
```

### 3.3 `parse_result`

```sql
CREATE TABLE parse_result (
  id                BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  mail_id           BIGINT UNSIGNED NOT NULL,
  container_header  JSON NOT NULL,
  shipments         JSON NOT NULL,
  lineage           JSON NULL,
  created_at        DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at        DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_mail (mail_id),
  CONSTRAINT fk_parse_mail FOREIGN KEY (mail_id) REFERENCES mail_message(id)
);
```

`shipments[]` 元素契约：

```ts
{
  row_index: number;
  row_status: 'VALID' | 'INVALID';
  invalid_reasons?: string[];
  warnings?: string[]; // e.g. CHANNEL_UNMAPPED
  F_FBACode?: string;
  F_Transporter?: string;
  F_CTNS?: number;
  F_CBM?: number | null;
  F_Weight?: number | null;
  F_FBAID?: string | null;
  F_ReferenceId?: string | null;
  F_ShipmentID?: string | null;
  F_Address?: string | null;
  F_Expected_DeliveryDateB?: string | null; // YYYY-MM-DD
  F_Expected_DeliveryDateE?: string | null;
  F_Remark?: string | null;
  channel_raw?: string;
}
```

`container_header` 契约：含 `F_ContainerNo`, `container_no_valid`, `F_CabinetType`, `F_ETA`, `F_ETD`, `F_BLCopyCode`, `F_Classis`, `F_ShippingLineId`, `F_MemoRemark`, `F_Instruction`, 推荐 `F_TransMode`/`F_OperationType`。

### 3.4 `container_import`

```sql
CREATE TABLE container_import (
  id            BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  mail_id       BIGINT UNSIGNED NOT NULL,
  container_no  VARCHAR(50) NOT NULL,
  external_id   VARCHAR(64) NULL,
  request_body  MEDIUMTEXT NULL,
  response_body MEDIUMTEXT NULL,
  status        VARCHAR(32) NOT NULL, -- PENDING|IMPORTING|SUCCESS|FAILED|CONFLICT|TIMEOUT_UNKNOWN
  last_error    VARCHAR(1000) NULL,
  shipments_hash CHAR(64) NOT NULL,
  created_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  KEY idx_mail (mail_id),
  KEY idx_container (container_no),
  UNIQUE KEY uk_mail_container_shiphash (mail_id, container_no, shipments_hash),
  CONSTRAINT fk_imp_mail FOREIGN KEY (mail_id) REFERENCES mail_message(id)
);
```

活跃柜占位（应用层）：导入前插入/更新 `status IN ('IMPORTING','SUCCESS')` 同行柜号冲突检查；另建：

```sql
CREATE TABLE container_active_lock (
  container_no  VARCHAR(50) NOT NULL PRIMARY KEY,
  mail_id       BIGINT UNSIGNED NOT NULL,
  import_id     BIGINT UNSIGNED NULL,
  locked_at     DATETIME(3) NOT NULL
);
```

### 3.5 `import_compensation`

```sql
CREATE TABLE import_compensation (
  id             BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  import_id      BIGINT UNSIGNED NOT NULL,
  retry_count    INT UNSIGNED NOT NULL DEFAULT 0,
  max_retry      INT UNSIGNED NOT NULL DEFAULT 3,
  next_retry_at  DATETIME(3) NULL,
  reason         VARCHAR(64) NOT NULL,
  status         VARCHAR(32) NOT NULL DEFAULT 'OPEN', -- OPEN|DONE|EXHAUSTED
  retry_token    CHAR(36) NOT NULL,
  created_at     DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at     DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_retry_token (retry_token),
  KEY idx_open (status, next_retry_at),
  CONSTRAINT fk_comp_imp FOREIGN KEY (import_id) REFERENCES container_import(id)
);
```

### 3.6 `cc_token_cache`

```sql
CREATE TABLE cc_token_cache (
  id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  login_mark  CHAR(36) NOT NULL,
  token       VARCHAR(128) NOT NULL,
  expire_at   DATETIME(3) NOT NULL,
  updated_at  DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_login_mark (login_mark)
);
```

### 3.7 `audit_log`（**一期不做 / 表已移除**）

> 现行口径：不落库、无 Admin 查询页。以下 DDL 仅作历史参考。

### 3.7.1 （历史）`audit_log`

```sql
CREATE TABLE audit_log (
  id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  actor       VARCHAR(64) NOT NULL,
  action      VARCHAR(64) NOT NULL,
  mail_id     BIGINT UNSIGNED NULL,
  payload     JSON NULL,
  created_at  DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  KEY idx_mail_time (mail_id, created_at)
);
```

### 3.8 其余

```sql
CREATE TABLE sender_customer_map (
  id             BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  match_type     VARCHAR(32) NOT NULL, -- EMAIL|DOMAIN|SUBJECT|ATTACHMENT
  match_value    VARCHAR(320) NOT NULL,
  customer_code  VARCHAR(64) NOT NULL,
  enabled        TINYINT(1) NOT NULL DEFAULT 1,
  UNIQUE KEY uk_match (match_type, match_value)
);

CREATE TABLE app_user (
  id            BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  username      VARCHAR(64) NOT NULL UNIQUE,
  password_hash VARCHAR(128) NOT NULL,
  role          VARCHAR(16) NOT NULL DEFAULT 'ops', -- ops|admin
  created_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
);
```

---

## 4. API 设计

Base：`/api`。鉴权：未登录 → `401`。成功包络：

```ts
{ ok: true, data: T }
{ ok: false, error: { code: string, message: string, details?: unknown } }
```

### 4.1 认证

| 方法 | 路径 | 入参 | 出参 | 错误 |
|---|---|---|---|---|
| POST | `/api/auth/login` | `{username,password}` | `{role}` + Set-Cookie | `401 INVALID_CREDENTIALS` |
| POST | `/api/auth/logout` | — | `{ok:true}` | — |
| GET | `/api/auth/me` | — | `{username,role}` | `401` |

### 4.2 邮件列表

| 方法 | 路径 | 入参 | 出参 |
|---|---|---|---|
| GET | `/api/mails` | query: `page=1&pageSize=20&mail_type=&status=&q=` | `{items: MailListItem[], total}` |

`MailListItem`：`id,subject,from_addr,received_at,mail_type,status,container_no?`

错误：`400 VALIDATION`

### 4.3 邮件详情

| 方法 | 路径 | 出参 |
|---|---|---|
| GET | `/api/mails/:id` | `MailDetail`：邮件字段 + `type_evidence` + `parse_result` + `attachments[]` + `imports[]` |
| GET | `/api/mails/:id/attachments/:attId/download` | file stream |

错误：`404 NOT_FOUND`

### 4.4 确认导入

| 方法 | 路径 | 入参 | 出参 |
|---|---|---|---|
| POST | `/api/mails/:id/import` | 见下 | `{mail_status, imports[], accepted_count}` |

```ts
// body
{
  version: number;
  idempotency_key: string; // mail_id:container_no:shipments_hash 或整单 UUID
  F_TransMode: 0|1|3;
  F_OperationType: 0|2|4;
  container_header: { /* 可覆盖字段 */ };
  selected_row_indexes: number[];
  ack_unmapped_channels?: boolean;
  force_skip_conflict?: boolean; // 需 admin + ENABLE_FORCE_IMPORT
}
```

| 错误码 | 含义 |
|---|---|
| `409 ALREADY_IMPORTING` | CAS 失败 |
| `409 VERSION_CONFLICT` | version 不匹配 |
| `400 ACK_UNMAPPED_REQUIRED` | 未确认未映射渠道 |
| `409 CONFLICT_CONTAINER` | GetContainerList / 本地锁冲突 |
| `503 CONFLICT_CHECK_FAILED` | 列表接口失败且未强跳 |
| `429 RATE_LIMITED` | >10/min |
| `403 FORBIDDEN` | 非 NEW / 无权限强跳 |
| `400 INVALID_ROWS` | 勾选含 INVALID |

限流：每用户 10 次/分钟（内存滑动窗或 DB）。

### 4.5 Admin 改类型

| 方法 | 路径 | 入参 | 条件 |
|---|---|---|---|
| POST | `/api/mails/:id/type` | `{version, mail_type, reason}` | `role=admin` 且 `ENABLE_TYPE_OVERRIDE=true` |

成功：更新 `mail_type`；若 NEW 且 valid≥1 → `PENDING_CONFIRM`；写 `audit_log action=TYPE_OVERRIDE`。  
错误：`403` / `409 MAIL_BUSY` / `409 VERSION_CONFLICT` / `409 IMMUTABLE_STATUS`

### 4.6 重新解析

| 方法 | 路径 | 条件 |
|---|---|---|
| POST | `/api/mails/:id/reparse` | status ∉ `IMPORTING|SUCCESS|PARTIAL_SUCCESS` |

行为：status→`PARSING`；worker 或 web 内同步调用 `ParsePipeline`（一期 **web 同步执行解析** 亦可；生产可投递 DB 标志位由 worker 捞——**一期锁定：API 进程内直接跑 ParsePipeline**，与 worker 共用 `src/services/parse`）。  
错误：`409 ILLEGAL_TRANSITION`

### 4.7 补偿重试

| 方法 | 路径 | 入参 |
|---|---|---|
| GET | `/api/imports` | `page,status,mail_id` |
| POST | `/api/imports/:importId/retry` | `{retry_token?}` |
| POST | `/api/compensations/:id/retry` | — admin 可重置 exhausted |

行为：锁 `container_import`；SUCCESS 跳过；核对超时单；再 SaveContainer。  
错误：`409` / `400 EXHAUSTED`

### 4.8 忽略邮件

| 方法 | 路径 |
|---|---|
| POST | `/api/mails/:id/ignore` | admin → `IGNORED` + audit |

### 4.9 健康检查

| GET `/api/health` | `{mysql:ok, imap_lock?:string}` | 无鉴权 |

---

## 5. 项目工程结构

```
email-forecast/
├── docker-compose.yml          # web + worker + mysql
├── Dockerfile                  # 同一镜像，不同 CMD
├── .env.example
├── package.json                # pnpm workspaces 可不用，单 package
├── prisma/
│   ├── schema.prisma
│   └── seed.ts                 # 仅 AppUser（admin/ops）
├── data/                       # volume 挂载（gitignore）
├── docx/                       # 需求/设计（已有，不进镜像必填）
├── src/
│   ├── app/
│   │   ├── (auth)/login/page.tsx
│   │   ├── (ops)/
│   │   │   ├── layout.tsx
│   │   │   ├── mails/page.tsx              # 列表
│   │   │   ├── mails/[id]/page.tsx         # 详情
│   │   │   ├── mails/[id]/import/page.tsx  # 确认导入
│   │   │   └── imports/page.tsx            # 日志/补偿
│   │   ├── api/...                         # Route Handlers
│   │   └── layout.tsx
│   ├── components/
│   │   ├── MailTable.tsx
│   │   ├── ShipmentVirtualTable.tsx        # antd + tanstack virtual
│   │   └── StatusTag.tsx
│   ├── services/
│   │   ├── db.ts                           # PrismaClient 单例
│   │   ├── state-machine.ts
│   │   ├── imap/
│   │   │   ├── client.ts
│   │   │   └── poller.ts
│   │   ├── parse/
│   │   │   ├── pipeline.ts
│   │   │   ├── classify.ts
│   │   │   ├── packing-list.ts
│   │   │   └── channel-map.ts
│   │   ├── cc/
│   │   │   ├── http.ts
│   │   │   ├── auth.ts                     # token DB+memory
│   │   │   ├── save-container.ts
│   │   │   └── conflict.ts
│   │   ├── import/
│   │   │   ├── confirm.ts
│   │   │   └── compensation.ts
│   │   └── audit.ts
│   ├── types/
│   │   ├── mail.ts                         # MailStatus, MailType
│   │   ├── parse.ts
│   │   └── cc.ts
│   ├── utils/
│   │   ├── hash.ts
│   │   ├── iso6346.ts
│   │   └── dates.ts                        # Asia/Shanghai
│   └── worker/
│       └── index.ts                        # setInterval 入口
├── tests/
│   ├── unit/
│   └── e2e/
└── README.md
```

### docker-compose 对应

| 服务 | 镜像/构建 | 命令 | 职责 |
|---|---|---|---|
| `mysql` | `mysql:8.0` | 官方入口 | 库 `email_forecast` |
| `web` | 本 Dockerfile | `pnpm start`（`next start`） | UI + `/api` + 导入/CC |
| `worker` | 同镜像 | `node dist/worker/index.js` 或 `tsx src/worker/index.ts` | 仅 IMAP+解析+PARSING 回收 |

共享：`./data` volume、同一 `DATABASE_URL`、同一代码树 `src/services/*`。

`.env` 键名严格对齐 PRD §9.1：`CC_SAAS_HEADER`、`POLL_INTERVAL_MS`、`ENABLE_TYPE_OVERRIDE` 等。  
Worker 轮询基线优先读 `imap_settings.poll_interval_ms`（设置页，默认 30min）；过滤规则见 `imap_filter_rule`；每封写 `imap_pull_log`（≤1000）。

---

## 6. MVP 实现路径（PRD §10）

| 里程碑 | 任务拆分（可直接建 Jira） | DoD |
|---|---|---|
| **M0** | 初始化 Next15+Prisma+Antd；`docker-compose.yml`；`.env.example`；`/api/health`；登录页壳 | `docker compose up` 打开登录页；migrate 成功 |
| **M1** | Prisma 全表；`seed.ts` 写入 M1–M4 元数据；列表+详情只读；状态/类型 Tag | 列表 4 条；类型与金样例一致 |
| **M2** | `classify.ts` 规则；`packing-list.ts` 吃邮件2 xlsx；详情展示 327 行虚拟表；种子挂附件路径 | shipments 行数=327；核心列断言通过 vitest |
| **M3** | `CcAdapter` login/token；SaveContainer mock 单测；可选 TEST 烟雾脚本 `scripts/cc-smoke.ts` | mock `code=200`；TEST 有账号则 1 柜成功 |
| **M4** | 确认导入页；CAS+幂等；冲突检测；补偿表+重试 API；Admin 改类型 | 勾选 2 行 → payload 2 货件；冲突阻断；双击不双写 |
| **M5** | GetShippingLineList 下拉；`/logs` 导入+拉取；README；回收定时；**无审计页** | 可演示全流程 | 可演示全流程 |

**Cursor 编码顺序：** 严格 M0→M5；每里程碑只改该阶段文件。

---

## 7. 风险与工程约束

| 项 | 约束 |
|---|---|
| 附件 | 单文件 ≤20MB；zip 只解一层；路径禁止 `..`；落盘 `data/mails/{mailId}/` |
| IMAP 锁 | 每轮 `SELECT GET_LOCK('imap_poll',0)`；`finally RELEASE_LOCK`；拿不到锁直接 `return` |
| Token | 读路径：DB `expire_at` 权威 → 内存缓存；写路径：`GET_LOCK('cc_login',5)` 后 login 写 DB |
| 虚拟滚动 | `ShipmentVirtualTable` 固定行高 48px；只渲染可视区±10 行；禁止 Antd Table 默认全量 DOM |
| CC 超时 | 禁止盲重放；`TIMEOUT_UNKNOWN` → 补偿 + GetContainerList 核对 |
| 状态机 | 仅 `state-machine.ts` 允许改 `status`；API 禁止通用 PATCH status |
| 韧性条文 | 实现错误处理对照 `docx/异常场景与系统韧性设计.md` 全文 |

---

## 8. 核心模块 I/O 契约（Cursor 直接实现）

### 8.1 `ParsePipeline.run(mailId: bigint)`

- 读 `mail_message` + attachments  
- 写：`type_evidence`, `mail_type`, `parse_result`, `status`, `last_error`  
- 副作用：无 CC 调用  

### 8.2 `ImapPoller.tick()`

- 锁 → fetch → upsert mail → seen → 对每个新 id 调 `ParsePipeline`  
- 另：回收 `PARSING` 超时、`IMPORTING` 超时扫描（只改状态/写补偿，不调 CC）  

### 8.3 `ConfirmImport.execute(input)`

- 校验 NEW + version + 勾选  
- CAS status  
- conflict check  
- 逐柜 `SaveContainer`  
- 更新 mail 终态 + audit  

### 8.4 `CcAuth.getToken()`

- 返回 `{token, loginMark}`；410 路径由 `CcHttpClient.request` 触发 `refresh+replay once`

---

## 9. docker-compose 骨架（落地原文）

```yaml
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: email_forecast
      MYSQL_USER: app
      MYSQL_PASSWORD: app
      MYSQL_ROOT_PASSWORD: root
    ports: ["7023:3306"]  # 本地避让宿主机 3306
    volumes: ["mysql_data:/var/lib/mysql"]
    command: ["--default-authentication-plugin=mysql_native_password","--character-set-server=utf8mb4"]
  web:
    build: .
    command: ["pnpm","start"]
    ports: ["3100:3100"]
    env_file: [.env]
    volumes: ["./data:/app/data"]
    depends_on: [mysql]
  worker:
    build: .
    command: ["node","dist/worker/index.js"]
    env_file: [.env]
    volumes: ["./data:/app/data"]
    depends_on: [mysql]
volumes:
  mysql_data:
```

---

## 10. 文档索引

| 文档 | 路径 |
|---|---|
| PRD | `docx/需求规格-邮件自动预报-v0.2.md` |
| 韧性 | `docx/异常场景与系统韧性设计.md` |
| 本设计 | `docx/技术设计方案-邮件自动预报-v1.0.md` |
| 实施计划 | `.cursor/rules/implementation-plan.mdc` |

---

## 附录 A — CC Write API 矩阵（一期扩范围）

| capability id | 默认 mode | 拟定 endpoint | 触发 mail_type | 完成标准 |
|---|---|---|---|---|
| `save_container` | live | `/Container/SaveContainer` | NEW_CONTAINER（人工确认） | 已有 |
| `transfer` | mock | `/Container/TransferWarehouse` | TRANSFER | live 真接通 + 烟雾 1 次 |
| `hold_split` | mock | `/Container/HoldSplitInstruction` | INSTRUCTION_HOLD_SPLIT | 同上 |
| `label` | mock | `/Container/ApplyLabelInstruction` | INSTRUCTION_LABEL | 同上 |

表 `cc_write_capability` 可改 mode：`live|mock|off`。`CC_MOCK=true` 时全局按 mock。mock ≠ TEST 验收。