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

客户端承担编辑、模型请求、排版、预览图和导出。平台仅鉴权、保留私有工程及恢复附件、分发已上传的预览；不解压、不渲染 `.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}`：

```json
{
  "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 项测试通过。