珠序 PearlStudio · 网页使用指南

适用版本：服务 v3.0.0（前端 app.js v30）· 更新日期 2026-09-24

本指南按"登录 → 新建作品 → 编辑珠位 → 保存导出 → 作品管理"的顺序介绍网页的全部功能，每一节都写明使用条件（谁能用、什么状态下可用、有哪些限制）。截图来自与生产环境同版本的开发机。

目录

1. 访问与环境要求
2. 登录与账号
3. 界面总览
4. 新建作品
5. 编辑珠位
6. 保存、导出与重新选型
7. 四种输出文件
8. 我的作品
9. 生成失败怎么办
10. API Token
11. 账号设置
12. 快捷键速查
13. 限制与常见问题

1. 访问与环境要求

⚠️ 当前为 HTTP 访问，密码和 Token 未加密传输。正式对外交付请走 HTTPS 入口。

2. 登录与账号

2.1 日常登录

• 用分配到的用户名和初始密码登录，登录后建议在"账号设置"里改密码。
• 登录有效期 12 小时，过期后刷新页面会回到登录页。
• 同一账号连续 10 次密码错误，会被锁定 15 分钟（提示"登录尝试过多，请 15 分钟后重试"）。
• 点左侧栏最下方 退出登录 可注销当前会话；如有未保存的珠位修改，会先弹窗确认。

2.2 作品库范围

作品库（第 8 节）只显示自己的作品，含自己账号下通过 API 提交的作品；看不到其他账号的作品。

3. 界面总览

左侧栏分两组：

• 创作空间
• 排布工作台：新建作品、编辑珠位、预览和导出（本指南第 4–7 节）。
• 我的作品：已生成作品的列表，右侧数字是作品总数（第 8 节）。
• 使用指南：弹出简要操作说明（见下图），底部 查看完整图文指南 在新标签页打开本指南。
• 管理：API Token、API 使用情况、账号设置、退出登录。

顶部面包屑显示当前页面；右上角是服务连接状态。

💡 地址栏会记录当前页面、作品、视图和工具（如 #/jobs/<作品ID>/effect?tool=add），可以直接收藏或发给同事，对方登录后打开即回到同一位置（仍受账号权限限制）。

4. 新建作品

工作台左侧的 新建作品 表单分三步。填完后点底部绿色按钮，系统会新建一件作品，完成后自动在右侧打开编辑器。

4.1 第 01 步：选择原图

上传方式：把图片拖进虚线框，或点击虚线框选择文件。不确定怎么用时，可以点页面右上角 使用示例图片 载入一张自带的金牛座珍珠图体验全流程。

图片要求（使用条件）：

图片类型（二选一）：

💡 选了"已有珍珠图"但系统一颗珍珠都识别不到时，会自动改用 AI 生成珠位重试，不需要手动切换。

商品编码（必填，最多 100 字符）：会印在编号排珠图顶部表格的 Number 栏（Item 栏固定为 Diamond Art），也用于下载文件的命名。上传图片后会自动用文件名预填，请改成真实的商品编码。

4.2 第 02 步：自动匹配珍珠尺寸

• 厂家色卡：宇航（259 个型号）或 勤彩（748 个型号）。切换厂家会重置下方规格。
• 已选规格列表：只显示当前已选的型号（默认 3 / 6 / 10 mm 那几个代表尺寸），每行可点 × 移除，保持简洁。至少保留一个，否则生成按钮不可用。
• ＋ 添加型号：点开弹窗，可按型号号码（如 A51）从该厂家全部型号里搜索勾选，不再局限于默认那几个；勾选即时生效，关闭弹窗后已选列表会更新。

- 这一栏同时是颜色匹配的候选池：按原图颜色逐颗匹配珍珠时，只会在已选型号里挑颜色最接近的一个；没选的型号即使色卡里有，也不会被用到。原图颜色多、想要更准的颜色还原时，先用“添加型号”把需要的颜色型号加进来。 - 自动选型规则：先按成品尺寸把原图珠径换算成毫米，再在不超过原图珠径的已选规格里选最大的一档。 - 例：已选 3 / 6 / 10 mm，原图某颗换算为 5.9 mm → 选 3 mm；为 6.2 mm → 选 6 mm。 - 比已选最小规格还小的珍珠，一律按最小规格处理，可能与原图细节有差异。 - 生成后在编辑器里也可以把任何一类珍珠换成同尺寸的其他颜色型号（见 5.7），不局限于生成前勾选的这些。 - 从“我的作品”点 重新出图（见第 8 节）载入表单时，这里会自动恢复该作品上次生成实际用到的型号组合，不会重置回默认的 3/6/10 mm。

4.3 第 03 步：设定成品尺寸

• 成品尺寸：预设 15×15、20×20、25×25、30×30、30×40、40×60 cm，或选 自定义 输入宽、高（每边 10–60 cm，可到 0.1 cm）。
• 成品尺寸包含四周各 2.5 cm 白边（用于放用料表格和贴钻说明），真正排珠的画面是 成品尺寸 − 5 cm。例如 30×40 cm 的成品，画面为 25×35 cm。表单下方会实时显示换算结果。
• 原图比例与画面不一致时会居中裁切，成品尺寸不会变。例如方图做 30×40 cm，会裁掉原图上下（或左右）多出的部分。
• 珠边净间距：相邻两颗珍珠边缘之间的最小空隙，0–5 mm，默认 0.25 mm。之后的编辑、保存都按这个间距校验。

4.4 生成与排队

点 识别珠位并替换（AI 模式下按钮为 生成珠位并替换）后，右侧显示任务进度：

• 生成按钮的使用条件：已选图片 + 已填商品编码 + 至少一个规格 + 服务已连接。
• 可以连续提交多个作品，不必等上一个完成；超出同时处理能力的会排队，前一个完成后自动继续。
• 每个账号同时排队 / 处理中的作品最多 20 个，超出会提示"您排队中的任务已达上限"；全站排队上限 200 个。
• 等待期间可以离开去看其他页面，作品库会自动刷新状态。

5. 编辑珠位

生成完成后，右侧是珠位编辑器。

从上到下依次是：

1. 标题栏：作品商品编码、状态标签、右侧保存状态（"已保存 · 版本 N" 或 "有未保存修改"）。
2. 视图标签：编辑珠位 / 效果图 / 编号排珠图 / 菲林图 / 用料统计（后四个见第 7 节）。
3. 工具栏（仅"编辑珠位"视图显示）。
4. 画布：白色区域是成品，虚线框内是可以放珍珠的画面区，虚线框外是白边，珍珠不能放进去。半透明底图是原图，便于对照。
5. 状态栏：厂家、成品及画面尺寸、当前操作提示。
6. 消息栏、保存 / 导出按钮。
7. 下方的 当前用料 表。

使用条件：只有状态为"可编辑"的作品才能编辑；正在保存或加载时所有工具暂时禁用。

5.1 工具栏

第一行 · 工具（括号内为快捷键）：

第二行 · 设置：

5.2 选择与移动

• 用 选择 工具点一颗珍珠，它会出现红圈，状态栏显示型号、尺寸和中心坐标（mm）；"当前材料"也会自动切换成这颗的型号。
• 按住拖动即可移动。移到会重叠、间距不足或越出虚线框的位置时，珍珠不会跟过去。
• 放大到一定程度后，每颗珍珠上会显示它在用料表中的编号。
• 按 Esc 取消选择。

5.3 单颗添加

1. 先在"当前材料"里选好型号和尺寸。
2. 切到 单颗 工具，鼠标移到画布上会出现预览圈：
3. 绿色 可放 / 已吸附 x mm · 可放：点击后添加。点击位置不合法时，会自动吸附到最近的合法位置。
4. 红色 冲突 / 越界 · 还差 x mm：附近放不下，需要换位置或换更小的尺寸。

5.4 路径排珠

按住拖出一条线，线上会预览将要放的珍珠：绿圈会被放下，红圈（与现有珍珠冲突）会被自动跳过。松开鼠标后完成，珠心间距 = 珠径 + 边缘间距。适合补轮廓线、边框。

5.5 擦除、套索删除

• 擦除：灰色圆圈是工具半径，按住拖过的区域内珍珠都会被删掉。
• 套索：按住画一个闭合区域，松开后删除圈内所有珍珠。

💡 套索圈过的区域会被记住，可以在"材料与区域"菜单里把上次套索圈内的珍珠换成当前材料（先删后撤销即可只用来圈选区域）。

5.6 批量补珠

鼠标悬停时显示"可补 N 颗"，点击后在工具半径内按最佳六方网格一次性补入"当前材料"珍珠，只补空位，不会挤动已有珍珠。没有空位时显示"无可用空位"。

5.7 更换珍珠型号 / 尺寸

有 5 种方式，按范围从小到大：

色卡弹窗（"更换此类"或"从色卡挑选"打开）：

• 顶部显示将要更换多少颗；可按型号搜索（如 A02）。
• 默认勾选 仅显示同尺寸：只换颜色，珠径不变，最安全。
• 取消勾选可以换成其他尺寸；换大后可能与邻珠冲突，冲突的珍珠会标红，需要调整后才能保存。批量替换 / 区域替换如果会造成冲突，会直接拒绝并提示"请改用更小珠径"。
• 点选一个型号后点 应用替换。

用料表实时显示编辑中的型号、珠径、数量和总颗数；未保存时标题为"当前编辑用料 · 待保存"。

5.8 冲突检查

• 重叠、净间距不足、越出虚线框的珍珠会标红，成对冲突之间有红色虚线；画布右上角弹出 珠位需要调整 面板，列出每处问题和差多少毫米。
• 点列表项或 定位下一处，画布会自动移到那颗珍珠并选中它。
• 有标红珍珠时不能保存；保存也不会自动帮你挪珍珠，需要手动移开、删除或换小尺寸。
• 随时可点 ✓ 全局校验 手动复查；通过时会显示"全局校验通过：N 颗珠位无重叠、无越界"。

5.9 未保存修改的暂存

编辑中的修改会自动暂存在当前浏览器里。意外关闭页面后重新打开这件作品，会提示"已恢复此浏览器中尚未保存的修改"。换浏览器、换电脑或退出登录后暂存会清空——正式文件以保存成功的版本为准，请及时保存。

6. 保存、导出与重新选型

保存说明

• 保存需要重新渲染 4 个文件，通常需要十几秒，期间按钮显示"正在保存…"。
• 如果同一作品在别处（另一个标签页或同事）已经保存过新版本，本次保存会被拒绝并提示"服务器已有更新版本"。此时当前修改仍保留在浏览器里，请先记下需要保留的修改，再点 载入已保存版本。
• 历史版本都会保留，但网页上只能打开最新版本。

ZIP 生产包内容（以商品编码 B07、25×25 cm 为例）：

B07-珍珠排布生产包-25x25cm.zip
├── B07-01-用料统计-25x25cm.png
├── B07-02-效果图-25x25cm.jpg
├── B07-03-菲林图-25x25cm.png
├── B07-04-编号排珠图-25x25cm.png
└── B07-05-用料汇总-25x25cm.xlsx

所有图片为 300 DPI。打印时请选择 100% / 实际尺寸，不要"适合页面"。

按原图重新选型（间距 0）

用于早期作品珠子选大、位置被推偏的情况。点击后会弹窗确认，然后：按原图重新识别 → 按向下取档规则重新选规格 → 净间距设为 0 → 重新排布并出图。

• ⚠️ 当前的手动珠位和换料修改都会被新排布替换（历史版本仍保留）。
• 不占用可生成次数。

7. 四种输出文件

切换编辑器上方的视图标签即可预览最近一次已保存版本的输出（有未保存修改时，预览仍是旧版本，保存后更新）。

7.1 效果图

用所选厂家该型号的真实样品照片合成的成品效果，便于给客户确认。

AI 模式生成的作品效果示例：

7.2 编号排珠图

生产用图纸：成品尺寸含白边，顶部表格印 Item（Diamond Art）/ Number（商品编码）/ Size，两侧是珍珠编号表，底部是贴钻步骤说明，画面中每颗珍珠标注用料编号。

7.3 菲林图

用于制版的黑白图，只保留珍珠位置和大小。

7.4 用料统计

每种型号的编号、珠径和数量，以及总颗数。ZIP 中另有同内容的 Excel（用料汇总 .xlsx）。

8. 我的作品

• 只显示自己账号下的作品，含通过 API 提交的。
• 按最近更新排序，每页 5 / 10 / 20 / 50 条（在底部切换，选择会被记住），超过一页时显示翻页。
• 列表中有排队或处理中的作品时，每 3 秒自动刷新。

卡片信息：效果图缩略图、商品编码、成品尺寸 · 厂家、珍珠总数 · 出图耗时 · 更新时间、状态标签（含版本号）。

卡片操作：

普通用户的作品库只有自己的作品：

9. 生成失败怎么办

消息栏会显示失败原因，下方出现恢复按钮：

常见失败原因：

• 未识别到珍珠：原图太模糊或珍珠太小。换更清晰的原图，或用"手动补珠"。（"已有珍珠图"模式下识别不到时通常会自动改用 AI 生成，很少走到这一步。）
• 点阵生成失败：AI 生成服务暂时不可用，稍后点"重新识别"。
• 服务内部错误：请联系技术支持处理。
• 可生成次数已用完：每个账号有可生成次数，网页新建和 API 调用合计，每成功生成一张新图算一次（排队中的任务会先占用次数；保存珠位、重新选型、手动补珠不算）。用完后新建作品和"重新识别"都会被拒绝，请联系技术支持增加次数。

10. API Token

Token 用于客户系统通过 API 调用出图（不能用来登录网页）。

创建：填名称（如"网店系统 / 正式环境"）→ 有效天数（1–3650，默认 90）→ 创建 Token。

• ⚠️ 完整 Token 只显示这一次。点 复制 Token 后交给对应用户；服务器只存哈希，丢失后无法找回，只能撤销后重建。
• 点 我已保存，关闭显示 或切换页面后完整值即消失。

• 列表显示名称、前缀、所属用户、到期时间、状态。默认只显示有效 Token，勾选 显示已撤销 / 已过期的 Token 可查看全部。
• 撤销：立即失效，不可恢复。
• 调用方式：请求头 Authorization: Bearer <TOKEN>；查询、原图、预览、下载也都要带这个请求头。不要把 Token 放进 URL。
• 登录后访问 /pearl/api/v2/docs 可查看 Swagger 接口文档，点 Authorize 填入 Token 试调。
• Token 不能用来调用账号和 Token 管理接口，这些只接受网页登录。

11. 账号设置

页面顶部显示当前用户名和角色。输入原密码和新密码（≥ 10 位）点 修改密码。修改成功后，该账号在其他地方的登录会被全部注销，当前页面保持登录。

12. 快捷键速查

编辑器获得焦点、且未在输入框中打字、没有弹窗时生效：

（macOS 上 Ctrl 可换成 ⌘。）

13. 限制与常见问题

限制汇总

常见问题

• 生成按钮是灰的？ 检查：是否已选图片、商品编码是否填写、是否至少勾选了一个规格、右上角是否"服务已连接"。
• 保存按钮是灰的？ 没有修改，或者有标红的冲突珍珠（看画布右上角的冲突面板）。
• 成品图和原图构图不一样？ 原图比例与画面比例不一致时会居中裁切，请上传与画面比例一致的原图（画面 = 成品尺寸 − 5 cm）。
• 珍珠放不上去 / 拖不动？ 目标位置会重叠、间距不足或越出虚线框。缩小"当前材料"尺寸，或先腾出空间。
• "边缘间距"改不小？ 不能比作品生成时的净间距更小，这是保存时的校验标准。如需更密，用"按原图重新选型（间距 0）"或以更小间距"重新出图"。
• 效果图没变化？ 效果图、编号图等预览显示的是已保存版本，修改后需要先保存。
• 打印尺寸不对？ 打印时选择 100% / 实际尺寸。
• 想修改已完成作品的尺寸、厂家、规格？ 在作品库点 重新出图，改参数后生成（会生成一件新作品）。
• 提示"服务器已有更新版本"？ 这件作品在别处被保存过。先记下需要保留的修改，再点"载入已保存版本"后重做。