# API 文档（中文完整版）

## 机器可读文档（推荐作为联调基准）
- Swagger UI：`http://127.0.0.1:8000/docs`
- OpenAPI JSON：`http://127.0.0.1:8000/openapi.json`
- 一键导出：
```bash
cd gig-poc
sh infrastructure/scripts/export-openapi.sh
```
- 导出到自定义路径：
```bash
sh infrastructure/scripts/export-openapi.sh ./docs/openapi.prod.json
```

## 通用约定
- 基础路径：默认通过网关暴露为 `/api`，下文写的是服务内部路径（如 `/poc/...`）。
- 数据格式：`Content-Type: application/json`。
- 时间字段：ISO-8601 格式（示例：`2026-03-30T12:00:00+08:00`）。
- 分数字段：大部分评分为 `0~1` 浮点数。
- 常见错误码：
  - `400/422`：请求参数不合法（字段缺失、类型不匹配、取值超范围）。
  - `404`：查询对象不存在（如岗位 ID、工人 ID、匹配记录 ID 不存在）。
  - `500`：服务内部异常（数据库、向量检索、模型调用失败等）。

## 数据结构说明

### Salary（薪资结构）
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `daily/hourly/monthly/task` | 薪资类型：日薪/时薪/月薪/按单 |
| `amount` | `number` | 薪资金额 |
| `currency` | `string` | 货币，默认 `CNY` |

### SkillScore（技能分）
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `string` | 技能名称 |
| `score` | `number` | 技能熟练度，范围 `0~1` |

### JobCard（岗位卡片）
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `job_id` | `string` | 岗位唯一 ID |
| `title` | `string` | 岗位标题 |
| `category` | `string` | 岗位类别 |
| `description` | `string` | 岗位描述 |
| `skills` | `string[]` | 需要的技能列表 |
| `city` | `string` | 城市 |
| `region` | `string` | 区域 |
| `location_detail` | `string` | 详细地址或地标 |
| `start_time` | `datetime` | 开始时间 |
| `duration_hours` | `number` | 工时（小时，>0） |
| `headcount` | `number` | 需求人数（>0） |
| `salary` | `Salary` | 薪资信息 |
| `work_mode` | `string` | 工作模式（如兼职/全职/活动） |
| `tags` | `string[]` | 业务标签 |
| `confidence` | `number` | 抽取或录入置信度，范围 `0~1` |

### WorkerCard（工人卡片）
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `worker_id` | `string` | 工人唯一 ID |
| `name` | `string` | 姓名/昵称 |
| `description` | `string` | 自我描述 |
| `skills` | `SkillScore[]` | 技能及熟练度 |
| `cities` | `string[]` | 可接单城市 |
| `regions` | `string[]` | 可接单区域 |
| `availability` | `string[]` | 可上岗时段（自由文本） |
| `experience_tags` | `string[]` | 经验标签 |
| `reliability_score` | `number` | 履约可靠性分，范围 `0~1` |
| `profile_completion` | `number` | 档案完善度，范围 `0~1` |
| `confidence` | `number` | 抽取或录入置信度，范围 `0~1` |

### MatchResult（匹配结果）
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `match_id` | `string` | 匹配记录 ID |
| `source_type` | `job_to_worker/worker_to_job` | 匹配方向 |
| `source_id` | `string` | 发起匹配的实体 ID |
| `target_id` | `string` | 被匹配到的实体 ID |
| `match_score` | `number` | 综合匹配分（`0~1`） |
| `breakdown.skill_score` | `number` | 技能匹配分 |
| `breakdown.region_score` | `number` | 地域匹配分 |
| `breakdown.time_score` | `number` | 时间匹配分 |
| `breakdown.experience_score` | `number` | 经验匹配分 |
| `breakdown.reliability_score` | `number` | 可靠性匹配分 |
| `reasons` | `string[]` | 至少 3 条可解释理由 |

## 系统接口

### `GET /health`
用途：检查服务、数据库、RAG 组件是否可用。

返回示例：
```json
{
  "service": "ok",
  "database": "ok",
  "rag": "ok",
  "timestamp": "2026-03-30T12:00:00+08:00"
}
```

字段说明：
- `service`：API 进程状态。
- `database`：数据库连通状态（`ok/error`）。
- `rag`：检索增强组件状态（`ok/error`）。
- `timestamp`：服务端当前时间。

### `GET /poc/ops/ai/metrics`
用途：查看 AI 调用观测指标（限流、熔断、降级、fallback 命中率）。

返回示例：
```json
{
  "metrics": {
    "requests_total": 12,
    "success_total": 10,
    "fail_total": 2,
    "fallback_total": 1,
    "rate_limited_total": 0,
    "circuit_open_total": 0,
    "endpoint_failover_total": 1,
    "fallback_hit_rate": 0.0833,
    "success_rate": 0.8333,
    "failure_rate": 0.1667
  }
}
```

### `GET /poc/ops/system/metrics`
用途：查看全局系统护栏指标（流量限流、熔断状态、缓存命中率、异步队列状态）。

返回示例：
```json
{
  "traffic": {
    "requests_total": 1000,
    "rate_limited_total": 0,
    "circuit_blocked_total": 0,
    "window_requests": 120,
    "window_errors": 3,
    "window_error_rate": 0.025,
    "avg_latency_ms": 35.4,
    "circuit_open": 0
  },
  "cache": {
    "backend": "redis",
    "match_hit_rate": 0.62,
    "query_hit_rate": 0.73,
    "match_size": 320,
    "query_size": 800
  },
  "ingest_queue": {
    "queued": 0,
    "processed": 1200,
    "failed": 2
  },
  "match_queue": {
    "queued": 2,
    "processed": 3400,
    "failed": 7
  }
}
```

## 抽取接口

### `POST /poc/extract/job`
用途：将岗位自然语言文本抽取为结构化 `JobCard`。

请求体：
```json
{
  "text": "明天下午南山会展中心需要2个签到协助，5小时，150/人，女生优先"
}
```

请求字段说明：
- `text`：待抽取文本，最小长度 5。

返回结构：`ExtractResponse`
```json
{
  "success": true,
  "data": {
    "job_id": "job_demo_001",
    "title": "活动签到协助",
    "category": "会展活动",
    "description": "南山会展中心活动签到协助",
    "skills": ["签到", "引导"],
    "city": "深圳",
    "region": "南山",
    "location_detail": "南山会展中心",
    "start_time": "2026-04-01T14:00:00+08:00",
    "duration_hours": 5,
    "headcount": 2,
    "salary": { "type": "daily", "amount": 150, "currency": "CNY" },
    "work_mode": "兼职",
    "tags": ["女生优先"],
    "confidence": 0.88
  },
  "errors": [],
  "missing_fields": []
}
```

字段说明：
- `success`：是否抽取成功。
- `data`：抽取出的结构化岗位对象；失败时可能为 `null`。
- `errors`：错误信息列表。
- `missing_fields`：缺失字段列表，便于前端二次补录。

### `POST /poc/extract/worker`
用途：将工人自然语言文本抽取为结构化 `WorkerCard`。

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

返回结构：同 `ExtractResponse`，其中 `data` 为 `WorkerCard`。

说明：
- 适合把聊天文本/简历摘要快速转成可入库结构。
- 若模型无法识别关键字段，会在 `missing_fields` 中给出提示。

## 入库接口

### `POST /poc/ingest/job`
用途：写入或更新岗位卡片（同时更新检索索引）。

请求体：
```json
{
  "job": {
    "job_id": "job_001",
    "title": "活动签到",
    "category": "会展活动",
    "description": "负责活动签到与引导",
    "skills": ["签到", "沟通"],
    "city": "深圳",
    "region": "福田",
    "location_detail": "会展中心",
    "start_time": "2026-04-02T09:00:00+08:00",
    "duration_hours": 8,
    "headcount": 3,
    "salary": { "type": "daily", "amount": 180, "currency": "CNY" },
    "work_mode": "兼职",
    "tags": ["展会"],
    "confidence": 0.95
  }
}
```

返回：返回入库后的 `JobCard`（通常与请求体一致）。

### `POST /poc/ingest/worker`
用途：写入或更新工人卡片（同时更新检索索引）。

请求体：
```json
{
  "worker": {
    "worker_id": "worker_001",
    "name": "张三",
    "description": "有活动执行经验",
    "skills": [
      { "name": "签到", "score": 0.9 },
      { "name": "引导", "score": 0.8 }
    ],
    "cities": ["深圳"],
    "regions": ["福田", "南山"],
    "availability": ["周末全天"],
    "experience_tags": ["会展", "地推"],
    "reliability_score": 0.92,
    "profile_completion": 0.86,
    "confidence": 0.93
  }
}
```

返回：返回入库后的 `WorkerCard`（通常与请求体一致）。

### `POST /poc/ingest/job/async`
用途：异步岗位入库，快速返回任务 ID，不阻塞主请求。

返回示例：
```json
{
  "task_id": "queue_xxx",
  "status": "queued"
}
```

### `POST /poc/ingest/worker/async`
用途：异步工人入库，快速返回任务 ID，不阻塞主请求。

返回结构同 `POST /poc/ingest/job/async`。

### `GET /poc/ingest/queue/{task_id}`
用途：查询异步入库任务状态。

可能状态：
- `queued`
- `processing`
- `done`
- `failed`
- `not_found`

### `POST /poc/ingest/bootstrap`
用途：导入内置样本数据（岗位、工人、技能、类目、区域）并构建检索数据。

请求体：无。

返回示例：
```json
{
  "jobs": 100,
  "workers": 300,
  "skills": 120,
  "categories": 20,
  "regions": 50
}
```

说明：
- 适合开发环境初始化。
- 重复执行会触发 upsert 逻辑（覆盖同 ID 数据）。

## 匹配接口

### `POST /poc/match/workers`
用途：以岗位为源，匹配合适工人。

请求体（二选一）：
1. 传 `job_id`（按已入库岗位匹配）：
```json
{
  "job_id": "job_001",
  "top_n": 10
}
```

2. 传内联 `job`（不依赖入库）：
```json
{
  "job": { "...": "JobCard" },
  "top_n": 10
}
```

字段说明：
- `job_id`：岗位 ID。
- `job`：完整岗位对象。
- `top_n`：返回条数，范围 `1~50`，默认 `10`。
- `job_id` 与 `job` 至少提供一个。

返回：
```json
{
  "items": [
    {
      "match_id": "match_001",
      "source_type": "job_to_worker",
      "source_id": "job_001",
      "target_id": "worker_007",
      "match_score": 0.87,
      "breakdown": {
        "skill_score": 0.9,
        "region_score": 1.0,
        "time_score": 0.8,
        "experience_score": 0.85,
        "reliability_score": 0.8
      },
      "reasons": ["技能高度匹配", "同区域可到岗", "有同类活动经验"]
    }
  ]
}
```

错误说明：
- 当 `job_id` 不存在且未传 `job` 时，返回 `404`，提示“岗位不存在”。

### `POST /poc/match/jobs`
用途：以工人为源，匹配合适岗位。

请求体（二选一）：
1. 传 `worker_id`：
```json
{
  "worker_id": "worker_001",
  "top_n": 10
}
```

2. 传内联 `worker`：
```json
{
  "worker": { "...": "WorkerCard" },
  "top_n": 10
}
```

字段约束：
- `worker_id` 与 `worker` 至少提供一个。
- `top_n` 范围 `1~50`，默认 `10`。

返回：`MatchResponse`，结构同上，`source_type` 为 `worker_to_job`。

错误说明：
- 当 `worker_id` 不存在且未传 `worker` 时，返回 `404`，提示“工人不存在”。

### `POST /poc/match/workers/async`
用途：岗位异步匹配工人（削峰入口），快速返回任务 ID。

请求体：
```json
{
  "job_id": "job_001",
  "top_n": 10
}
```

返回示例：
```json
{
  "task_id": "mq_xxx",
  "status": "queued"
}
```

### `POST /poc/match/jobs/async`
用途：工人异步匹配岗位（削峰入口），快速返回任务 ID。

请求体：
```json
{
  "worker_id": "worker_001",
  "top_n": 10
}
```

返回结构同 `POST /poc/match/workers/async`。

### `GET /poc/match/queue/{task_id}`
用途：查询异步匹配任务状态，完成后返回 `items` 结果集。

可能状态：
- `queued`
- `processing`
- `done`
- `failed`
- `not_found`

### `GET /poc/match/explain/{match_id}`
用途：查询单条匹配记录详情与解释理由。

路径参数：
- `match_id`：匹配记录 ID。

返回：
```json
{
  "match": {
    "match_id": "match_001",
    "source_type": "job_to_worker",
    "source_id": "job_001",
    "target_id": "worker_007",
    "match_score": 0.87,
    "breakdown": {
      "skill_score": 0.9,
      "region_score": 1.0,
      "time_score": 0.8,
      "experience_score": 0.85,
      "reliability_score": 0.8
    },
    "reasons": ["技能高度匹配", "同区域可到岗", "有同类活动经验"]
  }
}
```

错误说明：
- 找不到匹配记录时返回 `404`，提示“匹配记录不存在”。

### `POST /poc/match/feedback`
用途：提交匹配反馈（接受/拒绝），用于在线更新排序权重。

请求体：
```json
{
  "match_id": "match_001",
  "accepted": true
}
```

返回：
```json
{
  "weights": {
    "skill": 0.36,
    "region": 0.21,
    "time": 0.14,
    "experience": 0.14,
    "reliability": 0.15
  },
  "learning_enabled": true
}
```

错误说明：
- `match_id` 不存在时返回 `404`，提示“匹配记录不存在”。

### `GET /poc/match/weights`
用途：查看当前生效排序权重（默认权重或学习后的权重）。

返回结构同 `POST /poc/match/feedback`。

## 查询接口

### `GET /poc/jobs`
用途：分页前的基础列表查询（当前返回全量）。

返回：
```json
{
  "items": [{ "...": "JobCard(JSON)" }],
  "total": 100
}
```

### `GET /poc/workers`
用途：查询工人列表（当前返回全量）。

返回：
```json
{
  "items": [{ "...": "WorkerCard(JSON)" }],
  "total": 300
}
```

### `GET /poc/jobs/{job_id}`
用途：根据 ID 查询单个岗位。

路径参数：
- `job_id`：岗位 ID。

返回：`JobCard`。

错误说明：
- ID 不存在返回 `404`，提示“岗位不存在”。

### `GET /poc/workers/{worker_id}`
用途：根据 ID 查询单个工人。

路径参数：
- `worker_id`：工人 ID。

返回：`WorkerCard`。

错误说明：
- ID 不存在返回 `404`，提示“工人不存在”。

## 交接建议
- 以 `docs/openapi.json` 作为机器契约，`docs/API.md` 作为业务语义解释。
- 前端与测试联调时，优先校验：
  - 抽取失败时 `errors/missing_fields` 是否按预期返回。
  - 匹配结果 `breakdown` 五维分是否完整。
  - `top_n` 边界值（`1`、`50`、`>50`）的校验行为。

## 升级配置说明
- 抽取增强（schema-aware 重试）：
  - `EXTRACTION_LLM_MAX_RETRIES`：LLM 校验失败后的修复重试次数，默认 `2`。
- 检索 embedding 可配置：
  - `EMBEDDING_ENABLED`：是否启用正式 embedding，默认 `false`。
  - `EMBEDDING_BACKEND`：`hash` 或 `openai_compatible`。
  - `EMBEDDING_BASE_URL` / `EMBEDDING_API_KEY` / `EMBEDDING_MODEL`：embedding 服务配置。
  - `EMBEDDING_VECTOR_SIZE`：embedding 维度（需与 Qdrant 集合维度一致）。
- 排序在线学习：
  - `RANKING_LEARNING_ENABLED`：是否启用反馈学习，默认 `true`。
  - `RANKING_LEARNING_RATE`：在线更新学习率，默认 `0.08`。
  - 权重持久化文件：`data/match_weights.json`。
- 全局稳定性护栏：
  - `APP_RATE_LIMIT_PER_MINUTE`：全局每分钟请求上限。
  - `APP_CIRCUIT_BREAKER_ERROR_RATE`：窗口 5xx 错误率触发阈值。
  - `APP_CIRCUIT_BREAKER_MIN_REQUESTS`：熔断判定最小请求数。
  - `APP_CIRCUIT_BREAKER_WINDOW_SECONDS`：错误率统计窗口。
  - `APP_CIRCUIT_BREAKER_COOLDOWN_SECONDS`：熔断冷却时长。
  - `ALERT_WEBHOOK_URL`：告警 webhook 地址（可选）。
- 异步队列与缓存：
  - `INGEST_ASYNC_ENABLED`：是否启用异步入库队列。
  - `INGEST_QUEUE_MAX_SIZE`：队列最大长度。
  - `MATCH_ASYNC_ENABLED`：是否启用异步匹配队列。
  - `MATCH_QUEUE_MAX_SIZE`：异步匹配队列最大长度。
  - `MATCH_CACHE_ENABLED`：是否启用匹配缓存。
  - `MATCH_CACHE_TTL_SECONDS`：匹配缓存有效期。
  - `QUERY_CACHE_ENABLED`：是否启用查询缓存。
  - `QUERY_CACHE_TTL_SECONDS`：查询缓存有效期。
  - `CACHE_BACKEND`：缓存后端 `memory/redis`。
  - `REDIS_URL`：Redis 连接地址。
- 数据库连接池：
  - `DATABASE_POOL_SIZE`：连接池大小。
  - `DATABASE_MAX_OVERFLOW`：溢出连接数。
  - `DATABASE_POOL_TIMEOUT`：获取连接超时秒数。