wxsales/demo/2-impl.md

微信营销管理系统 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 名销售

验证命令：

/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 参数控制生成数量

验证命令：

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 过滤）

验证命令：

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）

验证命令：

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
• 端到端验证

验证命令：

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 幂等

测试执行命令

# 数据库测试
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 全部通过