yss-project/docs/task/20251025-project-list-layout-optimization.md

客服项目列表布局优化与路由调整

📋 任务概述

完成客服项目列表页面的布局优化和路由调整，包括：

1. 临时跳过域名限制，允许本地直接访问客服板块
2. 调整项目卡片点击跳转逻辑
3. 优化看板布局，四列平均分布占满整行

✅ 完成内容

1. 路由调整 - 跳过域名限制

修改文件：yss-project/src/app/app.routes.ts

修改内容：

// 客服路由
{
  path: 'customer-service',
  loadComponent: () => import('./pages/customer-service/customer-service-layout/customer-service-layout').then(m => m.CustomerServiceLayout),
  // canActivate: [WxworkAuthGuard], // 临时注释，方便本地开发
  children: [
    // ...
  ]
}

效果：

• ✅ 本地开发时可以直接访问 http://localhost:4200/customer-service
• ✅ 无需企业微信授权即可查看客服页面
• ⚠️ 生产环境部署时需要取消注释，恢复授权验证

2. 项目详情跳转优化

修改文件：yss-project/src/app/pages/customer-service/project-list/project-list.ts

修改内容：

// 详情跳转到客服项目详情页面（如果存在）或设计师项目详情页面
navigateToProject(project: ProjectListItem, columnId: 'order' | 'requirements' | 'delivery' | 'aftercare') {
  // 根据columnId映射到对应的阶段
  const stageMapping = {
    'order': '订单分配',
    'requirements': project.currentStage || '需求沟通',
    'delivery': project.currentStage || '建模',
    'aftercare': '客户评价'
  };
  
  // TODO: 当客服项目详情页开发完成后，跳转到 /customer-service/project-detail/:id
  // 目前临时跳转到设计师项目详情页，传递客服角色标识
  this.router.navigate(['/designer/project-detail', project.id], { 
    queryParams: { 
      role: 'customer-service',
      activeTab: 'progress',
      currentStage: stageMapping[columnId],
      from: 'customer-service-list' // 标识来源
    } 
  });
}

效果：

• ✅ 点击项目卡片跳转到设计师项目详情页
• ✅ 传递 role: 'customer-service' 标识客服角色
• ✅ 传递 from: 'customer-service-list' 标识来源
• ✅ 传递 currentStage 自动定位到对应阶段
• 📝 预留TODO注释，方便后续切换到客服专用详情页

3. 看板布局优化

修改文件：yss-project/src/app/pages/customer-service/project-list/project-list.scss

3.1 四列平均分布

修改前：

.project-content .kanban-header,
.project-content .kanban-body {
  display: grid;
  grid-auto-flow: column;
  grid-auto-columns: 320px; // 固定宽度，导致右侧有空白
  gap: 16px;
}

修改后：

.project-content .kanban-header,
.project-content .kanban-body {
  display: grid;
  grid-template-columns: repeat(4, 1fr); // 四列平均分布
  gap: 16px;
  width: 100%;
  min-width: 0; // 允许列收缩
  
  // 响应式设计
  @media (max-width: 1400px) {
    gap: 12px;
  }
  
  @media (max-width: 1200px) {
    grid-template-columns: repeat(2, 1fr); // 小屏幕显示2列
  }
  
  @media (max-width: 768px) {
    grid-template-columns: 1fr; // 移动端显示1列
  }
}

效果：

• ✅ 四个看板列平均分布，占满整行
• ✅ 没有右侧空白区域
• ✅ 响应式设计，适配不同屏幕尺寸

3.2 列内容优化

添加内容：

.project-content .kanban-body .kanban-column {
  min-height: 420px;
  max-height: calc(100vh - 300px); // 限制最大高度
  padding: 12px;
  background-color: $bg-white;
  border: 1px dashed $border-color;
  border-radius: 8px;
  box-shadow: $box-shadow;
  overflow-y: auto; // 内容超出时滚动
  overflow-x: hidden; // 禁止横向滚动
  min-width: 0; // 允许收缩
  
  // 自定义滚动条样式
  &::-webkit-scrollbar {
    width: 6px;
  }
  
  &::-webkit-scrollbar-track {
    background: transparent;
  }
  
  &::-webkit-scrollbar-thumb {
    background: rgba(0, 0, 0, 0.1);
    border-radius: 3px;
    
    &:hover {
      background: rgba(0, 0, 0, 0.2);
    }
  }
}

效果：

• ✅ 限制列的最大高度，避免页面过长
• ✅ 内容超出时显示滚动条
• ✅ 美化滚动条样式
• ✅ 禁止横向滚动，避免布局错乱

3.3 卡片内容优化

卡片头部：

.project-content .kanban-card-header {
  display: flex;
  align-items: flex-start;
  justify-content: space-between;
  margin-bottom: 12px;
  gap: 8px;
  min-width: 0; // 允许收缩
}

.project-content .kanban-card-header .left {
  display: flex;
  flex-direction: column;
  gap: 4px;
  flex: 1;
  min-width: 0; // 允许收缩
  overflow: hidden;
}

.project-content .kanban-card-header .left .project-name {
  margin: 0;
  font-size: 15px;
  font-weight: 600;
  color: $text-primary;
  line-height: 1.4;
  letter-spacing: -0.01em;
  overflow: hidden;
  text-overflow: ellipsis;
  display: -webkit-box;
  -webkit-line-clamp: 2; // 最多显示2行
  line-clamp: 2; // 标准属性
  -webkit-box-orient: vertical;
  word-break: break-word;
}

.project-content .kanban-card-header .left .project-id {
  font-size: 11px;
  color: $text-light;
  font-weight: 500;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

.project-content .kanban-card-header .right {
  display: flex;
  align-items: center;
  gap: 6px;
  flex-shrink: 0; // 不收缩
}

卡片内容：

.project-content .kanban-card-content {
  font-size: 13px;
  color: $text-secondary;
  min-width: 0; // 允许收缩
  overflow: hidden;
  
  // 确保所有子元素不溢出
  > * {
    min-width: 0;
    overflow: hidden;
  }
  
  // 文本内容截断
  p, div {
    overflow: hidden;
    text-overflow: ellipsis;
    word-break: break-word;
  }
}

效果：

• ✅ 项目名称最多显示2行，超出显示省略号
• ✅ 项目ID单行显示，超出显示省略号
• ✅ 所有文本内容都有溢出处理
• ✅ 徽章和按钮不会被压缩
• ✅ 布局更加紧凑和美观

📊 布局对比

修改前

┌────────────────────────────────────────────────────────────────┐
│  订单分配    │  确认需求    │  交付执行    │  售后    │ [空白] │
│  (320px)     │  (320px)     │  (320px)     │  (320px) │        │
└────────────────────────────────────────────────────────────────┘

修改后

┌────────────────────────────────────────────────────────────────┐
│  订单分配    │  确认需求    │  交付执行    │  售后              │
│  (25%)       │  (25%)       │  (25%)       │  (25%)             │
└────────────────────────────────────────────────────────────────┘

🎨 视觉改进

1. 布局改进

• ✅ 四列平均分布，充分利用屏幕空间
• ✅ 没有右侧空白区域
• ✅ 列宽度自适应，响应式设计

2. 内容优化

• ✅ 项目名称支持2行显示
• ✅ 长文本自动截断，显示省略号
• ✅ 列内容超出时显示滚动条
• ✅ 美化滚动条样式

3. 响应式设计

• ✅ 大屏幕（>1400px）：4列，间距16px
• ✅ 中屏幕（1200-1400px）：4列，间距12px
• ✅ 小屏幕（768-1200px）：2列
• ✅ 移动端（<768px）：1列

🔍 技术细节

Grid布局关键点

1. grid-template-columns: repeat(4, 1fr)

   • 创建4列，每列占据相等的空间（1fr = 1 fraction）
   • 自动填充可用空间

2. min-width: 0

   • 允许grid子元素收缩到小于内容宽度
   • 解决长文本导致的布局溢出问题

3. overflow: hidden

   • 防止内容溢出容器
   • 配合text-overflow: ellipsis显示省略号

文本截断技巧

1. 单行截断：

   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
   

2. 多行截断：

   display: -webkit-box;
   -webkit-line-clamp: 2;
   line-clamp: 2;
   -webkit-box-orient: vertical;
   overflow: hidden;
   

滚动条美化

&::-webkit-scrollbar {
  width: 6px;
}

&::-webkit-scrollbar-track {
  background: transparent;
}

&::-webkit-scrollbar-thumb {
  background: rgba(0, 0, 0, 0.1);
  border-radius: 3px;
  
  &:hover {
    background: rgba(0, 0, 0, 0.2);
  }
}

📝 使用说明

1. 本地开发访问

直接访问客服板块：

http://localhost:4200/customer-service
http://localhost:4200/customer-service/project-list

无需企业微信授权，可以直接查看页面。

2. 项目卡片点击

点击项目卡片后：

• 跳转到 /designer/project-detail/:id
• 携带查询参数：
  • role=customer-service - 客服角色标识
  • activeTab=progress - 默认显示进度标签
  • currentStage=xxx - 当前阶段
  • from=customer-service-list - 来源标识

3. 响应式布局

页面会根据屏幕宽度自动调整：

• 宽屏：4列并排显示
• 中屏：4列并排，间距缩小
• 小屏：2列并排显示
• 移动端：1列显示

⚠️ 注意事项

1. 生产环境部署

部署到生产环境前，需要恢复路由守卫：

// yss-project/src/app/app.routes.ts
{
  path: 'customer-service',
  loadComponent: () => import('./pages/customer-service/customer-service-layout/customer-service-layout').then(m => m.CustomerServiceLayout),
  canActivate: [WxworkAuthGuard], // 取消注释
  children: [
    // ...
  ]
}

2. 项目详情页开发

当客服专用的项目详情页开发完成后，需要修改跳转逻辑：

// yss-project/src/app/pages/customer-service/project-list/project-list.ts
navigateToProject(project: ProjectListItem, columnId: string) {
  // 跳转到客服项目详情页
  this.router.navigate(['/customer-service/project-detail', project.id], { 
    queryParams: { 
      currentStage: stageMapping[columnId]
    } 
  });
}

3. 浏览器兼容性

• Grid布局：支持所有现代浏览器（IE11需要polyfill）
• 多行文本截断：使用了-webkit-line-clamp，需要webkit内核
• 自定义滚动条：仅支持webkit内核浏览器

📁 修改的文件

1. yss-project/src/app/app.routes.ts

   • 临时注释客服路由的WxworkAuthGuard

2. yss-project/src/app/pages/customer-service/project-list/project-list.ts

   • 优化navigateToProject方法
   • 添加from参数标识来源
   • 添加TODO注释

3. yss-project/src/app/pages/customer-service/project-list/project-list.scss

   • 改用Grid布局，四列平均分布
   • 添加响应式设计
   • 优化列内容滚动
   • 优化卡片内容布局
   • 添加文本截断处理
   • 美化滚动条样式

🎯 效果预览

桌面端（>1400px）

• 4列并排，每列占25%宽度
• 间距16px
• 充分利用屏幕空间

平板端（768-1200px）

• 2列并排，每列占50%宽度
• 适合中等屏幕

移动端（<768px）

• 1列显示，占100%宽度
• 适合手机浏览

✅ 测试清单

• 客服板块可以直接访问（无需授权）
• 项目列表页正常显示
• 四个看板列平均分布，无右侧空白
• 点击项目卡片正确跳转
• 长项目名称正确截断
• 列内容超出时显示滚动条
• 响应式布局正常工作
• 无linter错误

---

完成时间: 2024-10-25
开发者: AI Assistant
状态: ✅ 已完成