# CareerNexus 职联 · 技术栈清单

> 记录本项目实际使用的全部技术栈（2026-08，与代码仓库一致）。
> 选型总原则：**离线优先、零重依赖、单命令启动、可复现**。

---

## 一、语言与运行时

| 技术 | 版本 | 用途 |
|---|---|---|
| Python | 3.11+（开发环境 3.13） | 后端、算法、数据管线、脚本 |
| JavaScript（原生） | ES2020+ | 前端全部交互（无 TypeScript/无构建） |
| Node.js | 20+ | 仅用于前端语法检查与逻辑单测（不参与运行） |

## 二、后端

| 技术 | 版本 | 用途 |
|---|---|---|
| FastAPI | ≥0.110 | REST 接口层（20+ 端点，统一响应格式/任务轮询/静态托管） |
| Uvicorn | ≥0.29 | ASGI 服务（127.0.0.1:9008，可切 0.0.0.0 + Token 鉴权） |
| Pydantic | v2 ≥2.6 | 全链路数据模型与 Schema 强校验（JD/抽取/图谱/匹配/简历） |
| httpx | ≥0.27 | LLM API 与 Embedding API 调用 |
| networkx | ≥3.2 | 时序知识图谱的底层有向图结构 |
| python-docx | ≥1.1 | 简历 DOCX 解析、规范简历 DOCX 导出 |
| pypdf | ≥4.0 | 简历 PDF 文本与内嵌照片提取 |
| reportlab | 仅样例生成 | 中文演示 PDF 样例制作（非运行依赖） |

## 三、前端（零构建、完全离线）

| 技术 | 说明 |
|---|---|
| 原生 HTML/CSS/JS | 无 React/Vue/npm，FastAPI 直接托管静态文件 |
| Canvas 2D | 图谱力导向/同心分层/职级分带/时序四种布局渲染、趋势图、雷达图、甘特图 |
| 自研设计系统 | 设计 token（主色 #2f54eb）、组件库（按钮/tag/卡片/抽屉/弹窗/分段控件）、内联 SVG 图标 |
| sysDialog 组件族 | 统一系统弹窗（sysPrompt/sysConfirm/sysAlert/sysCopy），替代浏览器原生弹窗 |
| cnFetch | 统一网络层：业务化中文错误、屏蔽内部细节、原位重试 |
| localStorage/sessionStorage | 视图状态、备注、学习记录、引导标记缓存 |

## 四、数据与存储

| 技术 | 用途 |
|---|---|
| 自研 TemporalKG（时序知识图谱） | 岗位-技能关系带生效区间/变更事件/证据源，任意时点切片 |
| JSON 快照（graph.json） | 图谱持久化与快速加载 |
| SQLite（标准库 sqlite3，WAL） | 应用状态库：审核留痕 audit_log、候选 review_candidates、任务 tasks、人工覆写 job_overrides |
| JSONL | JD 语料交换格式（jd_raw/、data/real/） |
| config.yaml + config.json | 静态配置 + 运行时设置（设置面板持久化，白名单键） |
| 文件系统 data/ | 语料/测试集/词表/简历/报告分目录治理 |

## 五、算法（全部纯 Python 自实现，无重型 ML 框架）

| 算法 | 实现 |
|---|---|
| MinHash LSH 近重复检测 | 256 哈希签名 + 5-gram shingles + 16 band 分带（抄袭 JD 聚簇） |
| 时间衰减加权 | w=exp(-λ·age)，抑制 JD 时滞 |
| TF-IDF + 凝聚聚类 | 字符 2/3-gram 向量化、平均链接贪心合并（新岗位发现） |
| 时序演化分析 | 季度窗口加权频次对比 → 新增/增强/减弱/退出事件 |
| 新岗位四指标判定 | 支撑 JD 数/独立企业数/双年窗口增长率/与既有岗位差异度 |
| Kahn 拓扑分层 | 学习路径按技能前置关系分层 + 每阶段 ≤3 技能拆分 |
| 四维加权匹配评分 | 必备 50%/加分 15%/经验 20%/场景 15%，权重可配 |
| 技能归一化四级容错 | 词表别名 → 包含匹配 → 类别迁移 → BGE-M3 语义召回（阈值 0.62） |
| 简历解析 | 正则族 + 版面分节 + 脱敏（姓名/手机/邮箱/住址）+ 照片提取 |

## 六、AI 模型

| 模型 | 接入方式 | 用途 |
|---|---|---|
| 讯飞星火 Spark 4.0 Ultra | OpenAI 兼容 API（JSON 模式 + Schema 校验 + 失败重试 + 离线降级） | JD 结构化抽取主通道（密钥经设置面板注入） |
| BGE-M3 | sentence-transformers 本地权重（models/bge-m3，4.3GB） | 语义相似召回兜底（词表外技能映射） |
| 通义千问 text-embedding-v4 | DashScope OpenAI 兼容 API（可选替代本地权重） | 联网语义向量 |
| 离线确定性抽取器 | 技能词表 + 版面规则（无模型） | 全部 AI 通道的降级兜底 |

## 七、测试与评测

| 技术 | 用途 |
|---|---|
| pytest + pytest-cov | 77 个单元/接口/持久化测试，覆盖率 ≥80% |
| node 逻辑单测 | tests/test_frontend_logic.js（49 个前端纯函数用例） |
| 自研 evaluate.py | 三层指标：合成集（100%）/ 真实 JD（AutoWeakS，F1 99.8%）/ 真实简历（100%） |
| run_demo.py | 端到端冒烟（pipeline + 图谱 + 匹配示例） |

## 八、部署与运维

| 技术 | 用途 |
|---|---|
| Docker（python:3.11-slim） | 一体化镜像；`INCLUDE_EMBED=1` 可选语义增强变体 |
| docker-compose | app 编排 + Neo4j `advanced` profile（可选） |
| Neo4j 5 Community（可选） | 生产图数据库增强，scripts/sync_neo4j.py MERGE 幂等同步 |
| init.bat / init.sh | 一键初始化（venv + 依赖镜像站安装 + 离线默认配置 + 数据集生成） |
| start.bat / start.sh | 一键启动（项目内 venv 直起服务，自动开浏览器） |
| ModelScope | BGE-M3 权重国内镜像下载（设置面板一键配置管线） |

## 九、数据源

| 数据集 | 授权 | 用途 |
|---|---|---|
| AutoWeakS（北大/人大，arXiv:2012.14234） | 论文公开语料 | 真实 JD 语料（2915 条被动接入）+ 500 条真实评测集 |
| AIStudio 中文简历标注集 | CC0 | 200 份真实简历评测 |
| Chinese_resume 数据集 | 公开（研究用途） | 批量匹配演示简历（脱敏后 32 份） |
| ISCO/ESCO 国际职业分类 | EU 公开 | 岗位标准外部锚点 |
| 程序生成语料（seed=2026） | 自产 | 1720 条演示 JD、176 条测试集、词表 179 项、匹配标注 52 对 |

## 十、版本与协作

| 技术 | 用途 |
|---|---|
| Git + Gitea | 代码托管（`https://git.bu4.ren/RoyirinRosmontis/CareerNexus.git`） |
| .gitignore/.dockerignore | 数据内容、密钥配置、模型权重不入库/不进镜像 |

---

## 已评估未采用（及原因）

| 技术 | 未采用原因 |
|---|---|
| React/Vue + AntV G6 | 引入 npm 构建链，违背"零构建离线" |
| FAISS / BGE reranker / BM25 引擎 | 需模型权重或额外服务；词表归一化 + 透明加权已满足精度 |
| BERTopic / HDBSCAN | 重依赖；纯 Python TF-IDF + 凝聚聚类可复现且足够 |
| GLiNER | 重型 NER 模型；离线确定性抽取器更轻且确定性更强 |
| RAGAS | 需在线评测框架；evaluate.py 字段级 F1 + 真实数据集评测已覆盖 |
| PostgreSQL | 单机演示规模用不上；SQLite 零配置，存储边界已隔离可随时切换 |