Commit Graph

68 Commits

Author SHA1 Message Date
k88936 8fa2bfc3ed 多视图视图地址的注释改成 TODO:接线时必须补地址校验,并删掉引错的 ADR 依据
- platform-tripo:`view_value` 的说明不再引用 ADR 0001(那份 ADR 里没有这条约定),改成 `TODO(multiview-url-validation)`,写明当前只有冒烟示例与接口测试能构造 `Url` 形态、api-server 没有现役入口,以及真正接线时必须在构造侧补协议 / 账号密码 / 内网主机校验
- 同时点明 image-to-model 的 `PublicUrl` 是同一处待办
2026-09-24 21:06:28 +08:00
k88936 e20ff2e89e provider 报 unknown 任务状态时改为可重试,不再直接判死
- platform-tripo:`TaskStatus::Unknown` 不再归一成 `OutputSchema` 终态失败,改成新的 `TripoError::TaskStatusUnknown`,并把它的可重试性判为真(SDK 自己也没把 unknown 算进终态)
- platform-tripo:补用例——provider 回 `"status":"unknown"` 时必须返回可重试的 `TaskStatusUnknown`,不能当成正常快照
- api-server:错误映射补 `TaskStatusUnknown` 分支(502 + 固定文案,轮询侧早已按可重试继续查到截止时间)
- api-server worker:状态查询遇到可重试错误时补一条 warn 日志,便于区分「一直是 unknown」和「一次网络抖动」
- docs:Provider 集成方案写明 unknown 按可重试处理及其理由
2026-09-24 21:06:04 +08:00
k88936 4ca1329d24 任务状态查询本身带上退避重试,瞬时故障不再作废一次计费任务
- platform-tripo:`get_task` 内部按 `TripoSettings::retries` 对瞬时故障(连接抖动 / 超时、408、429、5xx)退避重试,确定性失败(任务 id 非法、响应结构不符、404)立即返回;重试字段与退避函数改名,不再只服务产物下载
- api-server worker:查询在重试后仍是瞬时故障时继续按轮询间隔查到预算用尽,只有确定性失败才立刻收口
- 新增用例:一次 500 后成功(重试生效)、404 只打一次请求(不重试),并给测试客户端加了可指定 base_url 的构造
- docs/technical:写明查询带退避重试与「确定性失败立即返回」的边界
2026-09-24 20:39:12 +08:00
k88936 a08e3bf262 产物地址只允许公网主机,回环与内网段一律拒收
- platform-tripo:`TripoUrl::parse` 在协议与 userinfo 检查之后,再加一道主机检查——回环、内网、链路本地、组播与保留段(含云元数据 169.254.169.254)全部拒收;`localhost` 及其子域同样拒收;IPv4-mapped 的 IPv6 地址按内嵌的 IPv4 判定,`::ffff:127.0.0.1` 绕不过去
- 保留段按 IANA 特殊用途表逐段列出(0/8、100.64/10、192.0.0/24、198.18/15、240/4),因为 `Ipv4Addr::is_reserved` 与 `is_global` 在当前工具链上仍是 nightly
- 新增用例覆盖 17 个拒收地址与 5 个放行地址;产物下载用例本来就跑在 127.0.0.1 的本地 mock 上,改用 `parse_unchecked_for_test` 构造
- docs/technical:写明这条主机规则与「域名解析结果在这一层看不见」的已知限制
2026-09-24 20:36:57 +08:00
k88936 acdfb8ed73 3D 冒烟示例把产物写到 target 目录,不再落到仓库里
- server-rs/crates/platform-tripo/examples/tripo_generation_smoke.rs:产物落盘目录从「当前工作目录」改为 <cargo target>/tripo-smoke-artifacts,开始前建目录并打印路径;该目录本来就在入库排除范围内,根目录不会再攒出临时模型
- server-rs/crates/platform-tripo/examples/tripo_generation_smoke.rs:文件头文档同步改为说明新的产物落点
2026-09-24 19:05:51 +08:00
k88936 06f091f0ff 平台层校验补上 pbr 依赖贴图
- server-rs/crates/platform-tripo/src/common/validation.rs:validate_generation_options 增加 texture=false 与 pbr=true 的组合拒绝(TripoField::Pbr),直连调用方不用再把这种不会成立的组合拖到 provider 侧才报错;放在 generate_parts 分支之后,不改变该分支原有的归因
- server-rs/crates/platform-tripo/src/common/validation.rs:补用例锁住 texture=false + pbr=true 被拒、texture=true 时放行
2026-09-24 18:01:24 +08:00
k88936 b83113619e 产物结构体不再派生 Debug,改成只打元数据
- server-rs/crates/platform-tripo/src/common/types.rs:TripoArtifactBytes 去掉 derive(Debug),改为手写实现,只输出 url / content_type / content_length / 字节数,几十 MB 的 bytes 不会再被一次 {:?} 刷进日志
- server-rs/crates/platform-tripo/src/common/types.rs:补用例锁住 Debug 只带字节数、不带字节内容
2026-09-24 18:00:45 +08:00
k88936 03aec35350 写明 TripoUrl 脱敏只覆盖 query 与 fragment
- server-rs/crates/platform-tripo/src/common/types.rs:redacted() 的文档注明脱敏范围只到 query / fragment,若 provider 改成把 token 写进路径(如 path-style SAS)则需一并处理路径段;无 query 分支补注释说明路径原样保留
2026-09-24 18:00:30 +08:00
k88936 925be4573d 产物扩展名兜底认下 image/jpg
- server-rs/crates/platform-tripo/src/common/types.rs:fallback_artifact_extension 补上 image/jpg 分支,非标准写法但确有 provider 这么回,预览图不再落到默认 .glb 后缀
- server-rs/crates/platform-tripo/src/common/types.rs:补用例覆盖 png / jpg / webp 与读不出形态时的 glb 兜底
2026-09-24 18:00:21 +08:00
k88936 0c716d7d9c 产物文件名主干加上长度上限
- server-rs/crates/platform-tripo/src/common/types.rs:sanitize_artifact_file_stem 在字符过滤后按 MAX_ARTIFACT_FILE_STEM_LEN=128 截断,远端来的超长主干不再拼出超过文件系统名字上限的一长串
- server-rs/crates/platform-tripo/src/common/types.rs:新建 types 的用例模块,锁住超长 / 带路径的主干被中性化并截断、全中性化后为空时退回固定名
2026-09-24 18:00:05 +08:00
k88936 2330a25172 传输判据补上 is_body,并把截断体的归因写清
- server-rs/crates/platform-tripo/src/common/error.rs:transport_error_is_transient 补上 is_body(),与 TripoError::Request.retryable 文档列举的瞬时类型对齐
- server-rs/crates/platform-tripo/src/common/error.rs:注释写明「传输中途截断的响应体在 reqwest 里落在 Decode」这一实测结论,说明为何不把 Decode 判成可重试
- server-rs/crates/platform-tripo/src/common/error.rs:补用例用截断响应体锁住 Decode 不判可重试
2026-09-24 17:59:26 +08:00
k88936 ebce5f9304 平台层转发 base_url 前去掉首尾空白
- server-rs/crates/platform-tripo/src/common/config.rs:client_options 里 base_url 先 trim 再交给 SDK,带空白的地址不再以低层解析错误的形式暴露出来
- server-rs/crates/platform-tripo/src/common/config.rs:把 client_options 的用例扩到 base_url,锁住「校验看到的」与「发出去的」是同一个值
2026-09-24 17:58:03 +08:00
k88936 80ae730dc5 平台层转发 API Key 前去掉首尾空白
- server-rs/crates/platform-tripo/src/common/config.rs:client_options 里 api_key 先 trim 再交给 SDK,校验口径与发送口径统一,带空白的密钥不再变成 provider 侧的 401
- server-rs/crates/platform-tripo/src/common/config.rs:补用例锁住 client_options 发送的 api_key 已 trim
2026-09-24 17:57:44 +08:00
k88936 b54ff06bc7 平台层 Tripo 配置把 base_url 校验成绝对 http(s) 地址
- server-rs/crates/platform-tripo/src/common/config.rs:validate 用 url::Url 解析 base_url,缺 scheme(openapi.tripo3d.com)、非 http(s)(ftp://)与无 host 的值都在构造点按 Configuration 失败,不再拖到请求期变成传输层报错
- server-rs/crates/platform-tripo/src/common/config.rs:补用例覆盖缺 scheme / 非 http(s) / 非法 URL 被拒、前后带空白的合法地址放行
2026-09-24 17:57:31 +08:00
k88936 82e889dc6d 带地址响应体的过滤改成大小写不敏感
- server-rs/crates/platform-tripo/src/common/error.rs:body_snippet 先整串转小写再匹配 http:// 与 https://,`HTTPS://…` 这类大小写变体不再绕过过滤,签名 URL 不会被带进持久化的任务错误信息
2026-09-24 17:44:20 +08:00
k88936 f198b7a6d0 multiview 视图输入显式化为 url / fileToken,线上按文档 view-key 形态发出
- 契约新增 Model3dViewInput(url / fileToken 的 tagged enum),views 的四个视图都改用它,裸字符串在契约层即被拒绝
- platform-tripo 不再走 SDK 的位置数组形态:按 Tripo 文档推荐的 view-key 构造 inputs,值写成显式 {url} / {file_token},种类由契约字段决定、链路上不再猜前缀
- 视图校验(front 必填、至少两张、空白按未提供)与 inputs 构造合并成一条路径,不再两处重复规则
- 新增 4 条定向用例钉住发出的 JSON 形状、空白视图、视图数量与 taskId 复用;契约用例补齐裸字符串与视图内未知字段被拒
- 重新生成 ts-rs 绑定与导出索引,技术方案同步 multiview 输入口径
2026-09-23 18:59:05 +08:00
k88936 6b1114356c 59/60/61/65 按决定不修复,改为在代码里写清取舍
- worker.rs:说明 last_error_message 是落库且前端直接展示的摘要,只取 provider message,不塞内部 reason/taskStatus(#59)
- platform-tripo error.rs:说明 ADR 0001 要求平台层不带出 SDK 错误模型,Io/Serde 只保留文本(#60)
- platform-tripo mapping.rs:说明 Tripo 文档把 generated_image_url 列为 text_to_model 固定字段,按 ADR 0001 失败关闭保留必填(#61)
- platform-tripo image_to_model/client.rs:说明 PublicUrl 只做非空白校验的边界条件与将来接外部地址时的校验位置(#65)
2026-09-23 18:04:29 +08:00
k88936 42b4315b4f 可重试性改为显式判定,不再由 status 缺省推断
- TripoError::Request 增加 retryable 字段:由产生错误的一方按真实分类判定
- 传输层失败按 reqwest 的 is_timeout / is_connect 分类(新增 transport_error_is_transient,
  以及状态集合 http_status_is_transient)
- SDK 的 Error::Request 只在带瞬时状态码、或底层 reqwest 错误确实瞬时时可重试;
  source 为空(空 body / 格式错误 / 缺 data 字段)不再重试
- 产物客户端构造失败标为不可重试;无数据推进、body 读取失败与长度不一致标为可重试
- 新增四组用例:显式标记、状态集合、SDK 分类,以及用真实 reqwest 错误(连接被拒 vs 非法地址)验证分类
- 同步技术方案:写明「可重试性由产生错误处判定」的口径
2026-09-23 17:40:18 +08:00
k88936 f6f41f22c3 geometry_quality 预检只拒绝 detailed,standard 按不传处理
- validate_generation_options 对非 v3.1 / v3.0 家族只在取值 detailed 时拒绝,
  与 quad / smart_low_poly / generate_parts「只拒绝启用值」的处理对称
- 新增 wire_geometry_quality:不支持的家族把 standard 收敛成不发(等价于 provider 默认档),
  三个 endpoint 的请求映射都过这一层,避免 provider 因「不支持该字段」整单拒绝
- 新增两组表驱动用例:非 v3 家族 standard 放行 / detailed 拒绝,以及映射层的收敛结果
- 同步技术方案:写明「预检只拒绝启用值」与映射层收敛 standard 的口径
2026-09-23 17:33:51 +08:00
k88936 b33a8a141c 3D 产物下载的重试改为覆盖整个响应体
- download_model / download_rendered_image 把「取响应头 + 读完 body」作为一次可重试事务,
  每次尝试都重新取响应头并整体重下,不做断点续传
- body 传输失败与长度不一致归一成可重试的传输错误(不再带 HTTP 200),HTTP 状态只留在文案里
- 新增 TripoArtifactBytes(读完的产物)并公开 download_model / download_rendered_image 的 max_bytes 上限;
  超限按 OutputSchema 失败且不重试,流式句柄 TripoDownloadedArtifact 收回 crate 内部
- api-server 的 read_artifact 改成对完整产物做落库前校验(只判空),体积上限转由调用方传入
- smoke 示例改为一次写入完整字节;新增「body 中途断开后整体重下成功」与「超限不重试」两个用例
- 同步技术方案与实施计划:把「只重试响应头」的描述改成「重试包住整个 body」
2026-09-23 17:01:40 +08:00
k88936 ffee739774 platform-tripo 构造配置时拒绝零超时与空白凭据
- TripoSettings::new 改为返回 Result:request_timeout 必须大于零,api_key / base_url 不能是空白
- 新增 TripoSettings::validate 与 TripoError::Configuration,字段是公开的,因此 TripoProviderClient::new 在使用前再校验一次
- 拒绝零超时的理由是同一个值存在两种语义:tokio::time::timeout 立即超时,reqwest 却当成不超时
- api-server 构造入口把构造失败按既有 503 口径映射,并补全 TripoError 的匹配分支
- smoke 示例与 platform-tripo 测试跟进新的构造签名,新增零超时 / 空白凭据用例
2026-09-23 16:16:27 +08:00
k88936 aa6e3b8d79 SDK 请求错误不再丢弃响应体与底层错误链
- 映射 tripo3d_sdk::Error::Request 时带上 body 与 source 字段
- 响应体截断到 512 字符,疑似带 http(s) 地址的响应体整体丢弃
- 只取错误链底层文本,避免 reqwest 顶层 Display 带出完整签名 URL
- 补错误链收集、响应体过滤与截断的用例
2026-09-22 16:55:16 +08:00
k88936 ed2eb43fe6 补 3D 生成选项校验的表驱动单测
- 覆盖最简选项全模型放行、fast 必须配 v3.5 贴图版本
- 覆盖 generate_parts 的 texture/pbr/quad/smart_low_poly 互斥组合
- 覆盖 quad 家族限制与各模式 face_limit 的 min-1/min/max/max+1 边界
- 覆盖空白 task id 按 OutputSchema 失败与 trim 行为
2026-09-22 16:50:06 +08:00
k88936 e359158ecf 校验文案的版本标签改为从契约枚举推导
- validate_generation_options 的错误文案改用 wire_str_lossy 取 serde 线上值
- v3.x 家族的模型标签收敛到 v3_model_labels 助手
- 契约改名后诊断文案随之更新,不再手写重复的版本字符串
2026-09-22 16:19:09 +08:00
k88936 bcac5a7c12 三个提交入口的生成选项映射收敛为单一字段清单
- common::validation 用 tripo_generation_options_from! 由一份字段清单派生三个 From 实现
- multiview 手写的 TripoGenerationOptions 映射改为复用该 From 实现
- 新增共享字段时三条路径一起跟上,缺字段会在编译期报错
2026-09-22 16:15:38 +08:00
k88936 2e9aed3750 三个提交入口统一校验 provider 返回的 task id
- 新增 submitted_task_handle:空白 id 在提交调用附近以 OutputSchema 失败
- text / image / multiview 提交路径共用它,任务不再以孤儿状态等到下游查询才报错
2026-09-22 15:53:37 +08:00
k88936 09f0c51b81 空白视图规则收敛到单一助手
- 新增 view_input 同时服务提交前计数校验与 SDK 参数转换
- 空白 / 纯空白视图的判定不再有两份实现,避免校验与转换漂移
2026-09-22 15:49:34 +08:00
k88936 be07eb79c6 未知任务状态错误带上 task id
- map_status 接收 task_id,Unknown 分支改用与其它映射失败一致的 OutputSchema
- provider 异常可与具体任务对上,不再是一条无主错误
2026-09-22 15:47:01 +08:00
k88936 1749f427c1 任务快照只在失败终态保留 failure
- failure 改由终态判定驱动,不再只看 provider 是否留下错误字段
- 已完成的任务即使带过期错误字段也不再挂 failure,保持快照内部自洽
2026-09-22 15:45:45 +08:00
k88936 e18c6ee502 产物下载客户端不再跟随跳转
- 产物地址来自 provider 响应,禁止 reqwest 自动跳转以防 SSRF
- 需要跳转的地址会以非成功状态显式暴露,不再由服务端静默代发
2026-09-22 15:12:06 +08:00
k88936 669a08c7c2 产物下载失败信息补上可诊断上下文
- 传输失败带上脱敏 URL 与底层错误 source 链
- 非成功状态补上状态码文案与脱敏 URL
2026-09-22 13:51:29 +08:00
k88936 01a9941cbc 任务快照映射不再多余克隆字符串
- task_id 与 error_message 直接移交所有权,只保留错误路径上的必要克隆
2026-09-22 13:51:23 +08:00
k88936 fd0a37969e 3D 产物落盘文件名补上安全处理
- URL 无可用扩展名时按 content type 兜底,预览图不再写成 .glb
- 文件名主干中性化路径分隔符与遍历片段,避免逃出目标目录
2026-09-22 13:50:29 +08:00
k88936 e2809b83c0 3D 冒烟示例单端点失败不再中断其余端点
- wait_for_task / get_task / download_model 失败时记录该端点错误并继续
- 保留 throw_on_failure: false 的原有语义,仅补齐传输与超时类错误
2026-09-22 13:45:50 +08:00
k88936 2691ca8aca 补记图生输入的OSS直读待讨论项
- api-server 的 image_source 模块头与 platform-tripo 的 upload_image 各留一条 TODO(oss-direct-read):交签名 URL 或对端直读 OSS 能省掉字节中转,但把私有对象与带时效凭据交给第三方,安全口径与可行性待讨论
- 技术方案文档把图生输入口径更新为当前的 source 站内引用 tagged enum,并补同一条待讨论说明
- 讨论清楚之前保持「api-server 自己读、自己传」的现口径,不改行为
2026-09-21 20:02:18 +08:00
k88936 14066eea11 产物下载改为按「无数据推进」判超时
- artifact reqwest client 不再设包含响应体的总超时,改成 connect_timeout + read_timeout(reqwest 0.12 的「每次读操作」语义,读完自动重置)
- 响应头之前没有数据推进时用显式 tokio::time::timeout 兜住,避免连上却不返回响应头时无限挂住
- 新增 TripoProviderClient::artifact_stall_timeout 统一承载三处预算,取值沿用 TripoSettings::request_timeout
- 补 3 个 mock TCP 用例:响应头一直不来、传输中途断流按无数据推进失败,慢速但持续的下载必须完整收完(后者能拦住「改回总超时」的回归)
- 同步技术方案与后端架构文档里的下载超时口径
2026-09-21 19:54:57 +08:00
k88936 609b24c779 text-to-model入口的submit改名带端点
- TripoProviderClient::submit 改名为 submit_text_to_model,与 submit_image_to_model / submit_multiview_to_model 一致
- 同步 api-server tripo3d worker 与 tripo_generation_smoke example 的调用点
- 同步技术方案文档里写死的 submit 口径,方法名不再与另两个入口分叉
2026-09-21 19:49:31 +08:00
k88936 3af0d3d90b 契约枚举的线上取值只由serde定义
- shared-contracts 新增 wire_str 与 wire_str_lossy:线上取值只从 serde rename / rename_all 取,不再维护第二份字面量
- 删除模型版本、纹理质量、纹理版本、纹理对齐、几何质量、输入方向、导出方向、压缩共 8 个枚举上手工维护的 as_str
- platform-tripo 新增 common/wire.rs 负责契约枚举到 provider 请求字符串的转换,三个入口的 to_sdk_params 改走它并把失败归一成 provider 错误
- api-server 的定价文案与 job 模型版本取值改用 serde 取值,job 的 model_version 由 &'static str 改为 String
- 取值来源只剩 serde 一处,改 rename 不会再静默分叉
2026-09-21 19:46:43 +08:00
k88936 294b7461ff 去掉产物下载重试里的不可达panic分支
- download_artifact 原先用 for + last_error + expect 收尾,循环每轮都会 return,expect 实际不可达,却给库留下一条潜在 panic 路径
- 改为 loop 内递增 attempt,重试耗尽时直接返回最后一次错误,重试次数与退避行为不变
2026-09-21 15:15:07 +08:00
k88936 e9af6c0741 脱敏地址保留原始分隔符
- redacted 原先无条件用 ? 拼接脱敏标记,只有 fragment 的地址会被显示成带 query 的样子
- 改为按命中的分隔符原样拼接,日志里能区分 query 与 fragment
2026-09-21 15:14:51 +08:00
k88936 0f8ac57593 拒收带userinfo的产物地址
- TripoUrl::parse 原先只校验 scheme,带 user:password@ 的地址会被 Debug / redacted 原样打进日志
- 解析阶段直接拒绝 userinfo,产物地址不需要凭据
2026-09-21 15:14:07 +08:00
k88936 694a3c6f6c 产物下载前校验任务确实处于完成态
- download_model 与 download_rendered_image 原先只看 output 是否存在,快照字段全公开、status 与 output 可以被人为构造得不一致
- 两个入口统一走 completed_output:先校验 task_id,再要求 status=Completed 且有输出,否则按输出结构错误失败
2026-09-21 15:14:00 +08:00
k88936 6724f8b707 收紧产物文件名对远端扩展名的取值
- filename 直接取远端 URL 末段扩展名,path_segments 已百分号解码,%2F / %5C 会拼出跨目录路径
- 扩展名只接受长度不超过 10 的 ASCII 字母数字,其余一律退回 glb
2026-09-21 15:13:15 +08:00
k88936 33cd943ff9 长度与范围越界改用独立校验原因
- TripoValidationReason 新增 OutOfRange,与「参数组合互斥」不再共用 InvalidCombination
- prompt 超 1024 字符、negative_prompt 超 255 字符改报 OutOfRange
- face_limit 越界属同一类范围错误,一并改报 OutOfRange,调用方可按原因分流
2026-09-21 15:11:12 +08:00
k88936 7193bd28c2 多视图可选视图去掉首尾空白再提交provider
- optional_view 先用 trim 判空、再把未 trim 的原串交给 FileInput,两侧口径不一致
- 改为提交前 trim,空白视图仍按未提供处理
2026-09-21 15:10:49 +08:00
k88936 e8467c2870 多视图前视图去掉首尾空白再提交provider
- front 只按 trim 后判空,但先前把未 trim 的原串交给 FileInput,带空白的取值会被原样发出
- 改为提交前 trim,与 image_to_model 的输入口径一致
2026-09-21 15:10:24 +08:00
k88936 0982b952cb 收敛Tripo三入口重复的extra字段构造
- 新增 common/extra.rs 统一构造 texture_version 与 delight 的 SDK extra 字段,键名只留一份
- text_to_model 与 image_to_model 删除各自的 extra_fields 副本,改调公共实现
- multiview_to_model 的内联 extra.insert 也改为复用同一构造
- 未提供的参数仍不写入 extra,请求体行为与原先一致
2026-09-21 15:08:50 +08:00
k88936 a8799adf5d platform-tripo支持图片上传与预览图下载
- 产物下载类型改名为 TripoDownloadedArtifact,模型与预览图共用同一条流式读取路径
- 新增 download_rendered_image,读取 task 结果里的预览图地址
- 新增 upload_image,把图片字节上传 provider 换 file_token
- 图片输入收敛为 TripoImageInput 枚举,只有 file_token 与公网地址两种形态,不再接受裸字符串
- smoke 示例跟随新的图片输入类型
2026-09-21 14:06:47 +08:00
k88936 7790a181c4 provider按参数分层并公开组合校验入口
- submit 改为接收生成参数,图片输入由调用方解析后单独传入
- 公开 validate_text_to_model_params / validate_image_to_model_params 供平台层在副作用前预检
- 参数到 provider 校验选项的映射收敛为 From 实现,去掉重复拼装
- smoke 示例跟随新签名
2026-09-21 12:39:20 +08:00
k88936 188614d5d2 改用Provider流式下载Tripo产物
保持第三方SDK不变并在Provider侧读取签名模型URL

逐块暴露模型响应并校验Content-Length,smoke示例改为异步落盘

为未来SDK原生stream能力保留迁移TODO
2026-09-19 23:14:00 +08:00