performance-system-design.txt

# 自动化绩效管理系统 — 设计文档

> 日期：2026-03-17
> 状态：Design Approved
> 方案：方案 A — 纯企微 H5

---

## 1. 项目概述

为 50-500 人规模企业打造的全员自动化绩效管理系统，嵌入企业微信，支持灵活自定义考核周期，覆盖 OKR/KPI/360°/自定义模板等多种评估模式。

### 核心需求

- **用户**：全员使用（员工自评 + 管理者评估）
- **周期**：灵活自定义（HR 按需配置）
- **评估模式**：OKR + KPI + 360° + 自定义模板，可混搭
- **部署**：企业微信 H5 嵌入
- **规模**：50-500 人，多部门/分公司
- **上线目标**：2-3 周 MVP

### 功能清单

- 目标管理（员工/管理者设定季度/月度目标，追踪进展）
- 多级审批工作流（直接上级 → 分管领导 → HR 终审）
- 数据看板（团队绩效分布、趋势、排名）
- 企微自动通知（考核启动、截止提醒、结果推送）
- 历史记录与对比（多期绩效对比，个人成长轨迹）

---

## 2. 系统架构

### 整体结构

```
┌─────────────────────────────────────────────┐
│              企业微信                          │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ 员工端 H5 │  │ 管理者 H5 │  │ HR 管理 H5│  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │
│       │              │              │         │
├───────┴──────────────┴──────────────┴─────────┤
│           API 网关 (Nginx / 云服务)              │
├───────────────────────────────────────────────┤
│              FastAPI 后端服务                    │
│  ┌─────────┐ ┌─────────┐ ┌──────────────┐    │
│  │ 用户模块 │ │ 评估模块 │ │ 通知模块      │    │
│  ├─────────┤ ├─────────┤ ├──────────────┤    │
│  │ 目标模块 │ │ 审批模块 │ │ 数据报表模块  │    │
│  └─────────┘ └─────────┘ └──────────────┘    │
├───────────────────────────────────────────────┤
│              MySQL + Redis                      │
└───────────────────────────────────────────────┘
```

### 角色与权限

| 角色 | 权限范围 |
|------|---------|
| **HR 管理员** | 创建考核计划、配置模板、审批最终结果、查看全公司报表 |
| **部门管理者** | 设定团队目标、评估下属、审批自评、查看本部门报表 |
| **普通员工** | 设定个人目标、填写自评、查看自己的绩效结果和历史 |

### 技术选型

| 层级 | 选型 | 说明 |
|------|------|------|
| 后端 | FastAPI + SQLAlchemy + Alembic | 快速开发，Python 生态丰富 |
| 前端 | Vue 3 + Vant 4 | 移动端 UI 组件库，专为企微 H5 优化 |
| 数据库 | MySQL 8.0 | 成熟稳定 |
| 缓存 | Redis | 会话、验证码、限流 |
| 部署 | Docker + Nginx | 单机部署，支撑 500 人无压力 |
| 企微集成 | 企微 REST API | OAuth 登录 + 通讯录 + 消息推送 |

---

## 3. 多级审批设计

### 审批层级

```
员工自评 → 直接上级评估 → 分管领导审批 → HR 终审 → 结果归档
```

### 不同岗位的审批链路

| 场景 | 审批链 |
|------|--------|
| 普通员工 | 自评 → 直属上级 → HR |
| 基层主管 | 自评 → 部门经理 → 分管领导 → HR |
| 部门经理 | 自评 → 分管领导 → HR |
| 高管 | 自评 → HR 总监 → 总经理（可选） |

### 核心机制

- HR 创建考核计划时，可配置每个部门/岗位的审批链路（最少 2 级：评估人 + HR）
- 上一级审批通过后，自动流转到下一级，企微消息通知相关人员
- 任何一级可以**退回修改**，退回到上一环节，附批注意见

---

## 4. 数据库设计

### 7 张核心表

```sql
-- 1. 组织架构
department (id, name, parent_id, leader_id)

-- 2. 员工（与企微 userid 关联）
employee (id, name, wecom_userid, dept_id, position, level, status)

-- 3. 考核计划（由 HR 创建）
assessment_plan (id, name, cycle_type, start_date, end_date,
                 template_id, approval_chain, status)

-- 4. 评估模板（支持 OKR/KPI/360°/自定义）
eval_template (id, name, type, dimensions_json)
-- dimensions_json 示例：[{"name":"目标达成","weight":40,"type":"kpi"},
--                          {"name":"协作能力","weight":30,"type":"360"},
--                          {"name":"创新贡献","weight":30,"type":"okr"}]

-- 5. 个人考核记录（每个员工在每期考核中的实例）
assessment_record (id, plan_id, employee_id, status,
                   current_step, final_score)

-- 6. 评估明细（每个维度的评分，区分自评/上级评/360评）
eval_detail (id, record_id, dimension_id, evaluator_id,
             evaluator_role, score, comment)

-- 7. 审批流水（记录流转历史）
approval_log (id, record_id, from_step, to_step,
              approver_id, action, comment, created_at)
```

### 关键设计决策

- **模板用 JSON 存维度**：灵活支持 OKR/KPI/360° 混搭，不同岗位挂不同模板
- **审批链可配置**：`approval_chain` 用 JSON 存审批顺序，例如 `["direct_leader","vp","hr"]`
- **评估明细区分角色**：同一维度可以有自评分、上级评分、360 评分，最终加权计算

---

## 5. 核心业务流程

### 考核全流程

```
HR 创建考核计划
       │
       ▼
  选择评估模板 + 配置审批链 + 设定参与范围
       │
       ▼
  【启动】企微消息通知全员 → 员工设定目标（可选）
       │
       ▼
  考核期中 → 员工可更新目标进展
       │
       ▼
  【自评阶段】企微提醒 → 员工填写自评（各维度打分+文字说明）
       │
       ▼
  【上级评估】企微提醒直属上级 → 查看下属自评 → 打分+评语
       │
       ▼
  【分管领导审批】查看评分+评语 → 同意/退回
       │
       ▼
  【HR 终审】确认或调整 → 确认后锁定
       │
       ▼
  【结果推送】企微消息通知员工 → 查看绩效结果+评语
       │
       ▼
  归档 → 可用于历史对比分析
```

### 计分规则

| 评估类型 | 计算方式 |
|---------|---------|
| **KPI** | 目标值 vs 实际值，按达成率折算分数 |
| **OKR** | 每个 KR 按完成度 0-100%，加权平均 |
| **360°** | 自评 × 10% + 上级 × 40% + 同事 × 30% + 下属 × 20%（权重可配置） |
| **自定义** | 各维度直接打分，按维度权重加权汇总 |
| **最终得分** | 自评权重 × 30% + 上级评估权重 × 70%（可配置） |

### 阶段控制机制

- 每个阶段有**截止时间**，过期自动进入下一阶段（未完成的标记为"未提交"）
- HR 可以**手动调整阶段**，应对突发情况（如延期、补评）
- 任何环节**退回**后，系统企微通知被退回人，要求限期重新提交

---

## 6. 企业微信集成方案

### 企微应用架构

```
┌─────────────────────────────────────┐
│           企业微信管理后台             │
│  创建自建应用 "绩效管理系统"           │
│  ├─ 可见范围：全公司                  │
│  ├─ 企微主页：H5 入口页面             │
│  └─ 消息推送权限：已授权              │
└──────────────┬──────────────────────┘
               │ OAuth2.0 / JS-SDK
               ▼
┌─────────────────────────────────────┐
│          H5 页面（Vue 3 + Vant）      │
│  ┌──────────┐  ┌──────────────────┐  │
│  │ 员工端    │  │ 管理端           │  │
│  │ ·目标设定 │  │ ·创建考核计划    │  │
│  │ ·自评填写 │  │ ·审批管理        │  │
│  │ ·结果查看 │  │ ·数据看板        │  │
│  │ ·历史对比 │  │ ·模板管理        │  │
│  └──────────┘  └──────────────────┘  │
└──────────────┬──────────────────────┘
               │ API 调用
               ▼
┌─────────────────────────────────────┐
│           FastAPI 后端               │
│  企微 API 封装层：                    │
│  ├─ 身份认证（OAuth2.0）             │
│  ├─ 部门/人员同步（通讯录 API）       │
│  ├─ 消息推送（应用消息 API）          │
│  └─ JS-SDK 签名（H5 页面授权）       │
└─────────────────────────────────────┘
```

### 需要申请的企微权限

| 权限 | 用途 | 必要性 |
|------|------|--------|
| **通讯录读取** | 自动同步部门架构和员工信息 | ⭐ 必须 |
| **应用消息推送** | 考核提醒、审批通知、结果推送 | ⭐ 必须 |
| **OAuth2.0 网页授权** | 员工打开 H5 自动登录 | ⭐ 必须 |
| **JS-SDK** | 在企微内调用扫一扫、分享等原生能力 | 可选 |
| **通讯录写入** | 后续如需系统内同步组织架构变更 | 二期 |

### 消息推送时机

| 事件 | 推送对象 | 消息内容 |
|------|---------|---------|
| 考核启动 | 全员 | "新一轮考核已开启，请点击查看详情" |
| 自评截止前 1 天 | 未提交的员工 | "您的自评明天截止，请尽快完成" |
| 需要评估 | 直属上级 | "您有 N 位下属待评估" |
| 需要审批 | 审批人 | "N 条评估结果待您审批" |
| 被退回 | 被退回人 | "您的评估已被退回，原因：xxx" |
| 结果发布 | 员工 | "本期绩效结果已发布，点击查看" |

### 身份认证流程

```
员工在企微中点击应用
    → 企微携带 code 重定向到 H5
    → H5 将 code 发给后端
    → 后端用 code 换取用户身份（userid）
    → 匹配 employee 表 → 生成本地 token
    → 后续请求携带 token，无需重复登录
```

---

## 7. MVP 范围与开发排期

### MVP（2-3 周）必须包含

| 模块 | 功能 | 优先级 |
|------|------|--------|
| **基础架构** | FastAPI 项目骨架 + MySQL + Docker 部署 | P0 |
| **企微对接** | OAuth 登录 + 通讯录同步 + 消息推送 | P0 |
| **员工端** | 自评填写 + 目标设定 + 结果查看 | P0 |
| **管理端** | 创建考核计划 + 审批（退回/通过）+ 查看下属 | P0 |
| **HR 端** | 审批终审 + 简易数据概览（部门平均分/排名） | P0 |
| **模板** | 支持创建自定义模板（维度+权重） | P0 |

### 二期迭代（MVP 后）

| 模块 | 功能 |
|------|------|
| **360° 评估** | 同事互评、下属评价、完整 360° 流程 |
| **数据看板** | 可视化图表（趋势、分布、对比） |
| **高级模板** | OKR 专项模板、KPI 自动计算模板 |
| **导出功能** | Excel 导出考核数据、报表生成 |
| **历史对比** | 跨期绩效趋势、个人成长报告 |

### 三周开发排期

```
第 1 周：地基
├─ Day 1-2：项目搭建（FastAPI + Vue 3 + MySQL + Docker）
├─ Day 3-4：企微 OAuth 登录 + 通讯录同步
└─ Day 5：   数据库表结构 + Alembic 迁移

第 2 周：核心流程
├─ Day 1-2：考核计划创建 + 评估模板管理
├─ Day 3-4：自评 + 上级评估 + 审批流转
└─ Day 5：   企微消息推送（阶段提醒）

第 3 周：收尾 + 测试
├─ Day 1-2：HR 管理面板 + 简易数据概览
├─ Day 3：   全流程联调 + Bug 修复
├─ Day 4：   部署上线（Docker + Nginx + SSL）
└─ Day 5：   使用文档 + 企微侧配置指导
```

---

## 8. 前置准备事项

| 事项 | 说明 | 状态 |
|------|------|------|
| 企微自建应用 | 在管理后台创建应用，获取 AgentId + Secret | 待申请 |
| 域名 + SSL 证书 | 企微要求 HTTPS，需要备案域名 | 待准备 |
| 服务器 | 一台 2C4G 云服务器即可，推荐阿里云/腾讯云 | 待准备 |
| 通讯录权限 | 申请「通讯录权限」并设置为「全部员工」 | 待申请 |