# Hyreal Gen Pic · 门店装修工具

门店装修工具（淘宝闪购专业版）是一个本地 Web 应用，把「门店菜品采集」和「AI 视觉生成」放在统一界面中。两个能力保持独立入口，可以单独使用，也可以按“采集菜品 → 生成门店视觉资产 → 管理历史作品”的流程连续使用。

## 功能概览

### 门店采集

- 通过淘宝闪购后台 Cookie 按店铺批量读取菜品图片和名称。
- 支持手动维护店铺清单、勾选店铺、开始/停止采集。
- 默认跳过已完成的店铺，可开启“强制全量抓取”重新下载。
- 提供进度列表、任务日志和系统日志，便于定位 Cookie 过期、下载失败等问题。

### 视觉生成

- 自动扫描输出根目录下的门店，支持“全量扫描”或指定门店扫描。
- 按步骤生成 LOGO、海报、招牌、贴纸等门店视觉资产。
- 支持菜品商品图批量生成，可叠加门店 LOGO，并按菜品维护自定义提示词。
- 生成结果会下载到门店目录，同时保留 API 返回的远程地址。

### 历史创作

- 以图片墙展示历史作品，默认一行 8 个。
- 支持悬浮放大预览和悬浮下载。
- 重复生成会追加记录；历史列表读取并保留最近 48 小时内的记录。

## 环境要求

- Node.js 18 或更高版本。
- 可访问图片生成服务的 API Key。
- 如需采集功能，需要具备淘宝闪购后台访问权限的有效 Cookie（必须包含 `ksid`）。

## 快速开始

1. 安装依赖：

   ```bash
   npm install
   ```

2. 创建本地配置：

   ```bash
   cp config.example.json config.json
   ```

3. 编辑 `config.json`，至少填写 `apiKey`。也可以启动后在“系统设置”中填写。

4. 启动服务：

   ```bash
   npm start
   ```

   或使用平台脚本：

   - macOS：双击 `启动.command`，或执行 `./启动.command`
   - Windows：双击 `启动.bat`
   - Linux/macOS：执行 `./启动.sh`

5. 打开 `http://localhost:5177`。若修改了 `port`，请访问对应端口。

## 系统设置

| 配置 | 说明 |
| --- | --- |
| `apiKey` | 图片生成服务密钥。界面中会脱敏显示，重新输入新值即可更新。 |
| `apiBase` | 图片生成服务地址。当前固定为 `https://api.lk888.ai`，界面中不可修改。 |
| `model` | 默认生成模型，例如 `gpt-image-2`。可在系统设置中切换。 |
| `rootDir` | 门店数据与生成结果的输出根目录。默认使用项目上一级的 `workspace` 目录。 |
| `pageSize` | 门店采集时每一页请求的菜品数量，范围 `1-200`。 |
| `delayMs` | 采集下载间隔，范围 `0-60000` 毫秒。 |
| `maxConcurrentJobs` | 同时进行的生成任务数量。 |
| `requestTimeoutMs` | 生成服务请求超时时间，单位毫秒。 |
| Cookie | 用于淘宝闪购后台采集，仅保存在本地 `session.json`。 |

API Key 获取与充值入口可在“系统设置 → API 设置”中打开。

## 输出目录结构

默认输出根目录为：

```text
<项目上一级>/workspace
```

单个门店目录结构类似：

```text
workspace/
  001_门店名称_店铺ID/
    菜品原图.jpg
    _菜品图爬取记录.json
    _生成图片/
      logo.png
      店内海报_1138x292.png
      招牌头图_750x288.png
      菜品图/
        菜品名称.png
      generation-history.json
```

生成结果的本地文件可能因为重新生成被覆盖；`generation-history.json` 会追加保存远程结果地址，用于历史创作页恢复和下载。

## 使用流程

1. 进入 **系统设置**，配置 API Key、默认模型、输出根目录和采集 Cookie。
2. 进入 **门店采集**，添加店铺并勾选需要采集的门店。
3. 开始采集后，系统会把菜品原图保存到输出根目录。
4. 进入 **视觉生成**，选择全量扫描或指定门店扫描。
5. 按界面步骤先生成 LOGO，再生成其他视觉资产和菜品商品图。
6. 到 **历史创作** 中检索、预览和下载已生成的作品。

## 支持的生成模型

- `gpt-image-2`
- `gpt-image-2-guan`
- `doubao-seedream-5-0-pro-260628`
- `doubao-seedream-5-0-260128`
- `doubao-seedream-4-5-251128`
- `wan2.6-image`

## 项目结构

```text
.
├── server.js              # 本地服务、采集调度、生成队列和历史 API
├── public/
│   ├── index.html          # 应用外壳和页面结构
│   ├── app.js              # 导航、启动画面和系统设置
│   ├── crawl.js            # 门店采集界面逻辑
│   ├── gen.js              # 视觉生成界面逻辑
│   ├── history.js          # 历史创作界面逻辑
│   └── style.css           # 统一视觉系统
├── config.example.json     # 配置模板
├── 启动.command            # macOS 启动脚本
├── 启动.bat                # Windows 启动脚本
└── 启动.sh                 # Linux/macOS 启动脚本
```

## 本地数据与安全

以下文件包含本机运行数据或密钥，默认不会被 Git 提交：

```text
config.json
session.json
manual-shops.json
output/
workspace/
```

请勿将 API Key、后台 Cookie 或门店数据提交到 Git。采集功能只应操作你有权管理的店铺，并遵守平台条款与当地法规。

## 常见问题

### 采集提示 Cookie 过期或缺少 ksid

重新登录淘宝闪购后台，复制完整 Cookie，并到“系统设置 → 采集配置”更新。

### 视觉生成页面找不到门店

确认“系统设置”中的输出根目录正确；门店目录必须直接位于该根目录下，并且目录内有菜品图片或已生成的 `_生成图片` 目录。

### 生成任务一直排队

检查 `maxConcurrentJobs` 是否过小，或等待已有任务完成。生成服务也可能存在限流或临时不可用。

### 历史作品消失

历史创作列表只显示最近 48 小时内的记录。本地文件被重新生成覆盖时，页面会优先使用 API 返回的远程地址。