feat: add new folder
This commit is contained in:
Daniel
75
gig-poc/docs/API.md
Normal file
75
gig-poc/docs/API.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 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` 保留了前端可复用类型定义。
|
||||
42
gig-poc/docs/ARCHITECTURE.md
Normal file
42
gig-poc/docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# 架构说明
|
||||
|
||||
## 总体架构
|
||||
项目采用前后端分离部署：
|
||||
- `apps/api`：FastAPI 服务，负责抽取、入库、匹配、解释、查询
|
||||
- `apps/web`：React/Vite 控制台，负责 POC 演示
|
||||
- `postgres`：结构化数据持久化
|
||||
- `qdrant`：LightRAG 风格向量召回层
|
||||
|
||||
## 后端分层
|
||||
- `api`：HTTP 路由
|
||||
- `services`：抽取、入库、匹配、RAG 适配
|
||||
- `repositories`：数据库读写
|
||||
- `domain`：Pydantic schema 与 SQLAlchemy model
|
||||
|
||||
## 抽取链路
|
||||
1. 读取 `packages/prompts`
|
||||
2. 若配置了外部 LLM，则走 OpenAI 兼容结构化抽取
|
||||
3. 如果外部 LLM 不可用，则回退到本地规则抽取
|
||||
4. 所有输出统一走 Pydantic 校验
|
||||
|
||||
## RAG 方案
|
||||
当前 POC 使用 `LightRAGAdapter` 作为轻量适配层：
|
||||
- 结构化卡片先落 PostgreSQL
|
||||
- 关键信息序列化后写入 Qdrant
|
||||
- 使用技能近义词图做扩展召回
|
||||
- 对召回结果进入规则打分排序
|
||||
|
||||
## 匹配公式
|
||||
```text
|
||||
MatchScore =
|
||||
0.35 * SkillScore
|
||||
+ 0.20 * RegionScore
|
||||
+ 0.15 * TimeScore
|
||||
+ 0.15 * ExperienceScore
|
||||
+ 0.15 * ReliabilityScore
|
||||
```
|
||||
|
||||
## 部署方式
|
||||
- 本地：`infrastructure/docker-compose.yml`
|
||||
- 生产：`infrastructure/docker-compose.prod.yml`
|
||||
- 前端通过 Nginx 独立容器部署，并反向代理 API，保持前后端分离
|
||||
27
gig-poc/docs/DEMO.md
Normal file
27
gig-poc/docs/DEMO.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Demo 说明
|
||||
|
||||
## 一键启动
|
||||
```bash
|
||||
cd gig-poc
|
||||
sh infrastructure/scripts/dev-up.sh
|
||||
```
|
||||
|
||||
## 演示步骤
|
||||
1. 打开 `http://127.0.0.1:5173`
|
||||
2. 在“岗位测试页”输入岗位文本并点击“抽取岗位”
|
||||
3. 点击“入库并匹配工人”，观察 TopN 匹配与推荐原因
|
||||
4. 在“工人测试页”输入工人文本并点击“抽取工人画像”
|
||||
5. 点击“入库并匹配岗位”，观察 TopN 匹配与推荐原因
|
||||
6. 打开“数据浏览页”查看已入库样本
|
||||
7. 打开“系统状态页”查看健康状态，必要时重新执行 bootstrap
|
||||
|
||||
## 生产环境启动
|
||||
```bash
|
||||
cd gig-poc
|
||||
sh infrastructure/scripts/prod-up.sh
|
||||
```
|
||||
|
||||
## 演示建议
|
||||
- 先演示系统状态页，确认健康与 bootstrap 正常
|
||||
- 再演示岗位找人、人找岗位两个闭环
|
||||
- 最后展开 OpenAPI 文档讲接口交接方式
|
||||
78
gig-poc/docs/README.md
Normal file
78
gig-poc/docs/README.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# 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`：模型名称
|
||||
|
||||
## 启动方式
|
||||
1. `cd gig-poc`
|
||||
2. `sh infrastructure/scripts/dev-up.sh`
|
||||
|
||||
## 样本导入方式
|
||||
`dev-up.sh` 会在健康检查通过后自动触发 `/poc/ingest/bootstrap`，导入 100 岗位、300 工人和词表。
|
||||
|
||||
## API 地址
|
||||
- `http://127.0.0.1:8000`
|
||||
- OpenAPI：`http://127.0.0.1:8000/docs`
|
||||
|
||||
## 前端访问地址
|
||||
- `http://127.0.0.1:5173`
|
||||
|
||||
## 演示路径
|
||||
1. 打开岗位测试页，输入岗位描述并抽取
|
||||
2. 点击入库并匹配工人
|
||||
3. 打开工人测试页，输入工人描述并抽取
|
||||
4. 点击入库并匹配岗位
|
||||
5. 在系统状态页执行健康检查和样本导入
|
||||
|
||||
## 已实现范围
|
||||
- 岗位抽取
|
||||
- 工人抽取
|
||||
- JobCard / WorkerCard / MatchResult 统一 schema
|
||||
- 样本数据 bootstrap
|
||||
- LightRAG 风格向量检索适配层
|
||||
- 两阶段召回与排序
|
||||
- 推荐理由生成
|
||||
- Web 控制台
|
||||
- Docker Compose 本地与生产部署
|
||||
|
||||
## 未实现范围
|
||||
- 裂变、支付、合同、工时、薪资结算
|
||||
- 权限系统与复杂后台
|
||||
- 大规模并发优化
|
||||
Reference in New Issue
Block a user