wxsales/MVP.md

# 微信营销管理系统 MVP 方案

> 文档日期：2026-07-14
> 定位：最小可用产品，验证"微信聊天数据 → 客户与沟通记录 → 成交关联"的核心闭环

---

## 一、MVP 目标

用最简路径完成一件事：**把每个销售的微信聊天采集到中央数据库，AI 分析出客户和沟通记录，成交数据手动录入，形成"沟通→成交"的证据链。**

不做的事：
- 不做培训对练
- 不做 AI 自动回复
- 不做多租户
- 不做实时同步
- 不做复杂权限体系

---

## 二、MVP 范围

### 2.1 核心流程

```text
销售设备本机采集微信数据
  → 传输到中央数据库
  → AI 识别客户、提取沟通记录
  → 销售手动录入成交数据
  → 关联聊天与成交
  → 基础报表
```

### 2.2 支持规模

- 3～5 名销售
- 每人 1 个微信号
- 每日离线同步（复用现有 launchd 机制）
- 单台中央 PostgreSQL

---

## 三、系统架构

```text
销售设备 A (macOS)          销售设备 B (macOS)         销售设备 C (macOS)
  本机微信数据库采集          本机微信数据库采集          本机微信数据库采集
  采集代理脚本                采集代理脚本                采集代理脚本
        │                          │                          │
        └──────────────┬───────────┘──────────────────────────┘
                       ▼
               中央 PostgreSQL
            (wechat_sales_db)
                       │
                       ▼
               AI 分析服务
            (客户识别 + 沟通摘要)
                       │
                       ▼
               Web 管理后台
        (客户列表 / 聊天记录 / 成交录入 / 报表)
```

---

## 四、数据模型

MVP 只建 6 张核心表，不搞复杂实体关系。

### 4.1 salesperson — 销售人员

```sql
CREATE TABLE salesperson (
    id          SERIAL PRIMARY KEY,
    name        TEXT NOT NULL,
    team        TEXT,
    wx_account  TEXT NOT NULL,      -- 绑定的微信号
    device_id   TEXT,                -- 采集设备标识
    created_at  TIMESTAMPTZ DEFAULT now()
);
```

### 4.2 contact — 联系人（微信好友）

```sql
CREATE TABLE contact (
    id              SERIAL PRIMARY KEY,
    salesperson_id  INT NOT NULL REFERENCES salesperson(id),
    wx_username     TEXT NOT NULL,       -- 微信内部 ID
    nickname        TEXT,                -- 昵称
    remark          TEXT,                -- 备注
    display_name    TEXT,                -- 计算字段：备注优先，其次昵称
    is_group        BOOLEAN DEFAULT FALSE,
    created_at      TIMESTAMPTZ DEFAULT now(),
    UNIQUE(salesperson_id, wx_username)
);
```

### 4.3 conversation — 会话

```sql
CREATE TABLE conversation (
    id              SERIAL PRIMARY KEY,
    salesperson_id  INT NOT NULL REFERENCES salesperson(id),
    contact_id      INT REFERENCES contact(id),
    wx_chatroom     TEXT,            -- 群聊标识（群聊时用）
    conv_type       TEXT NOT NULL,   -- 'single' | 'group'
    last_synced_at  TIMESTAMPTZ,
    created_at      TIMESTAMPTZ DEFAULT now()
);
```

### 4.4 message — 消息

```sql
CREATE TABLE message (
    id                  BIGSERIAL PRIMARY KEY,
    salesperson_id      INT NOT NULL REFERENCES salesperson(id),
    conversation_id     INT NOT NULL REFERENCES conversation(id),
    sender_wx_username  TEXT NOT NULL,
    sender_display_name TEXT,
    message_type        TEXT NOT NULL,       -- text/image/voice/video/file/emoji/link/quote
    raw_content         TEXT,
    normalized_content  TEXT,                -- 清洗后可读内容
    created_at          TIMESTAMPTZ NOT NULL,
    source_shard        TEXT,
    source_table        TEXT,
    source_local_id     BIGINT,
    UNIQUE(source_shard, source_table, source_local_id)
);
CREATE INDEX idx_message_conv_time ON message(conversation_id, created_at);
CREATE INDEX idx_message_salesperson ON message(salesperson_id);
```

### 4.5 customer — 客户（AI 从联系人中识别）

```sql
CREATE TABLE customer (
    id              SERIAL PRIMARY KEY,
    salesperson_id  INT NOT NULL REFERENCES salesperson(id),
    contact_id      INT NOT NULL REFERENCES contact(id),
    customer_name   TEXT,                -- AI 识别的客户名称
    industry        TEXT,                -- AI 推断行业
    intent_level    TEXT,                -- high/medium/low/none
    key_needs       TEXT[],              -- AI 提取的关键需求
    last_analysis   TIMESTAMPTZ,
    created_at      TIMESTAMPTZ DEFAULT now(),
    UNIQUE(salesperson_id, contact_id)
);
```

### 4.6 deal — 成交记录（手动录入）

```sql
CREATE TABLE deal (
    id              SERIAL PRIMARY KEY,
    salesperson_id  INT NOT NULL REFERENCES salesperson(id),
    customer_id     INT REFERENCES customer(id),
    contact_id      INT REFERENCES contact(id),
    product_name    TEXT NOT NULL,
    amount          NUMERIC(12,2) NOT NULL,
    deal_date       DATE NOT NULL,
    status          TEXT NOT NULL DEFAULT 'closed',  -- closed/pending/refunded
    notes           TEXT,
    created_at      TIMESTAMPTZ DEFAULT now()
);
```

---

## 五、采集方案

### 5.1 复用现有能力

当前单机系统已具备：
- macOS 微信 4.x 数据库定位与解密
- 联系人、会话、消息解析与标准化
- 每日 launchd 定时同步
- 增量去重（`UNIQUE(source_shard, source_table, source_local_id)`）

MVP 阶段直接复用，只需扩展为多设备。

### 5.2 多设备采集流程

每台销售设备部署相同的采集代理：

```text
1. launchd 每天 05:00 触发
2. 退出微信 → 复制数据库副本 → 重启微信
3. 解密数据库副本
4. 解析联系人、会话、消息
5. 通过 SSH/HTTP 将增量数据推送到中央服务器
6. 中央服务器写入 PostgreSQL
7. 清理临时文件
```

### 5.3 中央服务器接收

中央服务器提供一个简单的接收接口：

```text
POST /api/sync
{
  "salesperson_id": 1,
  "device_id": "macbook-abc123",
  "contacts": [...],
  "conversations": [...],
  "messages": [...]
}
```

或者更简单：每台设备直接配置 PostgreSQL 远程连接，采集脚本直接写入中央库。MVP 阶段建议后者，省去中间服务。

### 5.4 数据隔离

每条数据都带 `salesperson_id`，确保销售之间数据隔离。查询时按销售过滤。

---

## 六、AI 分析

### 6.1 分析目标

MVP 只做两件事：

1. **客户识别**：从联系人中筛选出真实客户（排除微商、广告、纯社交联系人）
2. **沟通摘要**：对每个客户会话生成结构化摘要

### 6.2 客户识别

对每个联系人，取最近 N 条消息，调用 LLM 判断：

```json
{
  "is_customer": true,
  "customer_name": "张总",
  "industry": "餐饮",
  "intent_level": "medium",
  "key_needs": ["收银系统", "会员管理"],
  "reason": "多次询问产品价格和功能，提到门店运营需求"
}
```

筛选规则：
- 有超过 5 条对话的联系人
- 消息内容涉及产品咨询、价格、合作等关键词
- 排除纯群聊通知、广告推送类联系人

### 6.3 沟通摘要

对每个客户会话，按时间窗口（如最近 7 天或全部）生成：

```json
{
  "summary": "客户最初咨询收银系统价格，对比了竞品后关注会员管理功能，销售安排了产品演示，客户表示需要和合伙人商量。",
  "stage": "产品演示",
  "objections": ["价格偏高", "需要合伙人确认"],
  "next_action": "等待客户反馈，建议3天后跟进",
  "last_contact_date": "2026-07-12"
}
```

### 6.4 模型选择

- 优先使用现有 Ollama 本地模型（如 qwen2.5）降低成本
- 消息量大时分批处理，每次传入不超过 50 条消息
- 分析结果存入 `customer` 表，不单独建表

---

## 七、成交数据录入

### 7.1 录入方式

Web 后台提供简单表单：

- 选择销售
- 选择客户（从 AI 识别的客户列表中选）
- 填写产品名称、金额、成交日期
- 可选填写备注

### 7.2 关联逻辑

成交记录通过 `contact_id` 自动关联到对应的微信会话。这样就能看到：

- 某个成交客户的所有聊天记录
- 从首次接触到成交的完整沟通时间线
- 成交前的关键沟通节点

---

## 八、Web 管理后台

### 8.1 技术选型

| 模块 | 选型 |
|---|---|
| 前端 | React + TailwindCSS |
| 后端 | Python FastAPI |
| 数据库 | PostgreSQL 17 |
| 部署 | 单机部署，Nginx 反向代理 |

### 8.2 页面清单

MVP 只做 5 个页面：

#### 首页 / 仪表盘

- 今日新增消息数
- 活跃客户数
- 本月成交金额
- 各销售消息量对比

#### 销售列表

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

#### 客户列表

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

#### 客户详情

- 客户基本信息（AI 识别结果）
- 完整聊天记录（时间线展示，复用现有搜索页面能力）
- AI 沟通摘要
- 关联的成交记录

#### 成交录入

- 简单表单
- 成交列表（可按销售、日期、产品筛选）

---

## 九、实施计划

### 第 1 周：数据采集多设备化

- [ ] 创建中央 PostgreSQL 数据库 `wechat_sales_db`
- [ ] 建表（6 张核心表）
- [ ] 改造现有采集脚本，支持写入中央库（增加 `salesperson_id` 字段）
- [ ] 在 2 台设备上部署采集代理并验证

### 第 2 周：AI 分析 + Web 后台

- [ ] 搭建 FastAPI 后端骨架
- [ ] 实现客户识别分析脚本
- [ ] 实现沟通摘要分析脚本
- [ ] 搭建 React 前端骨架
- [ ] 完成客户列表和客户详情页

### 第 3 周：成交录入 + 报表

- [ ] 成交录入表单
- [ ] 成交列表页
- [ ] 仪表盘基础数据展示
- [ ] 聊天记录页面集成

### 第 4 周：联调 + 试点

- [ ] 3～5 名销售实际接入
- [ ] 录入真实成交数据
- [ ] 验证"聊天→客户→成交"关联准确性
- [ ] 收集反馈，修复问题

---

## 十、成功标准

MVP 上线后需验证：

1. **采集完整性**：每个销售每天的消息采集率 > 95%
2. **客户识别准确率**：AI 识别的客户中，> 80% 被销售确认是真实客户
3. **成交关联可用**：手动录入的成交记录能正确关联到对应聊天记录
4. **基础报表可用**：能看到每个销售的消息量、客户数、成交金额
5. **闭环验证**：至少能从 1 个成交客户回溯完整沟通链路

---

## 十一、与完整方案的关系

MVP 是总体方案"第一阶段"的精简版，主要区别：

| 维度 | MVP | 完整方案第一阶段 |
|---|---|---|
| 数据模型 | 6 张表 | 20+ 张表 |
| 成交数据 | 手动录入 | 接入 CRM/订单系统 |
| AI 分析 | 客户识别 + 沟通摘要 | 阶段识别 + 意向评分 + 异议分析 + 待办 |
| 权限 | 按 salesperson_id 简单隔离 | RBAC + 数据范围权限 |
| 同步 | 每日离线 | 每日 + 小时级 |
| 报表 | 基础统计 | 销售漏斗 + 能力雷达 + 话术分析 |
| 部署 | 单机 | 单机但面向多设备 |

MVP 验证通过后，按完整方案路线图逐步扩展。