# 微信营销管理系统 MVP 实施计划

> 文档日期：2026-07-14
> 版本：v0.1
> 依赖：0-req.md, 1-design.md

---

## 一、实施阶段

### 阶段 1：数据库与基础设施

**目标**：启动独立 PostgreSQL，建表，预置销售数据。

**产出文件**：
- `demo/db/schema.sql` — 完整建表 SQL
- `demo/db/init_db.sh` — 数据库启动与初始化脚本
- `demo/requirements.txt` — Python 依赖

**任务清单**：
- [ ] 编写 `schema.sql`（6 张表 + 索引）
- [ ] 编写 `init_db.sh`（启动 PG 5434 → 建库 → 建表 → 插入 3 名销售）
- [ ] 编写 `requirements.txt`
- [ ] 验证：执行 `init_db.sh` 后，`psql` 能查到 3 名销售

**验证命令**：
```bash
/usr/local/opt/postgresql@17/bin/psql -h demo/db/socket -p 5434 -d wxchat_sales -c "SELECT * FROM salesperson;"
```

---

### 阶段 2：模拟采集代理

**目标**：3 个模拟代理生成微信数据并写入中央库。

**产出文件**：
- `demo/agent/mock_sync.py` — 模拟采集代理

**任务清单**：
- [ ] 定义 5 个销售场景模板（询价成交、犹豫、咨询、长期跟进、竞品对比）
- [ ] 定义非客户联系人模板（广告、社交、群聊）
- [ ] 实现 `generate_contacts()` — 每销售 15～30 个联系人
- [ ] 实现 `generate_conversations()` — 每销售 10～20 个会话
- [ ] 实现 `generate_messages()` — 基于场景模板生成消息
- [ ] 实现 `sync_to_central()` — 批量写入 PG
- [ ] 实现增量同步（递增 source_local_id）
- [ ] 支持 `--salesperson-id` 参数
- [ ] 支持 `--batch` 参数控制生成数量

**验证命令**：
```bash
python demo/agent/mock_sync.py --salesperson-id 1
python demo/agent/mock_sync.py --salesperson-id 2
python demo/agent/mock_sync.py --salesperson-id 3
# 检查数据
psql ... -c "SELECT salesperson_id, count(*) FROM message GROUP BY salesperson_id;"
# 再次运行验证增量
python demo/agent/mock_sync.py --salesperson-id 1
psql ... -c "SELECT count(*) FROM message WHERE salesperson_id=1;"
# 消息数应增加
```

---

### 阶段 3：AI 分析服务

**目标**：规则引擎实现客户识别和沟通摘要。

**产出文件**：
- `demo/ai/analyze.py` — AI 分析服务

**任务清单**：
- [ ] 实现客户识别规则引擎
  - 消息数量过滤
  - 关键词匹配（价格词、产品词、合作词）
  - 行业推断
  - 意向等级判断
- [ ] 实现沟通摘要规则引擎
  - 阶段判断
  - 异议提取
  - 摘要生成
  - 下一步建议
- [ ] 支持 `--mode rule|llm` 参数
- [ ] 支持 `--force` 强制重新分析
- [ ] 已分析客户跳过（`last_analysis IS NULL` 过滤）

**验证命令**：
```bash
python demo/ai/analyze.py --mode rule
# 检查客户表
psql ... -c "SELECT customer_name, industry, intent_level, stage FROM customer;"
# 应有客户记录，非客户不在其中
```

---

### 阶段 4：Web 后端

**目标**：FastAPI 提供全部 API 接口。

**产出文件**：
- `demo/web/server.py` — FastAPI 后端

**任务清单**：
- [ ] 实现 DB 连接池
- [ ] 实现 `/api/dashboard`
- [ ] 实现 `/api/salespersons`
- [ ] 实现 `/api/customers`（支持筛选）
- [ ] 实现 `/api/customers/{id}`
- [ ] 实现 `/api/customers/{id}/messages`（分页）
- [ ] 实现 `/api/customers/{id}/deals`
- [ ] 实现 `POST /api/deals`
- [ ] 实现 `/api/deals`（支持筛选）
- [ ] 实现 `POST /api/analyze`
- [ ] 实现 `/api/sync/status`
- [ ] 静态文件托管（`/` → `web/static/index.html`）

**验证命令**：
```bash
uvicorn demo.web.server:app --port 8770 &
curl http://127.0.0.1:8770/api/dashboard | python -m json.tool
curl http://127.0.0.1:8770/api/customers | python -m json.tool
curl -X POST http://127.0.0.1:8770/api/deals \
  -H "Content-Type: application/json" \
  -d '{"salesperson_id":1,"customer_id":1,"product_name":"收银系统","amount":12000,"deal_date":"2026-07-14"}'
```

---

### 阶段 5：Web 前端

**目标**：单页 HTML 实现 5 个页面。

**产出文件**：
- `demo/web/static/index.html` — 单页前端

**任务清单**：
- [ ] 页面骨架 + TailwindCSS CDN + 导航栏
- [ ] 仪表盘面板（统计卡片 + 销售对比图）
- [ ] 销售列表面板
- [ ] 客户列表面板（筛选 + 列表）
- [ ] 客户详情面板（基本信息 + 摘要 + 聊天时间线 + 成交记录）
- [ ] 成交录入表单
- [ ] 成交列表面板
- [ ] SPA 路由切换（hash 或手动切换）
- [ ] API 调用封装
- [ ] 错误提示

**验证方式**：
- 浏览器访问 `http://127.0.0.1:8770`
- 逐个页面检查数据展示
- 录入一条成交，检查列表和客户详情

---

### 阶段 6：一键启动与集成

**目标**：`run_demo.sh` 一键启动全部服务。

**产出文件**：
- `demo/run_demo.sh` — 一键启动
- `demo/stop_demo.sh` — 一键停止
- `demo/README.md` — 项目说明

**任务清单**：
- [ ] 编写 `run_demo.sh`
  - 检查 PG 17
  - 启动 PG 5434
  - 建库建表
  - 运行 3 个 mock_sync
  - 运行 analyze
  - 启动 uvicorn 后台
  - 输出访问地址
- [ ] 编写 `stop_demo.sh`
  - 停止 uvicorn
  - 停止 PG
- [ ] 编写 `README.md`
- [ ] 端到端验证

**验证命令**：
```bash
cd demo && bash run_demo.sh
# 浏览器访问 http://127.0.0.1:8770
bash stop_demo.sh
# 再次运行验证幂等
bash run_demo.sh
```

---

## 二、依赖清单

### Python 包

```
psycopg2-binary>=2.9
fastapi>=0.111
uvicorn>=0.30
```

### 系统依赖

- PostgreSQL 17（本机已安装于 `/usr/local/opt/postgresql@17/`）
- Python 3.11+
- macOS（launchd、pg_ctl 等）

### 可选依赖

- Ollama + qwen2.5（LLM 分析模式，非必需）

---

## 三、风险与对策

| 风险 | 影响 | 对策 |
|---|---|---|
| PG 5434 端口被占用 | 启动失败 | 脚本检测并提示 |
| psycopg2 安装失败 | 无法连接 DB | 使用 psycopg2-binary 避免编译 |
| 模拟数据不够真实 | 演示效果差 | 场景模板覆盖 5 种典型销售对话 |
| 规则引擎误判 | 客户识别不准 | MVP 可接受，后续替换为 LLM |
| 前端无框架 | 代码维护性差 | MVP 可接受，后续可迁移到 React |

---

## 三点五、测试计划

### 测试分层

| 层级 | 范围 | 方式 | 产出文件 |
|---|---|---|---|
| 数据库层 | 建表、约束、索引 | SQL 验证脚本 | `demo/tests/test_db.sql` |
| 采集代理层 | 联系人/消息生成、增量同步、去重 | Python 单元测试 | `demo/tests/test_mock_sync.py` |
| AI 分析层 | 客户识别准确率、阶段判断、异议提取 | Python 单元测试 | `demo/tests/test_analyze.py` |
| API 层 | 全部 11 个接口的输入输出 | Python HTTP 测试 | `demo/tests/test_api.py` |
| 端到端 | run_demo.sh → 浏览器 → 成交录入 | Shell 脚本 + curl | `demo/tests/test_e2e.sh` |

### 各阶段测试任务

#### 阶段 1 测试（数据库）

- [ ] 执行 `test_db.sql` 验证 6 张表存在
- [ ] 验证唯一约束生效（插入重复数据应失败）
- [ ] 验证外键约束生效
- [ ] 验证 3 名预置销售数据正确

#### 阶段 2 测试（采集代理）

- [ ] 运行 mock_sync 后联系人数量在预期范围
- [ ] 运行 mock_sync 后消息数量 > 0
- [ ] 重复运行 mock_sync 不产生重复消息（增量同步）
- [ ] 消息类型分布合理（text 占比最高）
- [ ] 非客户联系人的消息不含业务关键词

#### 阶段 3 测试（AI 分析）

- [ ] 真实客户被正确识别（is_customer=true）
- [ ] 非客户不被识别为客户（广告/社交/家人）
- [ ] 意向等级判断合理（成交场景=high，犹豫场景=medium）
- [ ] 销售阶段判断合理（成交场景=成交，犹豫场景=异议处理）
- [ ] 异议提取包含"贵""考虑""商量"等关键词
- [ ] 重复运行不重复分析（last_analysis 过滤）

#### 阶段 4 测试（API）

- [ ] `GET /api/dashboard` 返回非空统计数据
- [ ] `GET /api/customers` 返回客户列表
- [ ] `GET /api/customers?intent_level=high` 筛选正确
- [ ] `GET /api/customers/{id}` 返回客户详情含摘要
- [ ] `GET /api/customers/{id}/messages` 返回聊天记录
- [ ] `POST /api/deals` 成功创建成交记录
- [ ] `GET /api/deals` 返回成交列表
- [ ] `POST /api/analyze` 触发分析并返回统计

#### 阶段 6 测试（端到端）

- [ ] `run_demo.sh` 执行无报错
- [ ] `curl http://127.0.0.1:8770/api/dashboard` 返回 200
- [ ] `stop_demo.sh` 停止所有进程
- [ ] 重复运行 `run_demo.sh` 幂等

### 测试执行命令

```bash
# 数据库测试
psql -h demo/db/socket -p 5434 -d wxchat_sales -f demo/tests/test_db.sql

# Python 单元测试
python -m pytest demo/tests/ -v

# 端到端测试
bash demo/tests/test_e2e.sh
```

---

## 四、工作量估算

| 阶段 | 预计工作量 | 产出文件数 |
|---|---|---|
| 阶段 1：数据库 | 1～2 小时 | 3 个文件 |
| 阶段 2：采集代理 | 3～4 小时 | 1 个文件（大） |
| 阶段 3：AI 分析 | 2～3 小时 | 1 个文件 |
| 阶段 4：Web 后端 | 2～3 小时 | 1 个文件 |
| 阶段 5：Web 前端 | 3～4 小时 | 1 个文件（大） |
| 阶段 6：集成启动 | 1 小时 | 3 个文件 |
| **合计** | **12～17 小时** | **10 个文件** |

---

## 五、里程碑

| 里程碑 | 标志 | 验收标准 |
|---|---|---|
| M1 数据库就绪 | `init_db.sh` 成功执行 | 3 名销售在库中 |
| M2 数据采集就绪 | 3 个 mock_sync 运行完成 | 消息数 > 600 |
| M3 AI 分析就绪 | `analyze.py` 运行完成 | 客户表非空 |
| M4 API 就绪 | FastAPI 启动 | 所有 API 返回正确数据 |
| M5 前端就绪 | 浏览器可访问 | 5 个页面数据正确 |
| M6 一键启动 | `run_demo.sh` 成功 | AC-1 ～ AC-12 全部通过 |