yss-project/DASHBOARD-COMPONENT-API-REFERENCE.md

组长端看板子组件 API 参考手册

快速查找

• DashboardMetricsComponent - 统计指标
• DashboardFilterBarComponent - 筛选条件
• ProjectKanbanComponent - 项目看板
• TodoSectionComponent - 待办任务
• WorkloadGanttComponent - 工作负载
• SmartMatchModalComponent - 智能推荐
• DashboardAlertsComponent - 预警提醒

---

DashboardMetricsComponent

功能

显示关键统计指标卡片，支持点击快速筛选

Props (Inputs)

属性名	类型	必需	默认值	说明
overdueCount	number	✅	0	超期项目数量
dueSoonCount	number	✅	0	临期项目数量
pendingApprovalCount	number	✅	0	待审批项目数量
pendingAssignmentCount	number	✅	0	待分配项目数量
overloadedDesignersCount	number	✅	0	超负荷设计师数量
averageWorkloadRate	number	✅	0	平均负载率（百分比）

Events (Outputs)

事件名	参数类型	说明
filterStatus	string	点击卡片时触发，参数为状态标识（'overdue', 'dueSoon' 等）

使用示例

<app-dashboard-metrics
  [overdueCount]="overdueProjects.length"
  [dueSoonCount]="dueSoonProjects.length"
  [pendingApprovalCount]="pendingApprovalProjects.length"
  [pendingAssignmentCount]="pendingAssignmentProjects.length"
  [overloadedDesignersCount]="overloadedDesignersCount"
  [averageWorkloadRate]="averageWorkloadRate"
  (filterStatus)="filterByStatus($event)">
</app-dashboard-metrics>

---

DashboardFilterBarComponent

功能

统一管理所有筛选条件，支持智能搜索建议

Props (Inputs)

属性名	类型	必需	默认值	说明
projects	Project[]	✅	[]	项目列表（用于搜索建议）
designers	string[]	✅	[]	设计师列表
corePhases	any[]	✅	[]	核心阶段列表
searchTerm	string	❌	''	搜索关键词（双向绑定）
selectedType	'all' | 'soft' | 'hard'	❌	'all'	项目类型（双向绑定）
selectedUrgency	'all' | 'high' | 'medium' | 'low'	❌	'all'	紧急程度（双向绑定）
selectedStatus	string	❌	'all'	项目状态（双向绑定）
selectedDesigner	string	❌	'all'	选中的设计师（双向绑定）
selectedMemberType	'all' | 'vip' | 'normal'	❌	'all'	会员类型（双向绑定）
selectedCorePhase	string	❌	'all'	核心阶段（双向绑定）
selectedProjectId	string	❌	''	选中的项目ID（双向绑定）
selectedTimeWindow	string	❌	'all'	时间窗（双向绑定）

Events (Outputs)

事件名	参数类型	说明
filterChange	FilterState	任何筛选条件改变时触发
viewProject	string	选择项目或点击搜索建议时触发（项目ID）

使用示例

<app-dashboard-filter-bar
  [projects]="projects"
  [designers]="designers"
  [corePhases]="corePhases"
  [(searchTerm)]="searchTerm"
  [(selectedStatus)]="selectedStatus"
  (filterChange)="onFilterChange($event)"
  (viewProject)="viewProjectDetails($event)">
</app-dashboard-filter-bar>

---

ProjectKanbanComponent

功能

显示四大核心阶段的项目看板视图

Props (Inputs)

属性名	类型	必需	默认值	说明
corePhases	any[]	✅	[]	核心阶段定义
projects	Project[]	✅	[]	项目列表

Events (Outputs)

事件名	参数类型	说明
viewProject	{projectId: string, phaseId: string}	点击项目卡片时触发
openSmartMatch	Project	点击智能推荐按钮时触发
assignProject	string	点击快速分配按钮时触发（项目ID）
reviewProject	{projectId: string, rating: string}	质量评审时触发

使用示例

<app-project-kanban
  [corePhases]="corePhases"
  [projects]="filteredProjects"
  (viewProject)="viewProjectDetailsByPhase($event.projectId, $event.phaseId)"
  (openSmartMatch)="openSmartMatch($event)"
  (assignProject)="quickAssignProject($event)"
  (reviewProject)="reviewProjectQuality($event)">
</app-project-kanban>

---

TodoSectionComponent

功能

显示待办任务和紧急事件，支持标签筛选

Props (Inputs)

属性名	类型	必需	默认值	说明
todoTasksFromIssues	TodoTaskFromIssue[]	✅	[]	待办任务列表
loadingTodoTasks	boolean	❌	false	待办任务加载状态
todoTaskError	string	❌	''	待办任务错误信息
urgentEvents	UrgentEvent[]	✅	[]	紧急事件列表
loadingUrgentEvents	boolean	❌	false	紧急事件加载状态

Events (Outputs)

事件名	参数类型	说明
refresh	void	点击刷新按钮时触发
navigateToIssue	TodoTaskFromIssue	点击待办任务时触发
markAsRead	TodoTaskFromIssue	标记任务为已读时触发
projectClick	string	点击紧急事件的项目时触发（项目ID）
confirmEventOnTime	UrgentEvent	确认事件按时完成时触发
markEventAsStagnant	UrgentEvent	标记为停滞期时触发
resolveUrgentEvent	UrgentEvent	解决紧急事件时触发
createTodoFromEvent	UrgentEvent	从紧急事件创建待办时触发

使用示例

<app-todo-section
  [todoTasksFromIssues]="todoTasksFromIssues"
  [urgentEvents]="urgentEvents"
  (refresh)="refreshTodoTasks()"
  (resolveUrgentEvent)="resolveUrgentEvent($event)">
</app-todo-section>

---

WorkloadGanttComponent

功能

显示设计师工作负载甘特图（周/月视图）

Props (Inputs)

Events (Outputs)

属性名	类型	必需	默认值	说明
designerWorkloadMap	Map	✅	new Map()	设计师工作量映射
realDesigners	any[]	✅	[]	真实设计师列表
filteredProjects	Project[]	✅	[]	筛选后的项目列表

事件名	参数类型	说明
employeeClick	string	点击设计师行时触发（设计师名称）

使用示例

<app-workload-gantt
  [designerWorkloadMap]="designerWorkloadMap"
  [realDesigners]="realDesigners"
  [filteredProjects]="filteredProjects"
  (employeeClick)="onEmployeeClick($event)">
</app-workload-gantt>

---

SmartMatchModalComponent

功能

显示智能推荐设计师弹窗

Props (Inputs)

属性名	类型	必需	默认值	说明
visible	boolean	✅	false	弹窗显示状态
selectedProject	Project | null	✅	null	选中的项目
recommendations	any[]	✅	[]	推荐的设计师列表

Events (Outputs)

事件名	参数类型	说明
close	void	关闭弹窗时触发
assign	string	分配项目时触发（设计师ID）

使用示例

<app-smart-match-modal
  [visible]="showSmartMatch"
  [selectedProject]="selectedProject"
  [recommendations]="recommendations"
  (close)="closeSmartMatch()"
  (assign)="assignToDesigner($event)">
</app-smart-match-modal>

---

DashboardAlertsComponent

功能

显示超期项目预警提醒

Props (Inputs)

属性名	类型	必需	默认值	说明
showAlert	boolean	✅	false	预警显示状态
overdueProjects	Project[]	✅	[]	超期项目列表
urgentPinnedProjects	Project[]	✅	[]	紧急固定区项目

Events (Outputs)

事件名	参数类型	说明
viewAllOverdue	void	点击"查看全部超期项目"时触发
closeAlert	void	关闭预警时触发
filterStatus	string	快速筛选时触发

使用示例

<app-dashboard-alerts
  [showAlert]="showAlert"
  [overdueProjects]="overdueProjects"
  (viewAllOverdue)="viewAllOverdueProjects()"
  (closeAlert)="closeAlert()">
</app-dashboard-alerts>

---

通用类型定义

Project

interface Project {
  id: string;
  name: string;
  currentStage: string;
  deadline: Date;
  designerName: string;
  urgency: 'high' | 'medium' | 'low';
  type: 'soft' | 'hard';
  isOverdue: boolean;
  dueSoon: boolean;
  memberType: 'vip' | 'normal';
  // ... 其他字段
}

FilterState

interface FilterState {
  searchTerm: string;
  type: 'all' | 'soft' | 'hard';
  urgency: 'all' | 'high' | 'medium' | 'low';
  status: string;
  designer: string;
  memberType: 'all' | 'vip' | 'normal';
  corePhase: string;
  projectId: string;
  timeWindow: 'all' | 'today' | 'threeDays' | 'sevenDays';
}

TodoTaskFromIssue

interface TodoTaskFromIssue {
  id: string;
  title: string;
  description: string;
  priority: IssuePriority;
  type: IssueType;
  status: IssueStatus;
  projectId: string;
  projectName: string;
  assigneeName: string;
  createdAt: Date;
  updatedAt: Date;
  dueDate?: Date;
  tags: string[];
}

UrgentEvent

interface UrgentEvent {
  id: string;
  title: string;
  description: string;
  eventType: 'phase_deadline' | 'delivery' | 'review' | 'customer_alert';
  category: 'customer' | 'phase' | 'review' | 'delivery';
  deadline: Date;
  projectId: string;
  projectName: string;
  designerName: string;
  urgencyLevel: 'critical' | 'high' | 'medium';
  overdueDays?: number;
  labels?: string[];
  // ... 其他字段
}

---

最佳实践

1. 性能优化

// 使用 trackBy 优化 ngFor
<div *ngFor="let item of items; trackBy: trackById">
  {{ item.name }}
</div>

trackById(index: number, item: any): string {
  return item.id;
}

2. 错误处理

// 在子组件中捕获错误并通过 Output 传递
try {
  // ... 操作
} catch (error) {
  this.error.emit({ message: '操作失败', error });
}

3. 加载状态

<!-- 显示加载状态 -->
<div *ngIf="loading">加载中...</div>
<div *ngIf="!loading && data.length === 0">暂无数据</div>
<div *ngIf="!loading && data.length > 0">
  <!-- 数据展示 -->
</div>

---

最后更新: 2024-11-21