yss-project/CUSTOMER-SERVICE-FINAL-PAYMENT-TRACKING.md

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

📋 功能概述

在客服工作台 (@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)

// 接口定义（第 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 渐变、动画和过渡效果
• 响应式设计和用户体验优化