# eai_agentplatform_app — 变更日志

> **最后更新：2026-08-16**

---

## V1.7（2026-08-16）

**组织架构 + 消息通知落地。** 补齐「部门组织架构管理」与「站内消息通知」两大能力，
打通「按部门学情拆分」与「事件推送提醒」；**社交社区/讨论区明确不做（定死）**。

### 新增
- **部门组织架构**：`department` 部门字典表 + `GET/POST/PUT/DELETE /api/departments`（admin）；
  部门改名时同步 `user.department` 字符串，有员工归属的部门拒绝删除；
  `GET /api/system/department-stats` 按部门聚合（人数/学习积分/公司介绍已读率/
  人均产品课程/正式考试通过率/平均分）；前端「系统管理 → 部门管理」页（部门列表 + 部门学情两个 Tab），
  用户管理「部门」字段改为可搜索下拉（支持自建输入，兼容历史自由文本）
- **站内消息通知**：`notification` 表 + 事件钩子（发布正式考试 → 通知全员；
  正式考试通过 → 通知本人并引导查看证书；用户被设岗 → 通知本人）；
  `GET /api/notifications`、`GET /api/notifications/unread-count`、
  `PUT /api/notifications/:id/read`、`PUT /api/notifications/read-all`；
  前端「消息通知」页 + 侧栏铃铛角标（60s 轮询未读数）

### 定死（不做）
- **社交社区/讨论区**：明确不实现，后续也不纳入路线图

---

## V1.6（2026-08-16）

**学员成长体系落地（游戏化 + 认证 + 学情）。** 对标主流企业培训平台（云学堂/绚星/腾讯乐享/Absorb 等）
三大高频能力，突破原「极致极简、杜绝统计/学情分析」设计边界，补齐学员成长激励与学习效果反馈闭环。

### 新增
- **学习积分 + 排行榜**：`point_event` 积分流水表 + `user.learning_points` 冗余总额；
  首次浏览公司/产品/课程、自测提交、正式考试通过、错题标记已掌握均自动加分（规则集中常量，见下）；
  `GET /api/points/me`（我的积分+流水）、`GET /api/points/leaderboard`（全员排行榜含名次）；
  前端 `/exam/leaderboard`「学习排行榜」页
- **考试合格证书**：`certificate` 表；正式考试通过自动颁发（按 `exam_record_id` 幂等去重）；
  `GET /api/exam/certificates` + `GET /api/exam/certificates/:id`（学员）、`GET /api/system/certificates`（管理员）；
  前端 `/exam/my-certificates`「我的证书」页（含可打印证书弹窗）
- **学习档案 / 能力雷达**：`GET /api/my/profile` 返回学习统计（浏览/自测/正式/错题/积分）、
  按域（公司认知/产品知识/销售能力）能力雷达、薄弱域、正式成绩趋势；
  前端 `/exam/my-profile`「我的学习档案」页 + 新增 `RadarChart` SVG 雷达图组件

### 积分规则（集中 `internal/api/points.go` 常量，可一键调整）
| 行为 | 积分 |
|------|------|
| 首次浏览公司介绍 | +10 |
| 首次浏览单个产品 | +2 |
| 首次浏览单门课程 | +5 |
| 自测提交一次 | +5 |
| 正式考试通过 | +50 |
| 错题标记已掌握 | +3 |

### 设计说明
- 能力雷达按「正式考试答题明细 → 题目 → 知识域」反推各域正确率；自测不落分（P03），故自测次数由积分流水统计
- 积分流水逐笔可审计；「错题标记已掌握」仅在未掌握→已掌握时加分，避免反复切换刷分

---

## V1.5（2026-08-16）

**岗位能力闭环补全（P1 + P2）落地。** 在 P0 岗位驱动组卷之上，补齐学员侧「我的岗位应学清单」、
「错题本」、成绩按岗位聚合、岗位考试蓝图、简答题 LLM 评分与后端自动化测试。

### 新增（P1）
- 学员「我的岗位应学清单」`GET /api/my/position`：返回本人岗位 + 应学范围（域/课程/产品/级别/权重/必学）
- 成绩按岗位聚合 `GET /api/system/exam-stats-by-position`（admin）：按岗位汇总员工数/参考人次/通过人次/通过率/平均分
- 岗位考试蓝图：`position_exam_blueprint` 表 + `GET/PUT /api/positions/:id/blueprint`（整表覆盖）；
  `pickQuestions` 优先按蓝图逐条抽题（域+题型+题量），无蓝图回退 P0 岗位映射抽题；
  `CreatePaper/UpdatePaper` 校验蓝图总题量 ≥ 试卷题量
- 前端：`/exam/my-position`「我的岗位清单」页；岗位管理页「考试蓝图」编辑面板；
  全部成绩页新增「按岗位统计」Tab

### 新增（P2）
- 错题本：`mistake_record` 表；交卷判分循环中答错自动入本（自测/正式均写，按
  `(user_id, question_id, source)` 去重，再次答错更新并重置为未掌握）；
  `GET /api/exam/mistakes` + `PUT /api/exam/mistakes/:id/resolve`；
  前端 `/exam/my-mistakes`「我的错题本」页（来源/状态筛选 + 标记已掌握）
- 简答题 + LLM 评分：`question.type` 增加 `essay`（`answer` 存评分标准，`options` 空）；
  交卷时对 essay 题调 LLM（复用 `title_gen` 文本生成路由，回退链 + 审计，`essay_grade` 能力不扣点）
  按评分标准打 0~1 得分率；总分改为 `Σ得分率/题数×总分`，选择题仍确定性判分；
  `detail_json` 新增 `score_rate` / `comment`；前端答题页 essay 文本域 + 结果页得分率展示
- 自动化测试：`internal/api/exam_test.go`（isCorrect/splitDomains/splitIDs/dedupe/
  normalizeUserAnswer/parseEssayScore/scoreBand/round1）、`internal/ai/retrieve_test.go`
  （splitTerms/cosine）；`go test ./...` 全绿

### 待确认（落地时按设计默认值，可一键调整）
- 错题本写入范围：现自测/正式均写入；如需仅正式考写入，去掉自测分支即可
- 简答题评分失败降级：LLM 路由未配置时交卷报错（Fail Fast）；运行时调用失败则评 0 分并
  在评语标注「评分失败」，不静默吞掉
- 蓝图维度：题目本身不携带 L1-L4 级别字段，故蓝图按「域 + 题型」抽样，不做级别加权

---

## V1.4（2026-08-16）

**岗位与知识对应能力（P0）落地。** 补齐「岗位 → 知识映射 → 用户设岗 → 岗位驱动组卷」闭环，
对齐 pj006 的岗位驱动思想，但保持极简单租户定位（不引入洋葱模型 / 多租户 / 多岗位）。

### 新增
- 数据表 `position`（岗位）与 `position_knowledge`（岗位知识要求映射：知识域 domain +
  可选课程 course_id / 产品 product_id + 级别 L1-L4 + 权重 + 必学开关）
- `User.PositionID`、`ExamPaper.PositionID` 可空列（AutoMigrate 幂等，对现有数据零破坏）
- 岗位 API（admin）：`GET/POST/PUT/DELETE /api/positions`、
  `GET/PUT /api/positions/:id/knowledge`（整表覆盖保存映射）、`PUT /api/users/:id/position`（设岗/清岗）
- 岗位驱动组卷：`pickQuestions` 按岗位知识映射圈定题池（岗位考试优先，否则回退 domain 抽题）；
  `CreatePaper/UpdatePaper` 校验「岗位必须存在且已配置知识映射」
- 前端「岗位管理」页（`/system/positions`）+ 知识映射编辑面板；用户管理页「关联岗位」行内下拉；
  题库管理试卷表单「关联岗位」下拉

### 待确认（落地时按设计默认值，可一键调整）
- 岗位考试课程过滤语义：现为宽松 `course_id IN ? OR course_id IS NULL`（岗位绑课程后仍纳入
  「未绑课程但域匹配」的题）；如需课程强约束，改为严格匹配 `course_id IN ?`
- 映射去重约束：现不建 `UNIQUE`，允许同岗位同域多条（如按产品细分）

---

## V1.3（2026-08-16）

**目录重构 + 全功能联调测试 + 修复 1 个缺陷。**

### 变更
- `docs/`（设计文档）从 `eai_agentplatform_app/` 移出到仓库根 `pj0231-eai_agentplatforming/docs/`，与 `CODING_RULES.md` 平级
- `knowledge_source/`（知识源运行时数据）从 `docs/` 移入 `backend-go/knowledge_source/`，归后端
- 后端 `KNOWLEDGE_SOURCE_DIR` 默认值 `../docs/knowledge_source` → `knowledge_source`；部署路径 `/opt/eai_agentplatform/knowledge_source`
- 前后端全功能联调测试通过（认证/权限边界/产品/课程/考试/素材审批/知识入库/AI）
- 素材存储目录 `data/media` → `data/kb_data`，子目录三态化：`approved/`（已审批公开）、
  `pending/`（待审批）、`rejected/`（已驳回）；环境变量 `MEDIA_DIR` → `KB_DATA_DIR`。
  表名 `media_file`、API 路由 `/api/media/*`、静态 URL 前缀 `/media` 均保持不变。

### 修复
- `GET /api/exam/cover?id={id}` 无法解析 query 参数（`parseID` 误读路径参数 `c.Param`），
  导致考试封面永远返回「无效的 id」；改用 `c.Query("id")` 修复

---

## V1.2（2026-08-15）

**后端 Python → Go 重写完成，删除旧 Python 后端目录。**

### 变更
- 后端由 FastAPI/Python 整体重写为 **Go + Gin + GORM + SQLite（modernc 纯Go驱动）**，位于 `backend-go/`
- 旧 Python 后端目录 `backend/` 已整体删除，Go 后端为唯一后端
- 认证：JWT（golang-jwt）+ bcrypt；文档转换：LibreOffice + pdftotext（裸进程）
- 部署：裸进程 + systemd + Clonezilla 整盘克隆，Go 单二进制交付（无 Docker、无源码交付）
- 文件存储路径：`backend/data/media` → `data/media`（Go 后端工作目录下，部署为 `/opt/eai_agentplatform/data/media`）

### 说明
- `docs/` 下历史设计文档（SY/AR/BE/设计稿）中残留的 `backend/`、`backend/data/media`、
  `backend/app/*` 及 Docker `build: ./backend` 等路径，为 **V1.1 设计期历史快照**，不再反映当前实现；
  当前实现以 `docs/db_schema.md`、`docs/deploy.md`、`backend-go/deploy/DELIVERY.md` 为准。

---

## V1.1（2026-08-15）

**最终定稿版。** 修复 V1.0 中 9 个内部不自洽问题。

### 新增
- AI LLM 底座明确为「内网可访问地址（OpenAI 兼容接口）」，消除矛盾
- MP4 仅预览、不提取文本、不进 AI 知识库，消除矛盾
- PDF 文本提取技术选型（PyMuPDF）
- 题库管理、组卷规则、合格线配置，补全考试闭环
- 产品 / 课程内容的后台维护入口
- 认证鉴权方案（JWT + bcrypt + 后端 API 鉴权）
- 大文件分片上传、审批后异步转换任务、上传安全
- 核心数据表字段设计（8 张核心表 + system_config）
- 部署架构补充 LLM 服务与 Nginx 反代

### 变更
- V1.0 → V1.1 整体修订

### 修复
- 消除「无外网依赖」与「配置 LLM 地址」的矛盾
- 消除「不做转码」与「视频进 AI」的矛盾

---

## V1.0（初始版）

初始产品需求文档。