From 0891ae188de5abff91bac5fa1334f45108d2017f Mon Sep 17 00:00:00 2001 From: wh Date: Thu, 9 Apr 2026 12:11:10 +0800 Subject: [PATCH] =?UTF-8?q?feat(spec):=20=E6=96=B0=E5=A2=9E=20label=5Fback?= =?UTF-8?q?end=20=E9=9C=80=E6=B1=82=E8=A7=84=E6=A0=BC=E8=AF=B4=E6=98=8E?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 包含 8 个用户故事、35 条功能性需求、9 条可度量成功标准 涵盖认证、多租户隔离、双标注流水线、并发任务领取、异步视频处理等核心场景 --- .../checklists/requirements.md | 34 +++ specs/001-label-backend-spec/spec.md | 273 ++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 specs/001-label-backend-spec/checklists/requirements.md create mode 100644 specs/001-label-backend-spec/spec.md diff --git a/specs/001-label-backend-spec/checklists/requirements.md b/specs/001-label-backend-spec/checklists/requirements.md new file mode 100644 index 0000000..407b074 --- /dev/null +++ b/specs/001-label-backend-spec/checklists/requirements.md @@ -0,0 +1,34 @@ +# 规格质量检查清单：label_backend 知识图谱智能标注平台 + +**用途**: 在进入规划阶段前验证规格说明的完整性和质量 +**创建日期**: 2026-04-09 +**功能**: [查看规格说明](../spec.md) + +## 内容质量 + +- [x] 无实现细节（无编程语言、框架、API 引用） +- [x] 聚焦用户价值和业务需求 +- [x] 面向非技术干系人编写 +- [x] 所有必填章节均已完成 + +## 需求完整性 + +- [x] 无 [NEEDS CLARIFICATION] 标记残留 +- [x] 需求可测试且无歧义 +- [x] 成功标准可度量 +- [x] 成功标准与技术无关（无实现细节） +- [x] 所有验收场景均已定义 +- [x] 已识别边界情况 +- [x] 范围边界清晰 +- [x] 已识别依赖和假设 + +## 功能就绪性 + +- [x] 所有功能性需求均有明确验收标准 +- [x] 用户场景覆盖主流程（认证、上传、标注、审批、导出） +- [x] 功能满足成功标准中定义的可度量结果 +- [x] 无实现细节渗入规格说明 + +## 备注 + +所有检查项均通过。规格说明已就绪，可进行 `/speckit.plan` 规划阶段。 diff --git a/specs/001-label-backend-spec/spec.md b/specs/001-label-backend-spec/spec.md new file mode 100644 index 0000000..da30290 --- /dev/null +++ b/specs/001-label-backend-spec/spec.md @@ -0,0 +1,273 @@ +# 功能规格说明：label_backend 知识图谱智能标注平台 + +**功能分支**: `001-label-backend-spec` +**创建日期**: 2026-04-09 +**状态**: 草稿 +**输入**: 根据文档 docs/superpowers/specs/2026-04-09-label-backend-design.md 生成需求规格文档 + +--- + +## 用户场景与测试 *(必填)* + +### 用户故事 1 - 用户登录与身份认证 (优先级: P1) + +公司员工使用用户名和密码登录平台，获取会话凭证后访问受权限保护的功能。会话在持续活跃时保持有效，用户主动退出或管理员禁用账号后会话立即失效。 + +**优先级理由**: 认证是所有其他功能的前提，无法登录则所有功能均不可用。 + +**独立测试**: 可独立通过以下方式测试：用正确凭证登录，携带返回凭证请求受保护接口，验证正常访问；携带错误凭证或过期凭证，验证被拒绝。 + +**验收场景**: + +1. **给定** 用户持有效用户名和密码，**当** 提交登录请求，**则** 系统返回会话凭证，且该凭证可用于后续请求 +2. **给定** 用户已登录并持有效凭证，**当** 发起正常业务请求，**则** 会话有效期自动延长 +3. **给定** 用户主动退出登录，**当** 使用旧凭证访问任意受保护接口，**则** 系统立即拒绝，返回未授权响应 +4. **给定** 管理员禁用某用户账号，**当** 被禁用用户使用现有凭证访问接口，**则** 系统立即拒绝，不设任何宽限期 +5. **给定** 用户使用错误密码，**当** 提交登录请求，**则** 系统返回认证失败，不泄露用户是否存在 + +--- + +### 用户故事 2 - 原始资料上传 (优先级: P1) + +上传员将文本文件、图片或视频上传至平台，系统存储文件并记录元数据，视频文件额外触发异步预处理流程（帧提取或转文字）。 + +**优先级理由**: 资料上传是整条标注流水线的起点，没有资料则无法产生任何标注任务。 + +**独立测试**: 可独立测试：上传一个文本文件或图片，验证系统成功接收并记录；上传视频，验证系统创建预处理任务并开始异步处理。 + +**验收场景**: + +1. **给定** 上传员已登录，**当** 上传一个文本文件，**则** 系统保存文件并创建资料记录，状态为"待提取" +2. **给定** 上传员已登录，**当** 上传一张图片，**则** 系统保存图片并创建资料记录，状态为"待提取" +3. **给定** 上传员已登录，**当** 上传一个视频文件，**则** 系统保存视频，创建预处理任务，资料状态变为"预处理中" +4. **给定** 视频预处理成功完成，**当** AI 服务回调成功，**则** 每帧（帧模式）或每段转译文本（片段模式）均作为独立资料进入标注队列，原视频状态变为"已完成" +5. **给定** 视频预处理因 AI 服务故障失败且已达最大重试次数，**当** 回调失败，**则** 任务标记为失败，管理员可查阅错误信息并手动重新触发 + +--- + +### 用户故事 3 - 提取阶段标注（EXTRACTION） (优先级: P1) + +标注员从任务池中领取一个提取任务，借助 AI 辅助预标注对文本资料完成三元组标注或对图片资料完成四元组标注，提交后由审批员审核。 + +**优先级理由**: 提取阶段是双流水线的第一个生产阶段，直接产出结构化知识。 + +**独立测试**: 可独立测试：标注员领取任务，修改 AI 预标注结果，提交后验证任务进入"待审批"状态；同一任务被多人同时尝试领取，验证只有一人成功。 + +**验收场景**: + +1. **给定** 存在未被领取的提取任务，**当** 标注员请求领取，**则** 任务归属到该标注员，状态变为"进行中" +2. **给定** 同一任务被 10 名标注员同时争抢，**当** 所有人同时发起领取请求，**则** 恰好一名标注员领取成功，其余人收到"任务已被他人领取"响应 +3. **给定** 标注员已领取任务，**当** 请求 AI 辅助预标注，**则** 系统调用 AI 服务返回结构化候选结果（不直接提交，供人工编辑） +4. **给定** 标注员完成人工编辑，**当** 提交标注结果，**则** 任务状态变为"已提交"，进入审批队列 +5. **给定** 标注员领取任务后决定放弃，**当** 放弃任务，**则** 任务回到任务池，可被其他标注员重新领取 + +--- + +### 用户故事 4 - 提取阶段审批 (优先级: P1) + +审批员查看提交的提取标注结果，选择通过或驳回。审批通过后系统自动创建问答生成任务；驳回时需填写驳回原因，标注员可重新领取该任务修改后再次提交。 + +**优先级理由**: 审批控制标注质量，是推进流水线到下一阶段的门控节点。 + +**独立测试**: 可独立测试：审批通过一个提取任务，验证系统自动创建 QA 生成任务；驳回一个任务，验证标注员可重领并修改。 + +**验收场景**: + +1. **给定** 审批员进入待审批队列，**当** 查看列表，**则** 只看到状态为"已提交"的任务 +2. **给定** 审批员查看某提取任务的标注结果，**当** 点击通过，**则** 标注结果标记为最终版，系统自动创建对应的问答生成任务并置于任务池中 +3. **给定** 审批员本人提交了某提取任务，**当** 该审批员尝试审批自己提交的任务，**则** 系统拒绝，提示不允许自审 +4. **给定** 审批员认为标注结果不合格，**当** 附带驳回原因并驳回，**则** 任务状态变为"已驳回"，标注员可在我的任务列表中看到该任务及原因 +5. **给定** 标注员查看被驳回的任务，**当** 重新领取并修改后提交，**则** 任务重新进入审批队列 + +--- + +### 用户故事 5 - 问答生成阶段标注与审批（QA_GENERATION） (优先级: P2) + +标注员领取问答生成任务，在 AI 候选问答对基础上完成人工编辑，提交后由审批员审批。审批通过即写入训练样本库；驳回则退回标注员修改。 + +**优先级理由**: QA 阶段是流水线的最后生产阶段，直接决定训练样本质量。 + +**独立测试**: 可独立测试：领取 QA 任务，修改候选问答对并提交；审批员通过后，验证训练样本库中出现对应记录。 + +**验收场景**: + +1. **给定** 存在由提取阶段审批通过自动创建的问答生成任务，**当** 标注员进入任务池，**则** 可以看到并领取该任务 +2. **给定** 标注员已领取问答生成任务，**当** 整体提交修改后的问答对列表，**则** 任务进入审批队列（每次提交均为完整列表替换，不允许部分追加） +3. **给定** 审批员通过问答生成任务，**当** 审批完成，**则** 对应训练样本状态变为"已审批"，整条资料流水线标记为完成 +4. **给定** 审批员驳回问答生成任务，**当** 驳回完成，**则** 候选问答对记录被清除，标注员可重领任务重新生成 + +--- + +### 用户故事 6 - 训练数据导出与微调提交 (优先级: P2) + +管理员从已审批的训练样本中选择一批次，导出为 GLM 微调格式的 JSONL 文件，并可选择一键提交至 GLM 微调服务。 + +**优先级理由**: 导出是将标注成果转化为 AI 训练价值的最终步骤。 + +**独立测试**: 可独立测试：选择若干已审批样本创建导出批次，验证生成 JSONL 文件；将批次提交微调服务，验证可查询到微调任务状态。 + +**验收场景**: + +1. **给定** 管理员查看样本库，**当** 筛选已审批样本，**则** 只返回状态为"已审批"的样本（分页，不可无界查询） +2. **给定** 管理员选择若干已审批样本，**当** 创建导出批次，**则** 系统生成 JSONL 文件并存储，返回批次标识；若任意样本不处于已审批状态则整批失败 +3. **给定** 导出批次已创建，**当** 管理员提交微调任务，**则** 系统向 AI 服务发起微调请求，记录微调任务标识，状态变为"进行中" +4. **给定** 微调任务已提交，**当** 管理员查询状态，**则** 返回最新的微调进度信息 + +--- + +### 用户故事 7 - 用户与权限管理 (优先级: P2) + +管理员管理本公司用户，包括创建用户、分配角色、启用/禁用账号。角色变更和账号禁用在保存后立即生效，无延迟窗口。 + +**优先级理由**: 人员和权限管理是平台运营的基础管控能力。 + +**独立测试**: 可独立测试：创建一个标注员角色用户，验证该用户可以领取任务但无法执行审批；将其角色升为审批员，立即验证可以审批；禁用该用户，验证其现有会话立即失效。 + +**验收场景**: + +1. **给定** 管理员创建一个新用户并分配角色，**当** 新用户登录，**则** 该用户拥有该角色对应的权限（高级角色自动包含低级角色权限） +2. **给定** 管理员将用户角色从标注员升为审批员，**当** 角色变更保存后，**则** 该用户无需重新登录即可使用审批功能 +3. **给定** 管理员禁用某用户账号，**当** 被禁用用户下次发起请求，**则** 系统立即返回拒绝响应，不设过渡期 +4. **给定** 管理员查询用户列表，**当** 获取结果，**则** 仅返回本公司用户，不可看到其他公司用户数据 + +--- + +### 用户故事 8 - 系统配置管理 (优先级: P3) + +管理员维护 AI Prompt 模板、模型参数、Token 有效期等系统配置项，支持公司级配置覆盖全局默认值。 + +**优先级理由**: 配置管理是运营支撑能力，可在系统运行后按需调整，不影响核心标注流程。 + +**独立测试**: 可独立测试：修改某公司的 Prompt 模板配置，验证该公司后续标注使用新模板，其他公司仍使用全局默认值。 + +**验收场景**: + +1. **给定** 管理员查看配置列表，**当** 获取结果，**则** 同时展示本公司专属配置和全局默认配置，公司专属配置对同一 Key 优先 +2. **给定** 管理员更新某配置项，**当** 保存成功，**则** 后续相关操作立即使用新配置值 +3. **给定** 某配置项仅有全局默认值无公司级覆盖，**当** 系统查询该配置，**则** 返回全局默认值 + +--- + +### 边界情况 + +- 标注员领取任务后长时间未操作——管理员可强制转移任务给其他标注员（状态保持"进行中"，持有人变更） +- 视频预处理回调因网络抖动发生重复投递——系统对同一任务的重复成功回调静默忽略，不重复创建标注任务 +- 某租户上传量极大时的无界查询——所有列表接口强制分页，无法绕过分页限制获取全量数据 +- 审批员同时兼任标注员角色时尝试自审——系统按提交者身份校验，自审请求被拒绝 +- 跨公司数据访问尝试——每次数据查询自动注入当前用户所属公司标识，无法通过参数篡改访问其他公司数据 +- 操作日志写入失败——审计写入失败不影响业务操作，仅记录错误并触发告警 +- 同一账号在多设备登录——每次登录生成独立会话凭证，互不影响；退出某设备仅使该设备凭证失效 + +--- + +## 需求说明 *(必填)* + +### 功能性需求 + +**认证与会话** + +- **FR-001**: 系统必须支持基于用户名和密码的登录认证，验证通过后返回会话凭证 +- **FR-002**: 系统必须在每次有效请求时自动延长会话有效期（滑动过期） +- **FR-003**: 系统必须支持主动退出登录，退出后凭证立即失效 +- **FR-004**: 系统必须在管理员禁用账号后立即使该账号所有有效凭证失效，不设任何宽限期 +- **FR-005**: 系统必须拒绝无凭证或过期凭证的请求，返回未授权响应 + +**访问控制** + +- **FR-006**: 系统必须实现四级角色体系：上传员 ⊂ 标注员 ⊂ 审批员 ⊂ 管理员，高级角色自动继承低级角色权限 +- **FR-007**: 系统必须在接口层声明每个接口所需的最低角色，角色不足时拒绝访问 +- **FR-008**: 系统必须在角色变更保存后立即生效，无需等待会话自然过期 + +**多租户数据隔离** + +- **FR-009**: 系统必须保证每个公司的数据完全隔离，任何查询均只返回当前用户所属公司的数据 +- **FR-010**: 系统必须禁止调用方通过请求参数指定公司标识来访问其他公司数据；公司标识必须从服务端会话中获取 +- **FR-011**: 全局系统配置对所有公司可见，公司级配置对同一配置项优先覆盖全局值 + +**资料管理** + +- **FR-012**: 系统必须支持文本、图片、视频三种原始资料的上传，文件内容存储至对象存储服务，数据库只保存元数据和存储路径 +- **FR-013**: 视频上传后必须触发异步预处理任务，不阻塞上传响应 +- **FR-014**: 系统必须支持视频帧提取模式（每帧作为独立图片进入图片标注流水线）和视频片段转文本模式（派生文本资料进入文本标注流水线） +- **FR-015**: 视频片段转文本产生的派生资料必须记录对原始视频资料的引用，可追溯来源 + +**任务管理** + +- **FR-016**: 系统必须支持并发安全的任务领取机制，确保同一任务不会被两名标注员同时持有 +- **FR-017**: 系统必须支持任务放弃（退回任务池）和管理员强制转移任务归属 +- **FR-018**: 每次任务状态变更必须记录历史快照（含操作人、操作时间、驳回原因等），不可修改或删除历史记录 +- **FR-019**: 所有任务列表接口必须强制分页，不允许无界查询 + +**提取阶段标注工作台** + +- **FR-020**: 系统必须调用 AI 服务生成候选提取结果供标注员参考编辑，不直接写入最终结果 +- **FR-021**: 标注员提交的提取结果以整体替换方式存储，禁止局部追加修改 +- **FR-022**: 审批员审批通过时，系统必须在同一操作中将提取结果标记为最终版并自动创建问答生成任务，该级联操作不得由前端发起独立请求触发 +- **FR-023**: 系统必须拒绝提交者本人审批或驳回自己提交的任务（禁止自审） +- **FR-024**: 审批驳回时，标注员必须可以看到被驳回任务及驳回原因，并可重新领取修改后再次提交 + +**问答生成阶段** + +- **FR-025**: 问答生成任务的标注结果采用整体替换，每次提交包含完整问答对列表 +- **FR-026**: 问答生成阶段审批通过时，对应训练样本必须写入训练样本库，资料状态标记为"已完成" +- **FR-027**: 问答生成阶段审批驳回时，候选问答对记录必须被清除，标注员可重领任务重新生成 + +**训练数据导出** + +- **FR-028**: 系统必须支持将已审批的训练样本批量导出为 GLM 微调格式，每条样本一行 +- **FR-029**: 导出时若任意选定样本不处于已审批状态，整批导出请求必须失败 +- **FR-030**: 系统必须支持将导出批次提交至外部 AI 微调服务，并可追踪微调任务进度 + +**审计日志** + +- **FR-031**: 系统必须对所有状态变更操作自动记录审计日志，包含操作人姓名快照、操作类型、结果、IP 地址等信息 +- **FR-032**: 审计日志只追加不修改，禁止对审计记录执行更新或删除 +- **FR-033**: 审计日志写入失败不得导致业务操作失败或回滚 + +**视频异步处理** + +- **FR-034**: 视频预处理任务必须支持自动重试，达到最大重试次数后置为失败状态，需管理员手动重新触发 +- **FR-035**: AI 服务对同一视频处理任务的重复成功回调必须被幂等处理，不得重复创建标注任务 + +### 核心实体 + +- **公司（Company）**: 多租户根节点，每个公司拥有独立的用户、资料和任务数据空间 +- **用户（User）**: 属于某公司，拥有角色（上传员/标注员/审批员/管理员），通过会话凭证访问系统 +- **原始资料（SourceData）**: 待标注的文件（文本/图片/视频），拥有状态流转（待处理→提取中→QA审核中→已完成）；视频派生资料通过父资料引用保留溯源链 +- **标注任务（AnnotationTask）**: 标注工作单元，分提取阶段和问答生成阶段，拥有领取、提交、审批、驳回完整生命周期 +- **标注结果（AnnotationResult）**: 提取阶段的结构化输出（三元组或四元组），以整体 JSON 存储 +- **训练样本（TrainingDataset）**: 经审批的问答对，GLM 微调格式，待导出 +- **导出批次（ExportBatch）**: 一批训练样本的导出记录，关联外部微调任务标识 +- **视频处理任务（VideoProcessJob）**: 视频预处理的异步任务跟踪，包含重试计数和最终输出路径 +- **系统配置（SysConfig）**: 配置键值对，分全局默认和公司级两层，公司级优先 + +--- + +## 成功标准 *(必填)* + +### 可度量结果 + +- **SC-001**: 同一标注任务被多人同时争抢时，有且仅有一人领取成功，其余人立即收到明确的"已被领取"响应，成功率 100%，无数据竞争导致的双重持有 +- **SC-002**: 管理员禁用账号或变更角色后，该账号的权限变更在下一次请求时立即生效（延迟小于 1 秒） +- **SC-003**: 提取阶段审批通过时，问答生成任务在同一次操作中自动出现在任务池，无需任何人工干预步骤 +- **SC-004**: 视频预处理回调的重复投递（同一任务多次成功回调）不产生重复标注任务，幂等处理成功率 100% +- **SC-005**: 跨公司数据访问尝试 100% 被系统拒绝，无任何数据泄露至非所属租户 +- **SC-006**: 审计日志对所有状态变更操作的覆盖率达到 100%，审计写入失败不影响业务成功率 +- **SC-007**: 所有列表接口在数据量增长时保持稳定响应，用户无法绕过分页限制一次性获取不受限制数量的记录 +- **SC-008**: 标注员完成一次任务领取→标注→提交的完整操作流程（不含 AI 辅助预标注等待时间）可在 5 分钟内完成 +- **SC-009**: 从资料上传到训练样本进入样本库的完整流水线（含两次人工标注和两次审批）中，每个节点的操作人、时间、结果均可查询追溯 + +--- + +## 假设与前提 + +- 系统服务于多个公司，每家公司的用户、资料和标注数据完全独立，不存在跨公司协作场景 +- 每位用户在同一时刻只属于一家公司，不存在用户跨公司兼职的场景 +- 视频预处理（帧提取、转文字）由外部 AI 服务异步完成，后端只负责触发和回调处理 +- 微调结果的质量评估不在本平台范围内，平台只负责提交微调任务并查询状态 +- 前端应用已独立开发，本规格仅覆盖后端 API 能力 +- 所有文件二进制内容存储在兼容 S3 协议的对象存储服务中，不存入关系型数据库 +- 生产环境使用容器化部署，后端服务、数据库、缓存、对象存储均为独立容器 +- AI 服务通过 HTTP 提供结构化的提取和问答生成能力，后端不内嵌 AI 模型 +- 标注流水线中一条资料同一时间只有一个活跃的提取任务或问答生成任务，不支持并行多版本标注 +- 审计日志的长期归档（超过月分区范围）由数据库运维团队负责，不在本系统范围内