# 邮件自动预报系统

Next.js 15 + Prisma + MySQL 8 + Ant Design 5 + Worker（IMAP 轮询）。

## 快速开始

```bash
# Windows 一键（推荐 local，不拉 node 镜像）
#   .\docs\start-system.ps1
#   或 docs\start-system.cmd
# 全量 compose（需 Docker Hub）：.\docs\start-system.ps1 -Mode compose

# 1. 依赖
pnpm install

# 2. 环境
cp .env.example .env
# 本地默认 MySQL 映射 7023（避免与宿主机 3306 冲突）
# DATABASE_URL=mysql://app:app@localhost:7023/email_forecast
# CC_MOCK=true  # 无 CC 账号时开 mock

# 3. 数据库
docker compose up -d mysql
pnpm exec prisma db push
pnpm db:seed          # 仅账号 admin/ops

# 4. Web + Worker（本地联调推荐；Worker 与系统一起起，才有自动拉取）
pnpm dev:stack
# 等价：pnpm dev 与 pnpm worker 同开
# http://localhost:3100  账号 admin/admin123 或 ops/ops123
# Windows 一键（mysql + web + worker）：.\docs\start-system.ps1

# 4b. 仅 Web（不拉 IMAP）
pnpm dev

# 4c. 生产形态三件套（mysql + web + worker）
# 需已有 .env；首次会 db push + seed 账号（SEED_ON_START=true）
pnpm compose:up
pnpm compose:ps          # 确认 web/worker/mysql 均为 running
# pnpm compose:logs
# 本机已用 pnpm dev 时，可只补 worker 容器：pnpm compose:up:core

# 5. IMAP 邮箱绑定（推荐：Web 设置页，无需改代码）
#    Admin 登录 → 设置 → 新增绑定（填对方邮箱 + QQ 授权码）→ 测试连接
#    兼容回退：仍可在 .env 填 IMAP_USER / IMAP_PASS
pnpm imap:smoke   # 仅连通（.env 回退）
pnpm imap:poll    # 拉取一轮（优先 DB 绑定）
pnpm worker       # 常驻轮询
# Admin 顶栏也可点「立即拉取」
```

## 架构

| 进程 | 职责 |
|---|---|
| `web` | UI + `/api/*` + ConfirmImport / SaveContainer + **设置/邮箱绑定** |
| `worker` | 仅 IMAP 拉取（读 `mailbox_account`）+ ParsePipeline + 超时回收 + 补偿 due + retention；**禁止**调 SaveContainer |
| `mysql` | 业务库 `email_forecast` |

> 本地只起 `pnpm dev` + mysql 时 **不会**自动拉信/回收。联调请用 `pnpm dev:stack`、`.\docs\start-system.ps1`，或 `docker compose up` 三件套。

## 邮件来源

列表数据仅来自 **IMAP 拉取**（设置页绑定邮箱）。开发种子 / 样例导入 / 旧 Demo 应用已移除。

## 路由

- `/login` `/mails` `/mails/[id]` `/mails/[id]/confirm` `/logs`（导入日志 / 拉取记录） `/settings`（Admin）

## 测试

```bash
pnpm test          # vitest 单元/集成
pnpm test:e2e      # playwright（需先起 dev）

# CC
pnpm cc:smoke                    # 跟随 .env（默认 mock 假成功，非 TEST 验收）
pnpm cc:smoke -- --mode=mock     # 强制 mock
pnpm cc:smoke -- --mode=live     # TEST 真烟雾：需 CC_MOCK=false + CC_USERNAME + 密码
pnpm retention:cleanup           # 按 DATA_RETENTION_DAYS 清理（可加 --dry-run）
pnpm retention:cleanup -- --dry-run
```

### CC mock vs live（一期验收）

| 模式 | 条件 | 含义 |
|---|---|---|
| **mock** | 设置页 Mock 开，或 `.env CC_MOCK=true` | SaveContainer/冲突/船司走内存假数据；**不算** PRD TEST 烟雾 |
| **live** | 设置页关 Mock + 用户名/密码（或 `.env`） | 真打 `test.saas...`：`customerLogin` → 冲突/船司/`SaveContainer` |

配置入口：**设置 → CarrierCentral（CC）连接**（Admin）。DB 配置优先于 `.env`，保存后立即生效。

PDF《carriercentral 客户端通用接口》只定义路径与字段；**不能替代租户账号**。无 `customerLogin` token 无法 SaveContainer。

顶栏 / `GET /api/health` 会暴露 `cc_mode` / `cc_live_ready`，避免误把 mock 当验收。

## 文档

- **协作入口（给接手同事）**：`docs/邮箱项目.md`
- PRD：`docx/需求规格-邮件自动预报-v0.2.md`
- 技术设计：`docx/技术设计方案-邮件自动预报-v1.0.md`
- UI/UX：`docx/产品UI-UX设计方案-邮件自动预报-v1.0.md`
- 韧性：`docx/异常场景与系统韧性设计.md`
- 运营 SOP：`docx/运营SOP-邮件自动预报.md`