# 平台助手 — 项目交接文档

**交接日期:** 2026-09-30
**交接对象:** 接手继续开发的智能体 / 开发者
**文档目标:** 让接手方无需历史对话即可完整了解项目现状、架构、业务逻辑、已知问题与待办事项，可直接开始开发。

---

## 1. 项目是什么

**平台助手（内部代号 pingtai）** 是面向 B2B 采购场景的智能询比价工作台：

- **采集**：自动抓取 3 家央企招标公告（中电建 / 新矿集团 / 中核集团），关键词+AI 双通道分类入库
- **线索管理**：线索列表 / 详情 / 星级评分 / 状态流转（待复核 → 询价中 → 协作中）/ 跟进日志
- **询价发布**：勾选线索一键发布到外部 B2B 产业平台（通过 MCP 通道调 `publish_rfq`），含发布前确认弹窗（补联系人/电话/地址）、物料清单 AI 提取、超长标题 AI 压缩
- **比价**：供应商报价 Excel/CSV 上传 → 自动解析 → 商品对齐去重 → 三种采购策略对比（集中/拆分/限 K 家）→ 采购建议报告 + CSV 导出
- **生图**：商品图片三阶段生成（图库 → Bing 搜索 → MiniMax AI 生成）
- **品类库**：关键词优先 + AI 反哺的品类字典（ProductCategory）
- **管理后台**：租户/用户/系统配置/计划/MCP 对接配置

**在线地址（生产）:** https://direv.cloud（Nginx → Next.js 3001 / NestJS 4000）
**演示账号:** `admin` / `admin123`（username + password，**不是 email**）

---

## 2. 技术栈与架构

| 层 | 技术 | 说明 |
|----|------|------|
| 前端 | Next.js 14 App Router + React 18 + Tailwind CSS 3 | **SPA 无路由**，useState 切换 14 个页面组件 |
| 后端 | NestJS 10 + TypeScript | 13 个子模块，端口 4000 |
| 数据库 | SQLite + Prisma ORM | `apps/api/prisma/dev.db`，15 个模型 |
| 采集脚本 | Node.js / Python | `scripts/tender-fetcher/`，CrawlerService 用 `execSync` 调度 |
| AI | MiniMax M2.7 (推理模型) | 品类分类 / 物料提取 / 标题压缩，endpoint `https://api.minimaxi.com/v1/chat/completions` |
| 外部对接 | MCP (Streamable HTTP, POST) | 集成 Integration 表 → product_network B2B 平台 |
| 部署 | 腾讯云 172.81.241.109 + PM2 + Nginx + certbot | `scripts/deploy.sh` 一键部署 |

### 架构图

```
                 ┌─────────────────────────────┐
  浏览器(3001)  ←│  Next.js 14 (pingtai-web)   │
                 └─────────────────────────────┘
                          │  /api/*
                 ┌────────▼─────────────────────┐
                 │  NestJS 10 (pingtai-api:4000) │
                 │  ├─ crawler: execSync 调脚本  │
                 │  ├─ lead:    评分/状态/发布    │
                 │  ├─ integration: MCP client   │
                 │  └─ comparison/image/...      │
                 └────────┬─────────┬───────────┘
                          │         │
              SQLite(dev.db)    MiniMax API
                          │
                 ┌────────▼─────────────────────┐
                 │  MCP server (devbox:3002/8095)│
                 │  → product_network B2B 平台   │
                 └──────────────────────────────┘
```

> ⚠️ MCP server 端口 **3002(Node)/8095(Java)** 都在 devbox 开发机上，不是本地端口。平台助手本地 web 是 **3001**、API 是 **4000**。两套 MCP server 后端数据库不同，appId/appSecret 互不通用。

---

## 3. 目录结构

```
平台助手/
├── apps/
│   ├── web/                  # Next.js 14 SPA
│   │   └── src/
│   │       ├── app/page.tsx  # SPA 根，useState<Page> 切换页面
│   │       ├── components/   # 14 个页面 + AuthProvider/Sidebar/Providers/ErrorBoundary
│   │       └── lib/apiBase.ts# API_BASE (NEXT_PUBLIC_API_URL，本地回退 localhost:4000)
│   └── api/                  # NestJS 10
│       ├── prisma/
│       │   ├── schema.prisma # 15 个模型
│       │   └── dev.db        # SQLite
│       └── src/
│           ├── admin/ audit-log/ auth/ common/ comparison/ crawler/
│           ├── image/ inquiry/ integration/ lead/ product/ product-category/
│           ├── reports/ rules/ users/ prisma/
│           └── app.module.ts / main.ts
├── packages/shared/          # 共享 TS 类型（编译型，无运行时依赖）
└── scripts/
    ├── tender-fetcher/       # fetch-v1.2.js(中电建) fetch-xkgroup.py(新矿) fetch-cnncecp.py(中核)
    ├── direv-publish/        # direv 平台发布脚本（10 个 .py，历史保留）
    ├── parse_products.py     # Excel/CSV → JSON（比价用）
    ├── search_image.py / process_image.py  # 生图辅助
    ├── backfill_category.js / clean_category.js / reclassify_leads.js 等  # 数据维护
    └── deploy.sh             # 一键部署
```

---

## 4. 开发环境搭建

```bash
npm run setup        # npm install + db:init（prisma generate → migrate → seed）
npm run dev          # 同时启动前端(3001)和后端(4000)
npm run dev:api      # 仅后端（nest start --watch，用 dist/ 编译产物）
npm run dev:web      # 仅前端
npm run db:init      # 改 schema 后必跑
npm run db:reset     # 删 db 重来
npm run build        # nest build + next build
npm run typecheck    # tsc --noEmit 所有包（无 root tsconfig，各包独立）
npm run lint
npm run dev:daemon   # nohup 后台启动（PID 写入 .dev-api.pid / .dev-web.pid）
npm run dev:stop     # kill PID 文件记录的进程
```

**端口速查（本地）:** web=3001, api=4000。⚠️ 本地 `next dev` 偶发 fallback 到 3000（3001 被 `admin_new` Vite 项目占用时），以终端实际打印为准。

### 后端陷阱

- `nest start --watch` 用 `dist/` 编译产物：Prisma schema 变更后必须 `npm run build -w apps/api` 重建 dist 再重启，单纯 `prisma generate` 不够
- 端口 4000 残留进程：`dev:stop` 只杀 PID 文件进程，多余进程 `lsof -ti:4000 | xargs kill -9`
- Prisma 变更流程：改 schema → `npm run db:init`
- 后端无测试框架

### 前端陷阱

- SPA 无路由：`page.tsx` 用 `useState<Page>` 切换，导航走 `onNavigate` prop，参数走 props
- 路径别名 `@/` → `src/`
- Prettier: noSemi, singleQuote, trailingComma: all, printWidth: 100
- Tailwind Token：`secondary(#0051d5)`, `border-subtle(#E2E8F0)`, `surface-container` 系

---

## 5. 数据库模型（15 个）

| 模型 | 用途 | 关键字段 |
|------|------|----------|
| **Lead** | 线索核心表 | title/noticeId/detailUrl/level(C-B-A)/status/star/amount/category/organization/region/regionDetail/source/contact/phone/deadline/quantity/unit/notes/aiScore/scoringDetails/publish/publishTime/inquiryNo/direvUrl/assignedTo/followLogs；`@@unique([source, noticeId])` 去重键 |
| **Rule** | 规则中心 | name/type/config(JSON)/enabled |
| **RuleVersion** | 规则版本 | ruleId/version/config/userId |
| **Report** | 报表 | title/type/status/config/channels/fileUrl |
| **AuditLog** | 审计日志 | action/detail/operator/ip |
| **CrawlerConfig** | 采集器配置 | name/targetUrl/status/type(bid_xxx)/sourceName/scriptPath/schedule(cron)/keywords/categories(JSON品类名数组)/lastRunAt/totalRuns/successRuns/failedRuns |
| **Inquiry** | 询价（历史表） | 类似 Lead，冗余保留 |
| **Product** | 供应商报价条目（比价） | name/spec/unit/price/quantity/category/brand/supplier/minOrder/imageUrl |
| **Tenant** | 租户 | companyName/plan/status/validUntil/platformUrl/apiKey |
| **User** | 用户 | email/username/password/role/tenantId |
| **GeneratedImage** | 生成图片 | productName/url/status/style/sourceHash |
| **ImageLibrary** | 图库 | productName/keyword/filePath/source(baidu)/style/ratio |
| **SystemConfig** | 系统配置 | key(unique)/value/group |
| **Integration** | MCP 对接配置 | name/endpoint/appId/apiKey(AES-256-GCM 加密)/customerCode/status/tools/companyUserId |
| **ProductCategory** | 品类字典 | name(unique)/keywords(JSON数组)/isAIGenerated |

### 种子数据（seed.ts）
- 15 电缆型号 × 5 供应商 = 75 Product + 管理用户（admin/admin123）
- crawlerConfig 3 条：中电建 + 新矿集团 + 中核集团（中核默认 paused）

---

## 6. API 端点总览

### 认证 `/api/auth`
| POST /api/auth/login | 登录（username+password，JWT 存 localStorage `auth`） |
| GET /api/auth/profile | 当前用户 |

### 线索 `/api/leads`（核心）
| GET /api/leads | 列表（query: status/level/search/star/source/category/assignedTo/timeRange + 分页） |
| GET /api/leads/stats | 统计（OverviewPage 用） |
| GET/PUT/DELETE /api/leads/:id | 详情/更新/删除 |
| POST /api/leads/:id/to-rfq, /to-collab | 状态流转：转询价 / 转协作 |
| POST /api/leads/:id/publish | **发布到 B2B 平台**，可选 body `{contactPhone?, contactName?, deliveryAddress?}` |
| POST /api/leads/batch-publish | body `{ids: string[]}`，循环调 publish |
| POST /api/leads/:id/follow-up (+ /:index/delete) | 跟进日志 |
| POST /api/leads/:id/level | 改优先级 |
| POST /api/leads/calculate-score | 重算 AI 评分 |

### 采集器 `/api/crawlers`
GET/POST/PUT /api/crawlers(:id) | CRUD
POST /api/crawlers/:id/run, /pause, /resume | 运行/暂停/恢复（联动 cron 注册）

### 比价 `/api/comparison`
GET /api/comparison | 商品分组比价数据
POST /api/comparison/upload | multipart file+supplier 上传报价
POST /api/comparison/suggestion | 生成采购建议报告

### 品类 `/api/categories`
GET/POST/PUT/DELETE | ProductCategory CRUD（InquiryPage 筛选项动态加载）

### 其他
- `/api/products` + upload-image（商品管理）
- `/api/images` generate/parse/approve/regenerate（生图）
- `/api/integrations` + :id/connect/disconnect/call-tool + test（MCP 配置）
- `/api/admin` tenants/users/plan-config/configs/stats（管理后台）
- `/api/rules` + versions/rollback
- `/api/reports` + :id/send
- `/api/inquiries` / `/api/users` / `/api/audit-logs` / `/api/health`
- `/api/lead-notes/extract/:leadId`（notes 提取）

---

## 7. 前端页面清单（14 个）

| 页面组件 | 功能 | 数据对接状态 |
|----------|------|---------------|
| LoginPage | 登录 | ✅ POST /api/auth/login |
| OverviewPage | 概览（统计卡片+线索列表） | ✅ Promise.all([leads/stats, leads]) |
| InquiryPage | 询价列表 + 筛选/搜索/星级/批量发布 + **发布前确认弹窗** | ✅ leads + publish（含弹窗传 overrides） |
| LeadDetailPage | 线索详情 + 状态流转 + 跟进日志 | ✅ leads/:id + 各流转端点 |
| ComparisonPage | 比价三步向导（上传→对比→建议） | ✅ comparison 三端点 |
| ProductPage | 商品管理 + 生图 | ✅ products + upload-image |
| ImagePage | 图片库/生成 | ✅ images |
| RuleCenterPage | 规则中心 + **采集器配置 Tab**（品类多选框） | ✅ crawlers + categories |
| ReportCenterPage | 报表 | ⚠️ 纯 mock |
| SystemMonitorPage | 系统监控 | ⚠️ 纯 mock |
| AdminPage | 管理后台（5 子区块：租户/用户/统计/configs/计划，configs 含 MCP 对接配置） | ✅ 已实现 |
| Sidebar / Providers / AuthProvider / ErrorBoundary | 框架 | — |

---

## 8. 核心业务流程

### 8.1 采集入库（crawler.service.ts）

```
CrawlerService.run(config)
  ├─ type=bid_powerchina → runPowerChina(): execSync('node fetch-v1.2.js --keyword "X"')
  ├─ type=bid_xkgroup    → runGenericScript(): execSync('python3 fetch-xkgroup.py')
  └─ 其他 bid_xxx        → runGenericScript()（脚本名从 type 推断）
      ↓
  results → categoryInference.batchInfer()  # 品类推断（关键词匹配 → 未命中走 MiniMax）
      ↓
  upsert 到 Lead（去重键 @@unique([source, noticeId])）
```

**关键词解析（resolveKeywords，最近重构）：**
1. 优先 `config.categories`（品类名数组）→ 查 ProductCategory 表把每个品类的 keywords 展开合并
2. 兜底 `config.keywords`（旧字段，直接解析）
3. 都没有 → `['']`（抓全部）

**中电建特殊处理：** 每个关键词有独立状态文件 `downloaded_<keyword>.json`（不是只有一个 downloaded.json）；结果从 `~/Desktop/招标公告/<date>/downloaded_<kw>.json` 读取。`~/desktop` 是 symlink → `/data/pingtai`（生产持久化）。

**公告 ID 提取坑：** `substr(summary, instr(summary, '公告ID:') + 6, 32)`（`+6` 而非 `+8`，字节/字符偏移曾出 bug）。

### 8.2 品类分类（品类方案 C：关键词优先 + AI 反哺）

```
采集入库/手动回填时对线索标题：
  1. 关键词匹配 ProductCategory.keywords contains 标题 → 命中直接写
  2. 未命中 → MiniMax API 分类 → 写品类 + 反写关键词到 ProductCategory
  3. 同类标题下次直接走关键词，不再调 AI
```

- 关键文件：`product-category/category-inference.service.ts`（AI 推断+反写）、`crawler.service.ts batchInfer()`、`notes-extractor.service.ts`（PDF/HTML 提取要点）
- **MiniMax 配置**：endpoint `https://api.minimaxi.com/v1/chat/completions`，model `MiniMax-M2.7`（env `MINIMAX_MODEL` 可覆盖），key 在 `apps/api/.env` 的 `MINIMAX_API_KEY`
- **⚠️ M2.7 是推理模型**：max_tokens 要够（物料提取正文 2000、标题提取 800），否则输出全被 `<think>` 吃掉；输出常混 `<think>`、`让我分析`、`**加粗**` 等解释文字，需要清洗
- 历史经验：AI 不可全信，2026-07-01 曾批量回填 507 条，结果 AI 新建 ~25 个细分类需人工 review。决策：新数据走关键词，老数据人工 review

### 8.3 发布询价到 B2B 平台（lead.service.ts publishToDirev）

```
POST /api/leads/:id/publish { contactPhone?, contactName?, deliveryAddress? }
  → publishToDirev(id, overrides)
    1. 组装 publishArgs（title/description/qty/notes/attachments/deadline/deliveryDate/contact...）
    2. 企业级硬编码字段：
       inquiryParty='郑州巨变网络科技有限公司', freightFlag=1(含运费), procurementType=1(公开采购),
       invoiceType=2(增值税专票), quotationDemand=1(需要报价), validDays=7
       ⚠️ paymentMethod 不传（传了报"企业字典找不到"）
       ⚠️ 上述 flag 必须 int，传字符串会报错（已修复过的坑）
    3. 超长标题（>50字）→ TitleCompressorService.compress() AI 压缩 → 失败硬截断兜底
    4. MaterialExtractorService.extractItems() 实时提取物料清单 items
    5. integrationService.executeTool('publish_rfq', publishArgs)（retries:2）
    6. 成功 → 更新 lead 状态（published/inquiryNo/direvUrl）；失败 → ServiceUnavailableException
```

**publishArgs 字段映射细节：**

| 字段 | 来源 | 备注 |
|------|------|------|
| title | lead.title（>50 字先 AI 压缩） | 平台 varchar(50) 限制 |
| description | lead.notes → summary → title | W31 P1 |
| qty | lead.quantity \|\| 1 | |
| notes | lead.notes | 商家报价时看到 |
| attachments | lead.attachments(JSON) \|\| [detailUrl] | |
| deadline | lead.deadline 前 10 位 | YYYY-MM-DD |
| deliveryDate | deadline + 30 天 | |
| contactName | overrides.contactName → lead.contact → '待补充' | 弹窗可编辑 |
| contactPhone | overrides.contactPhone → lead.phone → '待补充' | 必填，弹窗补全 |
| deliveryAddress | overrides.deliveryAddress → regionDetail → region | 弹窗可编辑 |
| userId/enterpriseId | Integration.companyUserId | MCP connect 时获取 |

### 8.4 MCP 集成（integration.service.ts）

- **协议**：Streamable HTTP（`StreamableHTTPClientTransport`），POST 方法
- **认证头**：`x-app-id` + `x-app-secret`（多租户 APIKey，替代旧 `x-api-key`），AES-256-GCM 加密存储（`ENCRYPT_KEY` in .env，32 bytes hex）
- **Session 管理（已实现）**：`buildSessionAwareFetch(integrationId)` 自定义 fetch wrapper——从 initialize 响应头提取 `mcp-session-id` 缓存 → 后续请求自动注入 → disconnect/重连清理
- **charset 修复（已实现）**：wrapper 检测 content-type 缺 charset 时补 `application/json; charset=utf-8`（否则 Java 解析器中文 Content-Length 不匹配报 JSON 错误）
- 17 个 MCP tool（询价5/商品4/比价4/推理4），发布调 `publish_rfq`

### 8.5 标题压缩（TitleCompressorService，新增）

- 位置：`apps/api/src/lead/title-compressor.service.ts`（已注册到 LeadModule）
- 逻辑：`compress(title, maxLength)`：
  1. `title.length <= maxLength` 直接返回（**≤50 字不调 AI**）
  2. 未配 `MINIMAX_API_KEY` → 硬截断 `title.slice(0, maxLength)`
  3. 调 MiniMax，**要求 JSON 结构化输出** `{"title":"..."}`（对抗 M2.7 多变思考噪音，行级正则过滤不可靠）
  4. `extractJsonTitle()` 正则提取 title 字段；解析不到 → 硬截断
  5. 结果仍超长 → slice 截断兜底
- max_tokens 800（400 会被明文思考耗尽导致答案截断）
- 生产验证：6 个真实标题全部压缩达标（62字→25字等）

### 8.6 比价（comparison.service.ts）

```
上传报价 (POST upload: file+supplier)
  → parse_products.py 解析 Excel/CSV → Product 入库
  → GET /api/comparison：
      按 name.trim().toLowerCase() 分组 → 组内按 supplier 去重留最低价
      → 每组算 bestPrice/bestSupplier/savings/priceSpread
  → POST /api/comparison/suggestion：
      三种策略对比：
      A. 无限制拆分（每 SKU 选最低总价供应商）
      B. 单一供应商（Σ 全 SKU 总价排名，取第 1）
      C. 限制 K 家（C(n,K) 组合枚举 + 每 SKU 取组合内最低价，K=2/3/4）
      → recommendations 自然语言建议 + CSV 导出
```

### 8.7 生图（image.service.ts）

三阶段：图库(ImageLibrary) → Bing 搜索(search_image.py) → MiniMax AI 生成；`process_image.py` 去水印+裁剪+白底合成。

---

## 9. 已知问题 / 坑（接手必读）

### 9.1 生产部署相关（⚠️ 最近出现）

1. **页面打开报"服务器内部错误" / `Failed to find Server Action`**（web 日志常见）：
   - 根因：**本地 build 的 `.next/` 直接 rsync 到生产**，生产 `node_modules` 版本与本地不一致 → Server Action ID 对不上 → 页面交互报错
   - **解决办法（AGENTS.md 明确记录）**：在生产服务器上执行 `cd /opt/pingtai/apps/web && npx next build` 重建 `.next`，再 `pm2 restart pingtai-web`
   - 若浏览器缓存旧 HTML 导致，提示用户强刷（Cmd+Shift+R）
2. **deploy.sh 不含 DB 迁移**：Prisma 变更部署前，需在生产 `apps/api/` 下手动 `npx prisma migrate deploy && npx prisma generate`，否则 schema 不同步
3. `pm2 restart` 默认不更新环境变量，需 `--update-env`（deploy.sh 已带）

### 9.2 数据质量（采集器只抓列表页）

| 字段 | 填写率(2026-07-16 生产统计 815 条) | 说明 |
|------|------|------|
| contact | 0% | 采集器未访问详情页 |
| phone | 0% | 同上 |
| quantity | 0% | 同上 |
| unit | 0% | 同上 |
| notes | 0% | 同上 |

当前应对：发布前弹窗手动补全。自动化提取（类似 notes-extractor 的详情页 AI 提取）**待实现**。

### 9.3 MiniMax / AI

- M2.7 输出噪音（`<think>`、`让我分析`、`**加粗**`）——所有 AI 调用都要清洗
- 生产 `.env` 已配 `MINIMAX_API_KEY` + `MINIMAX_MODEL`；本地 `.env` 需自行配置，否则走兜底
- 若 `MAX_COMPRESS_LEN` 等常量调整，注意 PROMPT 里 `'45'` 是字符串 replace，保持一致

### 9.4 采集器

- 中电建 state 文件 key：`systemId_招采公告`，**不要手动删除**
- 新矿集团脚本偶尔 `ReadTimeout`（日志见 Python traceback），不影响页面，重跑即可
- 新增采集器通用流程：放脚本到 `tender-fetcher/`，输出 `~/Desktop/招标公告/<date>/xxx_downloaded.json`，前端新建 CrawlerConfig（type=`bid_xxx`、sourceName、scriptPath），无需改代码
- cron 用 6 字段格式（兼容 cron@4.4.0）

### 9.5 MCP / B2B 发布

- `code:10021 "未获取到用户信息"`：产业平台修复中（创建 APIKey 已关联 companyUserId，后端直接使用）
- `paymentMethod` 传 "23" 报"企业字典找不到" → **不传**，后端用默认
- 字段类型必须是 int（freightFlag/procurementType/invoiceType），字符串会报错
- title 超 50 字已由 TitleCompressorService 前置处理

---

## 10. 当前工作区状态（未提交改动，2026-09-30）

> ⚠️ **接手第一件事：决定这些改动是否保留/提交/继续开发。**

### 已改文件（未 commit）

| 文件 | 改动内容 | 状态 |
|------|----------|------|
| `apps/api/src/lead/title-compressor.service.ts` | **新文件**：标题 AI 压缩服务（JSON 结构化输出方案） | ✅ 已实现+生产实测通过 |
| `apps/api/src/lead/lead.module.ts` | 注册 TitleCompressorService | ✅ |
| `apps/api/src/lead/lead.service.ts` | publishToDirev 集成标题压缩（>50 字先压缩再校验） | ✅ |
| `apps/api/src/crawler/crawler.service.ts` | resolveKeywords（品类→关键词展开）+ 每关键词独立状态文件 + 日志增强 | ✅ |
| `apps/web/src/components/InquiryPage.tsx` | 新增搜索框 fSearch → GET /api/leads?search= | ✅ |
| `apps/web/src/components/RuleCenterPage.tsx` | 采集器配置从 keywords 改为 **品类多选框**（categories JSON 数组） | ✅ |
| `scripts/tender-fetcher/fetch-v1.2.js` | 中电建脚本增强（过滤/回溯） | ✅ |

### 未跟踪文件

- `scripts/cleanup_garbage_categories.sql` — 清理 AI 垃圾品类
- `scripts/fix_corrupted_titles.sql` — 修复损坏标题
- `scripts/reclassify_leads.js` / `scripts/refetch_corrupted.js` — 历史数据维护
- `PRD-智能比价助手.md` — 比价功能 PRD（供外部平台参考）

### 工作区 vs 生产差异

- **本地有大量未提交改动，生产未部署**（生产 `.next/` 构建于 2026-09-03）
- 若需上线这些改动：`npm run typecheck` → `bash scripts/deploy.sh` → **生产重建 web `.next`**（见 9.1）

---

## 11. 生产部署与运维

- **服务器**：172.81.241.109（`SSH_HOST` 在 deploy.sh，如 IP 变更改这里）
- **SSH**：`sshpass -p 'Jubianshuzi@2026' ssh ubuntu@172.81.241.109`
- **一键部署**：`bash scripts/deploy.sh`（build + rsync dist/.next/源码 + pm2 restart --update-env）
- **路径**：代码 `/opt/pingtai/`，数据 `/data/pingtai/`（dev.db / uploads / library / 招标公告）
- **进程**：pm2 托管 `pingtai-api`(4000) + `pingtai-web`(3001)，systemd 自启
- **反代**：Nginx 80/443 → 3001；`/api/*` → 4000；`/uploads/*` → `/data/pingtai/uploads/`
- **HTTPS**：Let's Encrypt，certbot 自动续期 timer 已开
- **常用操作**：
  ```bash
  pm2 list / pm2 logs pingtai-api / pm2 restart pingtai-api --update-env
  tail -f /var/log/pingtai/api.out-1.log
  sqlite3 /data/pingtai/dev.db   # 直接查 DB
  tar czf pingtai-backup-$(date +%Y%m%d).tgz /data/pingtai/
  ```
- **历史包袱**：服务器上旧 Postgres/Redis 部署备份在 `/home/ubuntu/platform-assistant.bak-*`，旧 nginx conf 在 `/etc/nginx/conf.d/platform.conf.bak-*`，可回退
- **采集目录 symlink**：`~/desktop -> /data/pingtai`（必须指向 `/data/pingtai`，不是 `/data/pingtai/招标公告`，否则双层嵌套）

---

## 12. 待办事项 / 建议的下一步

1. **决策未提交改动**：title-compressor + crawler 品类化 + InquiryPage 搜索 + RuleCenterPage 品类多选框，是否继续/提交/部署
2. **修复生产页面 500**：若线上仍有 Server Action 报错，生产 `npx next build` 重建（见 9.1）
3. **详情页内容提取**（P1 数据质量）：采集器入库后加类似 notes-extractor 的 AI 提取步骤，补 contact/phone/quantity/unit（当前全缺）
4. **空品类历史线索 review**：AdminPage 品类管理人工 review AI 新建的细分类（合并/删除）
5. **ReportCenterPage / SystemMonitorPage**：仍是 mock，可接真实数据
6. **比价模块增强**（参考 PRD-智能比价助手.md）：报价有效期、供应商画像权重、多租户
7. **MCP 发布卡点跟进**：`code:10021` 等产业平台修复状态

---

## 13. 协作约定（对后续智能体）

- 语言：中文（对话/注释/文档/commit）
- **改动前必须对齐**：涉及具体修改按 AGENTS.md 协作流程（7 个技术维度：场景/触发/重要程度/数据/边界/样式/部署），不擅自开干
- 例外：拼写错误、单文件 typo、用户明确"按你判断做"、紧急 bug
- 改完必须端到端验证，不只"代码看起来对"
- 涉及数据库结构、生产配置、依赖升级要明确告知用户
- 提交信息用中文

---

**结束语：** 本项目最核心的链路是 **采集 → 分类 → 询价 → MCP 发布**，接手时建议先跑通这条链路的本地/生产实测，再动其他模块。祝顺利！