label_backend/specs/001-label-backend-spec/quickstart.md

# 快速启动指南：label_backend

**日期**: 2026-04-09  
**分支**: `001-label-backend-spec`

---

## 前置条件

- Docker Desktop ≥ 4.x（含 Docker Compose v2）
- JDK 17（本地开发时）
- Maven ≥ 3.8（本地开发时）

---

## 一、使用 Docker Compose 启动完整环境

```bash
# 克隆仓库
git clone <repo-url>
cd label_backend

# 启动所有服务（PostgreSQL + Redis + RustFS + AI Service + Backend + Frontend）
docker compose up -d

# 查看后端启动日志
docker compose logs -f backend

# 检查健康状态
docker compose ps
```

**服务端口**:
| 服务 | 端口 |
|------|------|
| 前端（Nginx） | http://localhost:80 |
| 后端 REST API | http://localhost:8080 |
| AI 服务（FastAPI） | http://localhost:8000 |
| PostgreSQL | localhost:5432 |
| Redis | localhost:6379 |
| RustFS S3 API | http://localhost:9000 |
| RustFS Web 控制台 | http://localhost:9001 |

---

## 二、初始化数据库

数据库 DDL 通过 `./sql/init.sql` 在 PostgreSQL 容器启动时自动执行（`docker-entrypoint-initdb.d`）。

若需手动执行：
```bash
docker compose exec postgres psql -U label -d label_db -f /docker-entrypoint-initdb.d/init.sql
```

**初始账号**（由 `init.sql` 中的 INSERT 语句创建）：
| 用户名 | 密码 | 角色 | 公司 |
|--------|------|------|------|
| admin | admin123 | ADMIN | 演示公司 |
| reviewer01 | review123 | REVIEWER | 演示公司 |
| annotator01 | annot123 | ANNOTATOR | 演示公司 |
| uploader01 | upload123 | UPLOADER | 演示公司 |

---

## 三、本地开发模式（不使用 Docker）

```bash
# 启动依赖服务（仅 PostgreSQL + Redis + RustFS，不启动后端）
docker compose up -d postgres redis rustfs

# 设置环境变量
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/label_db
export SPRING_DATASOURCE_USERNAME=label
export SPRING_DATASOURCE_PASSWORD=label_password
export SPRING_REDIS_HOST=localhost
export SPRING_REDIS_PORT=6379
export SPRING_REDIS_PASSWORD=redis_password
export RUSTFS_ENDPOINT=http://localhost:9000
export RUSTFS_ACCESS_KEY=minioadmin
export RUSTFS_SECRET_KEY=minioadmin
export AI_SERVICE_BASE_URL=http://localhost:8000

# 编译并启动
mvn clean spring-boot:run
```

---

## 四、验证安装

```bash
# 1. 登录（获取 Token）
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"companyCode":"DEMO","username":"admin","password":"admin123"}'

# 期望响应：{"code":"SUCCESS","data":{"token":"...","role":"ADMIN",...}}

# 2. 使用 Token 访问受保护接口（将 {TOKEN} 替换为上一步返回的 token）
curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer {TOKEN}"

# 期望响应：{"code":"SUCCESS","data":{"username":"admin","role":"ADMIN",...}}
```

---

## 五、运行测试

```bash
# 运行所有测试（Testcontainers 会自动启动真实 PG + Redis 容器）
mvn test

# 运行特定测试（并发任务领取）
mvn test -Dtest=TaskClaimConcurrencyTest

# 运行集成测试套件
mvn test -Dtest=*IntegrationTest
```

**注意**: Testcontainers 需要本地 Docker 可用。首次运行会拉取 PostgreSQL 和 Redis 镜像（约 200MB）。

---

## 六、关键配置项说明

配置文件位于 `src/main/resources/application.yml`。以下配置项可在运行时通过 `PUT /api/config/{key}` 接口（ADMIN 权限）动态调整，无需重启服务：

| 配置键 | 说明 | 默认值 |
|--------|------|--------|
| `token_ttl_seconds` | 会话凭证有效期（秒） | 7200（2小时） |
| `model_default` | AI 辅助默认模型 | glm-4 |
| `video_frame_interval` | 视频帧提取间隔（帧数） | 30 |
| `prompt_extract_text` | 文本三元组提取 Prompt | 见 init.sql |
| `prompt_extract_image` | 图片四元组提取 Prompt | 见 init.sql |
| `prompt_qa_gen_text` | 文本问答生成 Prompt | 见 init.sql |
| `prompt_qa_gen_image` | 图片问答生成 Prompt | 见 init.sql |

---

## 七、标注流水线快速验证

```bash
TOKEN="your-admin-token"

# 步骤 1：上传文本资料
curl -X POST http://localhost:8080/api/source/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@sample.txt" -F "dataType=TEXT"

# 步骤 2：为资料创建提取任务（sourceId 从上一步响应中获取）
curl -X POST http://localhost:8080/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceId": 1, "taskType": "AI_ASSISTED", "aiModel": "glm-4"}'

# 步骤 3：标注员领取任务（使用 annotator01 的 Token）
ANNOTATOR_TOKEN="annotator-token"
curl -X POST http://localhost:8080/api/tasks/1/claim \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN"

# 步骤 4：获取 AI 预标注结果
curl http://localhost:8080/api/extraction/1 \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN"

# 步骤 5：提交标注结果
curl -X PUT http://localhost:8080/api/extraction/1 \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"subject":"北京","predicate":"是首都","object":"中国","sourceText":"北京是中国的首都","startOffset":0,"endOffset":8}]}'

curl -X POST http://localhost:8080/api/extraction/1/submit \
  -H "Authorization: Bearer $ANNOTATOR_TOKEN"

# 步骤 6：审批员审批通过（使用 reviewer01 的 Token）
REVIEWER_TOKEN="reviewer-token"
curl -X POST http://localhost:8080/api/extraction/1/approve \
  -H "Authorization: Bearer $REVIEWER_TOKEN"
```