label_backend/docs/swagger-blackbox-test-cases.md

label-backend Swagger 接口黑盒测试用例

1. 文档说明

• 生成时间：2026-04-14
• 适用项目：label-backend
• 覆盖范围：当前 controller 中已开放的全部 Swagger/OpenAPI 接口
• 生成依据：
  • src/main/java/com/label/controller/**/*.java
  • src/main/java/com/label/service/**/*.java
  • src/main/resources/sql/init.sql
  • src/test/java/com/label/integration/**/*.java
• 说明：
  • 当前会话内未能直接访问 http://127.0.0.1:8080/v3/api-docs，本文档按代码、设计和现有集成测试反推生成。
  • 文中“预期结果”以黑盒测试应验证的业务契约为主；若当前实现存在契约空洞，用例应保留，用于发现缺陷。

2. 测试前提

2.1 基础环境

• Base URL：http://127.0.0.1:8080
• OpenAPI：GET /v3/api-docs
• Swagger UI：GET /swagger-ui.html
• 默认返回体：{ "code": "...", "message": "...", "data": ... }

2.2 认证前提

• 若要执行认证、鉴权、越权、Token 失效类用例，建议运行时配置 auth.enabled=true。
• 若当前运行环境仍为 auth.enabled=false 的 mock 模式，则以下用例中所有 401/403 校验需要在真实认证模式下执行。

2.3 种子数据建议

基于 src/main/resources/sql/init.sql，至少准备以下账号：

公司	用户名	密码	角色
DEMO	admin	admin123	ADMIN
DEMO	reviewer01	review123	REVIEWER
DEMO	annotator01	annot123	ANNOTATOR
DEMO	uploader01	upload123	UPLOADER

额外建议准备：

• 第二家公司 TESTB
• TESTB 下至少 1 个 ADMIN 账号
• DEMO、TESTB 各自的资料、任务、配置、导出批次、视频任务样本

2.4 通用 Header

• JSON 接口：Content-Type: application/json
• 文件上传：multipart/form-data
• 受保护接口：Authorization: Bearer <token>
• 视频回调启用密钥时：X-Callback-Secret: <VIDEO_CALLBACK_SECRET>

3. 通用黑盒用例

除 POST /api/auth/login 与 POST /api/video/callback 外，所有受保护接口均应复用以下通用用例。

用例ID	适用范围	场景	操作	预期结果
G-AUTH-001	全部受保护接口	缺少 Token	不传 Authorization	HTTP 401，code=UNAUTHORIZED
G-AUTH-002	全部受保护接口	Token 格式错误	传 Authorization: BearerX xxx 或 Basic xxx	HTTP 401，code=UNAUTHORIZED
G-AUTH-003	全部受保护接口	Token 无效或过期	传不存在/已失效 Token	HTTP 401，code=UNAUTHORIZED
G-ROLE-001	有角色要求的接口	角色不足	用低权限账号访问高权限接口	HTTP 403，code=FORBIDDEN
G-TENANT-001	租户数据相关接口	跨租户访问数据	用 TESTB Token 访问 DEMO 数据	返回 404、空列表或业务拒绝；不能读到 DEMO 数据
G-PAGE-001	分页接口	大页码限制	传超大 pageSize	返回成功，pageSize 被限制到系统上限，不出现异常
G-ERR-001	全部接口	非法请求不能打穿到 5xx	传缺参/错参/非法状态	返回可解释的 4xx 或失败业务码，不应无意义 500

4. 认证管理

4.1 POST /api/auth/login

用例ID	场景	请求	预期结果
AUTH-LOGIN-001	正常登录	{"companyCode":"DEMO","username":"admin","password":"admin123"}	HTTP 200，code=SUCCESS，返回 token/userId/username/role/expiresIn
AUTH-LOGIN-002	密码错误	password=wrong	HTTP 401，code=USER_NOT_FOUND
AUTH-LOGIN-003	公司代码不存在	companyCode=NO_SUCH	HTTP 401，code=USER_NOT_FOUND
AUTH-LOGIN-004	账号被禁用	先将用户禁用，再登录	HTTP 403，code=USER_DISABLED
AUTH-LOGIN-005	缺少必填字段	缺 companyCode、username 或 password	返回失败，不能生成有效 Token，不应出现无提示 500

4.2 POST /api/auth/logout

用例ID	场景	操作	预期结果
AUTH-LOGOUT-001	正常退出	用有效 Token 调用退出	HTTP 200，code=SUCCESS
AUTH-LOGOUT-002	退出后 Token 立即失效	退出后继续访问 /api/auth/me	HTTP 401，code=UNAUTHORIZED
AUTH-LOGOUT-003	无 Token 退出	复用 G-AUTH-001	HTTP 401

4.3 GET /api/auth/me

用例ID	场景	操作	预期结果
AUTH-ME-001	查询当前用户信息	用 admin Token 调用	HTTP 200，返回 id/username/realName/role/companyId/companyName
AUTH-ME-002	已退出 Token 查询自己	先登录再退出，再调 /me	HTTP 401，code=UNAUTHORIZED
AUTH-ME-003	被禁用账号的旧 Token 查询自己	先登录，管理员禁用该用户，再调 /me	HTTP 401，code=UNAUTHORIZED

5. 公司管理

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001。

5.1 GET /api/companies

用例ID	场景	请求	预期结果
COMPANY-LIST-001	管理员分页查询公司	?page=1&pageSize=20	HTTP 200，返回分页结构
COMPANY-LIST-002	按状态筛选	?status=ACTIVE	仅返回对应状态公司
COMPANY-LIST-003	非管理员访问	用 REVIEWER 或 UPLOADER 调用	HTTP 403，code=FORBIDDEN

5.2 POST /api/companies

用例ID	场景	请求	预期结果
COMPANY-CREATE-001	创建公司成功	{"companyName":"测试公司B","companyCode":"TESTB"}	HTTP 201，创建成功，状态默认 ACTIVE
COMPANY-CREATE-002	公司代码重复	使用已存在 companyCode	HTTP 409，code=DUPLICATE_COMPANY_CODE
COMPANY-CREATE-003	公司名称重复	使用已存在 companyName	HTTP 409，code=DUPLICATE_COMPANY_NAME
COMPANY-CREATE-004	公司名为空	companyName 空或空白	HTTP 400，code=INVALID_COMPANY_FIELD
COMPANY-CREATE-005	公司代码为空	companyCode 空或空白	HTTP 400，code=INVALID_COMPANY_FIELD

5.3 PUT /api/companies/{id}

用例ID	场景	请求	预期结果
COMPANY-UPDATE-001	更新公司成功	修改 companyName/companyCode	HTTP 200，字段更新成功
COMPANY-UPDATE-002	更新不存在公司	id 不存在	HTTP 404，code=NOT_FOUND
COMPANY-UPDATE-003	更新为重复代码	companyCode 改成已存在值	HTTP 409，code=DUPLICATE_COMPANY_CODE
COMPANY-UPDATE-004	更新为重复名称	companyName 改成已存在值	HTTP 409，code=DUPLICATE_COMPANY_NAME

5.4 PUT /api/companies/{id}/status

用例ID	场景	请求	预期结果
COMPANY-STATUS-001	禁用公司成功	{"status":"DISABLED"}	HTTP 200，公司状态变为 DISABLED
COMPANY-STATUS-002	恢复公司成功	{"status":"ACTIVE"}	HTTP 200，公司状态变为 ACTIVE
COMPANY-STATUS-003	非法状态值	{"status":"UNKNOWN"}	HTTP 400，code=INVALID_COMPANY_STATUS
COMPANY-STATUS-004	公司不存在	不存在 id	HTTP 404，code=NOT_FOUND

5.5 DELETE /api/companies/{id}

用例ID	场景	操作	预期结果
COMPANY-DELETE-001	删除空公司成功	删除无用户的公司	HTTP 200，删除成功
COMPANY-DELETE-002	公司下仍有用户	删除已有用户公司	HTTP 409，code=COMPANY_HAS_USERS
COMPANY-DELETE-003	删除不存在公司	不存在 id	HTTP 404，code=NOT_FOUND

6. 用户管理

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

6.1 GET /api/users

用例ID	场景	请求	预期结果
USER-LIST-001	管理员查看本公司用户	?page=1&pageSize=20	HTTP 200，仅返回当前公司用户
USER-LIST-002	跨租户隔离	用 TESTB 管理员查看列表	不出现 DEMO 用户
USER-LIST-003	非管理员访问	用 REVIEWER 调用	HTTP 403

6.2 POST /api/users

用例ID	场景	请求	预期结果
USER-CREATE-001	创建用户成功	{"username":"qa01","password":"qa123456","realName":"测试员","role":"ANNOTATOR"}	HTTP 200，创建成功，状态默认为 ACTIVE
USER-CREATE-002	用户名重复	同公司创建同名用户	HTTP 409，code=DUPLICATE_USERNAME
USER-CREATE-003	角色非法	role=VIEWER 或其他未支持角色	HTTP 400，code=INVALID_ROLE
USER-CREATE-004	跨租户污染校验	TESTB 管理员创建用户后，DEMO 不可见	创建成功且仅属于当前公司

6.3 PUT /api/users/{id}

用例ID	场景	请求	预期结果
USER-UPDATE-001	更新真实姓名成功	{"realName":"新名字"}	HTTP 200，真实姓名更新
USER-UPDATE-002	更新密码成功	{"password":"newpass123"}，再重新登录	新密码可登录，旧密码失效
USER-UPDATE-003	更新不存在用户	不存在 id	HTTP 404，code=NOT_FOUND
USER-UPDATE-004	更新他租户用户	用 TESTB 管理员修改 DEMO 用户	HTTP 404 或不可见

6.4 PUT /api/users/{id}/status

用例ID	场景	请求	预期结果
USER-STATUS-001	禁用用户成功	{"status":"DISABLED"}	HTTP 200，用户状态更新成功
USER-STATUS-002	禁用后旧 Token 失效	禁用后用该用户旧 Token 调 /api/auth/me	HTTP 401，code=UNAUTHORIZED
USER-STATUS-003	恢复用户成功	{"status":"ACTIVE"}	HTTP 200
USER-STATUS-004	非法状态值	{"status":"LOCKED"}	HTTP 400，code=INVALID_STATUS

6.5 PUT /api/users/{id}/role

用例ID	场景	请求	预期结果
USER-ROLE-001	修改角色成功	{"role":"REVIEWER"}	HTTP 200，用户角色更新成功
USER-ROLE-002	角色变更立即生效	同一 Token 变更前访问 reviewer 接口 403，变更后重试	变更后无需重新登录即可访问成功
USER-ROLE-003	非法角色值	{"role":"VIEWER"}	HTTP 400，code=INVALID_ROLE
USER-ROLE-004	修改不存在用户	不存在 id	HTTP 404，code=NOT_FOUND

7. 资料管理

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

7.1 POST /api/source/upload

用例ID	场景	请求	预期结果
SOURCE-UPLOAD-001	上传文本资料成功	multipart/form-data，传 file + dataType=TEXT	HTTP 201，返回资料 id/fileName/dataType/status
SOURCE-UPLOAD-002	上传图片资料成功	dataType=IMAGE	HTTP 201
SOURCE-UPLOAD-003	上传视频资料成功	dataType=VIDEO	HTTP 201
SOURCE-UPLOAD-004	空文件上传	文件为空	HTTP 400，code=FILE_EMPTY
SOURCE-UPLOAD-005	不支持的资料类型	dataType=PDF	HTTP 400，code=INVALID_TYPE
SOURCE-UPLOAD-006	Swagger 文案兼容性检查	dataType=text 小写	应与文档约定一致；若失败需修正文档或实现
SOURCE-UPLOAD-007	低权限无权上传	用无上传权限账号访问	HTTP 403

7.2 GET /api/source/list

用例ID	场景	请求	预期结果
SOURCE-LIST-001	上传员查看自己资料	用 uploader01 调用	仅返回自己上传的数据
SOURCE-LIST-002	管理员查看公司全部资料	用 admin 调用	返回公司内全部资料
SOURCE-LIST-003	按类型筛选	?dataType=TEXT	仅返回对应类型
SOURCE-LIST-004	按状态筛选	?status=PENDING	仅返回对应状态
SOURCE-LIST-005	跨租户隔离	TESTB 调用	看不到 DEMO 数据

7.3 GET /api/source/{id}

用例ID	场景	操作	预期结果
SOURCE-DETAIL-001	查看资料详情成功	查询本公司资料	HTTP 200，返回详情及下载地址
SOURCE-DETAIL-002	查询不存在资料	id 不存在	HTTP 404，code=NOT_FOUND
SOURCE-DETAIL-003	跨租户查看详情	用 TESTB Token 查 DEMO 资料	HTTP 404 或不可见

7.4 DELETE /api/source/{id}

用例ID	场景	操作	预期结果
SOURCE-DELETE-001	删除 PENDING 资料成功	删除未进入流水线资料	HTTP 200
SOURCE-DELETE-002	删除不存在资料	id 不存在	HTTP 404，code=NOT_FOUND
SOURCE-DELETE-003	删除已进入流水线资料	状态为 PREPROCESSING/EXTRACTING/QA_REVIEW/APPROVED	HTTP 409，code=SOURCE_IN_PIPELINE
SOURCE-DELETE-004	非管理员删除	用 UPLOADER 删除资料	HTTP 403

8. 任务管理

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

8.1 GET /api/tasks/pool

用例ID	场景	请求	预期结果
TASK-POOL-001	标注员查看任务池	用 ANNOTATOR 调用	仅返回 EXTRACTION + UNCLAIMED 任务
TASK-POOL-002	Reviewer/Admin 调用任务池	用 REVIEWER 或 ADMIN 调用	返回 SUBMITTED 待审任务
TASK-POOL-003	跨租户隔离	TESTB 调用	仅能看到本公司任务

8.2 GET /api/tasks/mine

用例ID	场景	请求	预期结果
TASK-MINE-001	查询我的任务成功	?page=1&pageSize=20	返回当前用户的 IN_PROGRESS/SUBMITTED/REJECTED 任务
TASK-MINE-002	按状态过滤	?status=REJECTED	仅返回对应状态
TASK-MINE-003	未领取任务不应出现在 mine	准备 UNCLAIMED 任务	列表中不出现该任务

8.3 GET /api/tasks/pending-review

用例ID	场景	请求	预期结果
TASK-REVIEW-001	Reviewer 查询待审批任务	?taskType=EXTRACTION	仅返回 SUBMITTED 且符合类型的任务
TASK-REVIEW-002	非 Reviewer 访问	用 ANNOTATOR 调用	HTTP 403
TASK-REVIEW-003	跨租户隔离	TESTB 调用	看不到 DEMO 待审任务

8.4 GET /api/tasks

用例ID	场景	请求	预期结果
TASK-LIST-001	管理员查询全部任务	?status=SUBMITTED&taskType=QA_GENERATION	返回过滤后的本公司任务
TASK-LIST-002	非管理员访问	用 REVIEWER 调用	HTTP 403

8.5 POST /api/tasks

用例ID	场景	请求	预期结果
TASK-CREATE-001	创建提取任务成功	{"sourceId":<id>,"taskType":"EXTRACTION"}	HTTP 200，返回新任务，状态 UNCLAIMED
TASK-CREATE-002	创建 QA 任务成功	{"sourceId":<id>,"taskType":"QA_GENERATION"}	HTTP 200
TASK-CREATE-003	缺少 sourceId	仅传 taskType	应返回明确失败，不应出现裸 500
TASK-CREATE-004	缺少 taskType	仅传 sourceId	应返回明确失败，不应出现裸 500

8.6 GET /api/tasks/{id}

用例ID	场景	操作	预期结果
TASK-DETAIL-001	查询任务详情成功	查询本公司任务	HTTP 200，返回任务详情
TASK-DETAIL-002	查询不存在任务	不存在 id	HTTP 404，code=NOT_FOUND
TASK-DETAIL-003	跨租户查看任务	用 TESTB 查询 DEMO 任务	HTTP 404 或不可见

8.7 POST /api/tasks/{id}/claim

用例ID	场景	操作	预期结果
TASK-CLAIM-001	正常领取未领取任务	ANNOTATOR 领取 UNCLAIMED 任务	HTTP 200，任务状态变为 IN_PROGRESS
TASK-CLAIM-002	并发抢任务	10 并发领取同一任务	恰好 1 个成功，其余 HTTP 409，code=TASK_CLAIMED
TASK-CLAIM-003	重复领取已被占用任务	第二个用户再领取	HTTP 409，code=TASK_CLAIMED

8.8 POST /api/tasks/{id}/unclaim

用例ID	场景	操作	预期结果
TASK-UNCLAIM-001	放弃进行中任务成功	当前领取人放弃 IN_PROGRESS 任务	HTTP 200，状态回到 UNCLAIMED
TASK-UNCLAIM-002	非法状态放弃	对 SUBMITTED/REJECTED/APPROVED 任务调用	HTTP 409，code=INVALID_STATE_TRANSITION
TASK-UNCLAIM-003	非领取人放弃他人任务	用别的标注员调用	应被拒绝，不能让他人释放任务

8.9 POST /api/tasks/{id}/reclaim

用例ID	场景	操作	预期结果
TASK-RECLAIM-001	原领取人重领被驳回任务	原领取人对 REJECTED 任务调用	HTTP 200，状态变为 IN_PROGRESS
TASK-RECLAIM-002	非原领取人重领	其他用户调用	HTTP 403，code=FORBIDDEN
TASK-RECLAIM-003	非驳回状态重领	对 IN_PROGRESS 任务调用	HTTP 409，code=INVALID_STATE_TRANSITION

8.10 PUT /api/tasks/{id}/reassign

用例ID	场景	请求	预期结果
TASK-REASSIGN-001	管理员强制指派成功	{"userId":<targetUserId>}	HTTP 200，任务归属变更到目标用户
TASK-REASSIGN-002	指派不存在任务	不存在 id	HTTP 404，code=NOT_FOUND
TASK-REASSIGN-003	缺少 userId	空请求体或缺字段	应返回明确失败，不应裸 500
TASK-REASSIGN-004	指派后状态一致性	指派后查询任务	任务应处于可执行状态，归属人与时间被更新

9. 提取标注

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

9.1 GET /api/extraction/{taskId}

用例ID	场景	操作	预期结果
EXT-GET-001	获取提取结果成功	查询本公司任务	HTTP 200，返回 taskId/sourceType/sourceFilePath/isFinal/resultJson
EXT-GET-002	查询不存在任务	不存在 taskId	HTTP 404，code=NOT_FOUND
EXT-GET-003	跨租户查询结果	用 TESTB 查询 DEMO 任务	HTTP 404 或不可见

9.2 PUT /api/extraction/{taskId}

用例ID	场景	请求体	预期结果
EXT-PUT-001	更新结果成功	传合法 JSON 字符串	HTTP 200
EXT-PUT-002	非法 JSON	传坏 JSON	HTTP 400，code=INVALID_JSON
EXT-PUT-003	任务不存在	不存在 taskId	HTTP 404，code=NOT_FOUND

9.3 POST /api/extraction/{taskId}/submit

用例ID	场景	操作	预期结果
EXT-SUBMIT-001	提交成功	IN_PROGRESS 任务提交	HTTP 200，任务变为 SUBMITTED
EXT-SUBMIT-002	非法状态提交	UNCLAIMED/REJECTED/APPROVED 时提交	HTTP 409，code=INVALID_STATE_TRANSITION

9.4 POST /api/extraction/{taskId}/approve

用例ID	场景	操作	预期结果
EXT-APPROVE-001	审批通过成功	Reviewer 审批 SUBMITTED 任务	HTTP 200，原任务 APPROVED，isFinal=true
EXT-APPROVE-002	审批通过触发后续链路	审批完成后查数据库/接口	自动创建 QA_GENERATION 任务，source_data.status=QA_REVIEW，创建 training_dataset
EXT-APPROVE-003	自审拦截	提交人与审批人相同	HTTP 403，code=SELF_REVIEW_FORBIDDEN
EXT-APPROVE-004	非法状态审批	未提交任务直接审批	HTTP 409，code=INVALID_STATE_TRANSITION

9.5 POST /api/extraction/{taskId}/reject

用例ID	场景	请求	预期结果
EXT-REJECT-001	驳回成功	{"reason":"实体识别有误"}	HTTP 200，任务变为 REJECTED
EXT-REJECT-002	驳回原因为空	空 body 或空 reason	HTTP 400，code=REASON_REQUIRED
EXT-REJECT-003	自审驳回	提交人与驳回人相同	HTTP 403，code=SELF_REVIEW_FORBIDDEN
EXT-REJECT-004	驳回后可重领重提	驳回后原领取人调 /reclaim 再 /submit	可重领，任务恢复到 SUBMITTED

10. 问答生成

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

10.1 GET /api/qa/{taskId}

用例ID	场景	操作	预期结果
QA-GET-001	获取候选问答对成功	查询本公司 QA 任务	HTTP 200，返回 taskId/sourceType/items
QA-GET-002	查询不存在任务	不存在 taskId	HTTP 404，code=NOT_FOUND
QA-GET-003	跨租户查询	用 TESTB 查询 DEMO 任务	HTTP 404 或不可见

10.2 PUT /api/qa/{taskId}

用例ID	场景	请求体	预期结果
QA-PUT-001	更新候选问答对成功	{"items":[...]}	HTTP 200
QA-PUT-002	非法 JSON	传坏 JSON	HTTP 400，code=INVALID_JSON
QA-PUT-003	缺失 items 字段	传空对象 {}	不应报 5xx；若允许则生成空 conversations

10.3 POST /api/qa/{taskId}/submit

用例ID	场景	操作	预期结果
QA-SUBMIT-001	提交成功	IN_PROGRESS 任务提交	HTTP 200，任务变为 SUBMITTED
QA-SUBMIT-002	非法状态提交	对 UNCLAIMED/REJECTED/APPROVED 任务提交	HTTP 409，code=INVALID_STATE_TRANSITION

10.4 POST /api/qa/{taskId}/approve

用例ID	场景	操作	预期结果
QA-APPROVE-001	QA 审批通过成功	Reviewer 审批 SUBMITTED QA 任务	HTTP 200
QA-APPROVE-002	审批通过完成整条流水线	审批完成后查状态	training_dataset.status=APPROVED，任务 APPROVED，source_data.status=APPROVED
QA-APPROVE-003	自审拦截	提交人与审批人相同	HTTP 403，code=SELF_REVIEW_FORBIDDEN

10.5 POST /api/qa/{taskId}/reject

用例ID	场景	请求	预期结果
QA-REJECT-001	驳回成功	{"reason":"问题描述不准确"}	HTTP 200，任务变为 REJECTED
QA-REJECT-002	驳回原因为空	空 body 或空 reason	HTTP 400，code=REASON_REQUIRED
QA-REJECT-003	驳回后候选数据删除	驳回后检查 training_dataset	候选问答对被删除，source_data 维持 QA_REVIEW
QA-REJECT-004	驳回后可重领重提	原领取人调 /reclaim 再 /submit	可重领，重新提交成功

11. 导出与微调

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

11.1 GET /api/training/samples

用例ID	场景	请求	预期结果
EXPORT-SAMPLE-001	查询已审批样本成功	?page=1&pageSize=20	HTTP 200，返回 APPROVED 样本
EXPORT-SAMPLE-002	仅看未导出样本	?exported=false	只返回 export_batch_id 为空的数据
EXPORT-SAMPLE-003	按样本类型过滤	?sampleType=TEXT	仅返回对应类型
EXPORT-SAMPLE-004	非管理员访问	用 ANNOTATOR 调用	HTTP 403

11.2 POST /api/export/batch

用例ID	场景	请求	预期结果
EXPORT-BATCH-001	创建导出批次成功	{"sampleIds":[<approvedId1>,<approvedId2>]}	HTTP 201，返回批次信息
EXPORT-BATCH-002	样本列表为空	{"sampleIds":[]}	HTTP 400，code=EMPTY_SAMPLES
EXPORT-BATCH-003	包含未审批样本	混入 PENDING_REVIEW/REJECTED 样本	HTTP 400，code=INVALID_SAMPLES
EXPORT-BATCH-004	包含他租户样本	混入其他公司样本 ID	HTTP 400，code=INVALID_SAMPLES
EXPORT-BATCH-005	批次创建后回写样本导出信息	创建成功后查询样本	exportBatchId/exportedAt 已写入

11.3 POST /api/export/{batchId}/finetune

用例ID	场景	操作	预期结果
FINETUNE-TRIGGER-001	首次触发微调成功	对 NOT_STARTED 批次调用	HTTP 200，返回 glmJobId/finetuneStatus=RUNNING
FINETUNE-TRIGGER-002	重复触发微调	对已启动批次再次调用	HTTP 409，code=FINETUNE_ALREADY_STARTED
FINETUNE-TRIGGER-003	触发不存在批次	不存在 batchId	HTTP 404，code=NOT_FOUND

11.4 GET /api/export/{batchId}/status

用例ID	场景	操作	预期结果
FINETUNE-STATUS-001	未启动批次查询状态	glmJobId 为空批次	HTTP 200，返回 NOT_STARTED/progress=0
FINETUNE-STATUS-002	已启动批次查询状态	对已提交微调任务批次调用	HTTP 200，返回 batchId/glmJobId/finetuneStatus/progress/errorMessage
FINETUNE-STATUS-003	跨租户状态隔离	用 TESTB 查 DEMO 批次	HTTP 404 或不可见

11.5 GET /api/export/list

用例ID	场景	请求	预期结果
EXPORT-LIST-001	分页查询导出批次成功	?page=1&pageSize=20	HTTP 200，仅返回当前公司批次
EXPORT-LIST-002	跨租户隔离	TESTB 调用	看不到 DEMO 批次

12. 系统配置

说明：本组接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001。

12.1 GET /api/config

用例ID	场景	操作	预期结果
CONFIG-LIST-001	查询合并配置成功	管理员查询	HTTP 200，返回当前公司可见配置列表
CONFIG-LIST-002	公司配置覆盖全局默认	先写公司专属 model_default，再查询	返回 scope=COMPANY 且值为公司专属值
CONFIG-LIST-003	未配置公司专属时回退全局	清除公司专属后查询	返回 scope=GLOBAL
CONFIG-LIST-004	跨租户隔离	DEMO 配置不影响 TESTB	另一公司仍看到自己的配置或全局默认

12.2 PUT /api/config/{key}

用例ID	场景	请求	预期结果
CONFIG-UPSERT-001	新增公司专属配置成功	{"value":"glm-4-plus","description":"默认模型"}	HTTP 200，创建成功
CONFIG-UPSERT-002	更新同键配置成功	同一个 key 连续两次 PUT	HTTP 200，第二次为更新而不是重复插入
CONFIG-UPSERT-003	未知配置键	PUT /api/config/unknown_key	HTTP 400，code=UNKNOWN_CONFIG_KEY
CONFIG-UPSERT-004	空配置值	{"value":""}	HTTP 400，code=INVALID_CONFIG_VALUE

13. 视频处理

说明：

• POST /api/video/callback 为公开接口，不复用 G-AUTH-001~003
• 其余视频接口复用 G-AUTH-001~003、G-ROLE-001、G-TENANT-001

13.1 POST /api/video/process

用例ID	场景	请求	预期结果
VIDEO-CREATE-001	创建视频处理任务成功	{"sourceId":<videoSourceId>,"jobType":"FRAME_EXTRACT","params":"{\"frameInterval\":30}"}	创建成功，返回 job，资料状态进入 PREPROCESSING
VIDEO-CREATE-002	使用另一种任务类型成功	jobType=VIDEO_TO_TEXT	创建成功
VIDEO-CREATE-003	缺少必要字段	缺 sourceId 或 jobType	返回失败，code=INVALID_PARAMS，且不能创建 job
VIDEO-CREATE-004	非法任务类型	jobType=UNKNOWN	HTTP 400，code=INVALID_JOB_TYPE
VIDEO-CREATE-005	非视频资料创建视频任务	对非 VIDEO 资料调用	应返回明确失败，不应产生错误状态迁移
VIDEO-CREATE-006	跨租户创建视频任务	用 TESTB 处理 DEMO 资料	HTTP 404 或不可见

13.2 GET /api/video/jobs/{jobId}

用例ID	场景	操作	预期结果
VIDEO-GET-001	查询视频任务成功	查询本公司 jobId	HTTP 200，返回任务状态、重试次数、输出路径等
VIDEO-GET-002	查询不存在任务	不存在 jobId	HTTP 404，code=NOT_FOUND
VIDEO-GET-003	跨租户查询	用 TESTB 查 DEMO 任务	HTTP 404 或不可见

13.3 POST /api/video/jobs/{jobId}/reset

用例ID	场景	操作	预期结果
VIDEO-RESET-001	重置失败任务成功	对 FAILED 任务调用	HTTP 200，job 状态变为 PENDING，retryCount=0
VIDEO-RESET-002	非失败任务不允许重置	对 PENDING/RETRYING/SUCCESS 调用	HTTP 400，code=INVALID_TRANSITION
VIDEO-RESET-003	跨租户重置	用 TESTB 调 DEMO 任务	HTTP 404 或不可见

13.4 POST /api/video/callback

用例ID	场景	请求	预期结果
VIDEO-CALLBACK-001	SUCCESS 回调成功	{"jobId":123,"status":"SUCCESS","outputPath":"processed/frames.zip"}	HTTP 200，job 变 SUCCESS，source_data.status=PENDING
VIDEO-CALLBACK-002	SUCCESS 回调幂等	对同一 jobId 连续两次发送相同 SUCCESS 回调	两次都成功，第二次不重复改状态、不重复产出副作用
VIDEO-CALLBACK-003	FAILED 回调触发重试	对未达重试上限 job 发 FAILED	job 变 RETRYING，retryCount+1
VIDEO-CALLBACK-004	超过最大重试次数	retryCount=maxRetries-1 时再发 FAILED	job 变 FAILED，source_data.status=PENDING
VIDEO-CALLBACK-005	回调 job 不存在	jobId 不存在	接口不应打穿服务；应安全返回，无脏数据写入
VIDEO-CALLBACK-006	启用共享密钥时密钥错误	不传或传错 X-Callback-Secret	返回失败，code=UNAUTHORIZED
VIDEO-CALLBACK-007	回调缺少 jobId/status	缺关键字段	返回明确失败，不应裸 500

14. 推荐执行顺序

建议按以下顺序执行，能更快定位问题来源：

1. 认证管理
2. 公司管理
3. 用户管理
4. 资料管理
5. 任务管理
6. 提取标注
7. 问答生成
8. 导出与微调
9. 系统配置
10. 视频处理

15. 高风险回归点

每次版本回归至少覆盖以下高风险用例：

优先级	用例ID	说明
P0	AUTH-LOGIN-001	登录主链路
P0	AUTH-LOGOUT-002	退出后 Token 立即失效
P0	USER-STATUS-002	禁用账号后旧 Token 失效
P0	SOURCE-DELETE-003	资料进入流水线后不可删除
P0	TASK-CLAIM-002	并发抢任务只允许一个成功
P0	EXT-APPROVE-002	提取审批通过自动推进 QA 链路
P0	QA-APPROVE-002	QA 审批通过完成整条流水线
P0	EXPORT-BATCH-003	非 APPROVED 样本不可导出
P0	CONFIG-LIST-004	配置跨租户隔离
P0	VIDEO-CALLBACK-002	视频回调幂等

16. 后续落地建议

本文档适合作为三类产物的源：

• Swagger 手工测试清单
• Postman/Apifox/Newman 自动化用例集
• src/test/java/com/label/blackbox 下的 API 黑盒自动化测试

若需要继续落地，建议优先把以下用例自动化：

• 认证与 Token 生命周期
• 任务领取并发
• 提取/问答审批状态流转
• 导出样本校验
• 视频回调幂等与重试