wxsales/demo/0-req.md

微信营销管理系统 MVP 需求规格

文档日期：2026-07-14 版本：v0.1 状态：需求定义

---

一、项目背景

基于《微信营销管理系统总体设计与实施方案》和《MVP.md》，在本机构建一个可运行的演示系统，模拟"销售本地处理系统 + 中央库管理系统"的完整闭环。

MVP 核心命题：把每个销售的微信聊天采集到中央数据库，AI 分析出客户和沟通记录，成交数据手动录入，形成"沟通→成交"的证据链。

---

二、系统边界

2.1 本期范围（In Scope）

能力	说明
销售本地采集代理	模拟 3 个销售设备的采集代理，生成模拟微信数据并同步到中央库
中央数据库	PostgreSQL 存储销售、联系人、会话、消息、客户、成交 6 张核心表
客户识别分析	从联系人中筛选真实客户，推断行业、意向等级、关键需求
沟通摘要分析	对每个客户会话生成结构化摘要（阶段、异议、下一步）
成交数据录入	Web 表单手动录入成交记录，关联到客户和聊天
Web 管理后台	仪表盘、销售列表、客户列表、客户详情（含聊天记录）、成交录入
一键启动	单脚本启动数据库、模拟采集、AI 分析、Web 服务

2.2 本期不做（Out of Scope）

排除项	原因
真实微信数据库解密	MVP 用模拟数据验证闭环，不依赖真实微信
培训对练系统	第二阶段
AI 自动回复	第三阶段
多租户	MVP 单租户
实时同步	MVP 每日批量同步
复杂权限体系	MVP 按 salesperson_id 简单隔离
向量化与语义检索	MVP 不做向量搜索
对象存储	MVP 不处理多媒体文件
CRM/订单系统对接	MVP 成交数据手动录入

---

三、用户角色

角色	描述	MVP 中的体现
销售人员	业务微信的使用者	系统自动模拟 3 名销售的数据采集
销售主管	查看团队数据和客户	Web 后台的主要使用者
管理员	管理销售账号和系统配置	通过脚本或后台管理销售账号

---

四、功能需求

FR-1 销售账号管理

描述：系统维护销售人员列表，每个销售绑定一个微信号和设备标识。

需求项：

• FR-1.1 支持创建销售人员记录（姓名、团队、微信号、设备 ID）
• FR-1.2 系统预置 3 名销售用于演示
• FR-1.3 每条数据都携带 salesperson_id，实现数据隔离

验收标准：

• 可通过 SQL 或 API 创建销售记录
• 3 名预置销售数据正确写入数据库

---

FR-2 本地采集代理（模拟）

描述：模拟每台销售设备上的采集代理，生成模拟微信数据并同步到中央库。

需求项：

• FR-2.1 每个代理绑定一个 salesperson_id
• FR-2.2 生成模拟联系人（每名销售 15～30 个联系人，含 2～3 个群聊）
• FR-2.3 生成模拟会话（每名销售 10～20 个会话）
• FR-2.4 生成模拟消息（每名销售 200～500 条消息，覆盖文本/图片/语音/文件等类型）
• FR-2.5 消息内容包含预设的销售场景模板（询价、产品咨询、异议处理、成交等）
• FR-2.6 支持增量同步：多次运行只新增不重复的消息
• FR-2.7 同步时记录 last_synced_at

验收标准：

• 运行 mock_sync.py --salesperson-id 1 后，中央库中出现该销售的联系人、会话、消息
• 重复运行不产生重复消息
• 消息内容可读、类型分布合理

---

FR-3 客户识别分析

描述：从联系人中识别出真实客户，排除非客户联系人。

需求项：

• FR-3.1 对每个有超过 5 条消息的联系人执行分析
• FR-3.2 输出字段：is_customer、customer_name、industry、intent_level、key_needs、reason
• FR-3.3 intent_level 取值：high / medium / low / none
• FR-3.4 分析结果写入 customer 表
• FR-3.5 支持两种分析模式：
  • 规则模式（默认）：基于关键词和消息频率的规则引擎
  • LLM 模式（可选）：调用本地 Ollama 模型分析
• FR-3.6 已分析的联系人不重复分析（除非强制 --force）

验收标准：

• 运行分析后，customer 表中出现被识别的客户
• 非客户联系人（如广告、纯社交）不被识别为客户
• 规则模式无需外部依赖即可运行

---

FR-4 沟通摘要分析

描述：对每个识别出的客户会话生成结构化摘要。

需求项：

• FR-4.1 对 customer 表中的每个客户，取其关联会话的全部消息
• FR-4.2 输出字段：summary（文本摘要）、stage（销售阶段）、objections（异议列表）、next_action（下一步建议）
• FR-4.3 stage 取值：新线索 / 建立联系 / 需求发现 / 方案匹配 / 产品演示 / 报价 / 异议处理 / 决策推进 / 成交 / 未成交
• FR-4.4 结果写入 customer 表的 last_analysis 时间戳和扩展字段
• FR-4.5 支持规则模式和 LLM 模式

验收标准：

• 运行分析后，客户记录中出现摘要和阶段信息
• 摘要内容与模拟对话场景一致
• 阶段判断合理

---

FR-5 成交数据录入

描述：通过 Web 表单手动录入成交记录。

需求项：

• FR-5.1 提供成交录入表单：选择销售 → 选择客户 → 填写产品名称、金额、成交日期
• FR-5.2 可选填写备注
• FR-5.3 成交记录通过 contact_id 自动关联到对应的微信会话
• FR-5.4 支持查看成交列表，按销售、日期、产品筛选
• FR-5.5 成交状态默认 closed，支持 pending 和 refunded

验收标准：

• 通过 Web 表单成功录入一条成交记录
• 成交列表正确展示已录入记录
• 在客户详情页能看到关联的成交记录

---

FR-6 Web 管理后台

描述：提供 Web 界面查看数据和管理成交录入。

FR-6.1 仪表盘

• 显示总消息数、活跃客户数、本月成交金额
• 显示各销售的消息量对比
• 显示最近同步时间

FR-6.2 销售列表

• 每个销售的消息量、客户数、成交金额
• 最后同步时间
• 同步状态

FR-6.3 客户列表

• 按销售筛选
• 按意向等级筛选
• 显示客户名称、行业、意向等级、最后沟通时间
• 点击进入客户详情

FR-6.4 客户详情

• 客户基本信息（AI 识别结果：行业、意向、关键需求）
• AI 沟通摘要（阶段、异议、下一步建议）
• 完整聊天记录（时间线展示，支持分页）
• 关联的成交记录

FR-6.5 成交录入与列表

• 成交录入表单
• 成交列表（按销售、日期、产品筛选）

验收标准：

• 5 个页面均可正常访问
• 数据正确展示
• 客户详情页能看到聊天记录和成交记录
• 成交录入后列表实时更新

---

FR-7 一键启动与停止

描述：提供脚本一键启动和停止整个演示系统。

需求项：

• FR-7.1 run_demo.sh 完成以下步骤：
  1. 启动 PostgreSQL（端口 5434）
  2. 执行建库建表
  3. 运行 3 个模拟采集代理
  4. 运行 AI 分析（规则模式）
  5. 启动 FastAPI + Web 前端（端口 8770）
  6. 输出访问地址
• FR-7.2 stop_demo.sh 停止所有服务
• FR-7.3 启动脚本可重复运行（幂等）

验收标准：

• 执行 run_demo.sh 后，浏览器访问 http://127.0.0.1:8770 能看到仪表盘
• 执行 stop_demo.sh 后，所有进程停止
• 重复运行不报错

---

五、数据模型

5.1 核心表（6 张）

表名	说明	主键
salesperson	销售人员	id (SERIAL)
contact	联系人（微信好友）	id (SERIAL)，唯一约束 (salesperson_id, wx_username)
conversation	会话	id (SERIAL)
message	消息	id (BIGSERIAL)，唯一约束 (source_shard, source_table, source_local_id)
customer	客户（AI 识别）	id (SERIAL)，唯一约束 (salesperson_id, contact_id)
deal	成交记录	id (SERIAL)

5.2 关键字段补充

customer 表在 MVP.md 基础上增加分析摘要字段：

-- 沟通摘要分析结果（FR-4）
summary       TEXT,          -- 文本摘要
stage         TEXT,          -- 销售阶段
objections    TEXT[],        -- 异议列表
next_action   TEXT,          -- 下一步建议

5.3 数据隔离

所有业务表均包含 salesperson_id 外键，查询时按销售过滤。

---

六、模拟数据规格

6.0 业务背景

产品：儿童益生菌粉（主打小儿抗过敏、调节免疫、改善肠道）

销售模式：toC 微信私域销售，目标客户为宝妈/家长

产品信息：

• 产品名：益童宝儿童益生菌粉
• 规格：30 袋/盒，每袋 2g
• 零售价：298 元/盒，3 盒套餐 798 元，6 盒套餐 1499 元
• 核心卖点：丹麦进口菌株、抗过敏临床验证、0 岁以上可用、无敏配方
• 适用症状：小儿湿疹、过敏性鼻炎、食物过敏、免疫力低下、腹泻/便秘

目标客户画像：

• 宝妈，25～40 岁
• 孩子有过敏症状（湿疹、鼻炎、食物过敏）
• 关注成分安全，对"进口""临床验证"敏感
• 价格敏感度中等，更关注效果和安全性
• 决策链短（宝妈自己决定），但需要信任建立

6.1 销售人员（3 名）

ID	姓名	团队	微信号	设备 ID	人设
1	张伟	华东团队	wxid_zhangwei	macbook-zw-001	资深销售，擅长建立信任，成交率高
2	李娜	华东团队	wxid_lina	macbook-ln-002	新人销售，热情但经验不足，容易过早报价
3	王强	华南团队	wxid_wangqiang	macbook-wq-003	中等水平，擅长跟进但异议处理较弱

6.2 联系人类型分布（每名销售）

类型	数量	说明
真实客户（宝妈）	5～8	有过敏症状咨询、产品问价、成分讨论、成交等对话
潜在客户	3～5	群里加的好友，初步咨询过但未深入
非客户联系人	5～10	朋友圈点赞、代购广告、其他品牌推销、家人朋友
群聊	2～3	宝妈群、育儿交流群、过敏宝宝互助群

6.3 消息场景模板

每个真实客户对应一个预设场景：

场景	阶段	消息轮次	示例内容
湿疹宝宝咨询后成交	成交	15～25	宝妈说孩子湿疹反复 → 销售问年龄症状 → 介绍益生菌抗过敏原理 → 发临床报告截图 → 宝妈问价格 → 销售推荐3盒套餐 → 宝妈确认下单
过敏性鼻炎咨询后犹豫	异议处理	10～20	宝妈说孩子鼻炎 → 销售介绍产品 → 宝妈问有没有副作用 → 销售解释无敏配方 → 宝妈觉得价格贵 → 销售解释日均成本 → 宝妈说要和老公商量
朋友推荐来咨询	需求发现	8～15	宝妈说朋友推荐 → 问产品适不适合自己孩子 → 销售问症状 → 宝妈描述孩子情况 → 销售初步建议
长期跟进复购	建立联系	20～30	首次咨询未买 → 销售定期关心孩子情况 → 宝妈反馈吃了效果不错 → 销售推荐复购套餐 → 成交
对比竞品后选择	方案匹配	12～20	宝妈说在对比合生元 → 销售对比菌株和临床数据 → 宝妈问为什么贵 → 销售解释进口菌株差异 → 宝妈犹豫

6.4 非客户联系人场景

类型	示例消息内容
代购广告	"【韩国直邮】儿童维生素团购开始啦..."
其他品牌推销	"姐，我们新款益生菌做活动，比你现在用的便宜..."
朋友圈互动	"在吗？""你朋友圈那个是什么产品？"
家人朋友	"周末有空吗？""孩子上学怎么样了？"
群聊通知	"[群公告] 本群禁发广告..." / "有没有宝妈推荐好的儿童霜？"

6.5 消息类型分布

类型	占比	典型内容
text	~75%	文字对话
image	~10%	产品图、临床报告截图、宝宝湿疹照片、成分表
voice	~6%	宝妈发语音描述孩子症状、销售语音解释
file	~2%	产品手册 PDF、检测报告
emoji	~5%	表情包互动
link	~2%	产品详情页链接、科普文章

---

七、接口规格

7.1 采集代理同步接口

采集代理直接写 PostgreSQL，不走 HTTP。MVP 阶段简化架构。

7.2 Web API（FastAPI）

方法	路径	说明
GET	/api/dashboard	仪表盘统计数据
GET	/api/salespersons	销售列表
GET	/api/salespersons/{id}/stats	单个销售统计
GET	/api/customers	客户列表（支持 salesperson_id、intent_level 筛选）
GET	/api/customers/{id}	客户详情（含摘要）
GET	/api/customers/{id}/messages	客户聊天记录（分页）
GET	/api/customers/{id}/deals	客户关联成交
POST	/api/deals	录入成交记录
GET	/api/deals	成交列表（支持筛选）
POST	/api/analyze	触发 AI 分析（客户识别 + 沟通摘要）
GET	/api/sync/status	同步状态

---

八、非功能需求

维度	要求
运行环境	macOS（本机）
Python	3.11+
PostgreSQL	17（复用本机已安装版本）
端口	PostgreSQL 5434，Web 8770（避开现有 5433 和 8765）
启动时间	< 30 秒
模拟数据量	3 名销售，约 1000 条消息，可秒级生成
前端	单页 HTML + TailwindCSS CDN，无需构建
后端	FastAPI，单文件即可
依赖	psycopg2-binary, fastapi, uvicorn（3 个包）

---

九、技术约束

1. 不修改现有系统：不改动 /Users/freedak/Documents/Codex/2026-07-14/ni/ 下的任何文件
2. 独立数据库：使用独立数据库 wxchat_sales，不复用现有 wechat_knowledge
3. 独立端口：PostgreSQL 5434，Web 8770，不与现有服务冲突
4. 无外部依赖：规则模式不依赖 Ollama 或任何外部 API
5. 可重复运行：脚本幂等，重复运行不报错、不产生重复数据

---

十、验收标准汇总

编号	验收项	验证方式
AC-1	run_demo.sh 一键启动全部服务	执行脚本，观察输出
AC-2	浏览器访问 http://127.0.0.1:8770 看到仪表盘	手动访问
AC-3	仪表盘显示 3 名销售的数据	检查数据非零
AC-4	客户列表显示 AI 识别的客户	检查列表非空
AC-5	客户详情页显示聊天记录	检查消息时间线
AC-6	客户详情页显示 AI 摘要	检查摘要、阶段、异议字段
AC-7	成交录入表单可提交	填写并提交
AC-8	成交列表显示已录入记录	检查列表
AC-9	客户详情页显示关联成交	检查成交区域
AC-10	stop_demo.sh 停止所有服务	执行脚本，检查进程
AC-11	重复运行 run_demo.sh 不报错	执行两次
AC-12	模拟采集代理增量同步不产生重复	运行两次 mock_sync，检查消息数

---

十一、后续演进

MVP 演示验证通过后的演进路径（不在本期范围）：

1. 接入真实微信数据：将 mock_sync 替换为真实的数据库采集代理
2. 接入 LLM 分析：将规则引擎替换为 Ollama 本地模型
3. 小时级同步：从每日批量改为小时级增量
4. 权限体系：增加登录认证和 RBAC
5. 向量检索：接入 pgvector 做语义搜索
6. 培训对练：按总体方案第二阶段实施