JobMatch V1 / P0

最小全栈 MVP，目标是把岗位管理闭环先跑通：

• 统一新建页
• JD 粘贴录入
• 纯手动创建
• 固定字段提取 fallback 链路
• 当前岗位字段编辑
• 原始 JD 快照后台保留
• 搜索、基础筛选、归档
• 轻量重复提醒

目录

• frontend/: Next.js App Router 前端
• backend/: FastAPI + SQLAlchemy async 后端

JD 提取配置

默认仍可使用 mock_fallback，如果要启用真实 LLM 提取，请在 jobmatch/.env 中配置：

EXTRACTION_RUNTIME_MODE=llm_primary_with_heuristic_fallback
LLM_BASE_URL=https://your-openai-compatible-endpoint/v1
LLM_API_KEY=your-llm-api-key
LLM_MODEL=your-llm-model
LLM_PROVIDER_NAME=openai_compatible

说明：

• LLM_BASE_URL 可留空，此时会走 OpenAI SDK 默认地址。
• 如果未配置 LLM_*，后端会回退读取 OPENAI_API_KEY 和 OPENAI_MODEL。
• 真实 LLM 调用失败、超时、鉴权失败、JSON 非法或 schema 不合法时，会自动降级到启发式提取。
• 启发式提取也失败时，接口会返回结构化失败信息，但不会阻断 JD 保存和手动填写。

本地启动

1. 复制并检查环境变量：

   cp .env.example .env

2. 启动 PostgreSQL：

   docker compose up -d

3. 启动后端：

   cd backend
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   alembic upgrade head
   uvicorn app.main:app --reload

4. 启动前端：

   cd frontend
   npm install
   npm run dev

本地版本管理与恢复

为了避免新功能开发时误伤当前可用功能，jobmatch/ 采用“checkpoint + 功能分支”的本地版本安全流程。

首次初始化

只需要执行一次，在确认当前代码处于可接受基线后完成：

cd jobmatch
npm --prefix frontend run lint
cd backend && pytest -q && cd ..
git init -b main
git add .
git commit -m "chore: initialize local version safety"
git tag -a "checkpoint/$(date '+%Y%m%d-%H%M')-baseline-stable" -m "Stable local baseline"

说明：

• jobmatch/.env 默认已被 .gitignore 排除，不会进入版本库。
• 如果首次初始化前还没有可用的本地 git，可临时复制 jobmatch/ 到工作区 .backups/ 作为应急备份，但这不是默认流程。

开始一个新功能

以后每次开始新功能、非微小重构或跨层改动前，都在 jobmatch/ 根目录运行：

./scripts/start-feature.sh <feature-slug>

例如：

./scripts/start-feature.sh job-list-polish

这个入口会自动：

• 检查当前 git 工作区是否干净
• 运行最小健康检查：
  • frontend: npm run lint
  • backend: pytest -q
• 创建 annotated checkpoint tag：checkpoint/YYYYMMDD-HHMM-<feature-slug>
• 切换到功能分支：codex/<feature-slug>

查看已有 checkpoint

git tag -l 'checkpoint/*' --sort=-creatordate

安全恢复查看

默认先切一个恢复分支检查，不直接做硬回退：

git switch -c restore/<feature-slug> checkpoint/YYYYMMDD-HHMM-<feature-slug>

例如：

git switch -c restore/job-list-polish checkpoint/20260329-1530-job-list-polish

重要约束

• checkpoint 创建失败时，不要继续写实现。
• 如果 npm run lint 或 pytest -q 没通过，先修复或确认失败原因，再开始新功能。
• 未经明确同意，不要执行 git reset --hard 之类的破坏性回退命令。

本地数据库恢复

如果前端保存岗位时出现 Failed to fetch，或后端保存接口返回 500 Internal Server Error，同时 PostgreSQL 容器日志里出现类似下面的报错：

could not open file "global/pg_filenode.map": Operation not permitted

说明本地开发库的底层数据目录已经损坏或权限异常。当前 docker-compose.yml 已改为使用 Docker named volume，推荐直接重建开发库：

cd jobmatch
docker compose down -v --remove-orphans
docker compose up -d

cd backend
pip install -e ".[dev]"
PYTHONPATH=. alembic upgrade head

重建完成后可用下面的命令快速验证：

curl http://localhost:8000/api/v1/health
curl -i -H 'Content-Type: application/json' \
  -d '{"mode":"manual","current_record":{"job_title":"测试岗位","company_name":"测试公司","full_location_text":"上海"}}' \
  http://localhost:8000/api/v1/jobs

当前提取模式

当前提取接口支持两种运行模式：

• mock_fallback
  • 只使用后端启发式规则提取
  • 返回正式的结构化草稿 schema
  • 提取失败时返回结构化失败原因
  • 不会阻断岗位保存
• llm_primary_with_heuristic_fallback
  • 优先调用真实 OpenAI 兼容接口
  • 如果真实 LLM 失败，会自动降级为启发式草稿
  • 返回的始终是可编辑草稿，不会自动覆盖用户已填字段

无论哪种模式，前端数据流都不变：只填充当前空白字段，用户仍可手动修正并继续保存。