Files
moyi-model-intelligence-hub/docs/31-media-result-delivery-boundary.md
T
xpp aee5fe10b4
Repository verification / backend (push) Canceled after 0s
Repository verification / frontend (push) Canceled after 0s
test:"增加隔离Docker环境并记录功能验收结果"
2026-10-28 14:17:04 +08:00

62 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 媒体结果交付边界与验收准备
状态:本地实现与回归;真实供应商生成/播放和规格驱动验收未完成。
负责人:Codex。更新时间:2026-10-28(Asia/Shanghai)。
关联任务:MED-01、MED-03;MED-04/05 保持未完成。
同日后续:用户随后要求本地 Docker 启动与测试,七项已审只读规格已获准并实际通过;并发仍因缺少执行器未执行。下文保留本提交时的准备记录,后续结果以 [32 号记录](32-local-docker-acceptance-and-concurrency.md) 为准,不改变真实供应商生成/播放尚未验收的结论。
## 本轮接手基线
接手时工作区干净,HEAD 为 `bb3baed`;上一轮媒体实现已在 `2e53b1d` 提交。本轮不重复提交旧改动。保留后续公平排队、长请求续租,以及暂缓 COD-01/02、不存储对话、不拆分管理员权限的已记录决定。原 `moyi` 半小时自动化已取消,不重新创建。
## 已复现的问题
1. 前端读取 `b64_json` 但缺少 MIME/format 时没有可播放/展示的 data URL。新增回归使用 PNG/JPEG 文件头,原实现返回 undefined。
2. 纯 `data:audio/...` 链接未参与媒体类型推断;无额外类型元数据时没有音频播放器地址。
3. URL 校验允许 userinfo,且 data URL 接受 SVG。后者不是产品所需的栅格媒体结果,不应作为主动文档打开。
4. 即时图片结果复制上游第一项的任意字段;与轮询白名单不一致。上游附加的 revised_prompt、错误细节或凭据字段可能随任务保存/回传。
5. “有返回字段”不等于“有这个任务的主文件”:无效 URL、只有尾帧、错误媒体类型仍可能被看作已交付。原无结果标记仅覆盖轮询的音频/视频,图片、3D、即时结果和历史前端状态不一致。
前三项已先运行前端失败回归(8 项中 3 项失败、5 项通过),随后修复;不是用户现场故障的根因认定。当前尚缺其具体渠道、型号、任务 ID 或脱敏错误。
## 模块与行为
- `provider.media.MediaAssetNormalizer`:纯字段边界,不调用 HTTP、不读取密钥、不改路由或账务。只接收媒体 URL/Base64、格式/MIME、预览和用量/credits 白名单;拒绝带凭据、错误 scheme、控制字符、SVG data 文档,以及已知类型不匹配的主文件。嵌套引用有深度上限;Base64 有大小和字符边界。
- `task.AsyncTaskResponseNormalizer`:只处理任务状态、进度与有界信封;信封深度最多 4,列表最多查看前 16 项,向共享媒体模块委托。不沿任意属性搜文件或向外取内容。保持原有外层用量优先级,避免无意改变已有计费选择。
- `AsyncProviderClient`:即时兼容图片结果与轮询共用规范化,支持已知 `data` 对象/列表,不再把任意上游字段带入成品记录。Base64 缺格式只对可识别的 PNG/JPEG/GIF 签名推断,不把所有未知内容默认成 PNG。
- `AsyncTaskService`:即时及轮询的所有媒体类型在成功但没有有效主文件时返回 `deliveryStatus=pending` / `TASK_RESULT_UNAVAILABLE`。沿用生成终态及现有结算:不再次生成、不因交付缺失自动退款,重复观测不重复扣费。任务用量仍可单独参与原有结算。
- 前端 `services/media.ts`:类型、签名 URL、data URL、Base64 与显式媒体字段一致处理;已声明任务类型只有一个通用主媒体通道,预览不算主文件。`hasPrimaryMedia` 供详情与完成通知共用,历史成功任务也不会凭空声称文件可下载。
这里的有效性是结构/引用校验,不是对远端可达性、文件完整性、编解码器或浏览器实际播放的证明。没有到 CDN 抓取每份成品,也没有新增鉴权下载猜测路径、供应商参数或价格。本轮尝试按 OpenAI Docs 获取官方媒体文档,站点返回 403;不据此声称核实了当前官方协议,亦不使用未经核实的默认格式或成品接口。
## 验证记录
- Java 21 + Maven 3.9.9 的媒体定向测试:49 项,0 失败/错误/跳过。
- 首轮 `mvn -B -o clean verify`:430 项,0 失败/错误/跳过;包含独立 PostgreSQL 15.18 和 Redis 7 的数据库/账务回归。后端基线原有 409 项,本轮增加 21 项。
- 最终补充已知 URL 后缀/任务类型交叉检查后,再次运行 `mvn -B -o clean verify`:**430 项,0 失败/错误/跳过**,2026-10-28 13:43:34(Asia/Shanghai)结束,用时 4 分 29 秒,BUILD SUCCESS。
- `npm --prefix prototype run build`:Vue 类型检查和 Vite 生产构建通过;`npm --prefix prototype test`:31 项,0 失败/跳过。
- 无效媒体四类型数据库测试、即时错类型测试证明:生成成功保持终态,费用只结算一次、预留归零,无重新提交;保留历史结算失败恢复、未知受理不退款、用户隔离等回归。
测试容器均使用本轮 `codex.task=moyi-media-20261028` 标签;PostgreSQL 无网络、无宿主端口,使用临时内存数据目录;Redis/Maven 只共享该网络命名空间。不连接现有 MOYI 业务数据库、不重启本机已有实例。日志及构建产物在受忽略的 `.tools/`、`target/` 和 `dist/`,不提交。
## 规格驱动验收现状
本轮按 `spec-driven-acceptance-testing` 执行了准备流程:
1. 在 `D:\PROJECT\xpp_dev_agent\dev-test` 运行 `qa project list`,已能启动;过去不存在 Python 的阻塞不再复现。
2. MOYI 尚未登记,已用 `qa project init moyi` 新建独立档案 `D:\PROJECT\xpp_dev_agent\qa-projects\moyi`;未修改框架代码或其他项目档案。
3. 填写已核实的源代码、认证、测试范围与 loopback 入口,新增 `specs/media-access-readonly.yaml`,始终 `status: draft`。
4. `qa validate --spec ..\qa-projects\moyi\specs\media-access-readonly.yaml` 退出 0;`qa project check moyi` 退出 1、无 error:实例版本待核实,匿名规格不需 `.env.local`,规格待人工批准。
七项待审预期:健康入口 200/status=ok;`/v1/tasks`、`/v1/tasks/qa-media-absent`、`/api/tasks`、`/v1/models`、`/api/models`、`/api/admin/providers` 无身份均为 401 / UNAUTHENTICATED,不回传相应任务/目录字段。全部只读,不登录、不建号、不生成、不付费。
**未执行 `qa approve` 或 `qa run --project moyi`**,因此没有 report.html、summary.json、JUnit 或浏览器证据,也没有规格驱动验收通过结论。用户明确审阅批准之后才执行;执行前还要核实本机实例版本。后续带身份的两用户任务隔离、媒体回读/播放需要专用测试账号、隔离任务与新的 draft,不复用真实用户凭证。
## 未完成项与下一步
- MED-04:音视频按 Token/时长计费和逐路由协议/费用/播放验收;没有报价或可核对用量时继续限制,不用固定单任务费替代。
- MED-05:只有任务元数据的渠道要接绑定原账号的鉴权内容下载,涉及凭据版本、下载体积/期限、用户授权和安全存储。不能把媒体结果规范化当作已实现成品下载。
- 用户实际失败需要具体渠道、型号、任务 ID 或脱敏错误来定位;本轮没有创建付费媒体任务,不能据本地桩认定真实生成已全部正常。
- 仅经审查验证的本地 Git 提交;不 push、不部署、不迁移业务数据。