1497 lines
63 KiB
Markdown
1497 lines
63 KiB
Markdown
# 标注平台后端设计方案
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档只覆盖一期 Java Backend 需要落地的模块，不扩展到训练集导出、微调任务编排二期能力。
|
||
|
||
## 2. 一期范围
|
||
|
||
### 2.1 一期要落地的模块
|
||
|
||
一期后端只建设以下四个业务模块：
|
||
|
||
1. 资源管理模块 `source_resource`
|
||
2. 任务管理模块 `annotation_task`
|
||
3. 审批标注结果模块 `annotation_result` / `annotation_result_history`
|
||
4. 系统配置模块 `sys_config`
|
||
|
||
一期继续复用现有认证鉴权基线：
|
||
|
||
- 用户登录、Token、会话版本控制沿用现有认证实现
|
||
- 岗位权限沿用 `position`
|
||
- 数据权限沿用 `role`
|
||
- 租户隔离沿用 `company_id`
|
||
|
||
|
||
### 2.2 一期不做的内容
|
||
|
||
以下内容不纳入本次一期后端设计范围：
|
||
|
||
- 新建部门体系
|
||
- 新建复杂工作流引擎
|
||
- 训练集导出中心的完整业务闭环
|
||
- 面向前台的复杂配置编排 UI
|
||
- AI Service 内部推理链路实现细节
|
||
|
||
|
||
## 3. 总体架构
|
||
|
||
### 3.1 系统组成
|
||
|
||
一期采用“四段式协作”：
|
||
|
||
1. `lb_backend`：对前端暴露 REST API，负责资源、任务、结果审核、系统配置。
|
||
2. `PostgreSQL`：持久化元数据、任务快照、审核结果、归档结果。
|
||
3. `RustFS`：保存原始资源、视频衍生文件、外置问答 JSON、导出文件。
|
||
4. `ai-service`：轮询待执行任务，拉取资源，完成抽取、校验、比对，并写回结果。
|
||
|
||
### 3.2 核心设计原则
|
||
|
||
1. 资源生命周期、任务执行生命周期、审核归档生命周期分开建模。
|
||
2. 大字段优先支持表内存储，但必须预留外置存储能力。
|
||
3. 后端创建任务时只负责写入 `PENDING`；执行态状态全部由 `ai-service` 驱动。
|
||
4. `annotation_result` 只保存“当前待处理结果”；归档后的最终结果统一进入 `annotation_result_history`。
|
||
5. 运行态结果不再依赖 `review_status`，而是通过 `requires_manual_review`、`is_deleted` 和历史归档记录组合表达状态。
|
||
|
||
### 3.3 一期包结构
|
||
|
||
一期包结构按 [微服务开发规范文档](D:/workspace/labeling/docs/微服务开发规范文档.md) 采用“按技术层分包”的标准结构，不再使用 `modules/resource`、`modules/task` 这类按大模块纵向拆包的目录形式：
|
||
|
||
```text
|
||
lb_backend/src/main/java/com/labelsys/backend
|
||
├── annotation
|
||
├── common
|
||
│ ├── exception
|
||
│ ├── Result.java
|
||
│ └── ResultCode.java
|
||
├── config
|
||
├── constant
|
||
├── context
|
||
├── controller
|
||
│ ├── AnnotationResultController.java
|
||
│ ├── AnnotationTaskController.java
|
||
│ ├── SourceResourceController.java
|
||
│ └── SysConfigController.java
|
||
├── dto
|
||
│ ├── common
|
||
│ │ ├── ApiResponse.java
|
||
│ │ └── PageResult.java
|
||
│ ├── request
|
||
│ │ ├── SourceUploadRequest.java
|
||
│ │ ├── SourceResourcePageQuery.java
|
||
│ │ ├── ManualModelConfigRequest.java
|
||
│ │ ├── TaskModelConfigRequest.java
|
||
│ │ ├── PromptConfigOptionRequest.java
|
||
│ │ ├── CreateAnnotationTaskRequest.java
|
||
│ │ ├── UpdateAnnotationTaskRequest.java
|
||
│ │ ├── AnnotationTaskPageQuery.java
|
||
│ │ ├── AnnotationResultPageQuery.java
|
||
│ │ ├── MergeReviewResultRequest.java
|
||
│ │ ├── SaveSysConfigRequest.java
|
||
│ │ └── SysConfigPageQuery.java
|
||
│ └── response
|
||
│ ├── SourceUploadResponse.java
|
||
│ ├── SourceResourceResponse.java
|
||
│ ├── TaskModelConfigResponse.java
|
||
│ ├── TaskPromptConfigResponse.java
|
||
│ ├── AnnotationResultResponse.java
|
||
│ ├── AnnotationResultCompareResponse.java
|
||
│ ├── AnnotationTaskResponse.java
|
||
│ ├── MergeReviewResultResponse.java
|
||
│ └── SysConfigResponse.java
|
||
├── entity
|
||
├── mapper
|
||
├── scheduled
|
||
├── service
|
||
├── typehandler
|
||
└── util
|
||
```
|
||
|
||
补充约定：
|
||
|
||
1. 控制器、DTO、实体、Mapper、Service 统一放在规范文档要求的根层目录下，业务边界通过类名前缀区分，例如 `AnnotationTaskController`、`SourceResourceMapper`。
|
||
2. 定时任务统一进入 `scheduled` 包，不再在业务模块下单独定义 `job` 子目录。
|
||
3. Mapper XML 统一放在 `src/main/resources/mapper`，SQL 基准文件统一放在 `src/main/resources/sql`。
|
||
4. DTO 进一步细分为 `dto/request`、`dto/response` 和 `dto/common`，避免不同模块的交互对象混放。
|
||
|
||
### 3.4 接口对象与数据库实体分层
|
||
|
||
1. 数据库实体仅用于 Repository / Mapper 层持久化，统一命名为 `*Entity`，不直接作为 Controller 入参或出参。
|
||
2. Controller 层只接收 `*Request`、`*Query`，只返回 `*Response`、`*View`、`PageResult<T>`。
|
||
3. Service 层负责实体转换与聚合装配，例如任务详情需要把 `annotation_task`、`annotation_task_resource`、`sys_config` 组合成前端可直接消费的交互对象。
|
||
4. API 字段命名遵循 Java 驼峰风格，例如数据库列 `is_deleted` 在接口层统一映射为 `isDeleted`。
|
||
5. 敏感字段不直接透出到界面层，模型 `apiKey` 只在任务快照和配置表中保存，接口返回时必须脱敏或不返回。
|
||
|
||
## 4. 权限模型
|
||
|
||
### 4.1 岗位权限
|
||
|
||
一期沿用现有岗位枚举：
|
||
|
||
- `ANNOTATOR`
|
||
- `DATA_TRAINER`
|
||
- `REVIEWER`
|
||
- `ADMIN`
|
||
|
||
权限建议如下：
|
||
|
||
| 模块 | 查询 | 新增/修改 | 删除 | 特殊说明 |
|
||
|---|---|---|---|---|
|
||
| 资源管理 | 全岗位可查 | 全岗位可上传 | 全岗位可删自身可见资源 | 删除时仍受数据权限约束 |
|
||
| 任务管理 | 全岗位可查 | 全岗位可创建 | 全岗位可删未执行任务 | backend 只创建 `PENDING` |
|
||
| 结果查询 | 全岗位可查可见数据 | 无 | 无 | 仅查询本人/本层级可见数据 |
|
||
| 人工审核 | `REVIEWER` 及以上 | `REVIEWER` 及以上 | 无 | 对所有未归档运行态结果开放；其中 `requires_manual_review = true` 的结果必须审核后才能归档 |
|
||
| 系统配置 | 全岗位可查 | `ADMIN` 建议可写 | 无 | 若沿需求“所有岗位可操作”，需由产品再次确认风险 |
|
||
|
||
说明：需求原文提到“系统配置模块对所有岗位可以操作”，这在安全上风险较高。本文档保留查询全开放，但建议写权限收敛到 `ADMIN`。如果必须全岗位可写，则需额外增加配置白名单和审计。
|
||
|
||
### 4.2 数据权限
|
||
|
||
一期沿用现有数据权限角色：
|
||
|
||
- `EMPLOYEE`：只看自己创建的数据
|
||
- `MANAGER`：看本公司 `EMPLOYEE + MANAGER`
|
||
- `ENGINEER`：看本公司全部数据
|
||
|
||
业务表统一保留：
|
||
|
||
- `company_id`
|
||
- `creator_id`
|
||
- `creator_role`
|
||
|
||
### 4.3 权限落地规则
|
||
|
||
1. 系统表以 `company_id` 作为租户边界。
|
||
2. 业务列表接口默认按 `company_id` 过滤。
|
||
3. 再按 `creator_role + creator_id` 追加数据权限过滤。
|
||
4. 审核类写操作额外校验岗位是否为 `REVIEWER` 或 `ADMIN`。
|
||
|
||
## 5. 领域对象与状态归属
|
||
|
||
### 5.1 领域对象
|
||
|
||
一期核心领域对象如下：
|
||
|
||
1. `SourceResource`：原始资源元数据。
|
||
2. `AnnotationTask`：某一次抽取/校验任务快照。
|
||
3. `AnnotationTaskResource`：任务与资源的多对多绑定关系。
|
||
4. `AnnotationResult`：当前待审核或待自动归档的运行态结果。
|
||
5. `AnnotationResultHistory`：归档后的最终结果。
|
||
6. `SysConfig`：模型、Prompt、系统参数配置。
|
||
|
||
### 5.2 状态归属评审结论
|
||
|
||
旧方案里 `source_data` 参考设计把资源、抽取、审核状态揉在一张表里，这不适合一期真实落地。重写后按以下原则拆分：
|
||
|
||
| 责任对象 | 负责状态 | 不负责状态 |
|
||
|---|---|---|
|
||
| `source_resource` | 文件是否上传完成、是否已归档 | 任务执行进度、审核结果 |
|
||
| `annotation_task` | AI 执行进度、失败原因、开始结束时间 | 资源存储状态、人工审核结论 |
|
||
| `annotation_task_resource` | 任务与资源的绑定关系 | 任务执行进度、审核结论 |
|
||
| `annotation_result` | 是否强制人工审核、是否软删除、审核人和审核时间 | 任务执行进度 |
|
||
| `annotation_result_history` | 最终归档结果、归档原因、归档人 | 运行态处理中的瞬时状态 |
|
||
|
||
### 5.3 一期状态定义
|
||
|
||
#### 5.3.1 资源状态 `source_status`
|
||
|
||
当前 SQL 中资源状态仍按以下值设计：
|
||
|
||
- `UPLOADED`：原始文件已上传，元数据已入库
|
||
- `PROCESSING`：预留给后续异步资源处理流程，一期暂不引入专门视频预处理作业
|
||
- `READY`：资源可用于创建任务
|
||
- `ARCHIVED`：资源已归档，不再允许创建新任务
|
||
|
||
不建议把 `EXTRACTING`、`QA_REVIEW`、`APPROVED`、`REJECTED` 放进资源表，因为这些属于任务或结果生命周期。
|
||
|
||
#### 5.3.2 任务状态 `task_status`
|
||
|
||
当前 SQL 中任务状态使用：
|
||
|
||
- `PENDING`
|
||
- `RUNNING`
|
||
- `COMPLETED`
|
||
- `FAILED`
|
||
|
||
#### 5.3.3 结果运行态
|
||
|
||
`annotation_result` 不再保存 `review_status`。运行态按下列规则推导：
|
||
|
||
| 运行态名称 | 计算规则 |
|
||
|---|---|
|
||
| `MANUAL_REVIEW_PENDING` | `requires_manual_review = true and is_deleted = false`，表示必须人工审核，禁止自动归档 |
|
||
| `AUTO_ARCHIVE_PENDING` | `requires_manual_review = false and is_deleted = false`，表示允许人工审核，也允许超时自动归档 |
|
||
| `ARCHIVED` | 对应记录已软删除，且已有 `annotation_result_history` 归档记录 |
|
||
|
||
## 6. 对象存储路径规范
|
||
|
||
### 6.1 评审结论
|
||
|
||
旧参考路径存在三个问题：
|
||
|
||
1. 直接把业务含义写死在一级目录，后续跨租户清理困难。
|
||
2. 部分路径使用原始文件名，不利于重名控制和脱敏。
|
||
3. 原始资源、衍生资源、审核外置文件、导出文件没有统一前缀策略。
|
||
|
||
### 6.2 一期统一规范
|
||
|
||
统一规则：
|
||
|
||
1. 路径全部使用小写。
|
||
2. 不直接使用用户原始文件名做对象 Key。
|
||
3. 优先使用业务主键和年月做路径分层。
|
||
4. 按“租户 / 资源域 / 类型 / 年月 / 业务 ID”组织。
|
||
|
||
### 6.3 Bucket 规划
|
||
|
||
| Bucket | 用途 |
|
||
|---|---|
|
||
| `source-data` | 原始文本、图片、视频及视频衍生物 |
|
||
| `annotation-artifacts` | 外置问答 JSON、diff JSON、人工审核快照 |
|
||
| `finetune-export` | 导出 JSONL 文件 |
|
||
|
||
### 6.4 路径格式
|
||
|
||
| 场景 | Bucket | 路径格式 |
|
||
|---|---|---|
|
||
| 文本原始文件 | `source-data` | `source/{companyId}/text/{yyyyMM}/{resourceId}/original.{ext}` |
|
||
| 图片原始文件 | `source-data` | `source/{companyId}/image/{yyyyMM}/{resourceId}/original.{ext}` |
|
||
| 视频原始文件 | `source-data` | `source/{companyId}/video/{yyyyMM}/{resourceId}/original.{ext}` |
|
||
| 外置问答 JSON | `annotation-artifacts` | `result/{companyId}/{yyyyMM}/{taskId}/{resultId}/qa.json` |
|
||
| 外置 diff JSON | `annotation-artifacts` | `result/{companyId}/{yyyyMM}/{taskId}/{resultId}/diff.json` |
|
||
| 导出 JSONL | `finetune-export` | `export/{companyId}/{yyyyMM}/{batchNo}/dataset.jsonl` |
|
||
|
||
### 6.5 命名规则
|
||
|
||
1. `resourceId`、`taskId`、`resultId` 使用数据库主键或雪花 ID。
|
||
2. `yyyyMM` 例如 `202604`。
|
||
3. 文件扩展名按后端识别后的标准扩展名写入，不沿用用户大小写。
|
||
4. 资源删除时优先删对象，再更新数据库状态。
|
||
|
||
|
||
## 7. source 场景流程与状态流转/回退
|
||
|
||
### 7.1 文本/图片上传场景
|
||
|
||
流程：
|
||
|
||
1. 前端上传文件到后端。
|
||
2. 后端完成文件校验和对象存储上传。
|
||
3. 后端创建 `source_resource`，状态写入 `UPLOADED`。
|
||
4. 当前一期不引入视频预处理作业，资源校验通过后直接置为 `READY`。
|
||
|
||
状态流转：
|
||
|
||
`UPLOADED -> READY -> ARCHIVED`
|
||
|
||
回退规则：
|
||
|
||
- 如果对象存储上传失败：不写库。
|
||
- 如果写库失败：回滚并删除已上传对象。
|
||
- 如果资源已被任务引用，不允许直接物理删除，只允许逻辑归档到 `ARCHIVED`。
|
||
|
||
### 7.2 视频资源当前处理策略
|
||
|
||
一期暂不建设独立的视频资源预处理作业，视频资源和文本/图片资源保持同样的主流程：
|
||
|
||
1. 视频上传成功后创建 `source_resource`，状态为 `UPLOADED`。
|
||
2. 完成基础校验后直接改为 `READY`。
|
||
3. 当前不做拆帧、转写、衍生文件生产。
|
||
|
||
状态流转：
|
||
|
||
`UPLOADED -> READY -> ARCHIVED`
|
||
|
||
### 7.3 任务驱动场景
|
||
|
||
资源与任务解耦，资源不会因为某个任务开始执行就改成任务态。即：
|
||
|
||
- 创建任务不会把资源状态从 `READY` 改成 `EXTRACTING`
|
||
- 任务重跑不会污染资源主状态
|
||
|
||
这是本次重写的核心结论之一。
|
||
|
||
## 8. 模块详细设计
|
||
|
||
## 8.1 资源管理模块
|
||
|
||
### 8.1.1 模块职责
|
||
|
||
1. 接收文本、图片、视频文件上传。
|
||
2. 保存资源元数据与对象存储定位信息。
|
||
3. 提供分页查询、详情查询、删除能力。
|
||
4. 为任务创建与结果审核提供统一的资源视图，不引入独立视频预处理作业。
|
||
|
||
### 8.1.2 接口列表
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `POST` | `/api/source-resources/upload` | 上传资源 |
|
||
| `GET` | `/api/source-resources` | 分页查询资源 |
|
||
| `GET` | `/api/source-resources/{id}` | 查询资源详情 |
|
||
| `DELETE` | `/api/source-resources/{id}` | 删除资源 |
|
||
|
||
### 8.1.3 接口交互对象
|
||
|
||
以下对象均为接口层 DTO，不直接复用数据库实体；列表和详情统一返回 `SourceResourceResponse`，保持前端交互对象一致：
|
||
|
||
```java
|
||
public class SourceUploadRequest {
|
||
private String resourceName;
|
||
private String resourceType; // TEXT / IMAGE / VIDEO
|
||
private String remark;
|
||
}
|
||
|
||
public class SourceUploadResponse {
|
||
private Long id;
|
||
private String resourceName;
|
||
private String resourceType;
|
||
private String bucketName;
|
||
private String filePath;
|
||
private Long fileSize;
|
||
private String sourceStatus;
|
||
private LocalDateTime createdAt;
|
||
}
|
||
|
||
public class SourceResourcePageQuery {
|
||
private String keyword;
|
||
private String resourceType;
|
||
private String sourceStatus;
|
||
private Integer pageNo;
|
||
private Integer pageSize;
|
||
}
|
||
|
||
public class SourceResourceResponse {
|
||
private Long id;
|
||
private String resourceName;
|
||
private String resourceType;
|
||
private String bucketName;
|
||
private String filePath;
|
||
private Long fileSize;
|
||
private String sourceStatus;
|
||
private String storageProvider;
|
||
private String remark;
|
||
private String creatorName;
|
||
private LocalDateTime createdAt;
|
||
private LocalDateTime updatedAt;
|
||
}
|
||
```
|
||
|
||
### 8.1.4 关键规则
|
||
|
||
1. 只允许上传 `TEXT / IMAGE / VIDEO`。
|
||
2. `source_status = READY` 的资源才能创建任务。
|
||
3. 已被任务引用的资源删除时，优先做逻辑归档，不直接删除数据库记录。
|
||
4. 删除资源时必须同步清理 RustFS 对象；如清理失败则整体删除失败。
|
||
|
||
|
||
## 8.2 任务管理模块
|
||
|
||
### 8.2.1 模块职责
|
||
|
||
1. 基于一个或多个资源创建抽取任务。
|
||
2. 保存模型配置 ID、Prompt 配置 ID，并在创建时固化模型与 Prompt 快照。
|
||
3. 提供任务分页、详情、修改、软删除。
|
||
4. 后端只负责创建 `PENDING`；状态推进由 `ai-service` 执行。
|
||
|
||
### 8.2.2 接口列表
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `POST` | `/api/annotation-tasks` | 创建任务 |
|
||
| `PUT` | `/api/annotation-tasks/{id}` | 修改任务 |
|
||
| `GET` | `/api/annotation-tasks` | 分页查询任务 |
|
||
| `GET` | `/api/annotation-tasks/{id}` | 查询任务详情 |
|
||
| `DELETE` | `/api/annotation-tasks/{id}` | 删除任务 |
|
||
|
||
### 8.2.3 接口交互对象
|
||
|
||
任务模块查询与界面交互不直接使用 `annotation_task` 数据库实体，而是通过聚合视图返回。创建和修改任务时，模型与 Prompt 均支持“选择已有配置”与“手动输入”两种方式：
|
||
|
||
```java
|
||
public class ManualModelConfigRequest {
|
||
private String modelName;
|
||
private String modelUrl;
|
||
private String apiKey;
|
||
}
|
||
|
||
public class TaskModelConfigRequest {
|
||
private String mode; // SELECT / MANUAL
|
||
private String selectedConfigName; // mode = SELECT 时必填
|
||
private ManualModelConfigRequest manualConfig; // mode = MANUAL 时必填
|
||
}
|
||
|
||
public class PromptConfigOptionRequest {
|
||
private String configName; // 下拉选择 sys_config 中已有 PROMPT 配置时传
|
||
private String promptContent; // 手动输入 Prompt 时传
|
||
}
|
||
|
||
public class CreateAnnotationTaskRequest {
|
||
private String taskName;
|
||
private String industryType; // 行业类型简写，默认 transport，示例 electricity
|
||
private String taskType; // 默认 EXTRACT_QA
|
||
private List<Long> resourceIds;
|
||
private TaskModelConfigRequest extractModel;
|
||
private TaskModelConfigRequest verifyModel;
|
||
private PromptConfigOptionRequest extractPrompt;
|
||
private PromptConfigOptionRequest verifyPrompt;
|
||
}
|
||
|
||
public class UpdateAnnotationTaskRequest {
|
||
private String industryType; // 行业类型简写，默认 transport，示例 electricity
|
||
private String taskType;
|
||
private List<Long> resourceIds;
|
||
private TaskModelConfigRequest extractModel;
|
||
private TaskModelConfigRequest verifyModel;
|
||
private PromptConfigOptionRequest extractPrompt;
|
||
private PromptConfigOptionRequest verifyPrompt;
|
||
}
|
||
|
||
public class AnnotationTaskPageQuery {
|
||
private String keyword;
|
||
private String taskType;
|
||
private String taskStatus;
|
||
private Long resourceId;
|
||
private Boolean isDeleted;
|
||
private Integer pageNo;
|
||
private Integer pageSize;
|
||
}
|
||
|
||
public class TaskModelConfigResponse {
|
||
private Long configId;
|
||
private String configName;
|
||
private String modelName;
|
||
private String modelUrl;
|
||
private String apiKeyMasked;
|
||
}
|
||
|
||
public class TaskPromptConfigResponse {
|
||
private Long configId;
|
||
private String configName;
|
||
private String promptContent;
|
||
private String promptPreview;
|
||
}
|
||
|
||
public class AnnotationTaskResponse {
|
||
private Long id;
|
||
private String taskName;
|
||
private String industryType;
|
||
private String taskType;
|
||
private List<Long> resourceIds;
|
||
private Integer resourceCount;
|
||
private String creatorName;
|
||
private TaskModelConfigResponse extractModel;
|
||
private TaskModelConfigResponse verifyModel;
|
||
private TaskPromptConfigResponse extractPrompt;
|
||
private TaskPromptConfigResponse verifyPrompt;
|
||
private String taskStatus;
|
||
private Boolean isDeleted;
|
||
private LocalDateTime startedAt;
|
||
private LocalDateTime finishedAt;
|
||
private String errorMessage;
|
||
private LocalDateTime createdAt;
|
||
private LocalDateTime updatedAt;
|
||
}
|
||
```
|
||
|
||
交互与落库规则：
|
||
|
||
前端界面与 `CreateAnnotationTaskRequest` 的模型交互流程明确如下：
|
||
|
||
1. `extractModel` 和 `verifyModel` 均采用统一对象结构 `TaskModelConfigRequest`，通过 `mode` 显式表达本次是“下拉选择已有配置”还是“手动输入模型配置”。
|
||
2. 当 `mode = SELECT` 时，前端展示 `MODEL` 类型配置下拉框，并把用户选中的 `selectedConfigName` 传给后端；后端按 `company_id + config_name` 查询 `sys_config`，校验通过后写入 `extract_model_config_id` 或 `verify_model_config_id`，并同步固化模型快照字段。
|
||
3. 当 `mode = MANUAL` 时，前端展示三个手输字段：`modelName`、`modelUrl`、`apiKey`，并通过 `manualConfig` 传给后端。
|
||
4. 对于手动输入的 `extractModel`，后端先按 `company_id + config_name = modelName` 查询 `sys_config` 中 `MODEL` 类型配置：
|
||
- 若存在：直接复用现有配置记录的 `id` 作为 `extract_model_config_id`
|
||
- 若不存在：自动在 `sys_config` 新增一条 `MODEL` 配置记录，`config_name = modelName`，`config_value` 保存 `modelName + modelUrl + apiKey` 组成的 JSON，再把新配置 `id` 写入 `extract_model_config_id`
|
||
- 无论配置是复用还是新建，任务表都要固化本次请求的模型快照字段 `extract_model_name`、`extract_model_url`、`extract_model_api_key`
|
||
5. 对于手动输入的 `verifyModel`，后端执行与 `extractModel` 完全一致的处理逻辑，写入 `verify_model_config_id` 及对应快照字段；若 `modelName` 不存在，同样自动创建 `sys_config` 记录。
|
||
6. `extractPrompt`、`verifyPrompt` 继续支持二选一：要么按 `configName` 选择已有 `PROMPT` 配置，要么直接传 `promptContent` 作为任务快照。
|
||
7. 手动输入 Prompt 时，仅固化到任务快照字段 `extract_prompt` / `verify_prompt`，对应 `*_prompt_config_id` 允许为空。
|
||
8. 创建接口和修改接口遵循完全相同的配置解析规则。
|
||
9. 若 `mode = SELECT` 时仍传入 `manualConfig`，或 `mode = MANUAL` 时仍传入 `selectedConfigName`，后端直接按参数非法处理，避免“选中配置”和“手工输入”语义冲突。
|
||
10. 若 `mode = MANUAL` 但 `modelName`、`modelUrl`、`apiKey` 任一为空，后端直接按参数非法处理。
|
||
|
||
### 8.2.4 状态流转
|
||
|
||
标准流转：
|
||
|
||
`PENDING -> RUNNING -> COMPLETED`
|
||
|
||
失败流转：
|
||
|
||
`PENDING -> RUNNING -> FAILED`
|
||
|
||
重试流转：
|
||
|
||
`FAILED -> PENDING`
|
||
|
||
删除规则：
|
||
|
||
- `PENDING / FAILED / COMPLETED` 允许软删除
|
||
- `RUNNING` 不允许删除
|
||
- 删除接口统一写入 `is_deleted = true`，列表查询默认过滤软删除任务
|
||
|
||
### 8.2.5 任务修改规则
|
||
|
||
修改任务接口覆盖以下属性：
|
||
|
||
- `industryType`
|
||
- `taskType`
|
||
- `resourceIds`
|
||
- `extractModel / verifyModel`
|
||
- `extractPrompt / verifyPrompt`
|
||
|
||
字段级状态约束如下：
|
||
|
||
| 任务状态 | `taskName` | `industryType` / `taskType` / `extractModel` / `verifyModel` / `extractPrompt` / `verifyPrompt` | `resourceIds` |
|
||
|---|---|---|---|
|
||
| `PENDING` | 不可修改 | 可修改 | 可修改 |
|
||
| `FAILED` | 不可修改 | 可修改 | 可修改 |
|
||
| `RUNNING` | 不可修改 | 可修改 | 不可修改 |
|
||
| `COMPLETED` | 不可修改 | 可修改 | 可修改 |
|
||
|
||
设计结论：
|
||
|
||
1. 修改接口不只是绑定资源，还覆盖任务类型、模型配置和 Prompt 配置。
|
||
2. `taskName` 作为任务标识一经创建不可修改，修改接口不接收该字段。
|
||
3. 资源绑定采用 `1A` 规则：仅当当前任务状态为 `RUNNING` 时禁止修改 `resourceIds`，其他状态允许修改。
|
||
4. `RUNNING` 状态下，后端必须校验本次更新前后的 `resourceIds` 是否变化，变化则直接拒绝。
|
||
5. 修改 `resourceIds` 时，后端采用“删旧关联 + 重建新关联”的方式维护 `annotation_task_resource`。
|
||
6. 更新配置类字段时，后端先按 `TaskModelConfigRequest.mode` 解析“选配”或“手输”路径；对于手动输入模型，按 `modelName` 自动创建 / 复用 `sys_config`，再同步刷新任务快照字段，保证任务表中的执行快照与配置引用一致。
|
||
|
||
|
||
## 8.3 审批标注结果模块
|
||
|
||
### 8.3.1 模块职责
|
||
|
||
1. 承接 AI 抽取与校验差异结果。
|
||
2. 查询运行态结果列表与详情。
|
||
3. 对所有未归档运行态结果提供人工审核比对和合并能力。
|
||
4. 对 `requires_manual_review = true` 的结果强制走人工审核闭环。
|
||
5. 对 `requires_manual_review = false` 的结果提供超时自动归档能力。
|
||
|
||
### 8.3.2 接口列表
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `GET` | `/api/annotation-results` | 分页查询结果 |
|
||
| `GET` | `/api/annotation-results/{id}` | 查询结果详情 |
|
||
| `GET` | `/api/annotation-results/{id}/compare` | 查询人工审核比对视图，适用于全部未归档运行态结果 |
|
||
| `POST` | `/api/annotation-results/{id}/merge-review` | 提交人工审核结果并归档 |
|
||
|
||
### 8.3.3 接口交互对象
|
||
|
||
以下结果对象均为接口层 Response / View，数据库字段 `is_deleted` 在接口层统一转换为 `isDeleted`。列表和详情统一返回 `AnnotationResultResponse`：
|
||
|
||
```java
|
||
public class AnnotationResultPageQuery {
|
||
private Long taskId;
|
||
private Long resourceId;
|
||
private Boolean requiresManualReview;
|
||
private String runtimeStatus; // MANUAL_REVIEW_PENDING / AUTO_ARCHIVE_PENDING / ARCHIVED
|
||
private Integer pageNo;
|
||
private Integer pageSize;
|
||
}
|
||
|
||
public class AnnotationResultResponse {
|
||
private Long id;
|
||
private Long taskId;
|
||
private Long resourceId;
|
||
private String qaContentJson;
|
||
private String qaContentStorageMode;
|
||
private String qaContentFilePath;
|
||
private String diffSummary;
|
||
private Boolean requiresManualReview;
|
||
private Boolean isDeleted;
|
||
private Long reviewerId;
|
||
private String reviewComment;
|
||
private LocalDateTime reviewedAt;
|
||
private String runtimeStatus;
|
||
private LocalDateTime createdAt;
|
||
private LocalDateTime updatedAt;
|
||
}
|
||
|
||
public class AnnotationResultCompareResponse {
|
||
private Long id;
|
||
private Long taskId;
|
||
private Long resourceId;
|
||
private String currentQaContentJson;
|
||
private String qaContentStorageMode;
|
||
private String qaContentFilePath;
|
||
private String diffSummary;
|
||
private String originalResourcePreview;
|
||
private Boolean requiresManualReview;
|
||
}
|
||
|
||
public class MergeReviewResultRequest {
|
||
private String diffSummary;
|
||
private String qaContentJson;
|
||
private String reviewComment;
|
||
}
|
||
|
||
public class MergeReviewResultResponse {
|
||
private Long resultId;
|
||
private Long historyId;
|
||
private String archiveReason;
|
||
private LocalDateTime archivedAt;
|
||
}
|
||
```
|
||
|
||
### 8.3.4 合并审核规则
|
||
|
||
1. 只要 `annotation_result.is_deleted = false`，审核员都可以进入人工审核流程，不要求 `requires_manual_review` 必须为 `true`。
|
||
2. `requires_manual_review = true` 仅表示“强制人工审核”，这类结果不允许走自动归档。
|
||
3. `compare` 接口统一返回当前运行态记录中的 `qaContentJson` 与 `diffSummary` 供界面编辑；当 `qaContentStorageMode = EXTERNAL` 时，额外返回 `qaContentFilePath`，用于界面展示当前外置文件来源。
|
||
4. `merge-review` 接口接收前端修订后的 `qaContentJson`、`diffSummary` 和 `reviewComment`，后端据此生成最终归档内容。
|
||
5. 当 `annotation_result.qa_content_storage_mode = EXTERNAL` 时：
|
||
- 后端以当前外置文件名为基准，在本地临时目录生成同名临时文件
|
||
- 将用户修改后的最终内容写入该临时文件
|
||
- 再把该临时文件上传到 RustFS 的归档路径
|
||
- 新建 `annotation_result_history` 记录，写入 `qa_content_storage_mode = EXTERNAL`
|
||
- `annotation_result_history.qa_content_file_path` 保存重新上传后的 RustFS 路径
|
||
- `annotation_result_history.qa_content_json` 仅保留精简摘要或默认值 `{}`
|
||
6. 当 `annotation_result.qa_content_storage_mode = INLINE` 时：
|
||
- 后端将用户最终确认的 `qaContentJson` 与 `diffSummary` 合并为一个归档 JSON
|
||
- 建议结构为 `{"qaContent": <qaContentJson>, "diffSummary": <diffSummary>}`
|
||
- 将该合并结果写入 `annotation_result_history.qa_content_json`
|
||
- `annotation_result_history.qa_content_storage_mode` 继续写入 `INLINE`
|
||
7. 人工审核归档成功后：
|
||
- 写入 `annotation_result_history`
|
||
- 回写运行态结果 `reviewer_id`、`review_comment`、`reviewed_at`
|
||
- 将运行态结果标记为 `is_deleted = true`，等价于从运行态结果集中删除
|
||
|
||
### 8.3.5 自动归档规则
|
||
|
||
仅对 `requires_manual_review = false and is_deleted = false` 的运行态结果开放自动归档：
|
||
|
||
1. 创建后进入 `AUTO_ARCHIVE_PENDING`
|
||
2. 即使处于 `AUTO_ARCHIVE_PENDING`，审核员仍可在超时前主动进入人工审核并抢占归档路径
|
||
3. 超过默认 2 小时且未被人工审核接管时，定时任务把记录迁移到 `annotation_result_history`
|
||
4. `requires_manual_review = true` 的记录一律跳过，不允许自动归档
|
||
5. 自动归档完成后将运行态结果 `is_deleted = true`
|
||
|
||
### 8.3.6 审核状态设计结论
|
||
|
||
一期不再单独保留 `review_status` 字段，原因如下：
|
||
|
||
1. 当前业务并不存在“审核通过后仍停留在运行表”的必要。
|
||
2. 一旦人工确认完成或满足自动归档条件，结果就应该进入历史归档表。
|
||
3. 运行态结果只关心“是否强制人工审核”和“是否已经归档”；是否允许人工审核由 `is_deleted = false` 统一决定。
|
||
|
||
## 8.4 系统配置模块
|
||
|
||
### 8.4.1 模块职责
|
||
|
||
1. 维护模型配置、Prompt 配置、系统参数。
|
||
2. 支持按类型分页查询和详情查看。
|
||
3. 支持新增和修改。
|
||
|
||
### 8.4.2 接口列表
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `POST` | `/api/sys-configs` | 新增配置 |
|
||
| `PUT` | `/api/sys-configs/{id}` | 修改配置 |
|
||
| `GET` | `/api/sys-configs` | 分页查询配置 |
|
||
| `GET` | `/api/sys-configs/{id}` | 查询配置详情 |
|
||
|
||
### 8.4.3 接口交互对象
|
||
|
||
配置模块同样使用独立 DTO，不直接向外暴露数据库实体；列表和详情统一返回 `SysConfigResponse`：
|
||
|
||
```java
|
||
public class SaveSysConfigRequest {
|
||
private String configType; // MODEL / PROMPT / SYSTEM
|
||
private String configName; // 同一 company 下全局唯一，不能与任意类型配置重名
|
||
private String configValue;
|
||
private String status;
|
||
}
|
||
|
||
public class SysConfigPageQuery {
|
||
private String configType;
|
||
private String configName;
|
||
private String status;
|
||
private Integer pageNo;
|
||
private Integer pageSize;
|
||
}
|
||
|
||
public class SysConfigResponse {
|
||
private Long id;
|
||
private String configType;
|
||
private String configName;
|
||
private String configValue;
|
||
private String status;
|
||
private String creatorName;
|
||
private LocalDateTime createdAt;
|
||
private LocalDateTime updatedAt;
|
||
}
|
||
```
|
||
|
||
### 8.4.4 配置值约束
|
||
|
||
| 类型 | `config_name` | `config_value` |
|
||
|---|---|---|
|
||
| `MODEL` | 模型配置名，直接使用模型名称，如 `qwen-max` | JSON，至少包含 `modelName`、`modelUrl`、`apiKey` |
|
||
| `PROMPT` | Prompt 名称，如 `extractPrompt` | 纯文本 |
|
||
| `SYSTEM` | 系统参数名 | 文本或 JSON |
|
||
|
||
补充约束：
|
||
|
||
1. `sys_config` 在同一 `company_id` 下，`config_name` 不允许重复，不再区分 `config_type` 后再重复命名。
|
||
2. 任务创建/修改界面的模型和 Prompt 下拉框均以 `configName` 作为选择值。
|
||
3. 对于 `MODEL` 类型配置，`config_name` 同时承担任务手动录入模型时的自动建档主键语义。
|
||
4. 新增配置时，后端必须先按 `company_id + config_name` 做重复校验；若已存在同名配置，不论其 `config_type` 是 `MODEL`、`PROMPT` 还是 `SYSTEM`，都直接返回 `CONFIG_DUPLICATE`。
|
||
5. 修改配置时，如 `configName` 发生变化，后端同样必须校验目标名称是否已被同公司下其他配置占用；若占用则拒绝修改。
|
||
6. 该约束适用于人工维护配置和任务创建时的模型自动建档两条路径，二者共用同一唯一性规则。
|
||
|
||
|
||
## 9. 通用返回结构
|
||
|
||
一期统一建议：
|
||
|
||
```java
|
||
public class ApiResponse<T> {
|
||
private String code;
|
||
private String message;
|
||
private T data;
|
||
}
|
||
|
||
public class PageResult<T> {
|
||
private List<T> records;
|
||
private Long total;
|
||
private Integer pageNo;
|
||
private Integer pageSize;
|
||
}
|
||
```
|
||
|
||
### 9.1 分页机制评审结论
|
||
|
||
一期分页机制明确采用 MyBatis-Plus 分页插件方案，不采用 `PageHelper`。
|
||
|
||
结论如下：
|
||
|
||
1. 当前项目已经使用 MyBatis-Plus，继续使用其分页能力更符合现有技术栈。
|
||
2. 不建议再引入 `PageHelper`，否则会形成两套分页机制并存，增加维护成本和排障复杂度。
|
||
3. 也不建议在每个列表查询里手写一套 `LIMIT/OFFSET + COUNT(*)` 作为默认方案，重复代码过多。
|
||
|
||
推荐实现方式：
|
||
|
||
1. 在 Spring 配置中启用 MyBatis-Plus `PaginationInnerInterceptor`。
|
||
2. 列表查询统一接收 `pageNo`、`pageSize`。
|
||
3. Mapper 自定义 SQL 场景使用 `Page<T>` + 查询对象参数的方式，由分页插件自动追加分页 SQL。
|
||
4. 对需要聚合的列表，例如任务列表里的 `resourceCount`，允许在 Mapper XML 中写聚合查询，但仍通过 MyBatis-Plus 分页插件处理分页。
|
||
|
||
分页设计约束：
|
||
|
||
- 默认分页方案：MyBatis-Plus `PaginationInnerInterceptor`
|
||
- 明确不使用：`PageHelper`
|
||
- 明确不推荐：每个列表接口手写裸 SQL 分页
|
||
|
||
### 9.2 分页实现设计
|
||
|
||
#### 9.2.1 Spring 配置
|
||
|
||
一期建议新增统一分页配置类，示例：
|
||
|
||
```java
|
||
@Configuration
|
||
public class MybatisPlusConfig {
|
||
|
||
@Bean
|
||
public MybatisPlusInterceptor mybatisPlusInterceptor() {
|
||
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
|
||
PaginationInnerInterceptor paginationInnerInterceptor =
|
||
new PaginationInnerInterceptor(DbType.POSTGRE_SQL);
|
||
paginationInnerInterceptor.setOverflow(false);
|
||
paginationInnerInterceptor.setMaxLimit(200L);
|
||
interceptor.addInnerInterceptor(paginationInnerInterceptor);
|
||
return interceptor;
|
||
}
|
||
}
|
||
```
|
||
|
||
约束说明：
|
||
|
||
1. `DbType` 使用 `POSTGRE_SQL`。
|
||
2. `maxLimit` 建议限制为 `200`，防止大页拖垮查询。
|
||
3. `overflow(false)`，页码越界时返回空列表，不自动回退到第一页。
|
||
|
||
#### 9.2.2 通用分页请求约束
|
||
|
||
所有分页查询 DTO 统一约束如下：
|
||
|
||
```java
|
||
public class PageQuery {
|
||
@Min(1)
|
||
private Integer pageNo = 1;
|
||
|
||
@Min(1)
|
||
@Max(200)
|
||
private Integer pageSize = 20;
|
||
}
|
||
```
|
||
|
||
业务分页 DTO 在此基础上扩展过滤字段，例如：
|
||
|
||
```java
|
||
public class AnnotationTaskPageQuery extends PageQuery {
|
||
private String keyword;
|
||
private String taskType;
|
||
private String taskStatus;
|
||
private Long resourceId;
|
||
}
|
||
```
|
||
|
||
#### 9.2.3 Service 层调用约定
|
||
|
||
Service 层统一构造 MyBatis-Plus `Page<T>`：
|
||
|
||
```java
|
||
public PageResult<AnnotationTaskResponse> pageTasks(AnnotationTaskPageQuery query) {
|
||
Page<AnnotationTaskResponse> page = new Page<>(query.getPageNo(), query.getPageSize());
|
||
IPage<AnnotationTaskResponse> result = annotationTaskMapper.selectTaskPage(page, query);
|
||
return PageResult.of(result);
|
||
}
|
||
```
|
||
|
||
建议补一个统一转换方法：
|
||
|
||
```java
|
||
public class PageResult<T> {
|
||
private List<T> records;
|
||
private Long total;
|
||
private Integer pageNo;
|
||
private Integer pageSize;
|
||
|
||
public static <T> PageResult<T> of(IPage<T> page) {
|
||
PageResult<T> result = new PageResult<>();
|
||
result.setRecords(page.getRecords());
|
||
result.setTotal(page.getTotal());
|
||
result.setPageNo((int) page.getCurrent());
|
||
result.setPageSize((int) page.getSize());
|
||
return result;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 9.2.4 Mapper 设计
|
||
|
||
分页查询建议采用“自定义 XML + `Page<T>` 首参”的方式。
|
||
|
||
Mapper 接口示例：
|
||
|
||
```java
|
||
public interface AnnotationTaskMapper extends BaseMapper<AnnotationTask> {
|
||
|
||
IPage<AnnotationTaskResponse> selectTaskPage(
|
||
Page<AnnotationTaskResponse> page,
|
||
@Param("query") AnnotationTaskPageQuery query
|
||
);
|
||
}
|
||
```
|
||
|
||
Mapper XML 设计原则：
|
||
|
||
1. `Page<T>` 放在第一个参数位置。
|
||
2. 过滤条件统一从 `query.xxx` 取值。
|
||
3. 列表查询只查当前页需要字段，不做 `select *`。
|
||
4. 排序规则必须显式写出，避免分页结果不稳定。
|
||
|
||
#### 9.2.5 聚合分页场景
|
||
|
||
任务列表需要返回 `resourceCount`，属于典型聚合分页场景。推荐写法：
|
||
|
||
```xml
|
||
<select id="selectTaskPage" resultType="com.labelsys.backend.dto.response.AnnotationTaskResponse">
|
||
SELECT
|
||
t.id,
|
||
t.task_name AS taskName,
|
||
t.task_type AS taskType,
|
||
t.task_status AS taskStatus,
|
||
t.is_deleted AS isDeleted,
|
||
t.created_at AS createdAt,
|
||
COUNT(tr.id) AS resourceCount
|
||
FROM annotation_task t
|
||
LEFT JOIN annotation_task_resource tr ON tr.task_id = t.id
|
||
WHERE t.company_id = #{query.companyId}
|
||
AND t.is_deleted = COALESCE(#{query.isDeleted}, FALSE)
|
||
<if test="query.keyword != null and query.keyword != ''">
|
||
AND t.task_name ILIKE CONCAT('%', #{query.keyword}, '%')
|
||
</if>
|
||
<if test="query.taskType != null and query.taskType != ''">
|
||
AND t.task_type = #{query.taskType}
|
||
</if>
|
||
<if test="query.taskStatus != null and query.taskStatus != ''">
|
||
AND t.task_status = #{query.taskStatus}
|
||
</if>
|
||
<if test="query.resourceId != null">
|
||
AND EXISTS (
|
||
SELECT 1
|
||
FROM annotation_task_resource tr2
|
||
WHERE tr2.task_id = t.id
|
||
AND tr2.resource_id = #{query.resourceId}
|
||
)
|
||
</if>
|
||
GROUP BY t.id, t.task_name, t.task_type, t.task_status, t.is_deleted, t.created_at
|
||
ORDER BY t.created_at DESC, t.id DESC
|
||
</select>
|
||
```
|
||
|
||
设计结论：
|
||
|
||
1. 聚合字段允许在 XML 中显式计算。
|
||
2. 资源过滤推荐用 `EXISTS`，避免直接 join 过滤导致重复行干扰分页。
|
||
3. 排序建议固定为 `created_at DESC, id DESC`，保证翻页稳定。
|
||
|
||
#### 9.2.6 Count SQL 评审
|
||
|
||
对于简单列表，MyBatis-Plus 可自动生成 count 查询。
|
||
|
||
对于复杂聚合分页，有两条约束：
|
||
|
||
1. 先使用分页插件默认 count 机制。
|
||
2. 如果后续发现 count SQL 在复杂 `GROUP BY` 或多层子查询下性能差，再针对具体接口单独拆 `count` 查询，不要在一期一开始就全量手写。
|
||
|
||
这也是主流团队的常见做法，先统一插件方案，遇到瓶颈再对个别热点查询做定向优化。
|
||
|
||
#### 9.2.7 落地范围
|
||
|
||
一期以下分页接口统一采用同一机制：
|
||
|
||
1. `/api/source-resources`
|
||
2. `/api/annotation-tasks`
|
||
3. `/api/annotation-results`
|
||
4. `/api/sys-configs`
|
||
|
||
## 10. 数据库设计
|
||
|
||
## 10.1 设计说明
|
||
|
||
|
||
1. 数据库以 `D:\workspace\labeling\lb_backend\src\main\resources\sql` 目录下的 SQL 文件为唯一基准来源。
|
||
2. `annotation_task` 当前真实建表同时保存配置引用字段和执行快照字段：前者用于界面回显与配置追溯，后者用于执行时解耦配置变更影响。
|
||
3. `annotation_task`、`annotation_result` 均采用软删除字段 `is_deleted` 表达逻辑删除或归档后的不可见状态。
|
||
4. 一期 ID 统一使用 `BIGINT`，由应用层生成，不使用自增。
|
||
|
||
## 10.2 表关系
|
||
|
||
```text
|
||
sys_company 1 --- n sys_user
|
||
sys_company 1 --- n sys_menu
|
||
sys_company 1 --- n sys_config
|
||
sys_company 1 --- n source_resource
|
||
sys_company 1 --- n annotation_task
|
||
sys_company 1 --- n annotation_result
|
||
sys_company 1 --- n annotation_result_history
|
||
sys_company 1 --- n training_dataset
|
||
sys_company 1 --- n export_batch
|
||
|
||
sys_user 1 --- n sys_config(creator_id)
|
||
sys_user 1 --- n source_resource(creator_id)
|
||
sys_user 1 --- n annotation_task(creator_id)
|
||
sys_user 1 --- n annotation_result(creator_id / reviewer_id)
|
||
sys_user 1 --- n annotation_result_history(creator_id / archived_by)
|
||
sys_user 1 --- n training_dataset(creator_id)
|
||
sys_user 1 --- n export_batch(creator_id)
|
||
|
||
sys_config 1 --- n annotation_task(extract_model_config_id)
|
||
sys_config 1 --- n annotation_task(verify_model_config_id)
|
||
sys_config 1 --- n annotation_task(extract_prompt_config_id)
|
||
sys_config 1 --- n annotation_task(verify_prompt_config_id)
|
||
|
||
annotation_task 1 --- n annotation_task_resource
|
||
source_resource 1 --- n annotation_task_resource
|
||
annotation_task 1 --- n annotation_result
|
||
source_resource 1 --- n annotation_result
|
||
annotation_result 1 --- n annotation_result_history
|
||
annotation_result_history 1 --- n training_dataset
|
||
export_batch 1 --- n export_batch_item
|
||
training_dataset 1 --- n export_batch_item
|
||
```
|
||
|
||
## 10.3 `sys_company`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 公司主键 |
|
||
| `company_code` | `VARCHAR(64)` | 否 | 无 | UNIQUE | 公司编码 |
|
||
| `company_name` | `VARCHAR(128)` | 否 | 无 | 无 | 公司名称 |
|
||
| `status` | `VARCHAR(32)` | 否 | `ENABLED` | 无 | 公司状态 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
## 10.4 `sys_user`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 用户主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，索引列 | 公司 ID |
|
||
| `phone` | `VARCHAR(32)` | 否 | 无 | 同公司唯一约束 | 手机号 |
|
||
| `username` | `VARCHAR(64)` | 是 | 无 | 无 | 用户名或展示别名 |
|
||
| `role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 组合索引列 | 数据权限角色 |
|
||
| `position` | `VARCHAR(32)` | 否 | `ANNOTATOR` | 组合索引列 | 岗位 |
|
||
| `real_name` | `VARCHAR(64)` | 否 | 无 | 无 | 真实姓名 |
|
||
| `password_hash` | `VARCHAR(255)` | 否 | 无 | 无 | 密码哈希 |
|
||
| `must_change_password` | `BOOLEAN` | 否 | `TRUE` | 无 | 是否首次登录强制改密 |
|
||
| `status` | `VARCHAR(32)` | 否 | `ENABLED` | 无 | 用户状态 |
|
||
| `session_version` | `INTEGER` | 否 | `1` | 无 | 会话版本号 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `uq_sys_user_company_phone(company_id, phone)`
|
||
- `idx_sys_user_company(company_id)`
|
||
- `idx_sys_user_role(company_id, role)`
|
||
- `idx_sys_user_position(company_id, position)`
|
||
|
||
## 10.5 `sys_menu`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 菜单主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，组合索引前缀列 | 公司 ID |
|
||
| `menu_code` | `VARCHAR(64)` | 否 | 无 | 无 | 菜单编码 |
|
||
| `menu_name` | `VARCHAR(128)` | 否 | 无 | 无 | 菜单名称 |
|
||
| `path` | `VARCHAR(255)` | 否 | 无 | 无 | 路由路径 |
|
||
| `visible_positions` | `VARCHAR(255)` | 否 | `ADMIN` | 无 | 可见岗位列表 |
|
||
| `sort_order` | `INTEGER` | 否 | `0` | 组合索引列 | 排序号 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_sys_menu_company_sort(company_id, sort_order)`
|
||
|
||
## 10.6 `sys_config`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 主键，非自增 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，索引前缀列 | 公司 ID |
|
||
| `config_type` | `VARCHAR(32)` | 否 | `SYSTEM` | 组合索引列 | 配置类型 |
|
||
| `config_name` | `VARCHAR(128)` | 否 | 无 | 同公司唯一索引，不允许同名 | 配置名称，也是前端下拉选择值 |
|
||
| `config_value` | `TEXT` | 否 | 无 | 无 | 配置值；`MODEL` 类型保存 `modelName/modelUrl/apiKey` JSON |
|
||
| `status` | `VARCHAR(32)` | 否 | `ENABLED` | 无 | 状态 |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK | 创建人 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `uq_sys_config_company_name(company_id, config_name)`
|
||
- `idx_sys_config_company_type(company_id, config_type)`
|
||
|
||
约束说明：
|
||
|
||
1. `uq_sys_config_company_name(company_id, config_name)` 是一期强约束，表示同一公司下 `config_name` 全局唯一。
|
||
2. 该唯一性不区分 `config_type`，例如同一公司下不能同时存在名为 `qwen-max` 的 `MODEL` 配置和名为 `qwen-max` 的 `SYSTEM` 配置。
|
||
3. 任务创建时若用户手动输入模型名称，自动写入 `sys_config` 前也必须先经过这条唯一性校验。
|
||
|
||
## 10.7 `source_resource`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 资源主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，索引前缀列 | 公司 ID |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK，组合索引列 | 上传人 |
|
||
| `creator_role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 无 | 创建时角色快照 |
|
||
| `resource_name` | `VARCHAR(255)` | 否 | 无 | 无 | 展示名称 |
|
||
| `resource_type` | `VARCHAR(32)` | 否 | `TEXT` | 组合索引列 | `TEXT / IMAGE / VIDEO` |
|
||
| `bucket_name` | `VARCHAR(128)` | 否 | 无 | 无 | 对象存储桶 |
|
||
| `file_path` | `VARCHAR(512)` | 否 | 无 | 无 | 对象路径 |
|
||
| `file_size` | `BIGINT` | 否 | `0` | 无 | 文件大小 |
|
||
| `source_status` | `VARCHAR(32)` | 否 | `UPLOADED` | 组合索引列 | 资源状态 |
|
||
| `storage_provider` | `VARCHAR(64)` | 否 | `rustfs` | 无 | 存储提供方 |
|
||
| `remark` | `VARCHAR(255)` | 是 | 无 | 无 | 备注 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_source_resource_company_type(company_id, resource_type)`
|
||
- `idx_source_resource_company_status(company_id, source_status)`
|
||
- `idx_source_resource_creator(company_id, creator_id)`
|
||
|
||
## 10.8 `annotation_task`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 任务主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，索引前缀列 | 公司 ID |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK，组合索引列 | 创建人 |
|
||
| `creator_role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 无 | 创建时角色快照 |
|
||
| `task_name` | `VARCHAR(255)` | 否 | 无 | 无 | 任务名称 |
|
||
| `industry_type` | `VARCHAR(32)` | 否 | `transport` | 无 | 行业类型简写，默认 transport，示例 electricity |
|
||
| `task_type` | `VARCHAR(32)` | 否 | `EXTRACT_QA` | 无 | 任务类型 |
|
||
| `extract_model_config_id` | `BIGINT` | 是 | 无 | FK | 抽取模型配置 ID，关联 `sys_config.id` |
|
||
| `extract_model_name` | `VARCHAR(128)` | 是 | 无 | 无 | 抽取模型名 |
|
||
| `extract_model_url` | `VARCHAR(255)` | 是 | 无 | 无 | 抽取模型地址 |
|
||
| `extract_model_api_key` | `VARCHAR(255)` | 是 | 无 | 无 | 抽取模型 Key |
|
||
| `verify_model_config_id` | `BIGINT` | 是 | 无 | FK | 校验模型配置 ID，关联 `sys_config.id` |
|
||
| `verify_model_name` | `VARCHAR(128)` | 是 | 无 | 无 | 校验模型名 |
|
||
| `verify_model_url` | `VARCHAR(255)` | 是 | 无 | 无 | 校验模型地址 |
|
||
| `verify_model_api_key` | `VARCHAR(255)` | 是 | 无 | 无 | 校验模型 Key |
|
||
| `extract_prompt_config_id` | `BIGINT` | 是 | 无 | FK | 抽取 Prompt 配置 ID，关联 `sys_config.id` |
|
||
| `extract_prompt` | `TEXT` | 是 | 无 | 无 | 抽取 Prompt 快照 |
|
||
| `verify_prompt_config_id` | `BIGINT` | 是 | 无 | FK | 校验 Prompt 配置 ID，关联 `sys_config.id` |
|
||
| `verify_prompt` | `TEXT` | 是 | 无 | 无 | 校验 Prompt 快照 |
|
||
| `task_status` | `VARCHAR(32)` | 否 | `PENDING` | 组合索引列 | 任务状态 |
|
||
| `is_deleted` | `BOOLEAN` | 否 | `FALSE` | 组合索引列 | 任务软删除标记 |
|
||
| `started_at` | `TIMESTAMP` | 是 | 无 | 无 | 开始时间 |
|
||
| `finished_at` | `TIMESTAMP` | 是 | 无 | 无 | 结束时间 |
|
||
| `error_message` | `TEXT` | 是 | 无 | 无 | 错误信息 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_annotation_task_company_status(company_id, task_status)`
|
||
- `idx_annotation_task_company_deleted(company_id, is_deleted)`
|
||
- `idx_annotation_task_creator(company_id, creator_id)`
|
||
|
||
设计说明：
|
||
|
||
1. `annotation_task` 主表不再直接保存 `resource_id`。
|
||
2. 一个任务可绑定多个资源，具体绑定关系落在 `annotation_task_resource`。
|
||
3. `task_type` 默认值为 `EXTRACT_QA`。
|
||
4. 配置 ID 字段用于关联按 `configName` 选中的模型/Prompt 配置；名称、URL、Key、Prompt 文本字段用于固化执行快照。
|
||
5. `industry_type` 用于保存任务所属行业类型简写，默认值为 `transport`，可选值按业务枚举扩展，例如 `electricity`。
|
||
6. `extractModel`、`verifyModel` 在接口层不再复用单层平铺字段，而是统一使用 `TaskModelConfigRequest(mode + selectedConfigName + manualConfig)` 显式表达页面交互模式。
|
||
7. 手动输入模型配置时，后端先按模型名称匹配 `sys_config.config_name`；不存在则自动创建 `MODEL` 配置后再写入任务；存在则复用已有配置 ID。
|
||
8. 手动输入 Prompt 时，仅保存快照文本，不强制自动创建 `PROMPT` 配置。
|
||
9. `task_name` 只允许创建时写入，后续更新接口不可修改。
|
||
10. 删除接口不物理删除任务，统一更新 `is_deleted = true`。
|
||
|
||
## 10.9 `annotation_task_resource`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 任务资源关联主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，组合索引前缀列 | 公司 ID |
|
||
| `task_id` | `BIGINT` | 否 | 无 | FK，唯一约束组成列，组合索引列 | 任务 ID |
|
||
| `resource_id` | `BIGINT` | 否 | 无 | FK，唯一约束组成列，组合索引列 | 资源 ID |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `uq_annotation_task_resource(task_id, resource_id)`
|
||
- `idx_annotation_task_resource_company_task(company_id, task_id)`
|
||
- `idx_annotation_task_resource_company_resource(company_id, resource_id)`
|
||
|
||
## 10.10 `annotation_result`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 运行态结果主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，索引前缀列 | 公司 ID |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK | 结果创建人 |
|
||
| `creator_role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 无 | 创建时角色快照 |
|
||
| `task_id` | `BIGINT` | 否 | 无 | FK，组合索引列 | 任务 ID |
|
||
| `resource_id` | `BIGINT` | 否 | 无 | FK | 资源 ID |
|
||
| `qa_content_json` | `TEXT` | 否 | `'{}'` | 无 | 问答 JSON |
|
||
| `qa_content_storage_mode` | `VARCHAR(32)` | 否 | `INLINE` | 无 | `INLINE / EXTERNAL` |
|
||
| `qa_content_file_path` | `VARCHAR(512)` | 是 | 无 | 无 | 外置问答文件路径 |
|
||
| `diff_summary` | `TEXT` | 否 | `'{}'` | 无 | 差异摘要 JSON |
|
||
| `requires_manual_review` | `BOOLEAN` | 否 | `FALSE` | 组合索引列 | 是否强制人工审核 |
|
||
| `is_deleted` | `BOOLEAN` | 否 | `FALSE` | 组合索引列 | 软删除标记 |
|
||
| `reviewer_id` | `BIGINT` | 是 | 无 | FK | 审核人 |
|
||
| `review_comment` | `TEXT` | 是 | 无 | 无 | 审核备注 |
|
||
| `reviewed_at` | `TIMESTAMP` | 是 | 无 | 无 | 审核时间 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_annotation_result_company_deleted(company_id, is_deleted)`
|
||
- `idx_annotation_result_company_manual(company_id, requires_manual_review)`
|
||
- `idx_annotation_result_task(company_id, task_id)`
|
||
|
||
设计说明：
|
||
|
||
1. 去掉 `result_type`，结果类型由任务和资源类型推导。
|
||
2. 去掉 `review_status`，审核完成后直接归档。
|
||
3. 新增 `is_deleted` 作为软删除标记，配合历史表形成完整生命周期。
|
||
|
||
## 10.11 `annotation_result_history`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 历史记录主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK，普通索引 | 公司 ID |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK | 原结果创建人 |
|
||
| `creator_role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 无 | 原创建角色 |
|
||
| `source_result_id` | `BIGINT` | 是 | 无 | FK | 来源运行态结果 ID |
|
||
| `task_id` | `BIGINT` | 否 | 无 | FK，组合索引列 | 任务 ID |
|
||
| `resource_id` | `BIGINT` | 否 | 无 | FK，组合索引列 | 资源 ID |
|
||
| `qa_content_json` | `TEXT` | 否 | `'{}'` | 无 | 归档后的问答 JSON |
|
||
| `qa_content_storage_mode` | `VARCHAR(32)` | 否 | `INLINE` | 无 | 归档后的问答存储模式 |
|
||
| `qa_content_file_path` | `VARCHAR(512)` | 是 | 无 | 无 | 归档后的外置问答文件路径 |
|
||
| `archive_reason` | `VARCHAR(255)` | 是 | 无 | 无 | 归档原因 |
|
||
| `archived_by` | `BIGINT` | 是 | 无 | FK | 归档操作人 |
|
||
| `archived_at` | `TIMESTAMP` | 是 | 无 | 无 | 归档时间 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_annotation_result_history_company(company_id)`
|
||
- `idx_annotation_result_history_task(company_id, task_id)`
|
||
- `idx_annotation_result_history_resource(company_id, resource_id)`
|
||
|
||
## 10.12 `training_dataset`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 训练样本主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK | 公司 ID |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK | 创建人 |
|
||
| `creator_role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 无 | 创建人数据权限角色 |
|
||
| `result_history_id` | `BIGINT` | 否 | 无 | FK | 来源历史结果 ID |
|
||
| `sample_type` | `VARCHAR(32)` | 否 | `TEXT` | 无 | 样本类型 |
|
||
| `glm_format_json` | `TEXT` | 否 | 无 | 无 | GLM 微调格式 JSON |
|
||
| `dataset_status` | `VARCHAR(32)` | 否 | `DRAFT` | 组合索引列 | 样本状态 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_training_dataset_company_status(company_id, dataset_status)`
|
||
|
||
## 10.13 `export_batch`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 导出批次主键 |
|
||
| `company_id` | `BIGINT` | 否 | 无 | FK | 公司 ID |
|
||
| `creator_id` | `BIGINT` | 否 | 无 | FK | 创建人 |
|
||
| `creator_role` | `VARCHAR(32)` | 否 | `EMPLOYEE` | 无 | 创建人数据权限角色 |
|
||
| `batch_no` | `VARCHAR(64)` | 否 | 无 | UNIQUE | 批次编号 |
|
||
| `dataset_file_path` | `VARCHAR(512)` | 是 | 无 | 无 | 导出文件路径 |
|
||
| `sample_count` | `INTEGER` | 否 | `0` | 无 | 样本数 |
|
||
| `finetune_job_id` | `VARCHAR(128)` | 是 | 无 | 无 | 微调任务 ID |
|
||
| `finetune_status` | `VARCHAR(32)` | 否 | `NOT_STARTED` | 组合索引列 | 微调状态 |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
| `updated_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 更新时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `idx_export_batch_company_status(company_id, finetune_status)`
|
||
|
||
## 10.14 `export_batch_item`
|
||
|
||
| 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | `BIGINT` | 否 | 无 | PK | 批次样本关系主键 |
|
||
| `batch_id` | `BIGINT` | 否 | 无 | FK，唯一约束组成列 | 导出批次 ID |
|
||
| `dataset_id` | `BIGINT` | 否 | 无 | FK，唯一约束组成列 | 训练样本 ID |
|
||
| `created_at` | `TIMESTAMP` | 是 | `CURRENT_TIMESTAMP` | 无 | 创建时间 |
|
||
|
||
实际索引/约束：
|
||
|
||
- `uq_export_batch_item(batch_id, dataset_id)`
|
||
|
||
## 11. 一期关键流程
|
||
|
||
### 11.1 资源上传到任务创建
|
||
|
||
1. 用户上传资源。
|
||
2. 后端将文件写入 RustFS，并生成 `source_resource`。
|
||
3. 当前无论文本、图片还是视频，校验通过后均直接置为 `READY`。
|
||
4. 用户选择一个或多个资源、模型、Prompt 创建任务。
|
||
5. 后端写入 `annotation_task` 和 `annotation_task_resource`，任务状态固定为 `PENDING`。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户上传资源] --> B[backend 写入 RustFS]
|
||
B --> C[创建 source_resource]
|
||
C --> D[资源校验通过]
|
||
D --> E[source_status = READY]
|
||
E --> F[用户选择资源/模型/Prompt]
|
||
F --> G[创建 annotation_task]
|
||
G --> H[创建 annotation_task_resource]
|
||
H --> I[task_status = PENDING]
|
||
```
|
||
|
||
### 11.2 AI 处理到结果入库
|
||
|
||
1. `ai-service` 轮询 `PENDING` 任务。
|
||
2. 拉取资源并处理，任务改为 `RUNNING`。
|
||
3. 生成抽取结果和校验结果。
|
||
4. 对比差异后写入 `annotation_result`，同时落库 `qa_content_json`、`diff_summary`、`qa_content_storage_mode` 等运行态字段。
|
||
5. 若结果必须由人工确认后才能进入最终归档，则标记 `requires_manual_review = true`。
|
||
6. 若结果允许系统在超时后直接归档，则标记 `requires_manual_review = false`。
|
||
7. 两种结果在 `is_deleted = false` 期间都允许审核员主动发起人工审核；差异仅在于是否允许后续自动归档。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[ai-service 轮询 PENDING 任务] --> B[任务置为 RUNNING]
|
||
B --> C[抽取与校验]
|
||
C --> D[生成 qa_content_json 和 diff_summary]
|
||
D --> E{是否必须人工审核?}
|
||
E -- 是 --> F[写入 annotation_result<br/>requires_manual_review = true]
|
||
E -- 否 --> G[写入 annotation_result<br/>requires_manual_review = false]
|
||
F --> H[等待人工审核归档]
|
||
G --> I[等待人工审核或自动归档]
|
||
```
|
||
|
||
### 11.3 人工审核归档
|
||
|
||
1. 审核员打开结果比对页。
|
||
2. 查询 `compare` 接口获取资源预览、当前 `qaContentJson`、`diffSummary`、`qaContentStorageMode` 和 `qaContentFilePath`。
|
||
3. 无论 `requires_manual_review = true` 还是 `false`，只要记录尚未归档，审核员都可以修改 `qaContentJson` 和必要的 `diffSummary`。
|
||
4. 调用 `merge-review` 接口提交最终内容。
|
||
5. 若当前记录 `qa_content_storage_mode = EXTERNAL`：
|
||
- 后端在本地生成与当前外置文件同名的临时文件
|
||
- 将用户最终内容写入该临时文件
|
||
- 上传到 RustFS 归档路径
|
||
- 新建 `annotation_result_history`，写入 `qa_content_storage_mode = EXTERNAL` 和新的 `qa_content_file_path`
|
||
6. 若当前记录 `qa_content_storage_mode = INLINE`：
|
||
- 后端将 `qaContentJson` 与 `diffSummary` 合并
|
||
- 将合并结果写入 `annotation_result_history.qa_content_json`
|
||
7. 归档成功后，运行态 `annotation_result` 回写审核人信息并标记 `is_deleted = true`，从运行态结果集中移除。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[审核员打开 compare 页面] --> B[读取 qaContentJson / diffSummary / storageMode]
|
||
B --> C[审核员修改最终内容]
|
||
C --> D[调用 merge-review]
|
||
D --> E{qa_content_storage_mode}
|
||
E -- EXTERNAL --> F[本地生成同名临时文件]
|
||
F --> G[写入最终内容]
|
||
G --> H[上传 RustFS 归档路径]
|
||
H --> I[写 annotation_result_history<br/>storage_mode = EXTERNAL]
|
||
E -- INLINE --> J[合并 qaContentJson + diffSummary]
|
||
J --> K[写 annotation_result_history<br/>storage_mode = INLINE]
|
||
I --> L[回写 reviewer 信息]
|
||
K --> L
|
||
L --> M[annotation_result.is_deleted = true]
|
||
```
|
||
|
||
### 11.4 自动归档
|
||
|
||
1. 定时任务仅扫描 `requires_manual_review = false and is_deleted = false` 的运行态结果。
|
||
2. 若结果已被审核员人工处理接管，则本次不再进入自动归档。
|
||
3. 若 `created_at + 2h < now()`，则执行自动归档。
|
||
4. 自动归档完成后写入 `annotation_result_history`。
|
||
5. 回写运行态结果 `is_deleted = true`。
|
||
6. `requires_manual_review = true` 的记录不参与自动归档扫描。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[AutoArchiveAnnotationResultJob 扫描运行态结果] --> B{requires_manual_review = false?}
|
||
B -- 否 --> C[跳过]
|
||
B -- 是 --> D{is_deleted = false?}
|
||
D -- 否 --> C
|
||
D -- 是 --> E{是否已被人工审核接管?}
|
||
E -- 是 --> C
|
||
E -- 否 --> F{是否超过2小时?}
|
||
F -- 否 --> C
|
||
F -- 是 --> G[写 annotation_result_history]
|
||
G --> H[annotation_result.is_deleted = true]
|
||
```
|
||
|
||
## 12. 典型任务与定时任务
|
||
|
||
一期当前仅保留一个后台任务：
|
||
|
||
1. `AutoArchiveAnnotationResultJob`
|
||
- 仅扫描 `requires_manual_review = false` 且超时的运行态结果
|
||
- 跳过已被人工审核接管或已归档的记录
|
||
- 迁移到历史表
|
||
- 回写 `is_deleted = true`
|
||
|
||
## 13. 错误处理与审计
|
||
|
||
### 13.1 错误码建议
|
||
|
||
| 错误码 | 场景 |
|
||
|---|---|
|
||
| `RESOURCE_NOT_READY` | 资源未就绪不可创建任务 |
|
||
| `TASK_STATUS_INVALID` | 当前任务状态不允许删除或重试 |
|
||
| `RESULT_NOT_REVIEWABLE` | 结果已归档、已从运行态移除，或当前记录不允许继续进入审核提交 |
|
||
| `CONFIG_DUPLICATE` | 同公司下 `configName` 重复 |
|
||
| `OBJECT_STORAGE_ERROR` | RustFS 上传/删除失败 |
|
||
|
||
### 13.2 审计建议
|
||
|
||
以下操作必须记录操作日志：
|
||
|
||
1. 资源删除
|
||
2. 任务创建与删除
|
||
3. 人工审核合并
|
||
4. 系统配置新增与修改
|
||
|
||
## 14. 一期验收标准
|
||
1. 资源、任务、结果、配置四个模块均有清晰 REST 接口。
|
||
2. 请求 DTO、响应 DTO、分页结构与数据库实体解耦，可直接映射 Controller 层代码。
|
||
3. 数据表字段类型、默认值、索引、约束与业务语义一致。
|
||
4. 对象存储路径能覆盖原始资源、外置问答结果和导出文件。
|
||
5. `annotation_result` 生命周期遵循“运行态在当前表、最终态进历史表”的原则。
|
||
6. source 相关状态只描述资源本身，不再混入任务和审核状态。
|
||
|
||
## 15. 与当前代码基线的差异说明
|
||
|
||
为满足最新需求，本文档相对旧版设计的关键调整如下：
|
||
|
||
1. `annotation_result` 去掉 `result_type`。
|
||
2. `annotation_result` 去掉 `review_status`。
|
||
3. `annotation_result` 增加 `is_deleted`。
|
||
4. `annotation_task` 改为任务主表 + `annotation_task_resource` 关联表，一个任务可绑定多个资源。
|
||
5. `annotation_task.task_type` 默认值调整为 `EXTRACT_QA`。
|
||
6. `annotation_task` 新增 `extract_model_config_id`、`verify_model_config_id`、`extract_prompt_config_id`、`verify_prompt_config_id`。
|
||
7. `annotation_task` 新增软删除字段 `is_deleted`，删除接口采用逻辑删除。
|
||
8. 任务修改接口明确不允许修改 `taskName`，且 `RUNNING` 状态不可修改绑定资源。
|
||
9. 任务、资源、结果、配置均通过独立接口 DTO/VO 对外提供，不直接暴露数据库实体。
|
||
10. 任务状态使用 `PENDING / RUNNING / COMPLETED / FAILED`。
|
||
11. `source_resource` 只保留资源状态，不承接抽取和审核流转。
|
||
12. 当前不引入独立的视频预处理作业设计。
|
||
13. 对象存储规范重新分桶、重新分层。
|
||
14. 创建和修改任务的请求对象改为支持按 `configName` 选择已有配置，或手动输入模型 / Prompt；模型名不存在时自动创建 `sys_config`。
|
||
15. `AnnotationTaskResponse`、`SourceResourceResponse`、`SysConfigResponse`、`AnnotationResultResponse` 分别统一列表和详情返回结构。
|
||
16. `sys_config` 改为同公司下 `config_name` 唯一，不再允许不同类型复用同名配置。
|
||
17. `annotation_task` 新增 `industry_type` 字段，默认值 `transport`，用于保存行业类型简写；`source_resource` 去掉 `content_type` 字段。
|
||
|
||
## 15. 开发规范
|
||
|
||
### 15.1 包命名规范
|
||
- 基础包名: `com.{service-name}`
|
||
- 服务名使用小写字母和连字符，如: `user-service`, `order-service`
|
||
|
||
### 15.2 类命名规范
|
||
- 实体类: 使用名词，如 `User`, `Order`
|
||
- 控制器: 以 `Controller` 结尾，如 `UserController`
|
||
- 服务类: 以 `Service` 结尾，如 `UserService`
|
||
- DTO类: 以 `Request`/`Response` 结尾，如 `UserRequest`, `UserResponse`
|
||
- 常量类: 以 `Constants` 结尾，如 `UserConstants`
|
||
|
||
### 15.3 方法命名规范
|
||
- 查询方法: `get`, `find`, `list`, `query`
|
||
- 创建方法: `create`, `add`, `save`
|
||
- 更新方法: `update`, `modify`
|
||
- 删除方法: `delete`, `remove`
|
||
|
||
### 15.4 异常处理规范
|
||
- 使用统一的异常处理机制
|
||
- 自定义业务异常继承 `RuntimeException`
|
||
- 使用 `@ControllerAdvice` 进行全局异常处理
|
||
|
||
### 15.5 日志规范
|
||
- 使用 `@Slf4j` 注解
|
||
- 日志级别: DEBUG(开发), INFO(生产)
|
||
- 关键操作必须记录日志
|
||
|
||
## 16 swagger 接口规范
|
||
### 16.1 接口设计原则：
|
||
- 所有接口和固定结构的注释请使用中文描述性注释，如 `@ApiModelProperty("用户名")`
|
||
- 如果接口返回的是稳定字段集合，应使用明确 DTO 或明确对象字段注解。
|
||
- 所有公开接口都能展示清晰的路径参数、查询参数、请求头参数、表单参数说明
|
||
### 16.2 swagger规范
|
||
- 所有接口、固定机构注释和说明统一使用中文
|
||
- 所有固定结构的请求体都使用 DTO 建模，并为每个字段提供名称、类型、必填性和含义说明
|
||
- 如果业务内部结果本身仍是动态 JSON，则至少提供一个固定外层 DTO，把最外层字段含义说明清楚，避免 Swagger 展示匿名 `Map`。
|
||
- 所有固定结构的主要响应对象都能展示字段说明
|
||
- 所有分页与统一返回包装的字段含义清晰可见
|
||
|
||
这份设计文档应作为后续一期实现、SQL 调整和接口落地的基准版本。
|