docs: add project readme

README.md

@@ -0,0 +1,171 @@
+# 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 返回的远程地址。