原生工程云备份与网页查看

客户端承担编辑、模型请求、排版、预览图和导出。平台仅鉴权、保留私有工程及恢复附件、分发已上传的预览；不解压、不渲染 .pcraft。网页 /assets/detail-generator 只查看项目和草稿，允许经确认联动删除，编辑回到客户端。

授权与版本

继续使用素材库网页登录授权产生的客户端 Bearer 会话，不能传入用户的 98k Key。每次调用实时检查会话、撤销、账号状态和当前内测权限；工程流上传开始与结束各检查一次。浏览器查看接口使用素材库 Cookie 会话，不向页面发放桌面写令牌。

GET /api/desktop/capabilities 声明 documentVersions: [1,2,3]、projectDeletion: true、nativeFiles 限制。旧 v1/v2 项目继续可读，v3 原生工程禁止被旧版本格式覆盖。

v3 项目

沿用 PUT /api/desktop/projects/desktop/{projectId}：

{
  "revision": 2,
  "status": "draft",
  "conversation": [],
  "composer": "",
  "document": {
    "version": 3,
    "id": "project-id",
    "name": "产品详情页",
    "native": {
      "format": "photocraft",
      "schemaVersion": 1,
      "documentSource": "native:<canvas文件的完整SHA256>",
      "files": [
        {"path": "canvas.pcraft", "source": "native:<完整SHA256>", "sha256": "<完整SHA256>", "size": 123456},
        {"path": "context.json", "source": "native:<完整SHA256>", "sha256": "<完整SHA256>", "size": 1234},
        {"path": "session-backup.json", "source": "native:<完整SHA256>", "sha256": "<完整SHA256>", "size": 4567}
      ]
    },
    "screens": [
      {"id": "hero", "name": "首屏", "width": 1440, "height": 2200, "previewSource": "local:<预览SHA256>"}
    ]
  }
}

可选 document.creation 使用现有 v2 的经验证创作资料、事实、卖点批次、方案和规则快照。原生恢复附件由客户端生成白名单备份，排除登录授权、Key 和系统凭据；服务端不解析其中的文件。

首次同步先以 revision:0 创建 draft 占位：native.documentSource:null, native.files:[]、分屏 previewSource:null。然后上传附件和预览，最后以服务器最新 revision 提交完整引用。已有项目先上传新内容，最终一次修改版本；断线或 409 时保留本机草稿与旧云端版本，不覆盖其他设备成果。

完整原生工程同时包含 canvas.pcraft、context.json、session-backup.json。完结状态额外要求每屏预览已上传。服务器提交前核对所有文件属于本账户本项目，且长度、SHA256、类型一致。列表以 backupState:pending|ready 区分未完成的首次同步；不能把占位显示为完整备份。

标记完结时，服务器与任务登记使用同一账户事务锁，复核本项目的任务表：排队、执行中、待应用、结果未知及仍持有效租约的任务均返回 409 task_busy。持久化会话或本次摘要中的 pending／unknown 也会阻止完结，不能通过省略摘要覆盖旧证据。草稿仍可同步并保留原请求身份；无未结任务的完结项目正常保存不会被降级。

conversation 仅存待处理请求的有限摘要；完整会话在私有恢复附件。存在未知请求时保留原任务 ID，并带 unknown:true；服务端会拒绝删除这样的项目。恢复只能查询原请求，不能自动重发模型调用。

原生文件传输

上传路径：PUT /api/desktop/projects/desktop/{projectId}/native/native:{sha256}。

Authorization: Bearer <素材库客户端会话>。
Content-Type: application/octet-stream。
Content-Length 为实际字节数，单文件最多 512 MiB。
X-Content-SHA256 必须等于路径中的 64 位小写 SHA256。
原始文件作为请求流发送；不能使用 Base64 JSON 或 multipart。
成功返回 {source,sha256,bytes,existing}。已存在相同内容返回 existing:true；不同内容必须使用不同哈希来源。
同项目同时只接收一份工程文件流，冲突返回 409 upload_busy；单次最多 10 分钟、连续无数据最多 60 秒。

下载使用同路径 GET，支持单段 Range: bytes=start-end / 后缀范围，返回 200 或 206，带 Content-Length、Accept-Ranges 和 X-Content-SHA256。服务器分块读写，应用内存不随整份原生文件大小增长。客户端必须核对下载长度与哈希后再恢复工程。

预览继续沿用 PUT /api/desktop/projects/desktop/{projectId}/assets/local:{id}，仅 PNG/JPEG/WebP，每张最多 20 MiB。建议使用稳定图片哈希作 ID；预览可缩小，但 screens.width/height 保留原画布坐标。网页只取这些预览，不取得原生附件或完整会话。

每项目云资源含保留旧内容总量最多 1 GiB、160 个文件；达到上限返回 413 project_quota。不自动删除当前版本、待提交的新文件或未知请求证据。上传未完成、校验失败、会话被撤销或项目已删除时清理本次临时文件；已提交结果不明时先查数据库引用，避免误删有效原件。

查看、删除与恢复

浏览器 GET /api/detail-projects 返回项目列表；GET /api/detail-projects/{web|desktop}/{id} 返回经裁剪的只读资料、分屏与图片引用。原生 manifest、存储键、模型绑定、请求诊断与完整会话不传给页面。只读图片使用 GET .../assets/{source}，每次重新核对账户与项目归属。

网页 DELETE /api/detail-projects/{source}/{id} 与客户端 DELETE /api/desktop/projects/{source}/{id} 均传 {revision}，先显示删除范围确认。服务端原子软删除 Web 项目及其客户端续作；运行、排队或结果未知的任务阻止删除。过期版本返回 409。列表保留删除墓碑供其他设备同步；已删项目不能被旧设备保存重建。本机工程由客户端移入可恢复区域，不直接销毁。

2026-10-22 验证范围

定向测试覆盖 v3 合同、完整引用、版本冲突、关联墓碑、账户隔离、真实临时磁盘流式传输/去重/Range、末尾撤权与删除清理、并发上传和提交时额度复核。Web 本地独立 fixture 实测 1280×900 与 390×844，检查首屏封面、草稿/完结、半同步提示、原生预览、分屏切换和删除确认取消。证据位于 output/native-web-completion-20261022/；该 fixture 不代表生产跨端验收。

收尾复核增加服务端完结保护：7 套 37 项定向测试通过；独立本地 PostgreSQL 的 4 组实际事务验收验证任务锁竞态、未知证据保留、账户隔离、完结保持和只删除本轮合成项目。测试无模型调用，原未知请求未修改；证据位于 output/native-closeout-recheck-20261022/。工作树另有未发布的知识库迁移草稿，发布迁移闭包继续以已提交的 39 项为准，HEAD 隔离闭包 20 项测试通过。

6.8 KiB Raw Blame History Unescape Escape