gongxiangp2/docs/detail-desktop-client.md

详情页工作台：客户端授权与项目同步

客户端在素材库网页完成账户登录和明确授权。网页登录密码、平台模型密钥不进入客户端。正式素材库地址为 https://sc.jiansun.vip。

使用方式

1. 打开本机「详情页工作台」，选择「正式素材库」，点击「在素材库登录」。
2. 在浏览器登录素材库账户，核对账户后点击「授权并返回客户端」。
3. 客户端显示本账户的网页项目、客户端项目和草稿。打开网页项目后，保存为独立的客户端项目，不覆盖原网页版本。
4. 「保存项目」同步画布、图片、对话记录和未发送的输入内容；本机自动保存供离线恢复。换电脑前需主动保存同步。
5. 退出登录会撤销当前客户端会话；授权页可查看、撤销本账户的其他客户端。

正式验收前继续仅对当前有效超级管理员开放，普通管理员不等于超级管理员。每次接口调用都重新核对数据库权限、账户状态和授权有效期。

接口与安全边界

所有接口位于 /api/desktop/，响应均禁止缓存。

接口	鉴权与作用
GET config	公共发现；返回固定客户端 ID、启用状态、S256
POST authorize	素材库网页登录态与同源校验；批准固定用途的授权
POST token	60 秒一次性授权码和 PKCE S256 校验，回调固定为本机临时端口的 /oauth/callback
GET/DELETE session	Bearer 客户端会话；核对账户／撤销当前会话
GET devices、DELETE devices/:id	素材库网页登录态；只管理本账户的授权
GET projects	本账户项目，游标分页，每页最多 50 项
GET projects/:source/:id	读取本人网页或客户端项目及文件清单
PUT projects/desktop/:id	保存客户端项目；使用 revision 防止并发覆盖，冲突返回 409
GET projects/:source/:id/assets/:asset	鉴权后获取该项目私有文件
PUT projects/desktop/:id/assets/:source	上传 PNG／JPG／WEBP，单张 20MiB、每项目 128 张／256MiB
GET models、GET agent-models	只返回管理员已开放且已通过验证的可用模型，不返回平台密钥

客户端会话有效期 7 天，数据库仅保存令牌哈希。授权撤销或超级管理员资格撤销后，旧会话立即失去接口权限。本版本不开放任意生产终端或命令执行，不通过这些接口代理付费模型生成。

项目最多 12 屏，统一宽度为 750px 或 1440px，总高度最多 30000px。客户端项目单独存储，不迁移或改写现有网页项目。项目图片复用独立的私有持久目录，不进入公开上传目录。

部署与验收

新增 migration 20261020090000_desktop_client_workspace，仅创建四张客户端表。生产迁移复用精确提交、真实备份、隔离恢复、数据库身份、迁移校验和与审计门禁，随后发布同一提交的应用镜像。

本地验收覆盖：真实网页登录／PKCE 回调、授权重放拒绝、跨账户访问拒绝、普通用户与撤权拒绝、私有文件、项目列表分页、并发版本冲突、项目与对话／输入草稿保存恢复、客户端重启恢复、退出后账户隔离，以及 1440px 图片导出。生产验收另记录在对应发布证据目录，不能以本地结果替代。