65 lines
7.3 KiB
Markdown
65 lines
7.3 KiB
Markdown
# 详情页生成首版
|
||
|
||
入口：`/assets/detail-generator`。功能尚未正式验收，启用后仍只允许数据库中当前有效的超级管理员使用。页面、API、私有文件及后台模型调用共用实时门禁；一般管理员角色、旧登录状态和权限组均不能绕过。
|
||
|
||
## 使用流程
|
||
|
||
1. 新建个人项目，输入 SKU／SPU／条码、具体款式、产品名称及真实资料。可以上传产品图、参考图、品牌标志和 PDF／DOCX／TXT／Markdown 文档，也可关联当前可见的素材库图片。
|
||
2. 选择或保存品牌风格草案。品牌配置来自数据库；项目保存独立快照，后续修改草案不改变旧项目。
|
||
3. 分析资料，检查卖点、缺失信息和分屏大纲，确认后生成。每屏宽 750px，最多 12 屏。
|
||
4. 修改中文文字、替换图片或单屏重新生成，再保存和导出。改字不调用生图模型。较长文案自动重排；超出每屏 2400px 时须精简后确认。
|
||
5. 导出分屏 PNG／JPG（多屏 ZIP）、完整 PNG 长图、分层 PSD。PSD 每屏独立分组，文字保持原生可编辑文字层；AI 场景仍是一张整体图片，标志另设图层。
|
||
|
||
项目及文件按创建者隔离，不自动发布到素材库。产品资料、品牌或模型变更会使原大纲失效，清除旧生成屏，要求重新确认。
|
||
|
||
## 启用配置
|
||
|
||
默认关闭。发布前先完成项目标准备份和受控迁移，应用 `20261012_detail_generator`、`20261012_ai_model_registry` 及 `20261013_ai_model_capabilities`；禁止对生产使用 `prisma db push`。
|
||
|
||
```dotenv
|
||
DETAIL_GENERATOR_ENABLED=true
|
||
DETAIL_GENERATOR_BASE_URL=https://api.vip98k.com/v1
|
||
DETAIL_GENERATOR_API_KEY=由部署环境安全注入
|
||
DETAIL_GENERATOR_STORAGE_DIR=/app/detail-generator-private
|
||
```
|
||
|
||
私有目录必须独立于 `uploads` 和 `public`，持久挂载并授予运行账号写入权限；不得通过 Nginx 静态映射或 S3 公共域名暴露。蓝绿应用实例共用该私有卷和数据库。Docker 镜像包含独立 Node 22／Fabric 7.4.0／Canvas 3 渲染运行时，现有平台 Canvas 2 保持独立。本地另执行 `npm ci --prefix workers/detail-renderer`；导出调用该独立 CLI，本地 Node 需至少 22。
|
||
|
||
可选 `DETAIL_RENDERER_NODE`、`DETAIL_RENDERER_ENTRY`、`DETAIL_FONT_DIR` 分别指定独立 Node、CLI 和字体目录。完整 Noto Sans SC 字体及 OFL 许可位于 `public/detail-generator/fonts`；浏览器、渲染和 PSD 使用同一字体文件与真实 PostScript 名称。使用 Photoshop 的设备也需要安装这套字体。
|
||
|
||
模型连接、目录、用途及三个阶段默认值由数据库管理，入口为 `/admin` → 超级管理员 → **AI 模型接入**，详见 [管理说明](ai-model-management.md)。现有环境配置需通过“迁入当前连接”显式导入，保留原分析／文案 `gemini-2.5-flash` 与生图 `nano-banana-2` 的配置及旧项目绑定；`DETAIL_GENERATOR_VALIDATED_MODELS_JSON` 仅用于此次旧配置迁入，不再驱动运行时菜单。
|
||
|
||
同步目录查询 `/models` 和已适配的公开能力目录，新模型默认关闭；服务端先根据明确的输入、输出及接口能力限定用途，管理员只能在这个范围内选择向用户开放的模型。纯对话模型不能开放生图，未知能力不能通过人工确认解锁。用户在“模型选择”中自行选择已开放的模型；默认值不锁死用户选择。缺少可用默认值时可保存项目资料及编辑、导出已有内容，生成保持停用。新增上游或替换 API Key 使用项目专用 `API_KEY_ENCRYPTION_KEY` 加密，密钥不写入 Git、项目文档、浏览器或任务记录。
|
||
|
||
## 任务与故障处理
|
||
|
||
PostgreSQL 保存任务、幂等键、租约和检查点；全局最多同时 2 个任务，每人最多 1 个。启动后每 2 秒检查队列，执行期间续租。各屏图片与项目版本原子提交，恢复时跳过已保存屏。
|
||
|
||
模型请求发出后遇到超时、传输中断或结果未知错误，任务进入 `unknown`，保留可用的服务商请求编号及内部幂等键。不会自动换模型或用新请求编号重试；该项目暂停后续模型调用。管理员须在服务商核对调用结果及计费，保留证据后另行恢复，首版没有未经核查的“强制重试”按钮。已完成项目仍可导出。
|
||
|
||
权限撤销、账号停用或归档会阻止下一次模型调用。一个已经发送到服务商的请求无法由本平台撤回；收到的结果仍处于私有项目边界。
|
||
|
||
## 本地验证与正式验收
|
||
|
||
```powershell
|
||
npm run typecheck
|
||
npm test -- --runInBand --testPathPatterns=detail-generator
|
||
npm test --prefix workers/detail-renderer
|
||
node --test scripts/safe-production-migrate.test.mjs scripts/detail-generator-migration.test.mjs
|
||
```
|
||
|
||
`scripts/verify-detail-generator.ts` 只允许连接 `127.0.0.1:15437/detail_test` 隔离数据库。它使用合成账户、产品资料和模拟网关验证完整流程，生成实际图片与 PSD 文件，不调用真实模型；输出位于 Git 忽略的 `output/detail-generator`。真实迁移 SQL 也已在独立 schema 中执行验证。
|
||
|
||
## 2026-10-12 验证记录
|
||
|
||
- 77 项相关 Jest、17 个隔离 PostgreSQL 流程、16 项迁移检查、6 项独立原生渲染检查通过。完整生产构建通过；独立 Node 22 渲染器也在平台 Node 18 Alpine 运行环境中完成检查。
|
||
- 桌面与移动端已实际检查。Canvas 中文直接修改、保存、刷新恢复，侧栏及浏览器返回的未保存确认均已验证；普通管理员入口隐藏，页面、API、私有文件及旧会话撤权检查通过。Impeccable 独立复核给出本地内测 `ship`。
|
||
- 生产构建发现的切屏崩溃已修复：React 管理稳定画布容器，Fabric 独占其子节点；回归测试模拟真实 DOM 包装。修复后实际浏览器完成第 1→2→3→1 屏切换、原生 Canvas 中文编辑后直接保存与刷新恢复，没有新增控制台错误。证据见 `.impeccable/review/detail-generator-real-preview.jpg`。
|
||
- 按用户授权，从素材库只读选取朴美 `GBPM-AD0358` 同款两张 1500px 展示图片。品牌依据同型号素材的数据库店铺字段，未推测材质、尺寸、承重或认证；未写入生产数据库或更改下载统计。
|
||
- 实际网关调用完成 2 次 Gemini 分析/文案、3 次 Nano Banana 双参考图生成、1 次单屏重生成；没有自动重试。三屏采用同一字体与配色，目视检查了主要产品结构、木纹外观和整体调性；单屏重生成后其余两屏的图片标识保持不变。
|
||
- 实际导出分屏 PNG/JPG、750×3600 长图和 PSD。PSD 结构读回包含 3 个屏幕分组、6 个可编辑中文文字层。真实样例与执行记录位于本机 Git 忽略的 `output/detail-generator/real-result`，私有模型配置不进入 Git、Docker 上下文或浏览器脚本。
|
||
|
||
这一轮只覆盖一个产品、一个品牌风格草案及两张同款参考图。AI 对细节、构图和道具的还原仍须人工确认，不能把该样例视为所有品牌、全部屏数或全部参考图组合的质量承诺。
|
||
|
||
正式开放前仍需要 Photoshop 打开 PSD、修改文字、移动图层、换图、保存重开的实际验收，以及正式品牌规范确认。当前 PSD 写入读回、中文字体、图层与合成像素验证不能替代 Photoshop 实际编辑验收。生产提交／部署及正式扩大开放范围另按明确指令执行。
|