docs: add complete operations manual covering full OKR cycle

docs/操作手册.md

@@ -0,0 +1,397 @@
+# 医梦AI OKR 绩效考核系统 — 操作手册
+
+## 系统概述
+
+本系统采用 OKR（40%）+ KPI（60%）双轨考核模型，基于树形组织架构，支持从目标制定到绩效面谈的完整闭环。系统内置四层 OKR 对齐机制（公司→部门→团队→个人），并提供消息通知、分角色权限、绩效审计留痕等企业级能力。
+
+### 考核周期状态机
+
+```
+DRAFT → OKR_ALIGN → EXECUTING → ASSESSING → ARCHIVED
+  ↓         ↓           ↓           ↓           ↓
+ 草稿    目标对齐    执行追踪    考评打分    归档完成
+```
+
+---
+
+## 第一章：系统初始化
+
+### 1.1 登录系统
+
+访问系统地址，使用管理员账号登录：
+
+- 默认账号：`admin`
+- 默认密码：`emoon123456`
+
+### 1.2 组织架构搭建
+
+**路径**：侧边栏 → 组织架构（需 HR 管理员或以上权限）
+
+**操作步骤**：
+
+1. 创建部门：点击"新建部门"，填写部门名称、上级部门、部门负责人
+2. 创建用户：点击"添加用户"，填写用户名、真实姓名、邮箱、职位
+3. 分配角色：为用户选择合适的角色（详见下方角色说明）
+4. 设置上下级：在用户列表中设置直属上级，构建汇报关系树
+
+**角色体系**：
+
+| 角色 | 权限范围 | 典型人员 |
+|------|---------|---------|
+| 超级管理员 | 全局所有权限 | 系统管理员 |
+| HR 管理员 | 全部人员数据、考核配置、报表导出 | HRBP |
+| 部门负责人 | 本部门及下级部门 OKR、评分审批 | 部门总监 |
+| 团队主管 | 直属下级 OKR、评分 | 团队 Leader |
+| 普通员工 | 仅自己的 OKR 和绩效数据 | 全员 |
+
+---
+
+## 第二章：创建考核周期
+
+### 2.1 新建考核周期
+
+**路径**：侧边栏 → 考核周期
+
+**操作步骤**：
+
+1. 点击"新建周期"
+2. 填写周期名称（如"2026年Q2考核"）
+3. 选择周期类型（月度/季度/年度）
+4. 设置开始日期和结束日期
+5. 点击创建
+
+周期创建后状态为 **DRAFT（草稿）**，尚未对员工开放。
+
+### 2.2 启动 OKR 对齐阶段
+
+**操作步骤**：
+
+1. 在周期列表中点击目标周期的"启动对齐"按钮
+2. 周期状态变为 **OKR_ALIGN**，全员可开始制定 OKR
+
+---
+
+## 第三章：多层级 OKR 制定
+
+### 3.1 制定公司级 OKR
+
+**执行人**：HR 管理员或超级管理员  
+**路径**：侧边栏 → 我的 OKR → 选择当前周期
+
+**操作步骤**：
+
+1. 点击"创建 OKR"，层级选择"公司"
+2. 填写公司级目标（O），建议 3-5 个
+3. 为每个 O 添加关键结果（KR），每条 KR 需设置：
+   - 标题（可衡量的具体结果）
+   - 目标值
+   - 权重（所有 KR 权重之和 = 100）
+4. 公司级 OKR 创建后自动通过，全员可见
+
+### 3.2 制定部门级 OKR
+
+**执行人**：部门负责人  
+**路径**：侧边栏 → 我的 OKR → 选择当前周期
+
+**操作步骤**：
+
+1. 点击"创建 OKR"，层级选择"部门"
+2. 点击"对齐目标"，在树中选择对齐的公司级 O（可选）
+3. 填写部门目标，添加 KR
+4. 部门级 OKR 创建后自动通过
+
+### 3.3 制定个人 OKR
+
+**执行人**：全员  
+**路径**：侧边栏 → 我的 OKR → 选择当前周期
+
+**操作步骤**：
+
+1. 点击"创建 OKR"，层级默认为"个人"
+2. 在"对齐目标"下拉树中选择上级的 OKR（可选但推荐）
+3. 填写个人目标（O），每人每周期 1 个 O
+4. 添加 2-5 条 KR，权重之和 = 100
+5. 点击"提交"，OKR 进入 **SUBMITTED** 状态，等待上级审核
+
+**注意事项**：
+- 上级必须已完成自己的 OKR 提交，下级才能提交
+- 未对齐的个人 OKR 会标记为"孤立目标"，在对齐视图中显示警告
+
+### 3.4 查看 OKR 对齐树
+
+**路径**：侧边栏 → OKR 对齐
+
+此页面以树形结构展示公司→部门→团队→个人的完整对齐关系：
+
+- 左侧树：按层级展示所有 OKR，显示进度条和层级标签
+- 右侧详情：点击节点查看 KR 列表和进度详情
+- 底部警告区：列出所有未对齐的孤立目标
+
+### 3.5 审核下级 OKR
+
+**执行人**：团队主管 / 部门负责人  
+**路径**：侧边栏 → 团队 OKR → 待审核
+
+**操作步骤**：
+
+1. 查看下级提交的 OKR 详情
+2. 检查对齐关系是否正确、KR 是否合理
+3. 点击"通过"或"驳回"（驳回需填写备注）
+4. 上级会收到审核结果的消息通知
+
+---
+
+## 第四章：OKR 执行与进度追踪
+
+### 4.1 切换到执行阶段
+
+**执行人**：HR 管理员  
+**路径**：侧边栏 → 考核周期 → 点击"开始执行"
+
+周期状态变为 **EXECUTING**，全员可更新 KR 进度。
+
+### 4.2 更新 KR 进度
+
+**执行人**：全员  
+**路径**：侧边栏 → 我的 OKR → 点击 KR 旁的"更新进度"
+
+**操作步骤**：
+
+1. 输入当前进度值
+2. 选择进度状态（未开始 / 进行中 / 已完成）
+3. 填写备注（可选）
+4. 提交
+
+**自动化行为**：
+- 系统自动计算该 O 的汇总进度（KR 加权平均）
+- 进度滞后于时间线时，系统会触发进度滞后提醒
+- 所有进度变更记录在操作日志中，可追溯
+
+### 4.3 周期截止提醒
+
+周期结束前 3 天，系统自动向全员发送截止提醒通知。右上角铃铛图标出现红色角标提示。
+
+---
+
+## 第五章：KPI 配置
+
+### 5.1 管理 KPI 模板
+
+**执行人**：HR 管理员  
+**路径**：侧边栏 → 绩效模板
+
+**操作步骤**：
+
+1. 创建 KPI 模板，填写模板名称和分类
+2. 添加考核项目（items_json），定义评分标准
+3. 可按岗位关联模板
+
+### 5.2 分配 KPI 配置
+
+**执行人**：HR 管理员  
+**路径**：通过 KPI 模板为每个周期的每位员工生成 KPI 配置
+
+设置完成后可锁定，锁定后的 KPI 配置不可编辑。
+
+---
+
+## 第六章：绩效考评
+
+### 6.1 切换到考评阶段
+
+**执行人**：HR 管理员  
+**路径**：侧边栏 → 考核周期 → 点击"开始考评"
+
+周期状态变为 **ASSESSING**。
+
+### 6.2 员工自评
+
+**执行人**：全员  
+**路径**：侧边栏 → 我的绩效 → 选择当前周期
+
+**操作步骤**：
+
+1. 查看自己的 OKR 完成情况和 KPI 配置
+2. 填写 OKR 自评分数
+3. 填写 KPI 自评分数
+4. 如有奖惩项，填写加分/扣分
+5. 提交自评（仅可提交一次）
+
+### 6.3 上级评分
+
+**执行人**：有下级的管理者  
+**路径**：侧边栏 → 绩效打分
+
+**操作步骤**：
+
+1. 在下级列表中选择待评分员工
+2. 页面采用左右分栏布局：
+   - 左侧：员工 OKR 详情 + KPI 配置
+   - 右侧：评分表单
+3. 分别为 OKR 和 KPI 打分
+4. 填写奖惩项和评语
+5. 提交评分
+
+**评分公式**：
+```
+总分 = OKR得分 + KPI得分 + 加分 - 扣分
+```
+系统自动计算并映射等级（A/B/C/D）。
+
+**自动化行为**：
+- 提交评分后，下级收到"评分已确认"消息通知
+- 评分数据写入 `audit_correction` 审计表，修改即留痕
+
+### 6.4 员工确认评分
+
+**执行人**：全员  
+**路径**：侧边栏 → 我的绩效
+
+查看上级评分结果，点击"确认"。确认后上级收到确认通知。
+
+---
+
+## 第七章：绩效面谈
+
+### 7.1 上级发起面谈
+
+**执行人**：管理者  
+**路径**：侧边栏 → 绩效沟通
+
+**操作步骤**：
+
+1. 选择被考核人
+2. 填写面谈记录：
+   - 工作亮点（highlights）
+   - 存在问题（issues）
+   - 改进方向（improvements）
+3. 保存面谈记录
+
+**自动化行为**：
+- 下级收到面谈通知
+- 通知面板可点击跳转到反馈页
+
+### 7.2 员工提交面谈反馈
+
+**执行人**：全员  
+**路径**：侧边栏 → 绩效沟通
+
+查看上级填写的面谈记录，在"员工反馈"栏中填写自己的意见和计划，提交回复。
+
+### 7.3 历史绩效查看
+
+**路径**：侧边栏 → 历史绩效
+
+可查看历次考核周期的绩效结果，用于纵向对比和成长轨迹追踪。
+
+---
+
+## 第八章：周期归档
+
+### 8.1 归档操作
+
+**执行人**：HR 管理员  
+**路径**：侧边栏 → 考核周期 → 点击"归档"
+
+周期状态变为 **ARCHIVED**。
+
+**归档时自动执行**：
+- OKR 目标写入 `snapshot_json`（历史快照）
+- KPI 配置写入 `snapshot_json`
+- 此后 OKR 和 KPI 数据不可修改，确保审计完整性
+
+### 8.2 周期自动推进
+
+系统每天凌晨 2 点自动检查周期状态：
+- 到期周期自动从 EXECUTING 切换到 ASSESSING
+- 到期周期自动从 ASSESSING 切换到 ARCHIVED
+
+---
+
+## 第九章：消息通知体系
+
+### 9.1 通知类型
+
+| 通知类型 | 触发时机 | 接收人 |
+|---------|---------|--------|
+| OKR 待审核 | 下级提交 OKR | 直属上级 |
+| 审核结果 | 上级通过/驳回 OKR | OKR 提交人 |
+| 评分待确认 | 上级完成评分 | 被评人 |
+| 评分已确认 | 下级确认评分 | 上级 |
+| 周期截止提醒 | 周期结束前 3 天 | 周期内全员 |
+| 进度滞后 | KR 进度落后时间线 | OKR 负责人 |
+| 面谈通知 | 上级发起面谈 | 下级 |
+
+### 9.2 查看通知
+
+- **铃铛图标**：右上角导航栏，显示未读红色角标
+- **通知面板**：点击铃铛展开，显示最近 20 条通知，点击可跳转到对应页面
+- **通知列表**：点击"查看全部"进入完整列表，支持分页和类型筛选
+- **全部已读**：一键标记所有通知为已读
+
+通知轮询间隔为 60 秒。
+
+---
+
+## 第十章：系统管理
+
+### 10.1 考核维度配置
+
+**路径**：侧边栏 → 考核维度（需 HR 管理员权限）
+
+可自定义考核维度（如"工作态度"、"专业能力"等），设置最高分和排序。
+
+### 10.2 操作日志
+
+**路径**：侧边栏 → 操作日志（需 HR 管理员权限）
+
+记录所有关键操作：谁（operatorId）、做了什么（action）、对哪个实体（entityType/entityId）、变更前后数据对比（oldDataJson/newDataJson）、操作时间、IP。
+
+### 10.3 审计修正
+
+当评分需要修正时，系统先将修正前的值写入 `audit_correction` 表，包括：
+- 修正类型
+- 旧值 JSON
+- 新值 JSON
+- 修正原因
+- 操作人
+
+确保"不可修改"语义通过审计留痕实现。
+
+---
+
+## 附录 A：常见问题
+
+**Q：为什么我无法提交 OKR？**
+A：检查三点：① 当前周期是否处于 OKR_ALIGN 阶段；② 你的上级是否已完成 OKR 提交；③ 是否已提交过本周期 OKR（需上级驳回后才能重新提交）。
+
+**Q：KR 权重之和必须等于 100 吗？**
+A：是的，系统强制校验。这是为了保证进度汇总计算的准确性。
+
+**Q：评分提交后还能修改吗？**
+A：上级评分提交后不可直接修改。如确需修正，需通过审计修正流程，旧值会被记录留痕。
+
+**Q：未对齐的 OKR 会怎样？**
+A：个人 OKR 如果不选择对齐目标，会在 OKR 对齐视图中被标记为"孤立目标"。不影响评分，但建议对齐以获得更好的团队协同。
+
+**Q：通知为什么会延迟？**
+A：通知采用异步处理（@Async），正常情况秒级送达。前端每 60 秒轮询未读数，首次进入页面立即拉取。
+
+---
+
+## 附录 B：角色权限速查
+
+| 操作 | 超级管理员 | HR管理员 | 部门负责人 | 团队主管 | 员工 |
+|------|:--:|:--:|:--:|:--:|:--:|
+| 管理用户/部门 | ✅ | ✅ | — | — | — |
+| 管理考核周期 | ✅ | ✅ | — | — | — |
+| 创建公司级 OKR | ✅ | ✅ | — | — | — |
+| 创建部门级 OKR | ✅ | ✅ | ✅ | — | — |
+| 查看本部门全部 OKR | ✅ | ✅ | ✅ | — | — |
+| 查看下级 OKR | ✅ | ✅ | ✅ | ✅ | — |
+| 审核下级 OKR | ✅ | ✅ | ✅ | ✅ | — |
+| 为下级打分 | ✅ | ✅ | ✅ | ✅ | — |
+| 查看自己的 OKR/分数 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 管理 KPI 模板 | ✅ | ✅ | — | — | — |
+| 导出报表 | ✅ | ✅ | ✅ | — | — |
+| 查看操作日志 | ✅ | ✅ | — | — | — |