157 lines
5.8 KiB
Markdown
157 lines
5.8 KiB
Markdown
# 协同拜访记录去重 — 设计方案
|
||
|
||
## 背景
|
||
|
||
当前机制：客户经理 A 创建拜访记录并选择协同人员 B 时，后端为 B 生成一条空内容的草稿副本。B 填写后，同一客户、同一天出现两条独立拜访记录，导致周报重复展示、亮灯表重复计数。
|
||
|
||
## 设计目标
|
||
|
||
1. 周报中同一客户同一次拜访合并展示为一张卡片
|
||
2. 亮灯表不重复计数
|
||
3. 每个参与人的填报进度不受影响（各自计入）
|
||
4. 每个参与人能独立编辑自己的副本
|
||
5. 历史数据兼容，不做强制迁移
|
||
|
||
## 方案概要
|
||
|
||
### 1. 数据库：新增 `visit_group_id`
|
||
|
||
```sql
|
||
ALTER TABLE visits ADD COLUMN visit_group_id UUID;
|
||
CREATE INDEX ix_visits_visit_group_id ON visits(visit_group_id);
|
||
```
|
||
|
||
- 单人拜访：`visit_group_id = NULL`
|
||
- 多人协同拜访：同一次拜访的所有记录共享同一个 `visit_group_id`
|
||
|
||
### 2. 后端：POST /visits/ 改造
|
||
|
||
**原逻辑：** 为每个协同人生成一条空内容草稿（`communication_content=""`, `photos=[]`, `companions=[]`）
|
||
|
||
**新逻辑：** 为每个协同人生成一条完整副本：
|
||
|
||
| 副本字段 | 值 | 说明 |
|
||
|----------|-----|------|
|
||
| `customer_id` | 同主记录 | |
|
||
| `visit_date` | 同主记录 | |
|
||
| `visit_method` | 同主记录 | |
|
||
| `time_range` | 同主记录 | |
|
||
| `visitor_name` | 同主记录 | 实际拜访人不变 |
|
||
| `visitor_phone` | 同主记录 | |
|
||
| `communication_content` | 原内容 + `（协同XXX）` | 如：`了解项目进度...（协同韦佶秀）` |
|
||
| `customer_demand` | 同主记录 | |
|
||
| `companions` | `[主记录创建人]` | 互换：协同人看到主访人 |
|
||
| `companion_names` | 同主记录 | |
|
||
| `photos` | 同主记录 | |
|
||
| `manager_id` | 协同人的 UUID | 归属到协同人名下 |
|
||
| `visit_group_id` | 同主记录 | **同一 UUID，关联所有副本** |
|
||
|
||
**前端表现（创建人韦佶秀视角）：**
|
||
|
||
```
|
||
相关人员选择了 [韦伦]
|
||
→ 保存后韦伦收到一条完整拜访记录
|
||
→ 韦伦记录内容末尾自动追加"（协同韦佶秀）"
|
||
```
|
||
|
||
### 3. 后端：PUT /visits/{id} 不变
|
||
|
||
协同人编辑自己的副本时不影响主记录，各自独立。
|
||
|
||
### 4. 仪表盘统计：按 visit_group_id 去重
|
||
|
||
`get_dashboard_stats` 中的 `week_visits` 改为：
|
||
|
||
```python
|
||
# 原：count 所有 visit 行
|
||
select count(distinct coalesce(visit_group_id, id))
|
||
from visits
|
||
where visit_date between monday and sunday
|
||
```
|
||
|
||
每个 visit_group_id 只算一次，跳过 NULL（单人拜访用 id 做 fallback key）。
|
||
|
||
### 5. 填报进度：不变
|
||
|
||
`get_reporting_progress` 按 `manager_id` 分组计数，每个参与人各算一次，不受去重影响。
|
||
|
||
### 6. 亮灯表：按 (customer_id, visit_date, visit_group_id) 去重
|
||
|
||
同一客户同一天同一次拜访只亮一盏灯。
|
||
|
||
### 7. 周报展示：按 visit_group_id 合并
|
||
|
||
`get_weekly_report` 查询时，同一个 `visit_group_id` 的记录合并成一条输出：
|
||
|
||
```json
|
||
{
|
||
"customer_name": "污水处理厂",
|
||
"visit_date": "2026-07-30",
|
||
"visit_method": "上门",
|
||
"time_range": "09:00-10:30",
|
||
"visit_group_id": "abc-123",
|
||
"participants": [
|
||
{
|
||
"manager_name": "韦佶秀",
|
||
"manager_id": "uuid-1",
|
||
"role": "primary",
|
||
"communication_content": "了解污水处理新项目...",
|
||
"customer_demand": "专线扩容至100M...",
|
||
"photos": ["photo_001", "photo_002"]
|
||
},
|
||
{
|
||
"manager_name": "韦伦",
|
||
"manager_id": "uuid-2",
|
||
"role": "companion",
|
||
"communication_content": "了解污水处理新项目...（协同韦佶秀）",
|
||
"customer_demand": "专线扩容至100M...",
|
||
"photos": ["photo_001", "photo_002"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**前端周报卡片展示：**
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 污水处理厂 2026-07-30 上门 │
|
||
│ 09:00-10:30 │
|
||
│ │
|
||
│ ▸ 韦佶秀（主访） │
|
||
│ 了解污水处理新项目建设进度，客户计划新增... │
|
||
│ 客户需求：专线扩容至100M，新增视频监控... │
|
||
│ 📷 2张 │
|
||
│ │
|
||
│ ▸ 韦伦（协同） │
|
||
│ 了解污水处理新项目建设进度...（协同韦佶秀） │
|
||
│ 客户需求：专线扩容至100M... │
|
||
│ 📷 2张 │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 8. 前端：协同记录编辑提示
|
||
|
||
协同人打开自己的副本编辑时，沟通内容区域上方显示一行提示：
|
||
|
||
> 💡 此记录为协同韦佶秀拜访「污水处理厂」的副本。你可以补充或修改内容，不会影响主记录。
|
||
|
||
## 改动清单
|
||
|
||
| 层 | 文件 | 改动 |
|
||
|----|------|------|
|
||
| DB | migration | `ALTER TABLE visits ADD visit_group_id UUID` |
|
||
| 后端 | `models/visit.py` | 新增 `visit_group_id` 字段 |
|
||
| 后端 | `schemas/visit.py` | `VisitOut` 新增 `visit_group_id` |
|
||
| 后端 | `api/visits.py` POST | 副本改为完整复制 + `(协同XXX)` 后缀 + 互换 companions + 设置 visit_group_id |
|
||
| 后端 | `services/dashboard.py` | `get_dashboard_stats` 的 week_visits 改为 distinct 去重 |
|
||
| 后端 | `services/dashboard.py` | `get_weekly_report` 合并同 visit_group_id 记录 |
|
||
| 后端 | `services/light_board.py` | 亮灯计数去重 |
|
||
| 前端 | 周报 `WeeklyReport.vue` | 拜访卡片支持 participants 展开/折叠 |
|
||
| 前端 | 移动端 `VisitForm.vue` | 协同记录编辑时显示提示条 |
|
||
|
||
## 兼容性
|
||
|
||
- 历史数据 `visit_group_id = NULL`，行为与现在完全一致
|
||
- 前端 `participants` 字段回退：单 participant 时展示与现在无差异
|