gongxiangp2/docs/photocraft-client-design.md

90 lines
13 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.

# 详情页原生客户端设计标准
更新:2026-10-23。适用于 `apps/detail-photocraft` 的二次开发;不替换线上素材库、旧 Electron 客户端或品牌中心的设计规范。
## 定位与依据
给品牌中心制作产品详情页的 Windows 原生创作工具。主工作面属于 **Operate**:用户看作品、操作图层、与 Agent 协作,界面应退到作品之后。
视觉和排版布局以 PhotoCraft 原生编辑器为主要参考,不沿用用户已否定的网页式四步大面板。保留素材库 Logo、账户、品牌、产品和项目等业务语义。沿用 PhotoCraft Pro 系列的平面灰阶工作区与蓝色操作反馈;源码默认 Pro Medium,主题可切换,本次 Agent 面板回归覆盖 Pro Medium 与 Pro Light。界面不借用 ArtCraft 的名称或品牌标志。
本地源码基线固定为 PhotoCraft **v0.10.0 / 8407d9ccb125af52944fca9d228383459f94aaef**,与此前实际验收的原版一致。版本升级需重验中文文字、共享撤销历史、PSD 和 GPU 显示。
## 工作区布局
```text
┌ Logo 原生菜单 ┐
├ 当前工具选项 我的项目 添加素材 产品资料 同步 账户 ┤
├ 工具条 ┬ 文档标签 / 画布 ┬ Agent / 图层 ┤
│ │ │ 对话与操作记录 │
│ │ 可编辑作品 │ │
│ │ │ │
│ │ ├───────────────┤
│ │ │ 对话 / 生图 │
│ │ │ 要求输入 / 设置 │
│ │ │ 双模型同一行 │
│ │ │ 发送 │
├────────┴ 缩放、尺寸、保存状态 ┴───────────────┤
```
- 中央画布始终为主区域,开关项目、素材或设置不能清空、替换尚未保存的作品。
- 顶部只保留原生菜单、项目入口及当前工具必要选项,无大标题、欢迎横幅或步骤说明墙。
- 左侧沿用 PhotoCraft 工具分组、快捷键、鼠标与键盘语义;不另造一套操作方式。
- 右侧固定协作面板,默认 Agent,可切换图层;调节宽度后记住。图层、属性、历史沿用原生编辑器。
- 右侧对话区独立滚动,用户气泡靠右、段落仍左对齐,Agent 回复与产出靠左;每轮只显示一个 Agent 标识。操作记录默认收起为摘要,点击展开该轮原始历史。
- 底部统一输入区使用独立边框、内边距和焦点反馈,输入文字超过三行后在框内滚动。对话与生图模型放在同一行的两个独立选单;选中内容仅以紧凑上下文显示。滑杆图标打开个人 Key 和连接设置;账户弹窗只负责素材库网页登录授权。保存与校验有加载、失败和成功反馈,不把已保存的 Key 回显到界面。
- 没有文档时直接进入“我的项目”,不另设欢迎页或草稿入口。项目以真实首屏缩略图、名称、草稿角标与本机/账户来源呈现,按更新时间排序;没有页面时显示待生成。可见行才请求封面,后台渲染并限制并发与缓存。
- 项目垃圾桶入口保持可见,确认时明确删除本机还是账户项目。本机移入所属账户回收区,账户删除复用现有鉴权、版本和任务保护;网络、版本冲突、正在执行和结果待核查分别显示原因。列表已知受保护时禁用删除并给出悬停原因;最终提交仍实时核对,不乐观移除。存在待核查任务时保留项目和请求记录。删除错误只出现在项目和确认区,不混入 Agent 对话。
- “我的项目/添加素材/画布”是互斥的中央目的地,切换不重建或清空原文档。返回画布时关闭浏览层;没有文档时回到我的项目。
- “我的项目/添加素材”等入口放在原生工具选项行右侧,不额外占用一整行;左侧工具参数可横向滚动。隐藏工具选项时保留最小可达入口。“添加素材”支持 SKU / SPU / 条码从素材库查询,图片预览后置入当前画布。目录与图片采用独立有界只读队列;缩略图最多两张在途。私有图片每次 GET 保持实时鉴权,预览不生成临时图片,置入及画布修改仍串行。
- 默认窗口 1440×900,验收 1280×800、1440×900、1920×1080 与 125% / 150% 缩放。最低 1100×720;窄窗口收起辅助面板,不把桌面客户端伪装成移动网页。
## 视觉与文案
- 直接复用 PhotoCraft 的主题 Tokens、原生按钮、菜单、标签页、图标与停靠行为。尺寸采用 4 / 8 / 12 / 16 / 24 的间距节奏。
- 主操作用蓝色,灰阶承载结构,错误与警告只用于真实异常;不添加装饰渐变、营销卡片、超大圆角或无意义动画。
- 界面文字优先采用正常可读的 12–14pt;正文与辅助文字达到 4.5:1 对比度。命中区域、焦点和快捷键可发现。
- 画布字体独立管理,中文基线 Noto Sans SC。界面主题和字号不改作品尺寸、字体或导出结果。
- 按钮写动作,如“打开”“置入”“发送”“接手”“撤销”。只在必须决策或失败恢复时解释;常态不展示实现细节、接口名或免责声明。
- 帮助说明放在悬停提示和按需展开区域;不可用操作明确说明缺少的条件,不伪造完成或可用状态。
- Agent 页签指示与 Key 展开使用 160ms 原生 cubic-out 状态过渡,发送悬停为 120ms;设置内提供“减少动态效果”,相关过渡直接切换。沿用 Rust / egui 动效,不引入 JavaScript GSAP 运行时;静态截图不作为动效帧率或系统辅助技术验收。
- Agent 快捷建议及操作记录展开入口使用紧凑图标胶囊,完整保留悬停、键盘焦点和按需展开行为;建议只填入草稿,用户明确发送才调用模型。
- 本客户端不展示原项目的社区、推广网站、GitHub 或向原项目报错的入口。帮助菜单保留系统信息及本客户端“关于”;必要开源署名、原始 NOTICE、MIT / Apache 许可和第三方素材来源集中放在“开源许可”。不改写作品内容、文件名或嵌入色彩配置中的真实来源信息。
## Agent 协作约定
1. 用户点击发送或在输入框内按 Ctrl+Enter 后,以一行实际状态呈现回复或画布更新;实际模型只通过 98k 对外接口调用。回复按真实 SSE 增量显示,部分说明不执行命令,完整结束并校验后才应用编辑;不用完整结果的打字动画模拟流式。预检查失败保留输入草稿。
2. 编辑建议绑定当前文档、图层和修订号。只允许已实现、已校验的画布命令,拒绝终端、脚本、任意本机文件和任意网络地址。
3. 操作逐步进入当前画布,每一步重新绘制并列出实际结果。不能只展示动画或最终截图。
4. 用户点击“接手”、切换文档、修改图层或执行撤销后,停止剩余自动编辑。旧建议不会覆盖新修改;继续前重新核对上下文。
5. Agent 与用户共用引擎的撤销、重做历史。撤销一步不影响此前无关人工操作;已经成功的步骤不因后续失败而被当作未执行。
6. 模型派发前保存请求身份;超时、断线、退出后的结果未知保持 `unknown`,只按原请求只读核查,绝不自动重发。接手画布不代表上游模型已取消。
重启核查先暂存到原项目,打开时核对账号、原任务、屏幕、方案和当前画布版本。只恢复未编辑的目标屏;其他屏的人工修改与图层身份必须保留。后台结果不切换当前项目,重复启动不重复插图;等待原结果不能阻塞本机保存。
7. 本地草稿、账户同步、工程文件和导出各有独立状态。任何联网失败都保留已保存的本机作品与输入草稿。
8. 实际生成结果在所属对话轮次中展示等比缩略图,点击打开默认居中的原生图片预览;只读本人项目任务内校验通过的产出,不接受任意本机路径或用占位图冒充结果。
## 账户、素材与资源边界
- 复用 `/api/desktop` 的网页登录授权、PKCE、本人项目及素材目录契约;密码和访问令牌不进入模型上下文、对话、工程包或日志。
- 正式验收前联网功能继续仅有效超级管理员使用;每次调用前重验账户、权限和模型开放政策,不信任界面缓存。
- 不读取 98k 的源码、数据库或服务器。每个素材库账户使用自己的 98k Key,只存本机操作系统凭据库;不打包或分发公司共用 Key。更换素材库账户后不共享模型连接。对话与生图分别保存选择,保留原有个人 Key 时切换模型不用重填。
- 模型选项复用线上现有的只读目录,对话用 `agent-models`、生图用 `models.modelOptions.image`。保存前与个人 Key 的公开 `/v1/models` 核对,不根据模型名称猜测用途;选择配置与原生生图执行分开验收。
- 输入区保留紧凑的“对话/生图”,不展示三个含糊任务的下拉选单。只有真实选中可替换图片时出现“替换选中图”;沿用原生生图与单屏替换能力,保持图框和独立文字层。没有自动模型路由实现时不声称已由 Agent 自动判断生图。生成过程用单行状态,接手后的结果待明确应用,进入同一份撤销历史。
- 品牌、品类在产品资料中一次选择,Agent 不重复询问。素材联动仅精确映射目录中的明确品类;旧资料缺品类保持空值,不能按近似名称套模板。项目按品牌和品类自动绑定已就绪规则;没有对应模板时显示待配置,不借用其他品类。
- 规则及模板模块目录由生产服务提供,首次下载后在所属账户本机缓存,使用内容 SHA 校验;后续先读本机,每五分钟在使用时后台检查一次。联网接口包括 304 响应之前均实时校验权限。已有项目使用固定快照,新版缓存不自动改写旧方案;延迟回包不能覆盖未保存输入。当前缓存范围是规则与模块元数据,完整 PSD、人物与参考图片资源包需另行接入和验收。
- 画布、图片处理、预览和导出在用户设备上执行。平台负责鉴权、目录、知识、私有文件传输与项目服务;不宣称平台没有资源开销。
- 以本机工程为主要工作副本:`.pcraft`、工作素材缓存、撤销历史与生成任务日志留在用户设备;个人 Key 的模型请求由客户端直连 98k。生产机不承担客户端的画布合成、PSD 导出或自动重跑任务。
- 服务端保留项目索引、权限、品牌/模板快照版本和必要的任务摘要(请求号、状态、所属项目与版本);完成后接收成果。为跨设备与本机故障恢复保留可选工程备份及版本同步,不能只上传一张最终图片。
- 大文件传输按需、增量、流式进行,避免一次在生产机展开整份工程或解码长图;后续可评估授权直连对象存储。原生工程云备份、版本同步及跨设备恢复的定向验收见[客户端与 Web 收尾记录](client-web-closeout-acceptance-2026-10-22.md);增量及对象存储直传仍需单独验证。
- 默认宽度 1440px,兼容 750px;最多 12 屏、总高 30000px。缩放只影响显示,不改变真实坐标。大图逐份加载、任务受控并发。
## 验收与完成口径
- 必须用实际编译的原生客户端检查,不以网页模型图、模拟数据或原版编辑器的通过记录代替二开验收。
- 覆盖:首次空态、加载、登录、撤权、项目列表与恢复、素材查询及置入、Agent 实际调用、逐步编辑、人工接手、共享撤销、重启后草稿和未知请求恢复。
- 用现有顾家 1440px 五屏样张回归中文排版、图片位置、保存恢复及分层 PSD;Photoshop 实际编辑另行验收,缺少环境时如实记录。
- 原生界面按 Impeccable critique / audit 检查布局、对比度、焦点、文案、溢出和反馈,保留实际窗口截图。
- 本次 Agent 停靠面板的局部 ship 裁定、真实流式调用与截图矩阵见 [Agent 面板验收](photocraft-agent-panel-acceptance-2026-10-21.md);不据此扩大为所有模型、系统辅助技术或完整客户端验收完成。
- 后续项目首页、删除、双模型及导航验收见 [本轮记录](photocraft-projects-agent-acceptance-2026-10-21.md),独立审查按对应截图和实际范围记录。
- 每次提交与发布以该次验收记录为准;设计标准不代表所有能力均已交付。同事表格的输入、输出和现有实现差距见[流程对照](photocraft-colleague-workflow-2026-10-23.md)。