# Gig POC README

## 项目目标
本项目实现一个“灵活用工最小 POC 内核系统”，围绕岗位理解、工人理解、LightRAG 检索、匹配排序和推荐解释构建完整闭环。

## 技术栈
- 后端：Python 3.11、FastAPI、Pydantic、SQLAlchemy、Uvicorn
- 数据层：PostgreSQL 16、Qdrant
- 前端：React 19、Vite 6
- 部署：Docker Compose
- 模型接入：OpenAI 兼容 LLM 接口，可选开启；默认启用本地规则兜底，推荐模型默认值为 `gpt-5.4`

## 目录结构
```text
/gig-poc
  /apps
    /web
    /api
  /packages
    /shared-types
    /prompts
    /sample-data
  /infrastructure
    docker-compose.yml
    docker-compose.prod.yml
    /sql
    /scripts
  /docs
    README.md
    API.md
    ARCHITECTURE.md
    DEMO.md
```

## 环境变量说明
- `DATABASE_URL`：PostgreSQL 连接串
- `QDRANT_URL`：Qdrant 服务地址
- `LLM_ENABLED`：是否启用外部 LLM 抽取
- `LLM_BASE_URL`：OpenAI 兼容接口地址
- `LLM_API_KEY`：模型服务密钥
- `LLM_MODEL`：模型名称
- `LLM_FALLBACK_BASE_URLS`：LLM 备用端点列表（JSON 数组）
- `AI_RATE_LIMIT_PER_MINUTE`：AI 请求每分钟限流阈值
- `AI_CIRCUIT_BREAKER_FAIL_THRESHOLD`：熔断触发失败次数
- `AI_CIRCUIT_BREAKER_COOLDOWN_SECONDS`：熔断冷却秒数
- `EMBEDDING_ENABLED`：是否启用正式 embedding
- `EMBEDDING_BACKEND`：`hash` 或 `openai_compatible`
- `EMBEDDING_BASE_URL` / `EMBEDDING_API_KEY` / `EMBEDDING_MODEL`：embedding 配置
- `INGEST_ASYNC_ENABLED`：是否启用异步入库队列
- `INGEST_QUEUE_MAX_SIZE`：异步队列最大长度
- `MATCH_CACHE_ENABLED`：是否启用匹配缓存
- `MATCH_CACHE_TTL_SECONDS`：匹配缓存 TTL（秒）
- `QUERY_CACHE_ENABLED`：是否启用查询缓存（列表与详情）
- `QUERY_CACHE_TTL_SECONDS`：查询缓存 TTL（秒）
- `CACHE_BACKEND`：缓存后端，`memory` 或 `redis`
- `REDIS_URL`：Redis 连接串
- `APP_RATE_LIMIT_PER_MINUTE`：全局请求限流阈值
- `APP_CIRCUIT_BREAKER_*`：全局熔断参数（错误率、窗口、冷却）
- `ALERT_WEBHOOK_URL`：告警 webhook（可选）
- `DATABASE_POOL_SIZE` / `DATABASE_MAX_OVERFLOW` / `DATABASE_POOL_TIMEOUT`：数据库连接池参数
- `MATCH_ASYNC_ENABLED`：是否启用异步匹配队列
- `MATCH_QUEUE_MAX_SIZE`：异步匹配队列最大长度

## 启动方式
1. `cd gig-poc`
2. `sh infrastructure/scripts/dev-up.sh`
3. 默认会自动执行：
   - 健康检查 + bootstrap
   - 一键闭环验收脚本（抽取 -> 入库 -> 匹配 -> 解释）
   - 导出 `docs/openapi.json`
4. 可选开启容量基线压测：
   - `RUN_BASELINE_ON_UP=true sh infrastructure/scripts/dev-up.sh`

## 生产环境启动/停止
- 启动：`sh infrastructure/scripts/prod-up.sh`
- 停止：`sh infrastructure/scripts/prod-down.sh`
- 可选环境变量：
  - `WEB_PORT`（默认 `80`）
  - `API_PORT`（默认 `8000`）
  - `BOOTSTRAP_ON_UP`（默认 `true`，可设置为 `false` 跳过样本初始化）

## 样本导入方式
`dev-up.sh` 会在健康检查通过后自动触发 `/poc/ingest/bootstrap`，导入 100 岗位、300 工人和词表。

## API 地址
- `http://127.0.0.1:8000`
- OpenAPI：`http://127.0.0.1:8000/docs`
- OpenAPI JSON 导出：`sh infrastructure/scripts/export-openapi.sh`
- OpenAPI 固化（离线生成并入库）：`sh infrastructure/scripts/freeze-openapi.sh`
- AI 观测接口：`GET /poc/ops/ai/metrics`
- 系统观测接口：`GET /poc/ops/system/metrics`
- 异步匹配接口：`POST /poc/match/workers/async`、`POST /poc/match/jobs/async`、`GET /poc/match/queue/{task_id}`

## 前端访问地址
- `http://127.0.0.1:5173`

## 演示路径
1. 打开岗位测试页，输入岗位描述并抽取
2. 点击入库并匹配工人
3. 打开工人测试页，输入工人描述并抽取
4. 点击入库并匹配岗位
5. 在系统状态页执行健康检查和样本导入

## 一键闭环验收
```bash
cd gig-poc
sh infrastructure/scripts/acceptance-e2e.sh
```

该脚本会自动验证两条链路：
- 岗位文本抽取 -> 岗位入库 -> 岗位匹配工人 -> 匹配解释
- 工人文本抽取 -> 工人入库 -> 工人匹配岗位 -> 匹配解释

## 容量基线压测
```bash
cd gig-poc
sh infrastructure/scripts/load-baseline.sh
```

输出文件：
- `docs/CAPACITY_BASELINE.md`

可选参数：
- `TOTAL_REQUESTS`（默认 `400`）
- `CONCURRENCY`（默认 `40`）

## 规模化建议（上线前）
- 应用层：开启多实例部署（建议至少 2 个 API 实例）并接入负载均衡。
- 数据层：PostgreSQL、Qdrant 使用托管或主从/集群形态，避免单点。
- 链路层：优先走异步入库接口（`/poc/ingest/*/async`）吸收突发写流量。
- 匹配层：高峰请求优先走异步匹配接口（`/poc/match/*/async`）做削峰。
- 观测层：接入 `/poc/ops/system/metrics` 与 `/poc/ops/ai/metrics` 到监控告警系统。
- 发布层：每次发布前更新 `docs/openapi.json` 与 `docs/CAPACITY_BASELINE.md`。

## K8s 扩容部署（基础模板）
目录：`infrastructure/k8s`

```bash
cd gig-poc
kubectl apply -k infrastructure/k8s
```

包含资源：
- API Deployment + Service + HPA（默认 3~20 副本）
- Web Deployment + Service + HPA（默认 2~10 副本）
- Redis Deployment + Service
- Ingress 示例路由

详细策略说明见：`docs/SCALING.md`

## 已实现范围
- 岗位抽取
- 工人抽取
- JobCard / WorkerCard / MatchResult 统一 schema
- 样本数据 bootstrap
- LightRAG 风格向量检索适配层
- 两阶段召回与排序
- 推荐理由生成
- Web 控制台
- Docker Compose 本地与生产部署

## 未实现范围
- 裂变、支付、合同、工时、薪资结算
- 权限系统与复杂后台
- 大规模并发优化