label_backend/README.md

# label-backend

## 项目简介

`label-backend` 是知识图谱智能标注平台的后端服务，负责资料上传、任务分发、提取标注、问答生成、训练样本导出、系统配置和视频预处理等核心流程。

系统采用 Spring Boot 3 + MyBatis-Plus + PostgreSQL + Redis 的技术组合，面向多租户标注场景设计，支持：

- 公司级数据隔离
- 基于 Redis Token 的认证鉴权
- 提取与问答两阶段标注流程
- 导出训练数据并对接微调任务
- 视频预处理与异步回调
- 审计日志与任务状态追踪

代码结构已按扁平标准目录整理，主包位于 `src/main/java/com/label`。

## 功能特性

- 认证鉴权
  - 使用 UUID Bearer Token + Redis 会话存储
  - 自定义 `@RequireAuth`、`@RequireRole`
  - 角色分级：`ADMIN > REVIEWER > ANNOTATOR > UPLOADER`
- 多租户隔离
  - 基于 `CompanyContext` + `TenantLineInnerInterceptor`
  - 对租户表自动追加 `company_id` 条件
  - 特殊表通过显式 `companyId` 参数校验
- 公司与用户管理
  - 公司 CRUD
  - 公司内用户创建、状态变更、角色变更
  - 角色变更和禁用后即时刷新或失效 Redis Token
- 资料管理
  - 支持文本、图片、视频三类原始资料
  - 上传到 RustFS，数据库保存元数据
  - 支持按角色查看、查询详情、删除
- 任务管理
  - 任务池、我的任务、待审批队列、管理员全量视图
  - Redis 分布式锁 + 数据库原子更新保证任务领取并发安全
- 提取标注
  - AI 预标注
  - 标注结果整体覆盖更新
  - 提交、审批通过、驳回
- 问答生成
  - 基于提取审批通过事件生成候选问答对
  - 支持编辑、提交、审批、驳回
- 训练数据导出
  - 查询已审批样本
  - 创建导出批次
  - 触发微调任务并查询状态
- 系统配置
  - 支持公司专属配置覆盖全局默认配置
  - 配置项存储于 `sys_config`
- 视频处理
  - 支持触发视频预处理任务
  - 支持异步回调、失败重试、管理员重置

## 技术栈

- Java 21
- Spring Boot 3.1.5
- Spring MVC
- MyBatis-Plus 3.5.3.1
- PostgreSQL
- Redis
- Spring AOP
- springdoc-openapi
- Testcontainers
- RustFS / S3 兼容对象存储

## 项目结构

项目根目录结构：

```text
label_backend/
├── assembly/                      # 分发包描述与占位目录
├── docs/                          # 设计、计划、规范文档
├── scripts/                       # 启动脚本
├── src/
│   ├── main/
│   │   ├── java/com/label/        # 主代码
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── logback.xml
│   │       └── sql/               # 初始化 SQL，不打入构建产物
│   └── test/
│       ├── java/                  # 单元测试与集成测试
│       └── resources/db/init.sql  # Testcontainers 测试初始化 SQL
├── docker-compose.yml
├── Dockerfile
├── pom.xml
└── README.md
```

Java 包结构：

```text
com.label
├── annotation     # 自定义注解，如 RequireAuth / RequireRole / OperationLog
├── aspect         # AOP 审计切面
├── common         # 通用能力：auth、context、exception、result、storage、ai、statemachine
├── config         # Spring 配置、MyBatis-Plus 配置、认证拦截器注册
├── controller     # 所有 REST 接口
├── dto            # DTO
├── entity         # 实体
├── event          # 领域事件
├── interceptor    # 认证拦截器
├── listener       # 事件监听器
├── mapper         # MyBatis Mapper
├── service        # 业务服务
└── util           # 工具类
```

## 数据库表结构

初始化脚本位于 [init.sql](d:/workspace/label/label_backend/src/main/resources/sql/init.sql)，包含 11 张核心表：

- `sys_company`
  - 租户公司表
- `sys_user`
  - 公司用户表，包含角色与状态
- `source_data`
  - 原始资料元数据，支持 `TEXT` / `IMAGE` / `VIDEO`
- `annotation_task`
  - 标注任务表，支持 `EXTRACTION` / `QA_GENERATION`
- `annotation_result`
  - 提取阶段 JSON 结果
- `training_dataset`
  - 训练样本数据，存储 GLM 格式 JSON
- `export_batch`
  - 导出批次与微调任务状态
- `sys_config`
  - 全局与公司级配置
- `sys_operation_log`
  - 审计日志，只追加不更新
- `annotation_task_history`
  - 任务状态变更历史
- `video_process_job`
  - 视频预处理任务与回调状态

当前主要状态机：

- `source_data.status`
  - `PENDING` / `PREPROCESSING` / `EXTRACTING` / `QA_REVIEW` / `APPROVED`
- `annotation_task.status`
  - `UNCLAIMED` / `IN_PROGRESS` / `SUBMITTED` / `APPROVED` / `REJECTED`
- `training_dataset.status`
  - `PENDING_REVIEW` / `APPROVED` / `REJECTED`
- `video_process_job.status`
  - `PENDING` / `RETRYING` / `SUCCESS` / `FAILED`

## 配置说明

主配置文件位于 [application.yml](d:/workspace/label/label_backend/src/main/resources/application.yml)。

### 环境变量

| 变量名 | 说明 |
|---|---|
| `SPRING_DATASOURCE_URL` | PostgreSQL JDBC 地址 |
| `SPRING_DATASOURCE_USERNAME` | PostgreSQL 用户名 |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL 密码 |
| `SPRING_DATA_REDIS_HOST` | Redis 主机 |
| `SPRING_DATA_REDIS_PORT` | Redis 端口 |
| `SPRING_DATA_REDIS_PASSWORD` | Redis 密码 |
| `RUSTFS_ENDPOINT` | RustFS / S3 兼容服务地址 |
| `RUSTFS_ACCESS_KEY` | RustFS Access Key |
| `RUSTFS_SECRET_KEY` | RustFS Secret Key |
| `AI_SERVICE_BASE_URL` | AI 服务地址 |
| `VIDEO_CALLBACK_SECRET` | 视频处理回调共享密钥 |

### 关键配置项

- `auth.enabled`
  - `true` 时启用真实 Token 鉴权
  - `false` 时使用 mock 身份，便于本地开发
- `auth.mock-company-id`
  - 开发模式下的模拟公司 ID
- `auth.mock-user-id`
  - 开发模式下的模拟用户 ID
- `auth.mock-role`
  - 开发模式下的模拟角色
- `token.ttl-seconds`
  - Token 有效期，默认 7200 秒
- `springdoc.api-docs.path`
  - OpenAPI 文档路径，默认 `/v3/api-docs`
- `springdoc.swagger-ui.path`
  - Swagger UI 路径，默认 `/swagger-ui.html`

## API接口

以下为当前主要接口分组。

### 1. 认证接口

- `POST /api/auth/login`
  - 登录并返回 Bearer Token
- `POST /api/auth/logout`
  - 登出并立即失效当前 Token
- `GET /api/auth/me`
  - 获取当前登录用户信息

### 2. 公司管理

- `GET /api/companies`
- `POST /api/companies`
- `PUT /api/companies/{id}`
- `PUT /api/companies/{id}/status`
- `DELETE /api/companies/{id}`

### 3. 用户管理

- `GET /api/users`
- `POST /api/users`
- `PUT /api/users/{id}`
- `PUT /api/users/{id}/status`
- `PUT /api/users/{id}/role`

### 4. 资料管理

- `POST /api/source/upload`
- `GET /api/source/list`
- `GET /api/source/{id}`
- `DELETE /api/source/{id}`

### 5. 任务管理

- `GET /api/tasks/pool`
- `GET /api/tasks/mine`
- `GET /api/tasks/pending-review`
- `GET /api/tasks`
- `POST /api/tasks`
- `GET /api/tasks/{id}`
- `POST /api/tasks/{id}/claim`
- `POST /api/tasks/{id}/unclaim`
- `POST /api/tasks/{id}/reclaim`
- `PUT /api/tasks/{id}/reassign`

### 6. 提取标注

- `GET /api/extraction/{taskId}`
- `PUT /api/extraction/{taskId}`
- `POST /api/extraction/{taskId}/submit`
- `POST /api/extraction/{taskId}/approve`
- `POST /api/extraction/{taskId}/reject`

### 7. 问答生成

- `GET /api/qa/{taskId}`
- `PUT /api/qa/{taskId}`
- `POST /api/qa/{taskId}/submit`
- `POST /api/qa/{taskId}/approve`
- `POST /api/qa/{taskId}/reject`

### 8. 导出与微调

- `GET /api/training/samples`
- `POST /api/export/batch`
- `POST /api/export/{batchId}/finetune`
- `GET /api/export/{batchId}/status`
- `GET /api/export/list`

### 9. 系统配置

- `GET /api/config`
- `PUT /api/config/{key}`

### 10. 视频处理

- `POST /api/video/process`
- `GET /api/video/jobs/{jobId}`
- `POST /api/video/jobs/{jobId}/reset`
- `POST /api/video/callback`

## 定时任务

当前项目中**没有启用 Spring `@Scheduled` 定时同步任务**。

现有异步能力主要通过以下方式完成：

- 事务提交后事件监听
  - 提取审批通过后触发问答生成
- 外部 AI 服务异步回调
  - 视频处理完成后回调 `/api/video/callback`
- Redis 分布式锁
  - 用于任务领取并发控制

如果后续需要周期性任务，建议单独引入明确的调度场景，不要复用当前业务链路中的事件机制。

## 部署说明

### 1. 数据库初始化

初始化 SQL 位于：

- 开发/部署初始化脚本
  - [src/main/resources/sql/init.sql](d:/workspace/label/label_backend/src/main/resources/sql/init.sql)

说明：

- `src/main/resources/sql/init.sql` 会随源码保存，但**不会被打入 jar、target/classes 或分发包**
- `docker-compose.yml` 通过挂载该文件完成 PostgreSQL 初始化

### 2. 本地构建

```bash
mvn clean package -DskipTests
```

构建产物：
...  
- `target/label-backend-1.0.0-SNAPSHOT.zip`
- `target/label-backend-1.0.0-SNAPSHOT.tar.gz`

### 3. 分发包结构

分发包由 [distribution.xml](d:/workspace/label/label_backend/assembly/distribution.xml) 组装，解压后结构如下：

```text
label-backend-<version>/
├── bin/
│   └── start.sh
├── etc/
│   ├── application.yml
│   └── logback.xml
├── libs/
│   ├── label-backend-<version>.jar
│   └── *.jar
└── logs/
```

### 4. 启动脚本

启动脚本位于 [start.sh](d:/workspace/label/label_backend/scripts/start.sh)。

行为说明：

- 在 Docker 容器中检测到 `/.dockerenv` 时，前台 `exec java ...`
- 在宿主机环境中使用 `nohup` 后台启动
- 日志默认写入 `logs/startup.log`

### 5. Docker Compose 启动

```bash
docker compose up -d
```

当前 `docker-compose.yml` 会启动：

- PostgreSQL
- Redis
- RustFS（当前使用 MinIO 作为 S3 兼容替代）
- backend
- ai-service 占位服务
- frontend 占位服务

### 6. Docker 镜像构建

```bash
docker build -t label-backend:latest .
```

`Dockerfile` 使用多阶段构建，并从项目根目录的 `scripts/start.sh` 复制启动脚本。

## 注意事项

1. 开发模式下 `auth.enabled=false`
   - 此时会使用 mock 用户身份，不适合生产环境
   - 生产部署前必须显式启用真实鉴权
2. 多租户隔离仍依赖 `CompanyContext` + `TenantLineInnerInterceptor`
   - 租户表查询默认依赖租户拦截器
   - 个别特殊场景通过显式 `companyId` 参数校验
3. `sys_config`、`sys_company`、`video_process_job` 属于特殊表
   - 其中部分表被排除出自动租户注入，需在服务层显式控制
4. SQL 已迁移到 `src/main/resources/sql`
   - 仅作为源码级初始化文件保留
   - 不会打进构建产物
5. 集成测试依赖 Testcontainers
   - 运行完整集成测试需要本机可用 Docker 环境
6. 认证实现已移除 Shiro
   - 当前使用自定义拦截器、注解与 Redis Token
7. 用户上下文 ThreadLocal 已移除
   - 当前只保留 `CompanyContext`
   - 用户主体通过请求属性中的 `TokenPrincipal` 传递

## 开发规范

当前约束摘要：

- 统一扁平目录结构，避免再次引入按业务域分层的旧目录
- DTO 统一放在 `dto/`，不再拆分 `request/response`
- Service 统一放在 `service/`，不拆 `service/impl`
- 业务规则优先放在 Service，Controller 只负责 HTTP 协议层
- 新增接口需同步补齐 Swagger 注解与测试
- 所有对外接口参数必须在 Swagger 中明确体现名称、类型和含义
- 固定结构请求体禁止继续使用匿名 `Map<String, Object>` 或 `Map<String, String>`，必须定义 DTO 并补齐 `@Schema` 字段说明
- 固定结构响应应优先使用明确 DTO，或至少为 Swagger 暴露对象补齐字段级 `@Schema` 注解
- 路径参数、查询参数、请求体、分页包装和通用返回体都必须维护可读的 OpenAPI 文档说明
- 需要保持历史兼容的原始 JSON 字符串请求体可以继续使用 `String`，但必须在 Swagger `@RequestBody` 中说明完整 JSON body 的提交方式和兼容原因
- 修改 Controller 参数、请求 DTO、响应 DTO 或对外实体后，必须运行 `mvn -Dtest=OpenApiAnnotationTest test`，确保 Swagger 参数名称、类型和含义没有回退
- 目录、配置、打包方式变化后，README、设计文档和部署说明必须同步更新