|
|
# 邮件自动预报系统
|
|
|
|
|
|
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
|
|
|
docker compose up -d mysql
|
|
|
pnpm exec prisma db push # 含 trace_id 列时需推一次
|
|
|
pnpm test:all # 一条命令：vitest + 覆盖率（coverage/）
|
|
|
pnpm test # 仅 vitest（含 integration，需 MySQL）
|
|
|
pnpm test:e2e # playwright（需先起 dev）
|
|
|
pnpm test:e2e:test-mode # TEST_MODE Playwright（端口 3110）
|
|
|
```
|
|
|
|
|
|
覆盖率报告：`coverage/coverage-summary.json` 与终端 `text-summary`。
|
|
|
|
|
|
TEST_MODE=1 时可用 `/test-workbench` 注入样例、切故障、看 Mock 请求。
|
|
|
|
|
|
生产告警：配置 `ALERT_WEBHOOK_URL` 后，IMAP 连续失败 ≥3 或 CC 鉴权/登录失败会 POST JSON（15 分钟去重）。未配置时只写日志。
|
|
|
|
|
|
### 已知问题与建议
|
|
|
|
|
|
| 项 | 现状 | 建议 |
|
|
|
|---|---|---|
|
|
|
| 关键字未命中 | `IGNORED` / `SKIP_FILTER`，不进业务列表 | 属过滤设计；已拉取但分类 `UNKNOWN` 会以 `PARSED` 出现在列表供人工处理 |
|
|
|
| IMAP SEARCH/FETCH | 瞬时超时会重试 3 次；鉴权失败不重试（走连续失败退避） | 保持 |
|
|
|
| `markSeen` | 处理失败且尚未落库时不再标已读，便于 lookback 重试 | 已按 UID 入库的仍标已读（DB 幂等） |
|
|
|
| 部分成功（CC 对象 data） | 仍作 `TIMEOUT_UNKNOWN` 进补偿 | 与「缺 external id」同路径，避免误标成功 |
|
|
|
| 工单/DO/转仓 5xx | 邮件 `FAILED`，未统一进预报补偿表 | 一键可从详情重试；若要对齐预报补偿可再抽公共队列 |
|
|
|
| 既有单测漂移 | `mail-intent` / `extract-header` / `four-business` / `work-order-dedupe` 4 项与当前解析文案/字段不一致 | 与本次可观测性无关；建议单独立项对齐 expected |
|
|
|
|
|
|
```bash
|
|
|
# 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`
|
