# 微信营销管理系统 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 基础上增加分析摘要字段：

```sql
-- 沟通摘要分析结果（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. **培训对练**：按总体方案第二阶段实施