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

## 快速查找

- [DashboardMetricsComponent](#dashboardmetricscomponent) - 统计指标
- [DashboardFilterBarComponent](#dashboardfilterbarcomponent) - 筛选条件
- [ProjectKanbanComponent](#projectkanbancomponent) - 项目看板
- [TodoSectionComponent](#todosectioncomponent) - 待办任务
- [WorkloadGanttComponent](#workloadganttcomponent) - 工作负载
- [SmartMatchModalComponent](#smartmatchmodalcomponent) - 智能推荐
- [DashboardAlertsComponent](#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' 等） |

### 使用示例

```html
<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） |

### 使用示例

```html
<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} | 质量评审时触发 |

### 使用示例

```html
<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 | 从紧急事件创建待办时触发 |

### 使用示例

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

---

## WorkloadGanttComponent

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

### Props (Inputs)

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

### Events (Outputs)

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

### 使用示例

```html
<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） |

### 使用示例

```html
<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 | 快速筛选时触发 |

### 使用示例

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

---

## 通用类型定义

### Project
```typescript
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
```typescript
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
```typescript
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
```typescript
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. 性能优化
```typescript
// 使用 trackBy 优化 ngFor
<div *ngFor="let item of items; trackBy: trackById">
  {{ item.name }}
</div>

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

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

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

---

**最后更新**: 2024-11-21