|
|
@@ -0,0 +1,386 @@
|
|
|
+# 组长端看板子组件 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
|
|
|
+
|
0235711