169 lines
8.2 KiB
Markdown
169 lines
8.2 KiB
Markdown
# P6：小程序前端 — 任务模块 — miniapp-fe-tasks
|
||
|
||
> 优先级：P6（依赖 P3 + P4 + P5-A）
|
||
> 预估工作量：大
|
||
> P5-B 承接：T4 同时细化 P5 应用 4/5 的 Prompt JSON 结构
|
||
|
||
---
|
||
|
||
## 需求（Requirements）
|
||
|
||
### 用户故事
|
||
|
||
1. 作为助教，我打开小程序首页看到按优先级排序的任务列表，高优先召回在最上面。
|
||
2. 作为助教，我长按任务可以置顶、放弃（需填原因）、或问 AI。
|
||
3. 作为助教，我点击任务进入详情页，看到客户信息、近期服务记录、AI 分析、备注入口。
|
||
4. 作为助教，我在绩效区域看到当月业绩、档位、工资预估、跳档激励。
|
||
5. 作为助教，我能管理自己的备注（查看、删除需二次确认）。
|
||
|
||
### 验收标准
|
||
|
||
- AC1：任务列表按优先级 0→1→2 分组展示，每组内按分数降序
|
||
- AC2：置顶任务固定在列表顶部，已放弃任务在独立列表
|
||
- AC3：爱心 icon 正确展示（💖>8.5 / 🧡>7 / 💛>5 / 💙<5）
|
||
- AC4：喜好标签正确展示（🎱/斯/🀅/🎤）
|
||
- AC5：跟/弃 icon 正确展示
|
||
- AC6：当月数据显示"预估"标记
|
||
- AC7：跳档激励"到达XXX即得YYY"计算正确
|
||
- AC8：任务卡片展示应用 4 的一句话总结（ai_cache 缓存读取）
|
||
- AC9：备注卡片以打星方式展示应用 6 评分（1-10 分，映射公式：`星数 = score ÷ 2`，5 颗星，支持半星；如 score=7 → 3.5 星）
|
||
- AC10：维客线索提供者按规则显示（见下方"维客线索提供者显示规则"章节）
|
||
|
||
---
|
||
|
||
## 维客线索提供者显示规则
|
||
|
||
### 后端过滤策略（安全性优先）
|
||
|
||
⚠️ **重要**：维客线索的过滤必须在后端完成，客户端不进行任何过滤逻辑，以防止数据泄露风险。
|
||
|
||
**后端返回规则**：
|
||
|
||
当客户端请求任务详情时，后端应返回已过滤的维客线索列表，仅包含以下类型：
|
||
|
||
| 线索类型 | 返回条件 | 说明 |
|
||
|---------|--------|------|
|
||
| 系统生成 | 总是返回 | `source = 'ai_consumption'`（应用 3 消费分析） |
|
||
| 我的记录 | 总是返回 | `source = 'manual'` 且 `recorded_by_assistant_id = 当前登录用户ID` |
|
||
| 他人记录 | 返回脱敏版本 | `source = 'manual'` 且 `recorded_by_assistant_id ≠ 当前登录用户ID`，返回时需脱敏 |
|
||
| 备注分析 | 返回脱敏版本 | `source = 'ai_note'`，返回时需脱敏 |
|
||
|
||
**脱敏规则**：
|
||
|
||
对于"他人记录"和"备注分析"类型的线索，后端返回时应：
|
||
- 移除或不返回 `recorded_by_assistant_id` 字段
|
||
- 移除或不返回 `recorded_by_name` 字段
|
||
- 保留 `source` 字段用于前端判断显示"By:某人"
|
||
|
||
### 前端显示规则
|
||
|
||
前端接收后端返回的维客线索后，直接根据 `source` 字段显示，无需额外过滤：
|
||
|
||
| source 值 | 显示文案 |
|
||
|----------|--------|
|
||
| `ai_consumption` | By:系统 |
|
||
| `manual` 且有 `recordedByAssistantId` | By:我 |
|
||
| `manual` 或 `ai_note` 且无 `recordedByAssistantId` | By:某人 |
|
||
|
||
**注意**：
|
||
- "某人"是字符串字面量，不是真实人名
|
||
- 不显示具体的助教姓名或ID
|
||
- 与客户详情页不同（客户详情页显示具体人名）
|
||
|
||
### 多人情况处理
|
||
|
||
当同一客户有多条维客线索时，前端按以下规则展示：
|
||
|
||
1. **按时间排序**：按 `created_at` 升序排列（最早的在前）
|
||
2. **取最先反馈**：
|
||
- 如果有"By:系统"的线索，优先显示最早的"By:系统"
|
||
- 如果没有"By:系统"，则显示最早的"By:我"或"By:某人"
|
||
3. **单条展示**：维客线索卡片中仅显示一条（最优先的），其他线索可通过"查看全部"或列表展开查看
|
||
|
||
### 前端实现示例
|
||
|
||
```typescript
|
||
// 前端：直接根据后端返回的数据显示，无需过滤
|
||
function getClueProvider(clue: RetentionClue): string {
|
||
if (clue.source === 'ai_consumption') {
|
||
return 'By:系统'
|
||
}
|
||
// 后端已确保：如果是 manual 且有 recordedByAssistantId，则是当前用户
|
||
if (clue.source === 'manual' && clue.recordedByAssistantId) {
|
||
return 'By:我'
|
||
}
|
||
// 其他情况（manual 无 ID、ai_note）都显示"By:某人"
|
||
return 'By:某人'
|
||
}
|
||
|
||
// 前端：从多条线索中选择最优先的
|
||
function selectPrimaryClue(clues: RetentionClue[]): RetentionClue {
|
||
// 1. 按 createdAt 升序排序
|
||
const sorted = clues.sort((a, b) =>
|
||
new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime()
|
||
)
|
||
|
||
// 2. 优先返回 source='ai_consumption' 的最早线索
|
||
const systemClue = sorted.find(c => c.source === 'ai_consumption')
|
||
if (systemClue) return systemClue
|
||
|
||
// 3. 否则返回最早的线索
|
||
return sorted[0]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 页面清单
|
||
|
||
### task-list（任务列表 + 绩效）
|
||
- 任务列表：优先级分组、长按操作
|
||
- 任务卡片：展示应用 4 的 `summary`（一句话总结）作为 AI 摘要（从 `ai_cache` cache_type=app4_analysis 读取）
|
||
- 绩效区域：当月业绩/档位/工资/跳档激励
|
||
- 通用组件：爱心 icon、喜好标签、跟/弃 icon
|
||
|
||
### task-detail（任务详情）
|
||
- 客户信息卡片
|
||
- 近期服务记录（时间+时长）
|
||
- AI 区域：
|
||
- 维客线索（应用 8 整合线索 + 人工，读取 `member_retention_clue`；Emoji 作为二级标签、提供者按规则展示）
|
||
- 客户分析（应用 7 缓存：运营策略数组 + 总结）
|
||
- 关系分析 + 任务建议 + 一句话总结（应用 4 缓存，读取应用 8 最新线索）
|
||
- 话术参考（应用 5 缓存）
|
||
- 备注分析评分（应用 6 缓存：1-10 分）
|
||
- 备注入口（提交后触发回访完成判定）；备注弹窗含星星评分（再次服务意愿+再来店可能性，各 1-5 星）：回访任务默认展开评分区域，其他任务类型默认隐藏通过"展开评价"按钮手动打开
|
||
- 备注卡片展示应用 6 的 `score`（1-10 分），以打星方式呈现（`星数 = score ÷ 2`，5 颗星，支持半星；从 `ai_cache` cache_type=app6_note_analysis 读取）
|
||
- 维客线索提供者显示规则（见上方"维客线索提供者显示规则"章节）
|
||
- "问问助手"按钮 → chat.html
|
||
|
||
### notes（备注管理）
|
||
- 备注列表
|
||
- 删除操作（二次确认弹窗）
|
||
|
||
---
|
||
|
||
## 小程序前端开发强制规范
|
||
|
||
> 以下规范适用于本 SPEC 中所有小程序页面实现，具有强制约束力。
|
||
|
||
1. **原型图是唯一视觉真相**：`docs/h5_ui/pages/*.html` 中的结构、层次、元素、配色、间距、交互行为是小程序页面实现的唯一参考标准。任何偏离原型图的实现都需要明确的产品确认。
|
||
2. **WXML ≠ HTML**：严禁在小程序中使用 HTML 标签（div/span/p/a/img 等），必须使用小程序原生标签（view/text/image/navigator 等）。
|
||
3. **WXSS ≠ CSS**：使用 rpx 单位、仅支持有限选择器、无 DOM/BOM API、样式隔离机制不同。Tailwind CSS 类名必须手动转换为 WXSS。
|
||
4. **TDesign 优先**：凡 TDesign 组件库能覆盖的 UI 元素，必须使用 TDesign 组件；自定义实现仅限 TDesign 无法覆盖的场景。
|
||
5. **Power 文档优先**：实现前必须加载 `wechat-miniprogram` Power 的相关 steering 文件（`view-layer.md`、`tdesign.md`、`builtin-components.md`），确保语法和组件用法正确。
|
||
6. **项目踩坑指南必读**：实现前必须阅读 `docs/prd/MIGRATION-PLAYBOOK.md` 第六章，该文档是基于本项目实际转换经验的避坑手册，涵盖 WXML/WXSS 差异、事件系统、TDesign 用法、rpx 换算规则及新页面开发 Checklist。
|
||
|
||
---
|
||
|
||
## 任务清单
|
||
|
||
- [ ] T1：实现 task-list 页面（任务列表 + 分组 + 排序）
|
||
- [ ] T2：实现长按操作（置顶/放弃/AI）
|
||
- [ ] T3：实现绩效展示区域（业绩/档位/工资/跳档激励）
|
||
- [ ] T4：实现 task-detail 页面（客户信息 + 服务记录 + AI 区域）
|
||
- T4-a：细化 P5 应用 4（关系分析）Prompt JSON 结构，实现 `service_history`、`assistant_info` 等字段的拼接函数（对应 P5-T7-完整）
|
||
- T4-b：细化 P5 应用 5（话术参考）Prompt JSON 结构，实现拼接函数（对应 P5-T8-完整）
|
||
- [ ] T5：实现备注提交功能（集成回访完成判定 + 星星评分：回访任务默认展开，其他任务类型通过"展开评价"按钮手动打开）
|
||
- [ ] T6：实现 notes 页面（列表 + 删除 + 分页懒加载）
|
||
- [ ] T7：实现通用组件（爱心 icon、喜好标签、跟/弃 icon、预估标记）
|