RoyirinRosmontis
a10442d78c
- 全链路：多源JD接入/清洗交叉验证/结构化抽取(星火+离线双通道)/时序知识图谱/新岗位发现/演化分析/人岗匹配/学习路径 - WebUI 五视图：驾驶舱/图谱工作台/岗位演化/匹配(单人+批量)/学习路径 - 设置中心(config.json)/Token鉴权/SQLite状态库/语义向量通道(BGE-M3本地或联网API) - 71 个 pytest 用例；数据目录仅保留结构(.gitkeep)，数据由 scripts/generate_dataset.py 复现
136 lines
9.4 KiB
Markdown
136 lines
9.4 KiB
Markdown
# CareerNexus 职联 · 项目方案补充（v3.1）
|
||
|
||
> 本文档是《CareerNexus职联_项目方案.md》（v3.0）的补充，记录方案定稿后的**实现增量**。
|
||
> 所有内容均已落地为可运行代码并通过测试验证（pytest 53 用例全绿），与原方案不一致处以本文为准。
|
||
> 版本：v3.1 · 2026-08
|
||
|
||
---
|
||
|
||
## 一、补充概览
|
||
|
||
v3.0 方案交付了"能跑的最小完整系统"。v3.1 在此之上完成四个方向的增强：
|
||
|
||
1. **交互与展示深化**：WebUI 从"能用"升级到"企业级产品形态"，演化分析从单一图表升级为七模块图表体系；
|
||
2. **应用能力扩展**：结构化简历模板与导出、批量人岗匹配、语义相似匹配通道；
|
||
3. **运行时工程化**：设置中心、Token 鉴权、SQLite 状态库、按需下载的打包策略、静态缓存控制；
|
||
4. **诚实性维护**：多处指标口径修正、测试隔离加固、文档与实现对齐。
|
||
|
||
---
|
||
|
||
## 二、前端体系（WebUI 2.0）
|
||
|
||
### 2.1 企业级设计系统
|
||
|
||
- 布局重构：**顶部品牌栏（56px）+ 横向导航条（46px，居中、选中态三重信号：主色加粗/浅蓝底/3px 指示条）**，替代原左侧深色边栏，主内容全宽。
|
||
- 设计 token：主色 #2f54eb、Arco 系语义色、8px 间距网格、按钮四态/tag/卡片/弹窗/toast/空态/骨架屏统一组件；图标全部内联 SVG，**零外部依赖、断网可用**。
|
||
- 静态资源缓存控制：非 /api 响应统一 `Cache-Control: no-cache` + 资源版本号，杜绝"浏览器拿旧前端"问题。
|
||
- **统一系统弹窗**（sysDialog 组件族：sysPrompt/sysConfirm/sysAlert/sysCopy），前端已无任何浏览器原生 alert/prompt/confirm。
|
||
- **URL 路由**：视图与图谱节点写入 location.hash（`#view=xxx&node=xxx`），刷新/分享可恢复到同一视图同一节点。
|
||
|
||
### 2.2 全景图谱工作台
|
||
|
||
- 节点四型分色分形状（Job/Skill/Industry/Scenario、待审核虚线框），必备实线/加分虚线 + 文字标签双编码，选中节点一跳高亮。
|
||
- 左上工具条（缩放/适应/筛选/标签开关/整理布局）、左下小地图与图例、导出 PNG、保存视图/分享链接。
|
||
- **右侧详情面板**（320px 可滚动）：基础信息、关联节点（可点击跳转+返回）、证据来源（点击弹 JD 原文）、技能热度 sparkline、审核留痕。
|
||
- **可编辑**：节点属性编辑弹窗（写后端并留痕）、备注增删、候选节点确认/驳回。
|
||
- **连线类型复选框**：必备/加分/场景/行业四类边独立开关（默认全开），选中高亮与之一致。
|
||
- 右下"智能建议"浮层、底部演化逻辑链 chips。
|
||
|
||
### 2.3 首次使用引导
|
||
|
||
- 首次启动自动弹出"初始设置"弹窗（同设置面板），完成标记 `guided` 持久化在服务端 `config.json`（换浏览器不重弹）；保存/跳过均可完成。
|
||
|
||
---
|
||
|
||
## 三、岗位演化页：七模块图表体系
|
||
|
||
信息结构自顶向下逐级下钻：
|
||
|
||
| 模块 | 内容 | 数据源 |
|
||
|---|---|---|
|
||
| ① 全部岗位演化热力图 | 岗位×季度矩阵，色深=事件数（开方缩放+封顶色阶），悬停看类型分布，点击行切换岗位 | /api/graph events |
|
||
| ② 统计条 | 当前必备/加分技能数、近 4 季度新增/退出、证据 JD 总量 | 岗位定义+事件 |
|
||
| ③ 能力画像时点对比器 | 任意两日期技能集合 diff：已退出(红)/保留(灰)/新增(绿)，重要性升级带↑，点击跳图谱 | 新接口 `GET /api/jobs/{id}/snapshot?at=` |
|
||
| ④ 变更类型构成堆叠柱状图 | 每季度 新增/增强/减弱/退出 四色堆叠 | 事件 |
|
||
| ⑤ 技能生命周期甘特图 | 每技能一行，横条=生效区间（必备蓝/加分青），圆点=变更事件；读出"Struts 2019 进场 2022 退场"编年史 | 边 intervals |
|
||
| ⑥ 技能热度走势 | **每季度实际生效的技能关系数**（按 REQUIRES 边生效区间统计） | 边 intervals |
|
||
| ⑦ 事件时间轴 | 四类事件分色，点击弹证据 JD 原文，时间轴限高滚动 | 事件+source_ids |
|
||
|
||
**指标口径修正**：原"累计新增−退出"算法基线错误（忽略技能存量，导致曲线贴底看似无数据），v3.1 改为按生效区间统计真实活跃数，已用线上数据验证。
|
||
|
||
---
|
||
|
||
## 四、人岗匹配增强
|
||
|
||
### 4.1 技能归一化四级容错
|
||
|
||
1. 精确/别名（大小写不敏感）：`redis→Redis`、`K8s→Kubernetes`；
|
||
2. 包含匹配（取最长命中）：`微服务架构→微服务`、`Java语言→Java`（`JavaScript` 不被截胡）；
|
||
3. 类别迁移提示：同类别技能作为"可迁移技能"展示；
|
||
4. **语义召回（v3.1 新增，可选增强）**：词表未命中时经向量相似度兜底（阈值 0.62，经真实数据标定——正确拦截 `JVM调优→模型微调` 错配与垃圾输入）。
|
||
|
||
诊断结果页补充"与目标岗位无关的技能（不计入评分）"展示区，消除"我加的技能哪去了"的困惑。
|
||
|
||
### 4.2 结构化简历模板与导出
|
||
|
||
- 解析增强：性别/学历/家庭住址识别（住址脱敏）、20+ 常见标题**智能分节**、**证件照提取**（docx 内嵌图 / pdf 页面图，data URI 返回）。
|
||
- 第 3 步左栏渲染**标准表格风简历**：左上照片、标签-值信息格、分节行（蓝底标题列），技能按匹配结论三色标注。
|
||
- **DOCX 导出**（`POST /api/resume/export`）：照片嵌入 + 信息表 + 分节正文（命中技能加粗上色）+ 人岗匹配诊断摘要，一键下载。
|
||
- 上传支持 .txt/.docx/.pdf（≤5MB，临时文件即解析即删）。
|
||
|
||
### 4.3 批量匹配（企业服务雏形）
|
||
|
||
- 新接口 `POST /api/match/batch`：≤50 份简历对同一岗位批量打分，单份失败不拖垮整批。
|
||
- 前端"单人诊断 / 批量匹配"子页签：**拖拽文件/文件夹（递归遍历）、多选、整目录导入**三种添加方式；结果表按总分降序（候选人/总分进度条/命中/缺口/结论）。
|
||
- **CSV 批量导出**（14 列含四维分，带 BOM，Excel 中文不乱码）。
|
||
|
||
---
|
||
|
||
## 五、语义向量通道（BGE-M3）
|
||
|
||
- 双模式可选：`local`（本地权重，sentence-transformers 懒加载）/ `api`（联网 Embedding API，默认 DashScope 兼容模式 text-embedding-v4）；任一就绪即启用，失败静默回退词表模式。
|
||
- 就绪检测：权重目录文件完整性（config.json + 权重文件 + 分词器）+ 依赖可导入，五字段状态经 /api/health 与 /api/config 暴露。
|
||
- 本机已实配：BGE-M3 权重 4.3GB（ModelScope 下载至 `models/bge-m3`），实测 `数据分析报表→数据分析(0.889)`、`写微服务→微服务(0.856)` 等正确命中。
|
||
|
||
---
|
||
|
||
## 六、设置中心与运行时工程
|
||
|
||
- **设置面板**（顶栏 ⚙，加宽 780px）：服务监听（127.0.0.1/0.0.0.0 + 端口 + 访问令牌）、LLM API（星火/OpenAI 兼容，密钥脱敏回显）、语义向量（双模式 + 下载引导）。
|
||
- **config.json 运行时设置**：白名单键持久化，优先级 config.json > config.yaml > 默认值；LLM/令牌/语义配置保存即热生效，监听/端口需重启（面板提供"保存并重启"，os.execv 原地重启）。
|
||
- **Token 鉴权**：设置令牌后 /api/* 需 `X-Access-Token` 头（health 与只读 GET /api/config 豁免），前端自动携带，401 自动弹设置引导。
|
||
- **双横幅提示**：LLM 离线回退 / 语义模型未就绪，同款橙色横幅上下排列，可独立关闭，配置后自动消失。
|
||
- **一键下载并配置**：`POST /api/semantic/setup` 异步管线（装依赖→镜像站下载权重→自动写配置），进度轮询（阶段+日志），幂等防并发——**打包只含基础环境（~400MB），重依赖按需下载**；`INCLUDE_EMBED=1` 全量镜像变体保留为断网交付选项。
|
||
|
||
---
|
||
|
||
## 七、SQLite 应用状态库
|
||
|
||
`data/careernexus.db`（标准库 sqlite3、WAL、零新增依赖）：
|
||
|
||
| 表 | 内容 | 消费方 |
|
||
|---|---|---|
|
||
| audit_log | 审核/编辑留痕（时间/节点/动作/操作人/改前改后） | 图谱详情留痕区、驾驶舱消息流、/api/audit |
|
||
| review_candidates | 新岗位待审核候选（与正式图谱隔离） | 审核台、候选节点、待办计数 |
|
||
| tasks | 异步任务状态，重启可恢复，中断自动标记失败 | 任务轮询 |
|
||
|
||
首次启动自动从旧 JSON 文件迁移种子（幂等，原文件保留）。语料（jd_raw JSONL）、图谱快照（graph.json）、配置（config.json）仍留文件——**"随运行增改的状态进库，语料与快照留文件"**。
|
||
|
||
---
|
||
|
||
## 八、工程与验证现状（2026-08 实测)
|
||
|
||
- **pytest 53 用例全绿**，覆盖率 78%（新增：批量匹配、语义双模式、一键配置、结构化简历与导出、存储层、设置与鉴权等专项）。
|
||
- 测试卫生修复：路径隔离（不再污染真实 config.json）、幂等快路径（单测 150s→1.5s）。
|
||
- 装配层重构：`main.py` 瘦身为 10 行入口，`app/bootstrap.py` 承担启动装配；全工程 32 个 Python 模块、10 个子包。
|
||
- 三项指标维持：JD 解析 100% / 简历提取 100% / 人岗匹配 100%（scripts/evaluate.py 可复现）。
|
||
- Neo4j 可选组件：compose `advanced` profile + `scripts/sync_neo4j.py`（MERGE 幂等，--dry-run 可预览）；Docker 默认镜像轻量离线，语义变体可选构建。
|
||
|
||
## 九、待办（下一步）
|
||
|
||
- Docker 镜像实际构建验证（Dockerfile 已就绪，未实机构建）。
|
||
- Neo4j 真实容器同步实测（当前 dry-run 验证）。
|
||
- 项目介绍 PPT（≤10 页）与 ≤10 分钟演示视频（按方案第十章演示脚本录制）。
|
||
|
||
*（补充完）*
|