freedakgmail
5926c73ff1
- 数据库: PostgreSQL schema + 3名销售/21客户/341消息/6成交 - 采集代理: mock_sync.py 模拟微信聊天同步 - AI分析: analyze.py 规则模式 + 千问LLM模式 - 后端: FastAPI 11个API接口 - 前端: 仪表盘/销售列表/客户列表/成交记录/交流分析/录入成交 - 交流分析: 全部客户对话概览 + LLM标准范式对话生成 - 部署: systemd + nginx, 已部署至 sale.all8ai.top
321 lines
9.5 KiB
Markdown
321 lines
9.5 KiB
Markdown
# 微信营销管理系统 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 全部通过 |
|