# 知识库积分统计看板 - 开发说明

## 一、功能概述

每月1号凌晨5点自动生成上个月的积分快照数据，并向指定人员发送通知。
通知点击后展示积分统计看板，支持公司级/部门级/员工级三层下钻查看。

### 入口
1. **通知入口**：点击待办通知（type=201）直接进入看板页面
2. **菜单入口**：知识库管理 → 积分看板（支持手动选择月份查看）

### 数据层级
| 层级 | 说明 | 交互 |
|------|------|------|
| 公司级 | 全公司汇总卡片 | 默认展示 |
| 部门级 | 各部门汇总表格 | 点击部门名称弹出员工列表 |
| 员工级 | 部门下员工明细 | 点击"详情"弹出积分明细 |

---

## 二、数据库表

### 2.1 知识库积分通知人员表

```sql
CREATE TABLE `work_knowledge_point_notify_user` (
    `id` VARCHAR(64) NOT NULL COMMENT '主键',
    `user_id` VARCHAR(64) NOT NULL COMMENT '用户ID（关联sys_user.id）',
    `del_flag` VARCHAR(1) NOT NULL DEFAULT '0' COMMENT '删除标记（0正常 1删除）',
    `create_date` DATETIME DEFAULT NULL COMMENT '创建时间',
    PRIMARY KEY (`id`),
    KEY `idx_user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='知识库积分通知人员表';
```

**使用说明**：在表中插入需要接收通知的用户记录即可。
```sql
-- 示例：添加通知人员
INSERT INTO work_knowledge_point_notify_user (id, user_id, del_flag, create_date)
VALUES (REPLACE(UUID(), '-', ''), '用户ID', '0', NOW());
```

### 2.2 知识库积分快照明细表（员工级）

```sql
CREATE TABLE `wk_point_snapshot_info` (
    `id` VARCHAR(64) NOT NULL COMMENT '主键',
    `del_flag` VARCHAR(1) NOT NULL DEFAULT '0' COMMENT '删除标记',
    `create_date` DATETIME DEFAULT NULL COMMENT '创建时间',
    `snapshot_year` INT NOT NULL COMMENT '快照年份',
    `snapshot_month` INT NOT NULL COMMENT '快照月份',
    `office_id` VARCHAR(64) DEFAULT NULL COMMENT '部门ID',
    `office_name` VARCHAR(200) DEFAULT NULL COMMENT '部门名称',
    `user_id` VARCHAR(64) NOT NULL COMMENT '用户ID',
    `user_name` VARCHAR(200) DEFAULT NULL COMMENT '用户姓名',
    `upload_count` INT DEFAULT 0 COMMENT '上传文档数',
    `field1` VARCHAR(64) DEFAULT NULL COMMENT '基础-阅读积分',
    `field2` VARCHAR(64) DEFAULT NULL COMMENT '基础-点赞积分',
    `field3` VARCHAR(64) DEFAULT NULL COMMENT '贡献-技术总结-创建',
    `field4` VARCHAR(64) DEFAULT NULL COMMENT '贡献-技术总结-审核',
    `field5` VARCHAR(64) DEFAULT NULL COMMENT '贡献-培训心得-创建',
    `field6` VARCHAR(64) DEFAULT NULL COMMENT '贡献-培训心得-审核',
    `field7` VARCHAR(64) DEFAULT NULL COMMENT '贡献-相关资料-创建',
    `field8` VARCHAR(64) DEFAULT NULL COMMENT '贡献-相关资料-审核',
    `field9` VARCHAR(64) DEFAULT NULL COMMENT '贡献-问答答疑-创建',
    `field10` VARCHAR(64) DEFAULT NULL COMMENT '贡献-问答答疑-回答',
    `field11` VARCHAR(64) DEFAULT NULL COMMENT '贡献-典型案例(原创)-创建',
    `field12` VARCHAR(64) DEFAULT NULL COMMENT '贡献-典型案例(原创)-审核',
    `field13` VARCHAR(64) DEFAULT NULL COMMENT '贡献-典型案例(转载)-创建',
    `field14` VARCHAR(64) DEFAULT NULL COMMENT '贡献-典型案例(转载)-审核',
    `field15` VARCHAR(64) DEFAULT NULL COMMENT '贡献-扣除积分',
    `field16` VARCHAR(64) DEFAULT NULL COMMENT '扩展字段16',
    `field17` VARCHAR(64) DEFAULT NULL COMMENT '扩展字段17',
    `field18` VARCHAR(64) DEFAULT NULL COMMENT '扩展字段18',
    `field19` VARCHAR(64) DEFAULT NULL COMMENT '扩展字段19',
    `field20` VARCHAR(64) DEFAULT NULL COMMENT '扩展字段20',
    PRIMARY KEY (`id`),
    KEY `idx_snapshot_ym` (`snapshot_year`, `snapshot_month`),
    KEY `idx_snapshot_user` (`snapshot_year`, `snapshot_month`, `user_id`),
    KEY `idx_snapshot_office` (`snapshot_year`, `snapshot_month`, `office_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='知识库积分快照明细表';
```

### 2.3 知识库积分快照汇总表（公司/部门/员工三级）

```sql
CREATE TABLE `wk_point_snapshot_summary` (
    `id` VARCHAR(64) NOT NULL COMMENT '主键',
    `del_flag` VARCHAR(1) NOT NULL DEFAULT '0' COMMENT '删除标记',
    `create_date` DATETIME DEFAULT NULL COMMENT '创建时间',
    `snapshot_year` INT NOT NULL COMMENT '快照年份',
    `snapshot_month` INT NOT NULL COMMENT '快照月份',
    `grade_type` VARCHAR(10) NOT NULL COMMENT '层级类型（1:公司 2:部门 3:员工）',
    `office_id` VARCHAR(64) DEFAULT NULL COMMENT '部门ID（公司级为空）',
    `office_name` VARCHAR(200) DEFAULT NULL COMMENT '部门名称',
    `user_id` VARCHAR(64) DEFAULT NULL COMMENT '用户ID（员工级才有）',
    `user_name` VARCHAR(200) DEFAULT NULL COMMENT '用户姓名',
    `upload_count` INT DEFAULT 0 COMMENT '上传文档数',
    `basic_subtotal` INT DEFAULT 0 COMMENT '基础积分汇总',
    `basic_exchange` INT DEFAULT 0 COMMENT '基础已兑换积分',
    `basic_remaining` INT DEFAULT 0 COMMENT '基础剩余积分',
    `contrib_subtotal` INT DEFAULT 0 COMMENT '贡献积分汇总（含扣除）',
    `contrib_deduction` INT DEFAULT 0 COMMENT '贡献-扣除积分',
    `contrib_exchange` INT DEFAULT 0 COMMENT '贡献已兑换积分',
    `contrib_remaining` INT DEFAULT 0 COMMENT '贡献剩余积分',
    PRIMARY KEY (`id`),
    KEY `idx_summary_ym` (`snapshot_year`, `snapshot_month`),
    KEY `idx_summary_ym_grade` (`snapshot_year`, `snapshot_month`, `grade_type`),
    KEY `idx_summary_ym_office` (`snapshot_year`, `snapshot_month`, `office_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='知识库积分快照汇总表';
```

---

## 三、通知参数说明

| 参数 | 值 | 说明 |
|------|------|------|
| utilNotifyId | `201` | 通知类型标识 |
| notifyId | `201,{year},{month}` | 如 `201,2026,6` |
| type | `201` | WorkProjectNotify.type |
| title | `{year}年{month}月-知识库积分统计` | 通知标题 |
| content | `{year}年{month}月-知识库积分统计` | 通知内容 |
| status | `0` | 待办状态 |
| remarks | `待通知` | 备注 |

---

## 四、定时任务

| 项目 | 说明 |
|------|------|
| 类 | `WorkCalendarTaskService` |
| 方法 | `getKnowledgeBasePointSnapshotOnMonth()` |
| cron | `0 0 5 1 * ?`（每月1号凌晨5点） |
| 逻辑 | 计算上个月的年月 → 生成快照 → 发送通知 |

---

## 五、接口清单

| 接口 | URL | 方法 | 说明 |
|------|------|------|------|
| 看板页面 | `/workKnowledgeBase/point/dashboard` | GET | 从菜单进入的看板页面 |
| 看板数据 | `/workKnowledgeBase/point/dashboardData` | GET | AJAX，参数：year, month |
| 部门员工 | `/workKnowledgeBase/point/departmentEmployees` | GET | AJAX，参数：year, month, officeId |
| 员工详情 | `/workKnowledgeBase/point/employeeSnapshot` | GET | AJAX，参数：year, month, userId |
| 手动生成 | `/workKnowledgeBase/point/generateSnapshot` | GET | AJAX，参数：year, month（需listAll权限） |

---

## 六、文件清单

### 新增文件
| 文件 | 说明 |
|------|------|
| `entity/WkPointSnapshotInfo.java` | 快照明细实体类 |
| `entity/WkPointSnapshotSummary.java` | 快照汇总实体类 |
| `entity/WorkKnowledgePointNotifyUser.java` | 通知人员实体类 |
| `dao/WkPointSnapshotInfoDao.java` | 快照明细DAO |
| `dao/WkPointSnapshotSummaryDao.java` | 快照汇总DAO |
| `dao/WorkKnowledgePointNotifyUserDao.java` | 通知人员DAO |
| `service/WkPointSnapshotService.java` | 快照Service（核心计算+通知发送） |
| `WkPointSnapshotInfoDao.xml` | 快照明细MyBatis映射 |
| `WkPointSnapshotSummaryDao.xml` | 快照汇总MyBatis映射 |
| `WorkKnowledgePointNotifyUserDao.xml` | 通知人员MyBatis映射 |
| `workKnowledgeBasePointDashboard.jsp` | 看板展示页面 |

### 修改文件
| 文件 | 修改内容 |
|------|------|
| `WorkCalendarTaskService.java` | 新增定时任务方法 + 注入WkPointSnapshotService |
| `WorkProjectNotifyController.java` | 新增type=201的通知处理分支 + 注入WkPointSnapshotService |
| `WorkKnowledgeBasePointController.java` | 新增看板页面入口和5个AJAX接口 + 注入WkPointSnapshotService |

---

## 七、部署步骤

1. **执行建表SQL**：按第二节依次执行3张表的CREATE TABLE语句
2. **插入通知人员**：在 `work_knowledge_point_notify_user` 表中添加需要接收通知的用户
3. **部署代码**：编译打包部署
4. **手动测试**：调用 `/workKnowledgeBase/point/generateSnapshot?year=2026&month=6` 生成测试数据
5. **查看看板**：访问 `/workKnowledgeBase/point/dashboard` 查看效果
6. **验证通知**：等待每月1号凌晨5点自动执行，或手动触发

---

## 八、扩展字段说明

`wk_point_snapshot_info` 表预留了 `field16` ~ `field20` 共5个扩展字段。
如需新增规则积分列：
1. 在 `WkPointSnapshotService.FIELD_MAPPING` 中添加映射
2. 在 `buildRuleIdToFieldMapping()` 中添加规则匹配
3. 在 `setField()` 方法中添加 case 分支
4. 在 JSP 详情弹窗中添加对应行