# 制造业算法开发与模型管理平台 V1.0 研发需求

> 文档定位：把 V1.0 产品规则转化为可设计、可实现、可测试的研发约束。本文件不替代详细接口设计、数据库设计和部署方案，但它规定这些设计必须满足的业务行为。
>
> 阅读建议：研发启动先读第 1-6 节建立范围、对象、数据、权限、文件和异步任务共识；再按负责的业务域阅读第 7-14 节；第 15-20 节用于审计、错误、非功能和交付检查。业务全景见 [00-V1.0快速阅读指南](00-V1.0快速阅读指南.md)。

## 1. 研发范围

### 1.1 必须实现的业务域

- 身份、用户、一级模块权限和审计。
- 数据集、模板、接入批次、待处理快照、质量任务、冻结版本和切片。
- 模型资产、算法包草稿与冻结版本、平台训练权重和外部权重。
- 训练实验、资源申请、训练任务、日志指标、结果确认和产物。
- 评测规则、评测任务、独立性检查、技术评测、报告和结论。
- 冒烟任务、发布申请、发布审批、下载发布。
- 单实例 API 的资源申请、部署、健康、服务生命周期、授权、API Key 和调用记录。
- 模型广场的已发布数据查询、下载和 API 使用入口。

### 1.2 禁止实现为 V1.0 默认依赖的能力

- 工作台和统一待办。
- 平台内算法开发或数据标注。
- 资源节点、资源池、资源管理员、人工资源审批与人工分配。
- 多节点、NPU、多实例、灰度、蓝绿和自动回滚。
- 训练暂停恢复、断点恢复和自动重试。
- 业务效果确认、模型反馈、漂移和自动重训练。

## 2. 领域边界

### 2.1 建议服务边界

| 领域 | 负责对象 | 不负责 |
|---|---|---|
| 身份与权限 | 用户、角色、会话、一级模块权限 | 业务对象状态判断 |
| 文件服务 | 上传会话、受控文件、校验和、下载授权 | 决定文件能否用于训练或发布 |
| 数据管理 | 数据集、模板、接入批次、数据快照、质量、版本、切片 | 模型训练执行 |
| 模型资产 | 模型、算法包版本、权重版本、文件依赖、来源链 | 生成技术评测结论 |
| 任务执行 | 训练、评测、冒烟、部署等异步任务的提交和状态 | 业务准入决策 |
| 资源适配 | 标准规格、自动审批记录、执行资源关联与就绪状态 | 节点管理和人工审批 |
| 模型评测 | 规则快照、独立性检查、技术任务、报告、结论 | 发布审批 |
| 发布管理 | 发布准入、申请、审批、发布记录 | 修改权重和评测报告 |
| 在线服务 | 部署、健康、服务、授权、凭证、调用 | 维护模型广场副本 |
| 模型广场 | 查询已发布投影、使用入口 | 创建模型或改变发布状态 |
| 审计 | 关键操作记录和查询 | 替代业务运行日志 |

领域可以在一个应用中模块化实现，也可以拆分服务，但数据所有权和状态决策必须保持上述边界。

### 2.2 一致性原则

- 同一业务对象只有一个权威状态源。
- 模型广场使用发布记录的只读投影，不复制维护模型状态。
- 执行任务状态由执行端或任务服务回写，页面查询不得推断成功。
- 审批记录与发布执行记录分开。
- 资源申请审批状态与执行资源状态分开。
- 业务事务提交和审计写入应具备一致性保障；不能出现业务已成功但关键审计永久缺失。

## 3. 通用数据规范

### 3.1 基础字段

所有正式对象至少包含：

| 字段 | 含义 | 规则 |
|---|---|---|
| `id` | 内部唯一标识 | 服务端生成，不复用 |
| `business_no` | 用户可见业务编号 | 唯一，只用于识别，不承载业务判断 |
| `status` | 当前状态 | 使用受控枚举 |
| `version` | 乐观锁版本 | 更新可变对象时校验 |
| `created_by` | 创建人 | 从当前会话取得 |
| `created_at` | 创建时间 | 服务端时间 |
| `updated_by` | 最近更新人 | 服务端记录 |
| `updated_at` | 最近更新时间 | 每次有效变更更新 |
| `source_id` | 来源对象 | 复制、重试、派生时记录 |
| `request_id` | 请求追踪标识 | 贯穿接口、任务和日志 |

### 3.2 快照字段

任务、评测、冒烟和发布申请应保存下列快照，而不是只保存指向可变对象的引用：

- 业务对象编号和版本。
- 关键配置 JSON。
- 文件标识和内容校验和。
- 规则版本或规则快照。
- 创建人和提交时间。
- 输入对象当时的状态。

快照使用结构化数据保存，禁止仅保存拼接文本。

### 3.3 删除规则

- 没有正式版本和下游引用的草稿可以物理删除或软删除，具体由详细设计确定。
- 正式版本、执行任务、报告、审批、发布、调用和审计记录不得由普通业务操作物理删除。
- 停用和下线是业务状态，不等同于删除。
- 文件删除前必须反向检查引用，检查失败时禁止删除。

## 4. 权限与职责

### 4.1 模块权限

V1.0 权限资源固定为六个一级模块：数据管理、模型训练、模型评测、模型管理、模型广场、系统管理。

- 角色可以关联一个或多个一级模块。
- 用户可以关联一个或多个角色，最终权限取有效角色并集。
- 不实现租户、组织、部门、对象、数据范围和按钮级授权。
- 前端根据权限控制入口；后端对每个接口再次校验。

### 4.2 业务职责校验

模块权限不能替代以下业务规则：

- 只有模型负责人或产品经理职责可以审批发布。
- 服务端按真实账号标识校验职责：普通账号的申请、审批、执行三主体两两不同；有效 Admin 可兼任，但不得绕过账号有效性、准入、冒烟、固定快照和审计。
- 评测工程师不能直接把技术结论转换为发布批准。
- 模型广场用户不能通过接口修改模型管理对象。
- 外部权重登记人不能伪造平台训练来源。

职责可以用用户属性、角色标签或单独职责表实现，详细设计需确保可审计。

### 4.3 会话

- 登录成功后签发受控会话。
- 停用、账号过期、密码重置或安全吊销时，使相关会话失效。
- 会话续期不得超过账号有效期。
- 认证失败日志不得包含密码。

## 5. 文件服务

### 5.1 上传

推荐流程：

1. 客户端申请上传会话。
2. 服务端返回上传标识和限制。
3. 客户端上传文件。
4. 服务端计算校验和并执行基础安全检查。
5. 业务模块使用受控文件标识完成绑定。

文件记录至少包含所有者、业务类型、文件名、大小、媒体类型、校验和、存储位置、扫描状态、引用状态和创建时间。

### 5.2 下载

下载请求必须校验：

- 当前会话和模块权限。
- 文件所属业务对象。
- 业务对象是否允许下载。
- 发布是否有效。
- 文件扫描状态和存储状态。

通过后生成短期下载响应或受控流。不得向前端返回永久存储地址。

### 5.3 媒体上传标识

API 推理媒体上传成功后返回受控文件标识，该标识至少绑定：

- 调用方和授权。
- 目标服务。
- 文件类型和大小。
- 有效截止时间。
- 当前状态。

推理请求使用该标识时重新校验归属、服务、有效期和文件状态。禁止传入本地路径、共享路径或任意 URL。

## 6. 异步任务框架

### 6.1 通用状态

执行型任务的具体状态由业务域声明。训练任务采用第 10.3 节的状态模型：实验草稿和资源申请完成最终检查后才创建任务，任务初始为待资源；不得用本节的通用示意顺序替代业务域状态机。

并非所有任务都使用全部状态。业务模块必须声明适用状态和可用操作。

### 6.2 提交

- 接口接收幂等键。
- 提交事务中固定输入快照并生成任务。
- 相同用户、业务对象和幂等键重复提交时返回原任务。
- 校验失败不得生成看似成功的执行任务。

### 6.3 回写

- 执行端回写必须包含任务编号、阶段、状态、时间和执行端事件编号。
- 重复事件应幂等处理。
- 非法状态跳转拒绝并记录异常。
- 回写成功后更新任务视图和最近更新时间。

### 6.4 失败与重试

- 失败记录错误分类、错误代码、用户可读原因、技术摘要和可重试标志。
- 业务页面不直接展示敏感堆栈。
- 用户重试时生成新任务，复制允许复用的输入，并记录原任务标识。
- V1.0 不提供自动重试。

## 7. 数据管理实现要求

### 7.1 数据集与模板

#### 数据集

- 名称在有效数据集范围内唯一。
- 数据类型创建后不可变。
- 业务分类变化只更新元数据和审计。
- 停用后选择器不返回该数据集，历史详情仍可访问。

#### 模板版本

- 模板版本保存完整结构，不只保存与上一版差异。
- 数据版本引用具体模板版本。
- 已引用模板版本禁止编辑。
- 模板兼容性检查输出字段级或媒体规则级差异。

### 7.2 数据接入

#### V1.0 接入边界

- V1.0 只接收用户从本机选择的文件：结构化 CSV/JSON，或首批外部已标注图片/音频/视频及其 JSON/CSV 标签清单；不实现数据库、SQL、REST API、MQTT、消息队列、文本粘贴、外部采集任务、定时采集或持续同步。
- 数据接入页面不得出现连接管理、凭证、连接测试、采集频率或外部数据源状态。远程数据源相关 FR 仅保留历史编号并标记为后续版本。
- 模型服务 API、应用授权、API Key、在线调用和调用日志属于模型服务域，不属于本节所排除的数据接入能力。

#### 文件受理与分片

- 上传前校验目标数据集状态、文件数量、单文件大小、批次总量、扩展名、可读性和空文件；单文件不超过 2GB，单批次不超过 20GB 或 10,000 个文件。
- 文件不超过 10MB 时可直接上传；超过 10MB 时按 16MB 分片上传并记录分片号、摘要、进度、失败原因和续传位置。
- 分片接口按批次、文件摘要和分片号幂等；重复上传已成功分片返回原结果，不重复保存。完成合并前校验分片数量、顺序和摘要。
- 浏览器不得为字段识别完整读取大文件，只读取文件头、前 2MB 且最多 200 条样本。原始文件由受控文件服务保存，页面和审计日志不展示服务器路径。
- 保存草稿只保存批次配置和已受理文件引用；用户尚未提交或本地文件尚未受理时，不得伪造文件已保存。

#### 批次

提交前校验：

- 目标数据集有效。
- 数据类型与数据集一致。
- 单批次数据类型唯一。
- 本地文件已上传完整且摘要校验通过。
- 操作人具备数据管理权限。

批次处理顺序：

1. 创建草稿并选择本地文件。
2. 完成文件校验及直传或分片上传。
3. 抽样识别字段、基础类型和样例值。
4. 用户选择纳入模板的字段，确认字段类型、必填性和用途；至少包含一个主键或主文件字段。
5. 固定模板快照后，后台读取完整文件并执行全量解析。
6. 按确认的模板校验全部记录，成功后生成待处理数据快照并进入待质检。

- 批次状态为草稿、上传中、待字段确认、后台解析中、成功、部分成功、失败、空批次或模板阻断。
- 上传状态、字段确认状态、后台解析状态、模板校验结论和质量结论分别保存，不得用一个“处理中”字段覆盖。
- 抽样字段识别只用于辅助确认模板，不代表文件解析完成、模板校验通过或数据可供质检。
- 后台解析未完成、全量记录数与摘要未生成或存在模板阻断时，质量检查入口必须禁用并返回具体原因。
- 文件级失败形成部分成功时，须保存成功文件、失败文件和原因；用户只能复制批次修正后重新提交，不得用部分结果生成可冻结版本。
- 空文件或全批无有效记录形成空批次；执行结果为成功、部分成功、失败、空批次或模板阻断，终态记录不可覆盖。

#### 后台解析与模板校验

- 后台任务固定批次、文件清单及摘要、模板快照、解析器版本和请求幂等键。
- 解析进度至少包含阶段、已处理文件数、已处理记录数、失败数、最近更新时间和可重试标志。
- 模板校验覆盖字段存在性、字段类型、必填值、时间格式和模板中配置的字段约束；问题定位到文件、记录序号和字段。
- 模板阻断与数据质量阻断是不同结论：前者必须修正文件或字段模板并重新解析，不能进入质量检查；后者在质量任务中处理。
- 后台任务失败、超时或回写中断时保留原任务与已确认进度；确认旧任务不再运行后，复制批次创建新尝试，不覆盖原记录。

### 7.3 待处理数据快照

全量解析和模板校验通过后生成待处理快照，至少包含：

- 来源批次。
- 文件清单、文件摘要和完整记录清单。
- 样本标识。
- 标签或结构摘要。
- 内容指纹。
- 模板快照、解析器版本、解析规则和结果。

快照内容变化时创建新快照，已有质量报告不能继续复用。

### 7.4 质量任务

- 提交时固定待处理快照、模板版本和质量规则快照。
- 执行状态与质量结论使用不同字段。
- 问题记录包含规则、级别、样本、字段或媒体位置、实际值、原因和建议。
- 阻断级问题不能被确认放行。
- 警告确认记录包含原因、确认人和时间。

### 7.5 冻结数据版本

建议在单个事务或可恢复事务流程中完成：

1. 锁定待处理快照。
2. 复核解析、模板校验、质量结论和警告确认。
3. 复算或核对样本清单和数据指纹。
4. 创建数据版本及版本文件引用。
5. 将版本设为已冻结。
6. 写入业务记录和审计。

任一步失败不得留下可被训练选择的半成品版本。

### 7.6 切片

- 保存来源数据版本、算法、参数、随机种子、时间边界、分组键和样本清单。
- 生成后计算集合互斥性。
- 对派生样本保存原始样本标识，独立性检查按原始标识和内容指纹执行。
- 切片只读；重新切分生成新切片。

### 7.7 数据对象关系与最小持久化要求

以下对象是 V1.0 数据链路的最小实现边界。可以按研发架构拆分表或服务，但不能合并为一个可变记录：

| 对象 | 必须关联 | 至少保存 | 状态/结论 |
|---|---|---|---|
| `dataset` | 数据类型、负责人 | 名称、用途、来源、启停状态 | 草稿、启用、停用 |
| `import_batch` | `dataset_id` | 批次说明、类型、版本、提交人、输入摘要 | 草稿、上传中、待字段确认、后台解析中、成功、部分成功、失败、空批次、模板阻断 |
| `file_record` | `batch_id` | `file_id`、名称、大小、扩展名、摘要、分片信息、安全扫描状态 | 受理中、完成、失败、隔离 |
| `field_candidate` | `file_id`、抽样尝试 | 字段名、候选类型、样例、空值率、识别来源 | 待确认、已采用、已排除 |
| `template_snapshot` | `batch_id`、数据类型 | 完整字段结构、类型、必填性、用途、规则、确认人、确认时间、摘要 | 草稿、已确认、已引用、停用 |
| `parse_attempt` | `batch_id`、`template_snapshot_id` | 解析器版本、文件快照、进度、记录数、失败数、结果摘要 | 排队、执行中、成功、部分成功、失败 |
| `pending_snapshot` | `parse_attempt_id`、模板快照 | 完整文件清单、样本清单、内容指纹、解析结果 | 待质检、已引用、失效 |
| `quality_task` | `pending_snapshot_id`、规则快照 | 执行快照、进度、问题统计、报告摘要 | 草稿、执行中、成功、失败；另存质量结论 |
| `data_version` | `pending_snapshot_id`、质量报告 | 版本号、样本清单、文件摘要、指纹、冻结人和时间 | 待冻结、已冻结、停用 |
| `split_task` | `data_version_id` | 方法、比例/边界/分组键、随机种子、集合清单、互斥检查 | 待生成、生成中、已生成、失败 |

所有关联必须支持反向追溯：从训练任务可以找到切分任务、数据版本、质量报告、模板快照、导入批次和文件摘要；从文件或模板也可以找到其下游引用。正式版本和执行快照不得通过更新来源对象而漂移。

### 7.8 切分实现规则

- `time`：要求模板存在可排序时间字段；训练、验证、测试边界必须严格有序且无重叠。允许同一设备跨集合，但原始样本、派生样本和内容指纹必须互斥。
- `ratio`：要求比例总和为100%且随机种子必填；样本级随机切分必须执行内容指纹去重。存在同源键但未选择分组时，至少产生明确泄漏风险警告；按产品规则需阻断的类型不得提交。
- `group`：要求选择已声明的设备、批次、工件或其他同源键；同组样本整体归属一个集合，分配结果与分组统计一起保存。
- 单个切分任务只能使用一种方法。`time` 与 `group` 不得同时配置，`ratio` 不得携带时间边界；旧版历史摘要切分仅可查询，禁止用于新训练。
- 训练选择器只返回已生成且样本清单完整的切片；空切片、互斥检查失败或来源版本已停用时不得选择。

### 7.9 原型边界与真实实现验收

当前原型只完成浏览器本地文件的字段抽样、小文件解析和门禁展示；未实现真实文件服务、分片续传、后台全量解析、全量模板校验、质检执行器或真实算力。研发实现时必须把以下能力作为服务端/执行端交付项：

1. 文件上传会话、分片幂等、断点恢复、合并校验和安全扫描。
2. 字段抽样与全量解析分离，解析任务可恢复、可重试，回调按尝试号和事件号去重。
3. 模板快照确认后才启动全量模板校验；模板阻断不得创建待质检快照。
4. 待处理快照和质量报告固定内容指纹；冻结时重新核对摘要，不一致则阻断。
5. 研发联调完成前，原型中的“成功/可质检/可冻结/可训练”仅属于本地模拟或页面状态，不得作为后端完成证据。

## 8. 模型资产实现要求

### 8.1 模型资产

模型资产是算法包版本和权重版本的聚合根。基本说明可修改，版本对象不可覆盖。

模型创建来源：

- 算法包完整技术校验通过后创建或关联。
- 外部权重候选的文件由文件服务留存并生成完整摘要，完成安全扫描及隔离执行加载、契约校验后，正式登记时创建或关联；仅在浏览器选择文件不得创建正式权重版本或宣称可推理。

评测通过不是模型创建条件。

### 8.2 算法包

算法包草稿状态建议为：

`上传中 → 待基础校验 → 基础校验失败/待补充声明 → 待完整校验 → 完整校验失败/校验通过 → 已冻结`

完整校验成功后：

- 固定包文件校验和。
- 固定运行声明。
- 生成冻结版本。
- 关联模型资产。
- 允许训练选择。

失败时不生成冻结版本。

### 8.3 权重版本

来源类型必须为“平台训练”或“外部导入”。

平台训练来源要求：

- 真实训练任务编号。
- 数据版本和切片。
- 算法包版本。
- 参数与环境快照。
- 权重和依赖文件。

外部导入来源要求：

- 提供者和原始标识。
- 来源说明或证明。
- 权重校验和。
- 推理入口、输入输出、框架、依赖和环境。
- 最小加载样例。

外部导入记录的平台训练任务字段必须为空，不得生成占位编号。

### 8.4 产物完整性

检查结果至少区分：

- 文件存在。
- 校验和一致。
- 格式可识别。
- 依赖完整。
- 入口可解析。
- 运行材料完整。
- 安全扫描状态。

检查通过不等同于评测通过或发布批准。

## 9. 资源适配实现要求

### 9.1 标准规格

标准规格由部署配置或受控配置源提供，至少包含：

- 规格标识和名称。
- CPU 和内存。
- GPU 类型、数量和显存，CPU 规格可为空。
- 支持的运行环境标签。
- 启用状态。

V1.0 不提供产品页面维护规格、节点、库存或资源池。申请页面只读查询可用规格定义。

### 9.2 资源申请状态模型

资源申请至少拆分以下字段：

| 字段 | 示例状态 | 决策来源 |
|---|---|---|
| 申请状态 | 草稿、已提交、提交失败 | 业务系统 |
| 审批状态 | 未审批、系统自动通过 | 业务规则引擎 |
| 执行资源状态 | 未关联、等待、就绪、异常、失效、未知 | 执行端或资源适配层 |

不得用一个“已通过”字段同时表达三类状态。

### 9.3 自动审批

提交时校验：

- 当前用户权限。
- 业务草稿存在、配置修订号一致且状态允许；此时不要求执行任务已经存在。
- 标准规格有效。
- 数量符合单机限制。
- 预计期限和申请原因完整。

校验通过后记录系统自动审批方式、规则版本、时间和申请快照。校验失败不生成通过记录。

资源申请先绑定训练、评测或部署草稿及配置修订号。最终提交时以事务或等价一致性机制创建不可变执行任务并绑定申请；绑定失败不得调度。一个申请只能绑定一个执行任务，重复请求依靠幂等键返回原结果。任务创建后才允许执行端关联实际资源，草稿阶段不预占容量。

### 9.4 就绪检查

训练、评测或部署启动前必须实时检查：

- 运行环境存在且兼容。
- 实际容量满足申请。
- 执行资源已关联到当前业务任务。
- 资源状态为就绪。
- 当前时间未超过允许使用边界。

任何条件未知、异常或不满足都禁止启动，并返回可区分原因。

### 9.5 不实现状态

V1.0 不产生“待人工审批、人工驳回、退回补充、待管理员分配、续期中、释放中”等状态。

资源不足属于执行资源状态，不属于人工审批驳回。

## 10. 训练实现要求

### 10.1 实验与任务

- 实验保存用户意图和可编辑草稿。
- 任务保存一次不可变执行快照。
- 一个实验可以有多个任务版本。
- 调参通过复制任务配置形成新任务，不修改原任务。

### 10.2 提交前检查

检查记录保存每个检查项的名称、结果、原因、影响对象和修复入口。

检查结果在以下变化后失效：

- 算法包、数据版本或切片变化。
- 参数或环境变化。
- 资源申请变化或失效。
- 检查超过产品配置的有效窗口。

### 10.3 状态模型

草稿和待检查属于实验配置，不是执行任务状态。最终检查通过并提交后生成任务，初始状态为待资源。

| 当前状态 | 条件或事件 | 下一状态 |
|---|---|---|
| 待资源 | 资源就绪且启动复核通过 | 排队中 |
| 待资源 | 环境异常或资源失效已确认 | 失败 |
| 排队中 | 执行端接受任务 | 准备中 |
| 排队中 | 尚未被执行端接受且取消成功 | 已取消 |
| 准备中 | 输入与环境加载成功 | 运行中 |
| 准备中 | 加载失败 | 失败 |
| 运行中 | 执行成功并收到完成回执 | 成功 |
| 运行中 | 执行失败或资源失效已确认 | 失败 |
| 运行中 | 停止请求被接受 | 停止中 |
| 停止中 | 执行端确认停止 | 已停止 |

成功、失败、已停止和已取消是执行终态。状态未知保留最后确认状态并单列观测异常，不冒充终态；并发取消与启动必须由服务端原子裁决。资源等待30分钟先撤销启动许可并请求取消，已启动则转停止确认；训练/评测/部署执行满24小时请求停止，被接受后停止中，10分钟未确认只标观测未知。提交关联重试前须确认旧尝试未启动或已终止、无存活执行且底层占用收尾已确认；可提前复制编辑草稿，但不得提前提交执行。迟到回调按旧尝试审计，不恢复启动。停止与完成竞态以执行端真实先后事实裁决。上述是执行端收尾，不新增资源释放产品流程。

允许跳转：

- 排队中可取消为已取消。
- 运行中可请求停止，执行端确认后进入已停止。
- 失败、已停止和已取消只能复制新任务，不能回到运行中。

### 10.4 日志和指标

- 日志按任务、时间和序号追加，不允许前端覆盖。
- 查询支持游标或分页，避免一次加载全部日志。
- 指标记录名称、步数或轮次、值和时间。
- 曲线接口按时间或步数增量查询。
- 敏感环境变量和凭证必须脱敏。

### 10.5 结果

训练任务分别记录：

- 执行结论。
- 产物完整性状态。
- 用户确认状态。
- 产物保留状态。
- 权重登记状态。

不得将这些状态合并为单一“完成”。

## 11. 评测实现要求

### 11.1 独立性检查

检查输入：

- 权重来源训练任务。
- 训练任务实际样本清单。
- 测试数据版本或切片样本清单。
- 原始样本标识、内容指纹和派生关系。

检查输出：

- 检查范围。
- 重叠数量和比例。
- 泄漏分类。
- 问题样本定位信息。
- 通过或阻断。

外部权重没有平台训练清单时，使用外部来源材料进行可提供范围内的检查，并明确证据范围。不得自动生成“零重叠”结论。

### 11.2 规则快照

规则至少包含指标、计算口径、方向、阈值、适用任务和报告有效期。评测任务必须保存完整快照。

### 11.3 任务和报告

- 指标评测、样例评测、稳定性评测可以是子任务，但统一关联同一评测任务。
- 子任务执行失败与指标不达标分别记录。
- 报告只在必需子任务完成后生成。
- 报告包含输入版本、规则、环境、资源和原始结果摘要。
- 报告生成后只读；重新评测生成新报告。

### 11.4 技术结论

- 结论只能为通过或不通过，不使用“审批通过”措辞。
- 结论生成逻辑以规则快照为准。
- 无法计算必需指标时不得判定为通过。
- 结论不直接改变发布状态。

## 12. 冒烟与发布实现要求

### 12.1 冒烟任务

输入固定权重版本、发布方式、运行产物摘要、环境和样例，形成候选快照。冒烟在发布申请前的临时受限环境执行，不依赖已批准申请；API冒烟健康探测只针对临时环境，不使用正式服务上线健康结果。申请引用同一候选内容和冒烟证据，正式部署仍须在审批通过后执行。

下载型至少验证：

- 包可解压且文件安全。
- 依赖和入口可解析。
- 权重可加载。
- 最小推理成功。

API 型至少验证：

- 运行包或镜像可启动。
- 健康检查通过。
- 输入输出契约正确。
- 最小推理成功。

冒烟文件摘要变化后，原结果不得用于发布。

### 12.2 发布准入

准入服务应按同一权重版本聚合：

- 冻结和完整性状态。
- 技术评测报告及有效性。
- 独立性结果。
- 冒烟结果。
- 模型说明和使用材料。
- 发布方式和产物摘要。

输出每项通过、警告或阻断。V1.0 中影响安全、权重一致性、评测或冒烟的项目必须为阻断。

### 12.3 发布申请状态

申请审批状态与发布执行状态分开：申请为“草稿 → 待审批 → 已通过或已拒绝”；执行为“已通过申请 → 发布执行中 → 已发布或发布失败”。

规则：

- 评测或冒烟未通过时不能提交进入待审批。
- 提交后快照只读。
- 申请人不能审批。
- 拒绝必须有原因，拒绝为本申请终态。
- 审批通过后才能执行发布。
- 执行失败不把审批状态改为拒绝。
- 修改权重、方式或摘要必须创建新申请。

### 12.4 下载发布

- 执行前校验申请状态、审批、快照和文件状态。
- 生成发布记录和受控下载资产。
- 模型广场投影只在发布成功后可见。
- 下线关闭投影和新增下载权限，保留历史。

## 13. 在线服务实现要求

### 13.1 部署状态

部署执行为“待资源 → 待部署 → 部署中 → 部署成功或部署失败”。仅部署成功后才创建健康检查记录；健康检查状态独立记录为检查中、健康、不健康或未知。部署失败不能进入健康检查，重试生成新执行记录。

部署状态与服务发布状态分开。部署尚未启动且取消已确认时为已取消；部署中停止被接受时为停止中，执行端确认后已停止；超时和未知按08号矩阵处理，重试必须先确认旧执行及底层占用已收尾。成功部署的实例停止属于服务生命周期，不反向改写已成功部署任务。

### 13.2 服务状态

`未发布 → 已发布 → 已停止 → 已发布`为可恢复路径；`已下线`为业务终态。

- 服务发布前复核发布审批、权重、评测、冒烟、部署、健康和资源。
- 停止后拒绝新调用。
- 恢复前重新检查资源和健康。
- 下线关闭入口并停止实例，保留调用和生命周期记录。
- V1.0 不触发资源释放流程。

### 13.3 同步与异步 REST JSON

接口设计必须包含：

- 认证头。
- 请求编号或幂等标识的适用规则。
- 输入参数类型、必填和限制。
- 媒体文件标识字段。
- 成功响应结构。
- 参数错误、认证失败、授权过期、范围不匹配、运行保护触发、文件无权、文件过期、服务停止、推理失败和超时受理响应。

同步处理达到 30 秒上限时，网关返回可查询的请求标识和“已受理/处理中”状态，后台继续原请求；调用方通过查询接口获取状态和结果，不重复提交。视频、较大媒体或预计超过 30 秒的处理直接使用异步接口。

同步和异步请求都必须支持幂等键。同一调用方在有效窗口内重复提交同一幂等键时，返回同一请求标识、处理中状态或原结果，不创建重复执行记录。

### 13.4 授权与 API Key

#### 申请与审批

- 应用接入申请保存申请编号、申请人、应用、负责人、工厂、产线/设备、服务及模型版本、用途、期限、提交时间、状态和状态版本。
- 模型运营人员或 Admin 只能处理待审批申请；拒绝原因必填。
- 审批请求绑定申请编号、申请快照摘要和状态版本；重复请求返回首次结果，并发通过与拒绝只允许首个合法决定生效。
- 通过结论和授权创建必须使用同一一致性边界；失败时不得留下已通过但无授权的申请。
- 拒绝不创建授权或 Key；申请人可按数据范围查看本人申请、结果和拒绝原因。

#### 数据存储

- 授权记录保存来源申请、应用、负责人、工厂、产线/设备、服务及模型版本、用途、生效日、到期日、运行保护、累计调用统计、审批人、审批时间和状态。
- Key 保存唯一标识、不可逆摘要、掩码尾部、创建时间、最后使用时间和状态。
- 不保存可还原的 Key 明文。

#### 创建

审批通过只创建有效授权，不自动生成 Key。模型运营人员或 Admin 对有效授权另行发起签发；服务端重新校验授权期限、服务发布与健康状态后生成随机 Key，明文仅在响应中返回一次。响应被关闭后不能再次查询明文。

#### 重生成

在单个一致性操作中：

1. 生成新 Key。
2. 使旧 Key 失效。
3. 保留授权期限、运行保护配置和累计调用统计。
4. 写入审计。
5. 返回一次新 Key 明文。

#### 鉴权

每次调用依次校验服务、应用授权范围、Key、期限、运行保护和媒体文件归属。失败不调用模型执行端，但仍生成带拒绝原因的调用日志。

### 13.5 调用记录

记录调用方、服务、权重版本、时间、结果、耗时、错误类别、请求编号和资源摘要。原始敏感输入和输出按安全策略脱敏或不落库。

## 14. 模型广场投影

- 发布成功后生成或更新当前发布投影。
- 投影引用模型资产和发布记录，不复制为另一套可编辑模型。
- 同一模型可分别存在下载和 API 使用方式。
- 下线事件使对应使用方式不可用。
- 列表与详情不得展示未发布、发布失败或审批通过但尚未发布的记录。
- 评测事实必须来自当前发布权重绑定的报告。

## 15. 审计事件

至少记录以下事件：

- 登录成功、失败、登出、锁定和解锁。
- 用户创建、编辑、启停和密码重置。
- 角色和模块权限变更。
- 数据导入、警告确认、版本冻结、基线和切分。
- 算法包校验和冻结、权重登记和文件下载。
- 训练、评测、冒烟和部署的提交、取消、停止和重试。
- 技术结论生成。
- 发布申请、审批、执行、失败和下线。
- API 授权、Key 创建、启停、重生成和吊销。
- 模型广场下载、API 调用和日志导出。

审计接口不提供编辑和单条删除。

## 16. 错误模型

业务接口应返回稳定错误类别：

| 类别 | 场景 | 前端处理 |
|---|---|---|
| 参数错误 | 必填、格式、范围不合法 | 定位字段并保留输入 |
| 未认证 | 会话无效 | 引导重新登录 |
| 无权限 | 无模块或业务职责 | 展示无权限，不伪装对象不存在 |
| 状态冲突 | 对象状态已变化 | 刷新对象并说明当前状态 |
| 版本冲突 | 乐观锁失败 | 展示他人已更新，禁止覆盖 |
| 业务阻断 | 评测、冒烟、独立性或资源不满足 | 展示检查项和修复路径 |
| 重复提交 | 幂等命中 | 返回原业务结果 |
| 执行失败 | 后台任务失败 | 展示阶段、原因和可重试性 |
| 依赖不可用 | 存储、执行端或资源状态不可得 | 展示未知或稍后重试 |
| 系统异常 | 未预期错误 | 展示请求编号，记录完整技术日志 |

## 17. 非功能验收

### 17.1 安全

- 密码使用强哈希保存。
- API Key 仅保存不可逆摘要。
- 密码、API Key 和模型服务令牌按各自用途加密或单向安全存储；V1.0 不实现远程数据源连接凭证存储。
- 文件传输使用安全协议。
- 上传包执行路径、压缩和恶意内容检查。
- 算法包、权重和推理在隔离环境执行。

### 17.2 可靠性

- 任务状态和快照持久化。
- 后台回写具备幂等处理。
- 页面刷新后状态可恢复。
- 依赖不可用时不伪造成功。
- 关键业务操作具有防重和一致性保障。

### 17.3 性能

V1.0先按以下产品下限设计和验收；部署基准测试用于确认目标环境是否满足，不得用测试结果在验收时临时降低门槛：

- 常规列表在约定基准数据量下P95不高于2秒；复杂审计查询P95不高于5秒。
- 普通写操作P95不高于2秒；异步任务在2秒内返回请求或任务标识。
- 执行端事件成功接收后5秒内可查询，超过配置窗口进入延迟或未知状态。
- 生产月度可用性目标不低于99.5%；业务元数据RPO不高于15分钟、RTO不高于4小时。
- 列表、详情和复杂审计查询分别提供数据量、并发、P50/P95/P99和错误率基准。
- 大文件上传和断点策略说明。
- 日志分页和指标增量查询基准。
- 训练、评测和部署状态回写延迟基准。
- 同步与异步推理在支持格式、大小和时长范围内的响应、吞吐与积压基准。

R5 已确认的30秒同步等待、100MB请求、5分钟视频以及CFG-04至CFG-06并发属于产品边界；实测用于验证环境能否满足该边界，并确定依赖首批规模的QPS、吞吐和容量，不得静默改写正式规则。首批规模未登记时，性能项只能标记“待容量基线”，不能标记通过。

### 17.4 可观测性

- 每个请求、异步任务和执行端事件可通过请求编号关联。
- 关键依赖调用记录耗时、结果和错误类别。
- 资源状态未知、任务回写中断和发布投影失败应产生运维告警。
- 运维告警不等同于面向业务用户的待办中心。

## 18. 研发环境验证项

## 18.1 V1.0默认实现参数

研发按 `02-功能需求.md` 第 12.1 节实现：单文件 2GB、批次 20GB/10,000 文件、解压 50GB；四类单机资源规格；单用户运行 2/排队 5、平台运行 8；资源等待 30 分钟、回调 5 分钟、任务 24 小时、停止确认 10 分钟；API 单请求 100MB、视频 5 分钟、同步 30 秒后返回可查询请求标识；应用授权支持1至3650天、1至120个月或1至10年，并配置每分钟速率和并发保护，不设置默认商业月度额度；报告有效 90 天；Key 有效 90 天且不得超过所属授权有效期；认证失败 5 次锁定 10 分钟；无操作 30 分钟退出；日志在线查询 180 天、默认近 90 天；容量告警 70%/85%/95%。

这些数值是 V1.0 的可执行默认配置。研发不得继续以“待确认”作为接口缺省行为；如现场不能满足，必须提交配置变更并补充边界测试。

以下项目不改变产品规则，但必须在对应研发活动开始前完成真实环境验证：

1. 首批算法任务、图片、音频、视频及标注格式支持矩阵和样例。
2. 算法包、权重、下载运行包的封装方式与真实可运行验收样例。
3. 安全扫描引擎、文件和解压上限、隔离区和失败处置。
4. 标准 CPU/GPU 规格来源、执行资源关联接口和就绪状态协议。
5. 资源等待、未知、失效和执行超时的状态转换。
6. 同步/异步推理格式、大小、时长、文件标识有效期、超时查询、幂等执行和成功统计。
7. 登录锁定、日志留存、容量告警和归档参数。
8. 发布职责在账号、角色或职责表中的具体实现方式。

每项确认应形成可定位的设计决策、负责人、日期和验证样例，不能只在聊天中确认。

## 19. 交付追踪

每个实现项必须关联产品追踪键、接口契约、数据对象、状态迁移、权限动作、日志事件和验收用例。缺少任一关联不得进入完成状态。资源适配接口至少定义规格编码、申请编号、配置修订号、申请结果、执行资源标识、就绪状态、原因、占用期限、释放事件和关联任务。

## 20. 定稿前强制规则

1. 跨模块引用同时校验发起模块权限和被引用对象只读权限，禁止因引用继承写入、下载或导出权限。
2. 数据版本由用户明确选择成功批次组成；部分成功等终态批次只读，不得原地补传、质检或冻结。复制关联新批次并重新选择本次拟纳入的全部文件（包括原成功文件和修正后的失败文件），提交成功后方可选择；不得将原部分成功批次的成功文件直接拼入新批次快照。合并成功批次时按样本标识和文件指纹去重，冲突阻断。仅未终结的上传中断可在原批次续传。
3. 待资源可取消；等待超时撤销启动许可并请求取消，未确认时保留执行态并标记观测超时/未知。取消或停止仅在执行端确认后进入已取消或已停止，重跑须核实旧执行及其底层占用已收尾。
4. 外部权重独立性结果区分通过、重叠/泄漏和证据不足，证据不足默认阻断正式评测和发布。
5. 下载校验区分模型广场发布产物与内部报告、日志、附件，不能统一要求发布有效。
6. 证据过期阻断新增下载、调用授权和服务恢复，并重新执行对应检查和发布准入。
7. API 运行保护定义每分钟速率、并发、输入大小、视频时长和同步等待规则；保护阈值按现场容量配置，不采用商业额度扣减。
8. 每次进入网关的调用均生成调用日志；鉴权失败、参数错误、限流、平台 5xx 和平台超时不计入成功统计；同步成功或异步成功完成后原子写入成功统计，同一请求只允许生成一次统计记录。

## 21. 训练配置分阶段实现要求

训练配置页面和服务端保存接口必须支持以下五阶段字段，不得只保存页面上的四个固定训练参数：

1. **训练方式**：`training_mode`、`task_type`、实验名称和说明。`projectTrain` 与 `fineTune` 的父模型规则必须在服务端复核。
2. **模型与数据**：项目版本、代码包版本、算法框架、数据版本、切分任务、训练/验证切片、模板快照、标签字段、基础模型和父版本。
3. **预处理与参数**：`preprocess_profile`、`normalization`、`window_size`、`window_stride`、`parameter_preset`，以及算法包 `paramSchema` 声明的核心/扩展参数。
4. **评估与输出**：`eval_metric`、`eval_frequency`、`selection_strategy`、`early_stopping`、`output_model_version`、算法包声明的 `output_dir`。
5. **资源与检查**：运行环境、标准规格、申请原因及逐项检查结果。

算法包的 `paramSchema` 是参数来源，至少声明名称、展示标签、类型、是否必填、默认值、范围或枚举和说明。前端根据声明渲染输入控件，服务端在保存草稿和创建任务时再次校验，不能由页面自行放宽范围。参数哈希必须覆盖核心参数和扩展参数。

平台只负责记录和校验预处理配置，具体归一化、窗口生成、评估和检查点保存由算法包执行。任务快照必须保存完整配置，研发不得只保存页面摘要；历史草稿缺少新增字段时按 V1.0 默认值兼容读取，但新建和修改草稿必须补齐完整字段。