黔景智作（QianScape AI / QSAI）是面向文旅运营人员的多页面素材创作产品。用户在主页选择工作流，输入一句话并按模板需要添加图片后即可生成；默认 Mock 链路无需模型密钥。
npm install
npm run dev前端地址为 http://localhost:5173，后端地址为 http://localhost:8787。
真实模型模式：在 .env 配置 COPY_API_KEY 与 IMAGE_API_KEY 后运行 PROVIDER_MODE=real npm run dev。文案走智谱 GLM，图片走第三方中转；中转方可以看到提示词与图片内容，请勿提交敏感素材。密钥仅保存在服务端，不会进入前端构建产物。真实生成通常需要数十秒到数分钟，提交后可切换页面或刷新，后台任务会继续执行。
| 类别 | 技术选型 | 说明 |
|---|---|---|
| UI 框架 | React 19 | 组件化界面，配合 React Router DOM 7 实现多页面路由 |
| 语言 | TypeScript 5.9 | 全仓严格类型检查 |
| 构建工具 | Vite 7 | 开发热更新与生产构建 |
| 图标 | Phosphor Icons React | 统一视觉图标体系 |
| 本地历史 | idb（IndexedDB） | 结果与参考图副本按工作流存本机，保留最近 20 条 |
| 素材打包 | JSZip | 前端生成包含文案与图片的 ZIP 素材包 |
| 前端测试 | Vitest + Testing Library + jsdom + fake-indexeddb | 组件渲染与 IndexedDB 相关逻辑测试 |
前端按 app / pages / features / components / config / styles 分层组织，API 层统一做响应校验、30s 超时与业务错误白名单传递。
| 类别 | 技术选型 | 说明 |
|---|---|---|
| 运行环境 | Node.js + tsx | TypeScript 源码直接运行，无需预编译 |
| Web 框架 | Express 5 | API 服务与静态资源托管 |
| 文件上传 | multer | 参考图 / 产品图 multipart 上传 |
| 图片处理 | sharp | 图片校验与格式处理 |
| 参数校验 | Zod 4 | 请求体与 Provider 响应结构校验 |
| 环境配置 | dotenv | .env 管理密钥与运行模式 |
| API 测试 | supertest | 后端接口集成测试 |
后端按 config / http / routes / services / storage / workflows / providers 模块化组织，支持模板注册、四工作流编排与部分成功聚合。
| 能力 | 模型 | 提供方 |
|---|---|---|
| 文案生成 | GLM（glm-5.3-flash） | 智谱 AI 开放平台 |
| 联网搜索 | web-search-pro（search_pro 引擎） | 智谱 AI 开放平台 |
| 图像生成 | gpt-image-2 | 第三方 API 中转站 |
| 视觉分析 | gpt-5.5 | 第三方 API 中转站 |
Provider 层提供 Mock / Real 双模式：Mock 无需任何密钥即可跑通全流程；Real 模式通过 .env 切换，密钥仅存于服务端。
| 类别 | 技术选型 |
|---|---|
| 代码规范 | ESLint + typescript-eslint |
| 单元 / 集成测试 | Vitest（前端组件 + 后端 API 共 470+ 用例） |
| 并行启动 | concurrently（一键同时跑前后端） |
| 版本管理 | Git / GitHub |
| 模板 | 输入 | 输出 |
|---|---|---|
| 小红书图鉴创作 | 含 2～36 数量的选题（如“贵阳的12种美食”），最多 4 张参考图 | 图鉴封面与正文页、3 个候选标题、发布正文与标签、清单 JSON |
| 原创 IP 商品化 | 一张产品图 + 产品描述（首次需初始化并锁定 IP 档案） | 品牌主视觉、识别系统、商品包装、场景应用四张 3:4 图、可选 2×2 总览图与发布文案 |
| 目的地手绘攻略 | 目的地短语（城市或景点，如“成都”），无需参考图 | 攻略封面、每日路线页、交通/住宿/美食页（1～3 天）、行程 JSON、发布文案 |
| 照片心情图集 | 1～7 张游客返图 + 可选活动主题与投稿昵称 | 一图一海报、整组共同情绪、3 个候选标题与心情文案 |
图鉴参考图只影响画面视觉，不改变清单事实；手绘攻略通过智谱联网检索获取目的地实时资料，检索失败自动降级为常识性建议并提示；游客返图每张海报只使用自己的照片，单张失败自动重跑且不影响其他海报。
| 路由 | 页面 |
|---|---|
/ |
一句话生成主页；先明确选择工作流再提交 |
/templates |
全部模板 |
/templates/:templateId |
模板详情 |
/templates/original-ip/create |
原创 IP 首次档案配置与兼容创建入口 |
/templates/travel-guide/create |
手绘攻略创建表单 |
/templates/ugc-photo-campaign/create |
照片心情图集创建表单 |
/results/:requestId |
当前生成结果 |
/history |
本机历史 |
/history/:recordId |
历史结果详情 |
- 参考图支持 JPG、PNG、WebP，单张不超过 10MB；原创 IP 每次生成上传 1 张产品图，图鉴最多 4 张，游客返图 1～7 张，手绘攻略不需要参考图。
- 上传后的参考图持久保存在后端
data/reference-assets/；生成完成后不会自动删除。 - 完整生成结果和参考图本地副本保存在当前浏览器 IndexedDB（v2，按工作流存储），按保存时间保留最近 20 条。
- 清空或删除本机历史只影响当前浏览器，不会删除后端参考图或已经下载的文件。
- 刷新
/results/:requestId或打开历史详情时，页面会从 IndexedDB 恢复已有结果，不会重新请求生成。 - 从历史重新生成时，产品描述/选题/目的地/活动主题自动预填，本地图随历史恢复，可直接再次生成。
- 主页通过
/api/generation-jobs创建后台任务，接口立即返回jobId；前端按真实阶段展示整理选题、内容、文案、图片和结果收尾状态。 - 生成中可进入全部模板或历史页；顶部历史图标旁会显示运行、完成或失败状态。刷新后使用同一
jobId恢复轮询，不会重复调用模型。 - 同一浏览器在一个非终态任务存在时拒绝重复创建；创建过程使用浏览器跨标签互斥，减少重复真实调用和费用风险。
- 后端任务快照位于
data/generation-jobs/，仅用于 24 小时内的状态恢复，不是业务历史；完整图片与文案历史仍只保存在当前浏览器 IndexedDB。 - 第一版不提供真实上游取消：离开页面、关闭标签或删除本机历史均不会撤销第三方模型请求。
- IndexedDB 不可用时，当前任务仍继续轮询并可查看结果；完整本机历史保存失败会单独提示，不影响生成结果和下载。
- 标题（图鉴、手绘攻略、游客返图为候选标题）、正文和标签可分别复制；手绘攻略结果页额外展示行程概览与逐日路线，游客返图结果页展示共同情绪与活动主题。
- 成功图片可单独下载，也可下载包含文案和图片的 ZIP 素材包；图鉴素材包额外包含
发布文案.txt与清单.json，手绘攻略素材包额外包含行程.json。 - 部分图片失败时，ZIP 仅包含成功图片和完整文案；全部图片失败时仍可查看并下载文案。
四工作流、新版正式首页和后台生成任务链路均已交付。2026-08-30 已通过 36 个测试文件、475 个用例、类型检查、lint、生产构建、Mock 异步 API 验收，并使用真实 Provider 完成“2个贵州景点”的跨页面、刷新恢复、2/2 图片生成与单条历史验收；构建仅保留现有主包超过 500kB 的非阻断提醒。验证记录见 tasks/acceptance-双工作流.md、tasks/acceptance-四工作流.md 和 Phase 3 文档。