first commit

.kiro/specs/employee-performance-system/design.md

@@ -0,0 +1,729 @@
+# 设计文档 - 员工月度绩效考核系统
+
+## 概述
+
+员工月度绩效考核系统是一个基于 Web 的全栈应用，采用前后端分离架构。系统集成 FastGPT AI 评分能力，实现员工绩效填报、AI 自动评分、管理层审核、数据统计分析的完整闭环。
+
+### 技术栈选择
+
+**后端:**
+- Node.js + TypeScript
+- Express.js 框架
+- MySQL 数据库
+- JWT 身份认证
+- Axios（FastGPT API 调用）
+
+**前端:**
+- React + TypeScript
+- Ant Design UI 组件库
+- React Router（路由管理）
+- Axios（HTTP 请求）
+- ECharts（数据可视化）
+
+### 核心设计原则
+
+1. **角色权限分离**: 严格按照员工、管理层、总经理三种角色进行权限控制
+2. **数据安全**: 敏感数据加密存储，操作日志完整记录
+3. **流程自动化**: 绩效提交自动触发 AI 评分，审核完成自动归档
+4. **可扩展性**: 模块化设计，便于后续功能扩展
+
+## 架构设计
+
+### 系统架构图
+
+```mermaid
+graph TB
+    subgraph "前端层"
+        A[员工端页面]
+        B[管理层端页面]
+        C[总经理端页面]
+    end
+    
+    subgraph "API 网关层"
+        D[Express API Server]
+        E[JWT 认证中间件]
+        F[权限验证中间件]
+    end
+    
+    subgraph "业务逻辑层"
+        G[用户服务]
+        H[绩效服务]
+        I[AI 评分服务]
+        J[统计分析服务]
+    end
+    
+    subgraph "数据访问层"
+        K[用户 DAO]
+        L[绩效 DAO]
+        M[AI 结果 DAO]
+    end
+    
+    subgraph "外部服务"
+        N[FastGPT API]
+    end
+    
+    subgraph "数据存储层"
+        O[(MySQL 数据库)]
+    end
+    
+    A --> D
+    B --> D
+    C --> D
+    D --> E
+    E --> F
+    F --> G
+    F --> H
+    F --> J
+    H --> I
+    I --> N
+    G --> K
+    H --> L
+    I --> M
+    K --> O
+    L --> O
+    M --> O
+```
+
+### 数据流设计
+
+**绩效提交流程:**
+```
+员工填报 → 前端验证 → API 提交 → 保存数据库 → 触发 AI 评分 → 调用 FastGPT → 解析结果 → 存储 AI 结果 → 返回成功
+```
+
+**绩效审核流程:**
+```
+管理层查看 → 加载绩效+AI结果 → 调整评分 → 填写意见 → 提交审核 → 计算等级奖惩 → 归档数据 → 通知员工
+```
+
+## 组件与接口
+
+### 后端核心模块
+
+#### 1. 用户认证模块 (AuthService)
+
+**职责**: 处理用户登录、令牌生成与验证
+
+**接口:**
+```typescript
+interface AuthService {
+  // 用户登录
+  login(username: string, password: string, role: string): Promise<LoginResult>;
+  
+  // 验证令牌
+  verifyToken(token: string): Promise<UserInfo>;
+  
+  // 刷新令牌
+  refreshToken(token: string): Promise<string>;
+}
+
+interface LoginResult {
+  token: string;
+  userInfo: UserInfo;
+}
+
+interface UserInfo {
+  userId: number;
+  name: string;
+  role: 'employee' | 'manager' | 'generalManager';
+  department: string;
+  position: string;
+}
+```
+
+#### 2. 绩效管理模块 (PerformanceService)
+
+**职责**: 处理绩效填报、查询、审核等核心业务逻辑
+
+**接口:**
+```typescript
+interface PerformanceService {
+  // 提交绩效（暂存或提交）
+  submitPerformance(data: PerformanceSubmitDTO): Promise<PerformanceResult>;
+  
+  // 查询员工个人绩效
+  getEmployeePerformance(userId: number, month?: string, page?: PageInfo): Promise<PerformanceListResult>;
+  
+  // 查询管理层下属绩效
+  getManagerSubordinates(managerId: number, filters: PerformanceFilter, page: PageInfo): Promise<PerformanceListResult>;
+  
+  // 审核绩效
+  reviewPerformance(perfId: number, reviewData: ReviewDTO): Promise<void>;
+  
+  // 驳回绩效
+  rejectPerformance(perfId: number, reason: string): Promise<void>;
+  
+  // 申请修改绩效
+  requestModification(perfId: number, reason: string): Promise<void>;
+  
+  // 批准修改申请
+  approveModification(perfId: number): Promise<void>;
+}
+
+interface PerformanceSubmitDTO {
+  userId: number;
+  month: string;
+  status: 'draft' | 'submit';
+  selfScore: number;
+  attendance: AttendanceData;
+  workSummary: string;
+  performanceItems: PerformanceItemDTO[];
+}
+
+interface PerformanceItemDTO {
+  itemName: string;
+  weight: number;
+  userContent: string;
+  selfScore: number;
+  evidence?: string;
+}
+
+interface AttendanceData {
+  leave: number;
+  late: number;
+  absent: number;
+  lackCard: number;
+  remark?: string;
+}
+
+interface ReviewDTO {
+  perfId: number;
+  managerScore: number;
+  reviewOpinion: string;
+  itemScores: ItemScoreDTO[];
+}
+
+interface ItemScoreDTO {
+  itemName: string;
+  managerScore: number;
+  scoreExplanation: string;
+}
+```
+
+#### 3. AI 评分模块 (AIEvaluationService)
+
+**职责**: 调用 FastGPT API 进行自动评分和反馈生成
+
+**接口:**
+```typescript
+interface AIEvaluationService {
+  // 执行 AI 评分
+  evaluatePerformance(perfId: number): Promise<AIResult>;
+  
+  // 构建 AI 请求 Prompt
+  buildPrompt(performance: PerformanceRecord): string;
+  
+  // 解析 AI 响应
+  parseAIResponse(response: string): AIScoreData;
+  
+  // 重试机制
+  retryEvaluation(perfId: number, maxRetries: number): Promise<AIResult>;
+}
+
+interface AIResult {
+  aiId: number;
+  perfId: number;
+  aiScoreDetail: AIScoreItem[];
+  aiTotalScore: number;
+  aiProblems: string[];
+  aiSuggestions: string[];
+  createTime: Date;
+}
+
+interface AIScoreItem {
+  itemName: string;
+  weight: number;
+  aiScore: number;
+  scoreExplanation: string;
+}
+```
+
+#### 4. 统计分析模块 (StatisticsService)
+
+**职责**: 提供多维度数据统计和报表生成
+
+**接口:**
+```typescript
+interface StatisticsService {
+  // 获取团队统计
+  getTeamStatistics(managerId: number, month: string): Promise<TeamStats>;
+  
+  // 获取全公司统计
+  getCompanyStatistics(month: string): Promise<CompanyStats>;
+  
+  // 多维度统计
+  getMultiDimensionStats(filters: StatFilter): Promise<MultiDimensionStats>;
+  
+  // 导出 Excel
+  exportToExcel(filters: ExportFilter): Promise<Buffer>;
+}
+
+interface TeamStats {
+  averageScore: number;
+  excellentCount: number;
+  qualifiedCount: number;
+  needMotivationCount: number;
+  totalCount: number;
+}
+
+interface CompanyStats {
+  departmentStats: DepartmentStat[];
+  positionStats: PositionStat[];
+  levelDistribution: LevelDistribution;
+}
+```
+
+### 前端核心组件
+
+#### 1. 员工端组件
+
+```typescript
+// 绩效填报组件
+interface PerformanceFormComponent {
+  props: {
+    month: string;
+    userInfo: UserInfo;
+  };
+  state: {
+    formData: PerformanceFormData;
+    isDraft: boolean;
+  };
+  methods: {
+    handleItemChange(index: number, field: string, value: any): void;
+    handleSave(): Promise<void>;
+    handleSubmit(): Promise<void>;
+    uploadEvidence(file: File): Promise<string>;
+  };
+}
+
+// 个人绩效查看组件
+interface PerformanceHistoryComponent {
+  props: {
+    userId: number;
+  };
+  state: {
+    performanceList: PerformanceRecord[];
+    selectedMonth: string;
+    pagination: PaginationState;
+  };
+  methods: {
+    loadPerformanceList(): Promise<void>;
+    viewDetail(perfId: number): void;
+    filterByMonth(month: string): void;
+  };
+}
+```
+
+#### 2. 管理层端组件
+
+```typescript
+// 下属绩效列表组件
+interface SubordinateListComponent {
+  props: {
+    managerId: number;
+  };
+  state: {
+    subordinateList: PerformanceRecord[];
+    filters: PerformanceFilter;
+    pagination: PaginationState;
+  };
+  methods: {
+    loadSubordinateList(): Promise<void>;
+    applyFilters(filters: PerformanceFilter): void;
+    viewDetail(perfId: number): void;
+  };
+}
+
+// 绩效审核组件
+interface PerformanceReviewComponent {
+  props: {
+    perfId: number;
+  };
+  state: {
+    performanceData: PerformanceRecord;
+    aiResult: AIResult;
+    reviewForm: ReviewFormData;
+  };
+  methods: {
+    loadPerformanceDetail(): Promise<void>;
+    adjustScore(itemName: string, score: number): void;
+    submitReview(): Promise<void>;
+    rejectPerformance(reason: string): Promise<void>;
+  };
+}
+```
+
+#### 3. 总经理端组件
+
+```typescript
+// 全局统计组件
+interface CompanyStatisticsComponent {
+  props: {
+    month: string;
+  };
+  state: {
+    companyStats: CompanyStats;
+    chartData: ChartData;
+    selectedDimension: string;
+  };
+  methods: {
+    loadStatistics(): Promise<void>;
+    switchDimension(dimension: string): void;
+    exportData(): Promise<void>;
+  };
+}
+```
+
+## 数据模型
+
+### 数据库表设计
+
+#### 1. 用户表 (user)
+
+```sql
+CREATE TABLE user (
+  user_id INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
+  username VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名（工号）',
+  password VARCHAR(255) NOT NULL COMMENT '密码（加密存储）',
+  name VARCHAR(50) NOT NULL COMMENT '姓名',
+  role ENUM('employee', 'manager', 'generalManager') NOT NULL COMMENT '角色',
+  department VARCHAR(50) NOT NULL COMMENT '部门',
+  position VARCHAR(50) NOT NULL COMMENT '岗位',
+  manager_id INT COMMENT '直属管理层ID',
+  status ENUM('active', 'inactive') DEFAULT 'active' COMMENT '状态',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_role (role),
+  INDEX idx_manager (manager_id),
+  FOREIGN KEY (manager_id) REFERENCES user(user_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
+```
+
+#### 2. 绩效主表 (performance_month)
+
+```sql
+CREATE TABLE performance_month (
+  perf_id INT PRIMARY KEY AUTO_INCREMENT COMMENT '绩效记录ID',
+  user_id INT NOT NULL COMMENT '员工ID',
+  month VARCHAR(7) NOT NULL COMMENT '考核月份（YYYY-MM）',
+  status ENUM('draft', 'submitted', 'under_review', 'completed', 'rejected') NOT NULL COMMENT '状态',
+  self_score DECIMAL(5,2) COMMENT '员工自评总分',
+  ai_score DECIMAL(5,2) COMMENT 'AI评分总分',
+  manager_score DECIMAL(5,2) COMMENT '管理层审核总分',
+  total_score DECIMAL(5,2) COMMENT '最终总分',
+  level ENUM('excellent', 'qualified', 'need_motivation', 'unqualified') COMMENT '绩效等级',
+  reward_punish VARCHAR(255) COMMENT '奖惩说明',
+  work_summary TEXT COMMENT '工作汇总',
+  submit_time TIMESTAMP COMMENT '提交时间',
+  review_time TIMESTAMP COMMENT '审核时间',
+  review_opinion TEXT COMMENT '审核意见',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_user_month (user_id, month),
+  INDEX idx_status (status),
+  INDEX idx_month (month),
+  FOREIGN KEY (user_id) REFERENCES user(user_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='绩效主表';
+```
+
+#### 3. 绩效项明细表 (perf_item)
+
+```sql
+CREATE TABLE perf_item (
+  item_id INT PRIMARY KEY AUTO_INCREMENT COMMENT '绩效项ID',
+  perf_id INT NOT NULL COMMENT '绩效记录ID',
+  item_name VARCHAR(100) NOT NULL COMMENT '考核项名称',
+  item_category ENUM('business', 'comprehensive') NOT NULL COMMENT '考核项类别',
+  weight INT NOT NULL COMMENT '权重（分数）',
+  user_content TEXT COMMENT '员工填写内容',
+  self_score DECIMAL(5,2) COMMENT '员工自评分',
+  ai_score DECIMAL(5,2) COMMENT 'AI评分',
+  ai_explanation TEXT COMMENT 'AI评分说明',
+  manager_score DECIMAL(5,2) COMMENT '管理层评分',
+  manager_explanation TEXT COMMENT '管理层评分说明',
+  evidence_url VARCHAR(500) COMMENT '佐证材料URL',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_perf (perf_id),
+  FOREIGN KEY (perf_id) REFERENCES performance_month(perf_id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='绩效项明细表';
+```
+
+#### 4. 考勤表 (attendance)
+
+```sql
+CREATE TABLE attendance (
+  attendance_id INT PRIMARY KEY AUTO_INCREMENT COMMENT '考勤ID',
+  perf_id INT NOT NULL COMMENT '绩效记录ID',
+  leave_days INT DEFAULT 0 COMMENT '事假天数',
+  late_times INT DEFAULT 0 COMMENT '迟到次数',
+  absent_days INT DEFAULT 0 COMMENT '旷工天数',
+  lack_card_times INT DEFAULT 0 COMMENT '缺卡次数',
+  attendance_score DECIMAL(5,2) COMMENT '考勤得分',
+  remark TEXT COMMENT '备注',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_perf (perf_id),
+  FOREIGN KEY (perf_id) REFERENCES performance_month(perf_id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='考勤表';
+```
+
+#### 5. AI 结果表 (ai_result)
+
+```sql
+CREATE TABLE ai_result (
+  ai_id INT PRIMARY KEY AUTO_INCREMENT COMMENT 'AI结果ID',
+  perf_id INT NOT NULL COMMENT '绩效记录ID',
+  ai_score_json TEXT NOT NULL COMMENT 'AI评分详情（JSON格式）',
+  ai_total_score DECIMAL(5,2) NOT NULL COMMENT 'AI总分',
+  problems TEXT COMMENT 'AI总结的问题（JSON数组）',
+  suggestions TEXT COMMENT 'AI改进建议（JSON数组）',
+  api_response TEXT COMMENT 'FastGPT原始响应',
+  create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '生成时间',
+  UNIQUE KEY uk_perf (perf_id),
+  FOREIGN KEY (perf_id) REFERENCES performance_month(perf_id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='AI结果表';
+```
+
+#### 6. 操作日志表 (operation_log)
+
+```sql
+CREATE TABLE operation_log (
+  log_id INT PRIMARY KEY AUTO_INCREMENT COMMENT '日志ID',
+  user_id INT NOT NULL COMMENT '操作人ID',
+  operation_type VARCHAR(50) NOT NULL COMMENT '操作类型',
+  target_type VARCHAR(50) COMMENT '目标类型',
+  target_id INT COMMENT '目标ID',
+  operation_detail TEXT COMMENT '操作详情',
+  ip_address VARCHAR(50) COMMENT 'IP地址',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_user (user_id),
+  INDEX idx_created (created_at),
+  FOREIGN KEY (user_id) REFERENCES user(user_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='操作日志表';
+```
+
+### 数据关系图
+
+```mermaid
+erDiagram
+    USER ||--o{ PERFORMANCE_MONTH : "has"
+    USER ||--o{ USER : "manages"
+    PERFORMANCE_MONTH ||--|{ PERF_ITEM : "contains"
+    PERFORMANCE_MONTH ||--|| ATTENDANCE : "has"
+    PERFORMANCE_MONTH ||--|| AI_RESULT : "has"
+    USER ||--o{ OPERATION_LOG : "performs"
+    
+    USER {
+        int user_id PK
+        string username
+        string password
+        string name
+        enum role
+        string department
+        string position
+        int manager_id FK
+    }
+    
+    PERFORMANCE_MONTH {
+        int perf_id PK
+        int user_id FK
+        string month
+        enum status
+        decimal self_score
+        decimal ai_score
+        decimal manager_score
+        decimal total_score
+        enum level
+    }
+    
+    PERF_ITEM {
+        int item_id PK
+        int perf_id FK
+        string item_name
+        enum item_category
+        int weight
+        text user_content
+        decimal self_score
+        decimal ai_score
+        decimal manager_score
+    }
+    
+    ATTENDANCE {
+        int attendance_id PK
+        int perf_id FK
+        int leave_days
+        int late_times
+        int absent_days
+        int lack_card_times
+        decimal attendance_score
+    }
+    
+    AI_RESULT {
+        int ai_id PK
+        int perf_id FK
+        text ai_score_json
+        decimal ai_total_score
+        text problems
+        text suggestions
+    }
+```
+
+## 正确性属性
+
+*正确性属性是系统应该在所有有效执行中保持为真的特征或行为——本质上是关于系统应该做什么的形式化陈述。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
+
+### 属性 1: 认证正确性
+
+*对于任意* 用户凭据（用户名、密码、角色），认证结果应与凭据有效性严格一致——有效凭据必须返回 token，无效凭据必须被拒绝，不存在中间状态。
+
+**Validates: Requirements 1.1, 1.2**
+
+---
+
+### 属性 2: 权限隔离不变量
+
+*对于任意* 员工用户，使用其 token 查询其他员工的绩效数据时，系统应始终返回 403 权限不足错误，不泄露任何数据。
+
+**Validates: Requirements 1.5**
+
+---
+
+### 属性 3: 草稿暂存往返一致性
+
+*对于任意* 绩效填报数据，暂存后再读取，返回的数据应与暂存时提交的数据完全一致（往返属性）。
+
+**Validates: Requirements 2.5**
+
+---
+
+### 属性 4: 提交幂等性
+
+*对于任意* 已提交状态的绩效记录，再次尝试提交同一用户同一月份的绩效时，系统应拒绝并返回错误，绩效记录状态保持不变。
+
+**Validates: Requirements 2.6**
+
+---
+
+### 属性 5: 绩效等级与奖惩计算正确性
+
+*对于任意* 最终总分（0-100），系统计算出的绩效等级和奖惩金额应严格符合以下规则：
+- 分数 >= 90 → 优秀，奖励
+- 80 <= 分数 <= 89 → 合格，扣 100 元
+- 70 <= 分数 <= 79 → 合格，扣 200 元
+- 60 <= 分数 <= 69 → 需激励，扣 300 元
+- 分数 < 60 → 不合格，扣 600 元
+
+**Validates: Requirements 5.1, 5.2, 5.3, 5.4, 5.5**
+
+---
+
+### 属性 6: 连续低分预警正确性
+
+*对于任意* 员工，若其连续 N 个月（N >= 2）的最终总分均低于 60 分，系统应正确标记对应的预警状态（N=2 书面警告，N>=3 劝退处理）。
+
+**Validates: Requirements 5.6, 5.7**
+
+---
+
+### 属性 7: 绩效记录查询完整性
+
+*对于任意* 已提交或已完成的绩效记录，员工查询个人历史绩效时，该记录必须出现在结果列表中，且内容与提交时一致（插入/查询往返属性）。
+
+**Validates: Requirements 6.1, 6.2**
+
+---
+
+### 属性 8: 考勤分数计算正确性
+
+*对于任意* 考勤数据（事假天数、迟到次数、缺卡次数），系统计算的考勤分数应满足：
+- 基础分 10 分
+- 每天事假扣 5 分
+- 每次迟到/缺卡扣 2 分
+- 最终分数不低于 0 分（下限保护）
+
+**Validates: Requirements 11.1, 11.2, 11.3, 11.5**
+
+---
+
+### 属性 9: AI 响应 JSON 解析往返一致性
+
+*对于任意* 符合规范的 AI 评分 JSON 字符串，系统解析后再序列化，应得到语义等价的对象（解析往返属性）。
+
+**Validates: Requirements 3.6, 13.3**
+
+---
+
+### 属性 10: AI 输出格式约束
+
+*对于任意* AI 评分结果，`ai_problems` 和 `ai_suggestions` 数组的长度应在 3 到 5 之间（含边界值）。
+
+**Validates: Requirements 3.3, 3.4**
+
+---
+
+## 错误处理
+
+### 错误码规范
+
+| 状态码 | 含义 | 场景 |
+|--------|------|------|
+| 200 | 成功 | 正常响应 |
+| 400 | 参数错误 | 请求参数缺失或格式错误 |
+| 401 | 未登录/Token 失效 | Token 过期或未携带 |
+| 403 | 权限不足 | 越权访问他人数据 |
+| 500 | 服务器异常 | 内部错误 |
+
+### 关键错误场景处理
+
+**AI 调用失败:**
+- 超时（>10s）：记录错误日志，绩效状态标记为 `ai_failed`，管理员可手动触发重试
+- 返回格式异常：记录原始响应，尝试降级解析，失败则通知管理员
+
+**数据库操作失败:**
+- 使用事务保证绩效提交的原子性（绩效主表 + 绩效项 + 考勤数据同时写入）
+- 失败时回滚并返回 500 错误
+
+**并发提交冲突:**
+- 利用 `UNIQUE KEY uk_user_month (user_id, month)` 数据库约束防止重复提交
+- 捕获唯一键冲突异常，返回友好提示
+
+## 测试策略
+
+### 双重测试方法
+
+系统采用单元测试和属性测试相结合的方式，两者互补：
+
+- **单元测试**: 验证具体示例、边界条件和错误场景
+- **属性测试**: 验证跨所有输入的通用属性
+
+### 属性测试配置
+
+- 使用 **fast-check**（TypeScript 属性测试库）
+- 每个属性测试最少运行 **100 次迭代**
+- 每个测试用注释标注对应的设计属性编号
+- 标注格式: `// Feature: employee-performance-system, Property N: <属性描述>`
+
+### 属性测试覆盖
+
+| 属性编号 | 测试内容 | 测试类型 |
+|----------|----------|----------|
+| 属性 1 | 认证凭据有效性 | property |
+| 属性 2 | 权限隔离 | property |
+| 属性 3 | 草稿暂存往返 | property |
+| 属性 4 | 提交幂等性 | property |
+| 属性 5 | 等级奖惩计算 | property |
+| 属性 6 | 连续低分预警 | property |
+| 属性 7 | 绩效记录查询 | property |
+| 属性 8 | 考勤分数计算 | property |
+| 属性 9 | AI JSON 解析往返 | property |
+| 属性 10 | AI 输出格式约束 | property |
+
+### 单元测试覆盖
+
+- 用户登录接口（具体示例：正确凭据、错误密码、不存在用户）
+- 绩效提交接口（具体示例：暂存、提交、重复提交）
+- 审核流程（具体示例：通过、驳回、修改申请）
+- Excel 导出格式验证
+- 分页查询边界条件（第一页、最后一页、空结果）
+

.kiro/specs/employee-performance-system/requirements.md

@@ -0,0 +1,188 @@
+# 需求文档 - 员工月度绩效考核系统
+
+## 简介
+
+优一科技员工月度绩效考核系统是一个用于规范化、自动化管理员工月度绩效考核的系统。系统覆盖员工、管理层、总经理三类角色，以月度为周期进行绩效考核，集成 AI 自动评分功能，实现绩效填报、审核、统计分析的全流程管理。
+
+## 术语表
+
+- **System**: 员工月度绩效考核系统
+- **Employee**: 员工角色，负责填报个人绩效
+- **Manager**: 管理层角色，负责审核下属员工绩效
+- **General_Manager**: 总经理角色，负责全公司绩效查看和统计分析
+- **Performance_Record**: 绩效记录，包含员工某月的完整绩效数据
+- **AI_Evaluator**: AI 评分模块，基于 FastGPT 实现自动打分和建议生成
+- **Business_Quality**: 业务素质考评，占总分 70%
+- **Comprehensive_Quality**: 综合素质考评，占总分 30%
+- **Performance_Cycle**: 绩效考核周期，为自然月
+- **Submission_Period**: 提交期，每月 1-5 日
+- **Review_Period**: 审核期，每月 6-10 日
+
+## 需求
+
+### 需求 1: 用户认证与权限管理
+
+**用户故事:** 作为系统用户，我希望能够安全登录系统并根据我的角色访问相应的功能，以便保护数据安全和隐私。
+
+#### 验收标准
+
+1. WHEN 用户提供有效的用户名、密码和角色信息 THEN THE System SHALL 验证凭据并返回有效的访问令牌
+2. WHEN 用户提供无效的登录凭据 THEN THE System SHALL 拒绝访问并返回明确的错误信息
+3. WHEN 用户访问需要权限的资源 THEN THE System SHALL 验证用户角色并仅允许授权访问
+4. WHEN 访问令牌过期（24小时后）THEN THE System SHALL 要求用户重新登录
+5. THE System SHALL 确保员工仅能访问个人数据，管理层仅能访问下属数据，总经理可访问全量数据
+
+### 需求 2: 员工绩效填报
+
+**用户故事:** 作为员工，我希望能够在每月 1-5 日填写上月绩效内容，以便完成月度绩效考核。
+
+#### 验收标准
+
+1. WHEN 员工在提交期（每月 1-5 日）访问填报页面 THEN THE System SHALL 显示当前考核月份和员工基础信息
+2. WHEN 员工填写绩效内容 THEN THE System SHALL 要求填写 17 项考核指标（业务素质 9 项 + 综合素质 8 项）的完成情况描述和自评分数
+3. WHEN 员工填写考勤数据 THEN THE System SHALL 记录事假、病假、迟到、旷工、缺卡的具体次数及说明
+4. WHEN 员工上传佐证材料 THEN THE System SHALL 支持上传文件（截图、文档、代码片段等）作为可选附件
+5. WHEN 员工选择暂存 THEN THE System SHALL 保存草稿并允许后续继续编辑
+6. WHEN 员工选择提交 THEN THE System SHALL 锁定表单并触发 AI 评分流程
+7. WHEN 员工提交后需要修改 THEN THE System SHALL 要求员工向管理层申请退回修改
+
+### 需求 3: AI 自动评分与反馈
+
+**用户故事:** 作为系统，我需要在员工提交绩效后自动调用 AI 进行评分和反馈生成，以便提供客观的初步评估。
+
+#### 验收标准
+
+1. WHEN 员工提交绩效记录 THEN THE System SHALL 自动调用 FastGPT API 进行 AI 评分
+2. WHEN AI 评分完成 THEN THE System SHALL 存储每个考核项的 AI 评分、评分说明、总分（业务素质 70% + 综合素质 30%）
+3. WHEN AI 分析完成 THEN THE System SHALL 生成 3-5 条核心问题总结
+4. WHEN AI 分析完成 THEN THE System SHALL 生成 3-5 条具体可落地的改进建议
+5. WHEN AI 调用失败或超时（>10秒）THEN THE System SHALL 记录错误并通知管理员
+6. THE System SHALL 确保 AI 返回的数据格式为标准 JSON 并可被系统正确解析
+
+### 需求 4: 管理层绩效审核
+
+**用户故事:** 作为管理层，我希望能够在每月 6-10 日审核下属员工的绩效，以便完成最终评分和反馈。
+
+#### 验收标准
+
+1. WHEN 管理层在审核期（每月 6-10 日）访问审核页面 THEN THE System SHALL 显示所有下属员工的绩效提交列表
+2. WHEN 管理层查看员工绩效 THEN THE System SHALL 显示员工填报内容、自评分数、AI 评分及 AI 反馈
+3. WHEN 管理层调整评分 THEN THE System SHALL 允许修改每个考核项的分数并要求填写调整原因
+4. WHEN 管理层填写审核意见 THEN THE System SHALL 记录详细的审核意见说明
+5. WHEN 管理层审核通过 THEN THE System SHALL 计算最终总分、确定绩效等级和奖惩说明，并归档绩效记录
+6. WHEN 管理层驳回绩效 THEN THE System SHALL 要求填写驳回原因并通知员工修改
+7. WHEN 管理层审核完成 THEN THE System SHALL 锁定绩效记录不可随意修改
+
+### 需求 5: 绩效等级与奖惩计算
+
+**用户故事:** 作为系统，我需要根据最终总分自动计算绩效等级和奖惩金额，以便明确员工的考核结果。
+
+#### 验收标准
+
+1. WHEN 最终总分 >= 90 分 THEN THE System SHALL 标记为"优秀"等级并说明按公司规定给予奖励
+2. WHEN 最终总分在 80-89 分 THEN THE System SHALL 标记为"合格"等级并说明扣除当月绩效工资 100 元
+3. WHEN 最终总分在 70-79 分 THEN THE System SHALL 标记为"合格"等级并说明扣除当月绩效工资 200 元
+4. WHEN 最终总分在 60-69 分 THEN THE System SHALL 标记为"需激励"等级并说明扣除当月绩效工资 300 元
+5. WHEN 最终总分 < 60 分 THEN THE System SHALL 标记为"不合格"等级并说明扣除当月绩效工资 600 元
+6. WHEN 员工连续 2 个月考核分数低于 60 分 THEN THE System SHALL 标记需要书面警告
+7. WHEN 员工连续 3 个月考核分数低于 60 分 THEN THE System SHALL 标记需要劝退处理
+
+### 需求 6: 个人绩效查看
+
+**用户故事:** 作为员工，我希望能够查看我的历史绩效记录和 AI 反馈，以便了解自己的工作表现和改进方向。
+
+#### 验收标准
+
+1. WHEN 员工访问个人绩效页面 THEN THE System SHALL 显示所有历史月份的绩效记录列表
+2. WHEN 员工查看某月绩效详情 THEN THE System SHALL 显示填报内容、自评分数、AI 评分、管理层评分、最终总分和等级
+3. WHEN 员工查看 AI 反馈 THEN THE System SHALL 显示 AI 总结的问题和改进建议
+4. WHEN 员工查看奖惩说明 THEN THE System SHALL 显示当月绩效对应的奖惩情况
+5. THE System SHALL 支持按月份筛选和分页查看历史绩效
+
+### 需求 7: 管理层数据查看与导出
+
+**用户故事:** 作为管理层，我希望能够查看和导出下属员工的绩效数据，以便进行团队管理和统计分析。
+
+#### 验收标准
+
+1. WHEN 管理层访问团队绩效页面 THEN THE System SHALL 显示下属员工的绩效列表
+2. WHEN 管理层筛选数据 THEN THE System SHALL 支持按考核月份、部门、员工姓名、绩效状态进行筛选
+3. WHEN 管理层导出数据 THEN THE System SHALL 生成 Excel 格式的绩效表
+4. WHEN 管理层查看团队统计 THEN THE System SHALL 显示团队绩效平均分
+5. WHEN 管理层查看团队统计 THEN THE System SHALL 显示优秀、合格、需激励员工的人数及占比
+6. THE System SHALL 支持导出单个员工的历史绩效或所有下属的当月/指定时间段绩效
+
+### 需求 8: 总经理全局管理
+
+**用户故事:** 作为总经理，我希望能够查看全公司的绩效数据并进行多维度统计分析，以便掌握公司整体绩效水平。
+
+#### 验收标准
+
+1. WHEN 总经理访问全局绩效页面 THEN THE System SHALL 显示各部门、各岗位的月度绩效整体情况
+2. WHEN 总经理进行统计分析 THEN THE System SHALL 支持按考核月份、部门、岗位、绩效等级等维度进行统计
+3. WHEN 总经理查看统计报表 THEN THE System SHALL 生成可视化图表（柱状图、饼图等）
+4. WHEN 总经理导出数据 THEN THE System SHALL 支持导出全公司所有员工的所有月份绩效数据
+5. WHEN 总经理配置考核规则 THEN THE System SHALL 允许修改考核指标权重、评分标准、奖惩金额
+6. WHEN 考核规则修改后 THEN THE System SHALL 自动应用于后续考核周期
+
+### 需求 9: 数据持久化与历史追溯
+
+**用户故事:** 作为系统管理员，我需要确保所有绩效数据被安全存储并可追溯，以便满足审计和合规要求。
+
+#### 验收标准
+
+1. WHEN 绩效数据生成或修改 THEN THE System SHALL 将数据持久化存储到 MySQL 数据库
+2. WHEN 用户查询历史数据 THEN THE System SHALL 能够检索任意历史月份的绩效记录
+3. WHEN 绩效数据被修改 THEN THE System SHALL 记录修改人、修改时间、修改内容
+4. WHEN 管理层审核完成 THEN THE System SHALL 将绩效数据归档并标记为不可随意修改
+5. THE System SHALL 对员工个人信息、绩效奖惩等敏感数据进行加密存储
+6. THE System SHALL 支持数据备份与恢复功能
+
+### 需求 10: 系统性能与稳定性
+
+**用户故事:** 作为系统用户，我希望系统运行稳定、响应迅速，以便高效完成绩效考核工作。
+
+#### 验收标准
+
+1. WHEN 用户访问页面 THEN THE System SHALL 在 2 秒内完成页面加载
+2. WHEN 员工提交绩效 THEN THE System SHALL 确保提交成功率 >= 99%
+3. WHEN AI 评分被触发 THEN THE System SHALL 在 10 秒内返回评分结果
+4. WHEN 管理层审核绩效 THEN THE System SHALL 确保审核操作成功率 >= 99%
+5. THE System SHALL 支持主流 PC 浏览器（Chrome、Edge、Firefox）
+6. WHEN 系统出现异常 THEN THE System SHALL 记录错误日志并提供友好的错误提示
+
+### 需求 11: 考勤数据处理
+
+**用户故事:** 作为系统，我需要根据员工填写的考勤数据自动计算考勤分数，以便准确评估综合素质。
+
+#### 验收标准
+
+1. WHEN 员工全勤（无事假、迟到、缺卡、旷工）THEN THE System SHALL 给予考勤满分 10 分
+2. WHEN 员工有事假记录 THEN THE System SHALL 每天扣除 5 分
+3. WHEN 员工有迟到或缺卡记录 THEN THE System SHALL 每次扣除 2 分
+4. WHEN 员工有旷工记录 THEN THE System SHALL 按公司制度另行处理
+5. THE System SHALL 确保考勤分数不低于 0 分
+
+### 需求 12: 绩效修改申请流程
+
+**用户故事:** 作为员工，当我提交绩效后发现需要修改时，我希望能够向管理层申请退回修改，以便更正错误信息。
+
+#### 验收标准
+
+1. WHEN 员工提交绩效后需要修改 THEN THE System SHALL 提供"申请修改"功能
+2. WHEN 员工发起修改申请 THEN THE System SHALL 通知所属管理层
+3. WHEN 管理层同意修改申请 THEN THE System SHALL 解锁绩效表单并允许员工重新编辑
+4. WHEN 管理层拒绝修改申请 THEN THE System SHALL 通知员工并说明拒绝原因
+5. WHEN 员工修改完成后 THEN THE System SHALL 要求重新提交并触发新的 AI 评分
+
+### 需求 13: FastGPT 集成
+
+**用户故事:** 作为系统开发者，我需要正确集成 FastGPT API，以便实现 AI 自动评分功能。
+
+#### 验收标准
+
+1. WHEN 系统调用 FastGPT API THEN THE System SHALL 使用正确的 API-Key 和模型配置
+2. WHEN 构建 AI 请求 THEN THE System SHALL 包含员工岗位、考核月份、填报内容、考核规则等完整参数
+3. WHEN 接收 AI 响应 THEN THE System SHALL 验证返回的 JSON 格式是否符合预期结构
+4. WHEN AI 返回无效数据 THEN THE System SHALL 记录错误并提供降级处理方案
+5. THE System SHALL 确保 AI 调用的安全性，防止敏感信息泄露

.kiro/specs/employee-performance-system/tasks.md

@@ -0,0 +1,192 @@
+# 实施计划 - 员工月度绩效考核系统
+
+## 概述
+
+按照前后端分离架构，分阶段实施：先搭建后端基础设施和核心业务逻辑，再实现前端各角色页面，最后集成 AI 评分和统计分析功能。
+
+## 任务
+
+- [x] 1. 项目初始化与基础设施搭建
+  - 初始化后端 Node.js + TypeScript + Express 项目结构
+  - 初始化前端 React + TypeScript + Ant Design 项目结构
+  - 配置 MySQL 数据库连接（使用 mysql2 驱动）
+  - 创建数据库初始化脚本（6张表的 DDL）
+  - 配置环境变量（.env：DB连接、JWT密钥、FastGPT API Key）
+  - _Requirements: 9.1, 10.5_
+
+- [x] 2. 用户认证模块
+  - [x] 2.1 实现用户登录接口 `/api/user/login`
+    - 查询用户表验证用户名、密码（bcrypt 比对）和角色
+    - 生成 JWT token（有效期 24 小时），返回 userInfo
+    - _Requirements: 1.1, 1.2_
+  - [x] 2.2 实现 JWT 认证中间件
+    - 验证请求头中的 token，解析用户信息注入 req.user
+    - token 过期或无效时返回 401
+    - _Requirements: 1.4_
+  - [x] 2.3 实现角色权限中间件
+    - 根据路由配置允许的角色列表，验证当前用户角色
+    - 权限不足时返回 403
+    - _Requirements: 1.3, 1.5_
+  - [x] 2.4 编写认证模块属性测试
+
+    - **属性 1: 认证正确性** — 对任意凭据，认证结果与凭据有效性一致
+    - **属性 2: 权限隔离不变量** — 员工无法访问他人数据
+    - **Validates: Requirements 1.1, 1.2, 1.5**
+
+- [x] 3. 数据库访问层（DAO）
+  - [x] 3.1 实现 UserDAO
+    - `findByUsername(username)`: 按用户名查询
+    - `findSubordinates(managerId)`: 查询下属列表
+    - _Requirements: 1.1, 4.1_
+  - [x] 3.2 实现 PerformanceDAO
+    - `upsert(data)`: 创建或更新绩效记录（支持暂存/提交）
+    - `findByUserAndMonth(userId, month)`: 查询指定月份绩效
+    - `findByManagerId(managerId, filters, page)`: 查询下属绩效列表
+    - `updateStatus(perfId, status)`: 更新绩效状态
+    - `updateReview(perfId, reviewData)`: 更新审核结果
+    - _Requirements: 2.5, 2.6, 4.1, 4.5, 9.1_
+  - [x] 3.3 实现 AIResultDAO
+    - `save(aiResult)`: 保存 AI 评分结果
+    - `findByPerfId(perfId)`: 查询绩效对应的 AI 结果
+    - _Requirements: 3.2, 3.3_
+
+- [x] 4. 考勤分数计算与绩效等级模块
+  - [x] 4.1 实现考勤分数计算函数 `calculateAttendanceScore`
+    - 基础分 10 分，事假每天扣 5 分，迟到/缺卡每次扣 2 分，下限 0 分
+    - _Requirements: 11.1, 11.2, 11.3, 11.5_
+  - [x] 4.2 实现绩效等级与奖惩计算函数 `calculateLevelAndReward`
+    - 根据总分返回等级（excellent/qualified/need_motivation/unqualified）和奖惩说明
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5_
+  - [x] 4.3 实现连续低分预警检测函数 `checkConsecutiveLowScore`
+    - 查询员工最近 N 个月记录，检测连续低于 60 分的情况
+    - _Requirements: 5.6, 5.7_
+  - [x] 4.4 编写计算模块属性测试
+
+    - **属性 5: 绩效等级与奖惩计算正确性** — 对任意分数，等级和奖惩符合规则
+    - **属性 6: 连续低分预警正确性** — 连续低分正确触发预警
+    - **属性 8: 考勤分数计算正确性** — 对任意考勤数据，分数计算正确且不低于 0
+    - **Validates: Requirements 5.1-5.7, 11.1-11.5**
+
+- [x] 5. 检查点 — 确保所有测试通过，如有问题请告知
+
+- [x] 6. 员工端绩效填报接口
+  - [x] 6.1 实现绩效提交接口 `/api/performance/submit`
+    - 支持 draft（暂存）和 submit（提交）两种状态
+    - 使用数据库事务同时写入 performance_month、perf_item、attendance 三张表
+    - 提交时触发异步 AI 评分（不阻塞响应）
+    - _Requirements: 2.1, 2.2, 2.3, 2.5, 2.6_
+  - [x] 6.2 实现个人绩效查询接口 `/api/performance/employee/get`
+    - 支持按月份筛选和分页
+    - 返回绩效记录含 AI 结果、考勤、审核意见
+    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5_
+  - [x] 6.3 实现修改申请接口 `/api/performance/request-modification`
+    - 员工发起申请，记录申请原因，通知管理层
+    - _Requirements: 12.1, 12.2_
+  - [x] 6.4 编写员工端接口属性测试
+
+    - **属性 3: 草稿暂存往返一致性** — 暂存后读取数据一致
+    - **属性 4: 提交幂等性** — 同一用户同月不可重复提交
+    - **属性 7: 绩效记录查询完整性** — 提交后查询必能找到
+    - **Validates: Requirements 2.5, 2.6, 6.1**
+
+- [x] 7. AI 评分模块
+  - [x] 7.1 实现 FastGPT 调用服务 `AIEvaluationService`
+    - 构建包含岗位、月份、填报内容、考核规则的 Prompt
+    - 调用 FastGPT API（超时 10s）
+    - _Requirements: 13.1, 13.2_
+  - [x] 7.2 实现 AI 响应解析函数 `parseAIResponse`
+    - 解析 JSON 格式响应，提取 ai_score_detail、ai_total_score、ai_problems、ai_suggestions
+    - 验证格式合法性，异常时记录原始响应并抛出错误
+    - _Requirements: 3.2, 3.3, 3.4, 13.3, 13.4_
+  - [x] 7.3 实现重试机制（最多 3 次）和错误降级处理
+    - _Requirements: 3.5_
+  - [x] 7.4 编写 AI 模块属性测试
+
+    - **属性 9: AI 响应 JSON 解析往返一致性** — 解析后序列化得到等价对象
+    - **属性 10: AI 输出格式约束** — problems 和 suggestions 数组长度在 3-5 之间
+    - **Validates: Requirements 3.3, 3.4, 3.6**
+
+- [x] 8. 管理层审核接口
+  - [x] 8.1 实现下属绩效列表接口 `/api/performance/manager/list`
+    - 支持按月份、部门、员工姓名、状态筛选和分页
+    - _Requirements: 4.1, 7.1, 7.2_
+  - [x] 8.2 实现绩效审核接口 `/api/performance/manager/review`
+    - 更新各考核项管理层评分和说明
+    - 计算最终总分、等级、奖惩，归档绩效记录（状态改为 completed）
+    - _Requirements: 4.3, 4.4, 4.5, 4.7_
+  - [x] 8.3 实现绩效驳回接口 `/api/performance/manager/reject`
+    - 记录驳回原因，状态改为 rejected
+    - _Requirements: 4.6_
+  - [x] 8.4 实现修改申请审批接口 `/api/performance/manager/approve-modification`
+    - 同意时解锁绩效记录，拒绝时通知员工
+    - _Requirements: 12.3, 12.4_
+
+- [x] 9. 检查点 — 确保所有测试通过，如有问题请告知
+
+- [x] 10. 统计分析与导出接口
+  - [x] 10.1 实现团队统计接口 `/api/statistics/team`
+    - 统计下属团队平均分、优秀/合格/需激励人数及占比
+    - _Requirements: 7.4, 7.5_
+  - [x] 10.2 实现全公司统计接口 `/api/statistics/company`
+    - 按部门、岗位、绩效等级多维度统计
+    - _Requirements: 8.1, 8.2_
+  - [x] 10.3 实现 Excel 导出接口 `/api/performance/export`
+    - 使用 exceljs 生成 Excel 文件，支持单员工历史和团队批量导出
+    - _Requirements: 7.3, 7.6, 8.4_
+
+- [x] 11. 总经理端接口
+  - [x] 11.1 实现考核规则配置接口 `/api/config/rules`
+    - 支持修改考核指标权重、评分标准、奖惩金额
+    - 修改后记录操作日志，应用于后续考核周期
+    - _Requirements: 8.5, 8.6_
+
+- [x] 12. 前端基础框架搭建
+  - [x] 12.1 配置 React Router，定义三类角色的路由结构
+    - 员工路由：`/employee/*`，管理层路由：`/manager/*`，总经理路由：`/gm/*`
+    - _Requirements: 1.3_
+  - [x] 12.2 实现登录页面和 AuthContext
+    - 登录表单（用户名、密码、角色选择），登录成功后存储 token 跳转对应角色首页
+    - _Requirements: 1.1, 1.2_
+  - [x] 12.3 实现 Axios 请求拦截器
+    - 自动携带 token，处理 401/403 响应（跳转登录页）
+    - _Requirements: 1.4_
+
+- [x] 13. 员工端前端页面
+  - [x] 13.1 实现绩效填报页面 `PerformanceForm`
+    - 自动带出考核月份、员工基础信息
+    - 17 项考核指标逐项填写（完成情况描述 + 自评分 + 可选佐证上传）
+    - 考勤数据填写区域、工作汇总文本区域、暂存和提交按钮
+    - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6_
+  - [x] 13.2 实现个人绩效历史页面 `PerformanceHistory`
+    - 绩效记录列表（含状态、总分、等级），月份筛选和分页
+    - 点击查看详情（含 AI 评分、AI 问题/建议、审核意见、奖惩说明）
+    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5_
+
+- [x] 14. 管理层端前端页面
+  - [x] 14.1 实现下属绩效列表页面 `SubordinateList`
+    - 列表展示员工绩效状态，筛选条件（月份、部门、姓名、状态）
+    - _Requirements: 4.1, 7.1, 7.2_
+  - [x] 14.2 实现绩效审核页面 `PerformanceReview`
+    - 展示员工填报内容、自评分、AI 评分及 AI 反馈
+    - 可调整各考核项分数并填写说明，提交审核通过或驳回
+    - _Requirements: 4.2, 4.3, 4.4, 4.5, 4.6_
+  - [x] 14.3 实现团队统计页面 `TeamStatistics`
+    - 显示团队平均分、各等级人数及占比，Excel 导出按钮
+    - _Requirements: 7.3, 7.4, 7.5_
+
+- [x] 15. 总经理端前端页面
+  - [x] 15.1 实现全公司绩效总览页面 `CompanyOverview`
+    - 各部门、各岗位绩效整体情况，ECharts 柱状图和饼图，多维度筛选
+    - _Requirements: 8.1, 8.2, 8.3_
+  - [x] 15.2 实现全量数据导出和考核规则配置页面
+    - 全量 Excel 导出，考核指标权重和奖惩金额配置表单
+    - _Requirements: 8.4, 8.5, 8.6_
+
+- [x] 16. 最终检查点 — 确保所有测试通过，前后端联调完成，如有问题请告知
+
+## 备注
+
+- 标有 `*` 的任务为可选测试任务，可跳过以加快 MVP 交付
+- 每个任务引用了具体的需求条目，便于追溯
+- 检查点任务确保每个阶段的增量验证
+- 属性测试使用 fast-check 库，每个属性最少运行 100 次迭代