# API 文档

## 系统接口
### `GET /health`
返回：
```json
{
  "service": "ok",
  "database": "ok",
  "rag": "ok",
  "timestamp": "2026-03-30T12:00:00+08:00"
}
```

## 抽取接口
### `POST /poc/extract/job`
请求：
```json
{ "text": "明天下午南山会展中心需要2个签到协助，5小时，150/人，女生优先" }
```

### `POST /poc/extract/worker`
请求：
```json
{ "text": "我做过商场促销和活动签到，也能做登记和引导，周末都能接，福田南山都方便。" }
```

## 入库接口
### `POST /poc/ingest/job`
请求体：
```json
{ "job": { "...": "JobCard" } }
```

### `POST /poc/ingest/worker`
请求体：
```json
{ "worker": { "...": "WorkerCard" } }
```

### `POST /poc/ingest/bootstrap`
说明：导入样本数据、词表、Qdrant 检索索引数据。

## 匹配接口
### `POST /poc/match/workers`
支持 `job_id` 或内联 `job`：
```json
{
  "job_id": "job_001",
  "top_n": 10
}
```

### `POST /poc/match/jobs`
支持 `worker_id` 或内联 `worker`：
```json
{
  "worker_id": "worker_001",
  "top_n": 10
}
```

### `GET /poc/match/explain/{match_id}`
返回具体匹配明细与理由。

## 查询接口
### `GET /poc/jobs`
### `GET /poc/workers`
### `GET /poc/jobs/{job_id}`
### `GET /poc/workers/{worker_id}`

## 交接说明
- 抽取接口返回 `success/data/errors/missing_fields`，方便后续切换更强 LLM 时做错误回退。
- 匹配接口输出 `breakdown` 五维打分，可直接给后续运营、策略或模型团队继续调权。
- `packages/shared-types/src/index.ts` 保留了前端可复用类型定义。