# 客服板块：待跟进尾款项目功能实现总结

## 📋 功能概述

在客服工作台 (`@dashboard @customer-service`) 中实现了"待跟进尾款项目"功能，该功能通过查询 `Project` 表和 `ProjectPayment` 表，自动识别并展示所有在售后阶段且尾款未结清的项目。

## 🎯 核心功能

### 1. 数据查询逻辑

**查询条件：**
- 查询处于售后归档阶段的项目（`currentStage` 包含：售后归档、尾款结算、客户评价、投诉处理、已归档、aftercare）
- 排除已删除的项目（`isDeleted != true`）
- 限制最多查询 100 个项目

**付款计算逻辑：**
1. 从项目的 `data.quotation.total` 字段获取订单总金额
2. 查询该项目的所有 `ProjectPayment` 记录（包括预付款、里程碑付款和尾款）
3. 累计所有状态为 `paid` 的付款记录，得到已付金额
4. 计算剩余金额 = 订单总金额 - 已付金额
5. 只有当剩余金额 > ¥100 时，才将该项目列入待跟进列表（避免小额零头）

**状态判断：**
- **已逾期**：存在尾款记录（`type: 'final'`）且未支付，应付时间（`dueDate`）已过期
- **待付款**：存在尾款记录但未支付，应付时间尚未到期
- **待创建**：没有尾款记录但仍有剩余金额，需要创建尾款记录

### 2. 数据展示

每个待跟进项目卡片显示：
- **项目名称**：清晰展示项目标题
- **剩余金额**：大字体高亮显示，带动画效果
- **订单总额和已付金额**：小字体辅助显示，便于了解整体情况
- **客户信息**：客户姓名和联系电话
- **应付时间**：显示尾款应付日期
- **状态标识**：
  - 🔴 已逾期（红色，带脉动动画，显示逾期天数）
  - 🟡 待付款（黄色）
  - 🟠 待创建（橙色）
- **付款进度条**：可视化展示已付款比例，带渐变和光泽动画

### 3. 交互功能

**开始跟进按钮：**
- 记录跟进活动到 `ActivityLog` 表
- 导航到项目详情页的售后归档阶段
- 自动聚焦到付款区域（`queryParams: { stage: 'aftercare', focus: 'payment' }`）

**查看详情按钮：**
- 导航到项目详情页
- 查看完整的项目信息

### 4. 排序规则

- 已逾期的项目优先显示在前面
- 同为逾期状态的项目按逾期天数降序排列（逾期时间最长的排最前）
- 其他项目按更新时间排序

## 📂 涉及的数据表

### Project 表
| 字段 | 用途 |
|------|------|
| `objectId` | 项目唯一标识 |
| `title` / `name` | 项目名称 |
| `currentStage` | 项目当前阶段（用于筛选售后阶段项目） |
| `data.quotation.total` | 订单总金额（从订单分配阶段保存） |
| `contact` | 客户联系信息（Pointer → ContactInfo） |
| `deadline` | 项目截止日期（作为应付时间的备选） |
| `isDeleted` | 软删除标记 |

### ProjectPayment 表
| 字段 | 用途 |
|------|------|
| `objectId` | 付款记录唯一标识 |
| `project` | 关联项目（Pointer → Project） |
| `type` | 付款类型（advance/milestone/final） |
| `amount` | 付款金额 |
| `status` | 付款状态（pending/paid/overdue） |
| `dueDate` | 应付时间 |
| `isDeleted` | 软删除标记 |

## 🎨 UI/UX 特性

### 视觉设计
- **渐变背景**：不同状态使用不同的背景渐变
  - 正常：蓝白渐变
  - 逾期：红白渐变
  - 待创建：橙白渐变
- **左侧色条**：根据状态显示不同颜色的垂直条，hover 时变宽
- **动画效果**：
  - 金额数字带脉动发光效果
  - 逾期标签带脉冲动画
  - 进度条带光泽扫过动画
  - hover 时卡片上浮并显示阴影

### 响应式布局
- 卡片自动适应屏幕宽度
- 按钮在小屏幕上保持清晰可点击

### 用户体验
- 加载时显示详细的控制台日志，便于调试
- 空状态友好提示
- 操作按钮配有清晰的图标和说明

## 📝 代码文件

### TypeScript (`dashboard.ts`)
```typescript
// 接口定义（第 125-137 行）
pendingFinalPaymentProjects = signal<Array<{
  id: string;
  projectId: string;
  projectName: string;
  customerName: string;
  customerPhone: string;
  finalPaymentAmount: number; // 剩余未付金额
  totalAmount: number; // 订单总金额
  paidAmount: number; // 已付金额
  dueDate: Date;
  status: string; // 已逾期/待创建/待付款
  overdueDay: number;
}>>([]);

// 数据加载方法（第 1256-1404 行）
private async loadPendingFinalPaymentProjects(): Promise<void> {
  // 1. 查询售后阶段项目
  // 2. 计算每个项目的付款情况
  // 3. 筛选出有剩余金额的项目
  // 4. 排序并更新信号
}

// 交互方法（第 1440-1483 行）
async followUpFinalPayment(projectId: string): Promise<void>
viewProjectDetail(projectId: string): void
```

### HTML 模板 (`dashboard.html`)
- 第 146-250 行：待跟进尾款项目列表区域
- 包含项目卡片、进度条、操作按钮

### SCSS 样式 (`dashboard.scss`)
- 第 55-395 行：待跟进尾款项目样式
- 包含卡片样式、状态颜色、进度条、动画定义

## 🔍 调试信息

代码中添加了详细的控制台日志：
- 🔍 开始加载待跟进尾款项目
- 📊 找到 X 个售后阶段项目
- 📋 项目详细信息（订单总额、已付、剩余）
- ✅ 添加待跟进项目信息
- ✅ 加载完成统计
- ❌ 错误信息（如果有）

## 🚀 使用方式

1. 进入客服工作台
2. 页面自动加载并展示"待跟进尾款项目"板块
3. 查看项目列表，优先处理已逾期项目
4. 点击"开始跟进"按钮，系统自动：
   - 记录跟进活动
   - 跳转到项目详情的售后归档阶段
   - 聚焦到付款区域
5. 或点击"查看详情"查看完整项目信息

## ✅ 优势特点

1. **数据准确性**：直接从订单报价和付款记录计算，确保数据一致性
2. **实时更新**：每次加载都查询最新数据
3. **智能筛选**：自动排除小额零头（<¥100），减少干扰
4. **状态清晰**：三种状态（已逾期/待付款/待创建）一目了然
5. **便捷操作**：一键跟进并记录日志
6. **视觉反馈**：丰富的动画和颜色提示，提升用户体验
7. **详细日志**：完善的控制台输出，便于问题排查

## 🎓 技术要点

- 使用 Angular Signals 进行响应式状态管理
- Parse Server 查询和数据关联（Pointer）
- 异步数据加载和错误处理
- CSS 渐变、动画和过渡效果
- 响应式设计和用户体验优化