auto-save 2026-05-26 07:04 (~4)

2026-05-26 07:04:39 +08:00
parent c9d8fa7139
commit d803d65c0c
4 changed files with 86 additions and 33 deletions
--- a/docs/source-analysis.html
+++ b/docs/source-analysis.html
@@ -541,12 +541,12 @@
            <tr>
              <td>画布构建</td>
              <td><code>cd web && npm run build</code></td>
-              <td>受同一登录保护的 Vue / Vite 画布应用。构建时先执行 <code>pnpm build:canvas</code> 生成 <code>web/canvas-app/dist</code>，再执行 Next 静态导出，最后由 <code>web/scripts/sync-canvas-root.mjs</code> 把画布产物覆盖到 <code>web/out</code> 根目录；Nginx 登录校验后的 <code>/</code> fallback 到画布 <code>index.html</code>，<code>/canvas/</code> 只做 308 兼容跳转。画布项目当前保存在浏览器 <code>localStorage</code>，生成出来的图片 / 视频资产通过本项目 <code>/api</code> 写入当前登录用户自己的后端 job。</td>
+              <td>受同一登录保护的 Vue / Vite 画布应用。构建时先执行 <code>pnpm build:canvas</code> 生成 <code>web/canvas-app/dist</code>，再执行 Next 静态导出，最后由 <code>web/scripts/sync-canvas-root.mjs</code> 把画布产物覆盖到 <code>web/out</code> 根目录；Nginx 登录校验后的 <code>/</code> fallback 到画布 <code>index.html</code>，<code>/canvas/</code> 只做 308 兼容跳转。画布项目以服务端 Postgres 为主持久化，浏览器 <code>localStorage</code> 只作为缓存和首次导入来源；生成出来的图片 / 视频资产通过本项目 <code>/api</code> 写入当前登录用户自己的后端 job。</td>
            </tr>
            <tr>
              <td>生产部署</td>
              <td><code>./scripts/deploy-prod-safe.sh</code></td>
-              <td>服务器目录为 <code>/opt/skg-marketing-studio</code>；后端任务文件挂载到 <code>./data/jobs</code>，全局资源中心挂载到 <code>./data/asset_library</code>、<code>./data/prompt_library</code> 和 <code>./data/_trash</code>，真实 Key 只放服务器 <code>deploy/.env.production</code>。生产部署唯一入口是 <code>deploy-prod-safe.sh</code>：先备份服务器 env、案例和资源库，再用 protect/exclude 保护 <code>data/</code>、<code>jobs/</code>、<code>secrets/</code>、<code>deploy/.env.production</code> 后同步代码，最后 Docker 重建并跑 <code>verify-prod-docker.sh</code>。禁止再用裸 <code>rsync --delete</code> 手动同步。</td>
+              <td>服务器目录为 <code>/opt/skg-marketing-studio</code>；后端任务文件挂载到 <code>./data/jobs</code>，全局资源中心挂载到 <code>./data/asset_library</code>、<code>./data/prompt_library</code> 和 <code>./data/_trash</code>，Postgres 数据目录为 <code>./data/postgres</code>，真实 Key 和数据库密码只放服务器 <code>deploy/.env.production</code>。生产部署唯一入口是 <code>deploy-prod-safe.sh</code>：先备份服务器 env、案例、资源库和 secrets，如 Postgres 容器存在则额外导出 <code>pg_dump</code>，再用 protect/exclude 保护 <code>data/</code>、<code>jobs/</code>、<code>secrets/</code>、<code>deploy/.env.production</code> 后同步代码，最后 Docker 重建并跑 <code>verify-prod-docker.sh</code>。禁止再用裸 <code>rsync --delete</code> 手动同步。</td>
            </tr>
            <tr>
              <td>前端开发服务</td>
@@ -581,16 +581,17 @@
          <p><strong>2026-05-25 根域名画布版：</strong><code>https://marketing.skg.com</code> 登录后直接进入个人生成画布，不再先进入 React 单对话框首页再点画布；<code>/canvas/</code> 只保留为旧链接兼容跳转。后续优先少改成熟画布结构，只在必要时改模式文案、生成接入和结果/队列显示。</p>
          <p><strong>2026-05-25 上游能力恢复版：</strong>用户明确要求“API 没关系，其他恢复，别削弱”。因此根域名画布恢复 <code>chatfire-AI/huobao-canvas</code> 的成熟节点和工作流结构：推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置、多角度分镜、故事板、绘本和批量下载都保留；只继续替换品牌、路由和 API 接入。生成请求仍走 SKG 后端 <code>/api</code> 与登录 Cookie，员工不需要个人 API Key。</p>
          <p><strong>2026-05-25 媒体模型接入收口：</strong>图片和视频模型选择只暴露当前后端真实可用项：图片为 <code>auto</code>、<code>gpt-image-2</code>、<code>gemini-3-pro-image-preview</code>；视频当前只接通 <code>Seedance 2.0 Fast</code>（真实模型 <code>doubao-seedance-2-0-fast-260128</code>）。旧上游的 Nano Banana、Seedream、Kling、Veo 或浏览器本地自定义媒体模型不能进入生成下拉，避免同事选到实际不可用的模型。</p>
+          <p><strong>2026-05-26 公司沉淀版：</strong>画布项目从浏览器本地存储升级为服务端 Postgres 持久化；<code>localStorage</code> 只作为离线缓存和首次导入来源。后端同时建立用户、任务、资源索引和审计表，保留原有 <code>state.json</code> 文件作为任务详情真源，避免一次迁移动到大文件资产结构。</p>
        </div>
-        <p>当前默认业务管线是“个人隔离任务 → 根域名进入个人画布 → 用提示词、推荐词、AI 润色或工作流模板创建节点 → 画布自动执行或手动连接图片/视频/文本节点 → 生成结果沉淀在当前个人画布 → 需要时进入详情页继续编辑”。画布不再被削成三模式入口；首帧、尾帧、参考图、图生视频、多角度分镜、故事板和绘本等上游概念按节点能力保留。底层生成仍由 <code>web/canvas-app/src/hooks/useApi.js</code> 适配到本项目 <code>/creative/jobs/image</code>、<code>/jobs/{id}/frames/{idx}/generate</code>、<code>/jobs/{id}/frames/{idx}/storyboard/video</code>，并按当前登录用户写入个人 job。图片尺寸只显示 <code>auto</code>、<code>1024x1536</code>、<code>1024x1024</code>、<code>1536x1024</code>；视频画幅只显示 <code>720x1280</code>、<code>1280x720</code>、<code>1024x1024</code>、<code>960x1280</code>；视频时长只显示 <code>5/8/10/12/15</code> 秒。多人互不影响依赖后端 <code>owner_id</code> 和飞书 / 备用登录会话隔离。旧 React 单对话框首页、信息流复刻链路仍保留在源码里作为回滚/高级能力，但不作为生产默认入口。</p>
+        <p>当前默认业务管线是“个人隔离任务 → 根域名进入个人画布 → 画布项目同步到服务端 Postgres → 用提示词、推荐词、AI 润色或工作流模板创建节点 → 画布自动执行或手动连接图片/视频/文本节点 → 生成结果沉淀在当前个人画布 → 需要时进入详情页继续编辑”。画布不再被削成三模式入口；首帧、尾帧、参考图、图生视频、多角度分镜、故事板和绘本等上游概念按节点能力保留。底层生成仍由 <code>web/canvas-app/src/hooks/useApi.js</code> 适配到本项目 <code>/creative/jobs/image</code>、<code>/jobs/{id}/frames/{idx}/generate</code>、<code>/jobs/{id}/frames/{idx}/storyboard/video</code>，并按当前登录用户写入个人 job。图片尺寸只显示 <code>auto</code>、<code>1024x1536</code>、<code>1024x1024</code>、<code>1536x1024</code>；视频画幅只显示 <code>720x1280</code>、<code>1280x720</code>、<code>1024x1024</code>、<code>960x1280</code>；视频时长只显示 <code>5/8/10/12/15</code> 秒。多人互不影响依赖后端 <code>owner_id</code>、画布项目 owner 和飞书 / 备用登录会话隔离。旧 React 单对话框首页、信息流复刻链路仍保留在源码里作为回滚/高级能力，但不作为生产默认入口。</p>
        <div class="pipeline">
          <div class="step"><div class="num">01</div><h3>个人任务</h3><p><code>GET /jobs</code> 按当前登录用户过滤；旧无 owner 任务只对备用账号可见。</p></div>
-          <div class="step"><div class="num">02</div><h3>进入画布</h3><p>用户直接在根域名个人画布里操作，上游项目列表、推荐词、节点菜单、工作流模板和批量下载能力保留。</p></div>
+          <div class="step"><div class="num">02</div><h3>进入画布</h3><p>用户直接在根域名个人画布里操作；项目列表优先读取服务端 <code>/canvas-projects</code>，本地旧项目会首次导入。</p></div>
          <div class="step"><div class="num">03</div><h3>组织节点</h3><p>可通过底部 prompt、AI 润色、自动执行、手动添加节点或工作流模板创建文本、图片、视频、LLM、配置和参考图节点。</p></div>
          <div class="step"><div class="num">04</div><h3>参考素材</h3><p>首帧、尾帧、参考图和图片节点按上游节点语义保留；提交到后端时由 <code>useApi.js</code> 转成 <code>first_image</code>、<code>last_image</code> 或图片编辑参考。</p></div>
          <div class="step"><div class="num">05</div><h3>工作流执行</h3><p>自动执行会根据提示词创建文生图、图转视频、故事板、多角度分镜或绘本等节点组；手动模式下用户可自行连接节点。</p></div>
          <div class="step"><div class="num">06</div><h3>生成图片 / 视频</h3><p><code>generateImage</code> 和 <code>generateStoryboardVideo</code> 继续走 SKG 后端 <code>/api</code>；视频提交后先写入 <code>queued</code> 占位，再由后端队列按并发上限启动。</p></div>
-          <div class="step"><div class="num">07</div><h3>结果沉淀</h3><p>生成图、视频 URL、任务状态和下载入口回填到画布节点；完整任务结果仍可进入 <code>/detail/?job=</code> 查看。</p></div>
+          <div class="step"><div class="num">07</div><h3>结果沉淀</h3><p>生成图、视频 URL、任务状态和下载入口回填到画布节点；画布结构保存到 Postgres，完整任务结果仍可进入 <code>/detail/?job=</code> 查看。</p></div>
          <div class="step"><div class="num">08</div><h3>详情页</h3><p><code>/detail/?job=&lt;id&gt;</code> 展示参考图、全量生成图、视频候选、提示词和营销图文，并支持继续生成。</p></div>
          <div class="step"><div class="num">09</div><h3>高级复刻</h3><p>旧 <code>AdRecreationBoard</code> 与 <code>/agent/</code> 作为高级入口保留，不再是默认路径。</p></div>
        </div>
@@ -606,7 +607,8 @@
                <tr><td><code>web/next.config.mjs</code></td><td>Next.js 构建配置：静态导出、图片不走优化、禁用开发环境左下角 Next Dev Indicator，并移除 Next 16 已不支持的 <code>eslint</code> 顶层配置，避免本地 dev 出现配置 Issue 提示。</td></tr>
                <tr><td><code>web/app/globals.css</code></td><td>全局主题变量、登录页视觉样式、信息流工作台玻璃拟态 token、ReactFlow 样式引用，以及本地开发态 <code>nextjs-portal</code> 遮挡隐藏规则。工作台在 <code>skg-board-theme</code> 内按 Figma 本地 MCP 参考改成黑灰玻璃系统：深灰背景、<code>#383838</code> 胶囊侧栏、<code>rgba(255,255,255,.1)</code> 玻璃面、<code>backdrop-filter: blur(5px)</code>、<code>20px</code> 圆角、<code>10px 10px 10px rgba(0,0,0,.3)</code> 阴影和绿黄状态色；新增 <code>skg-board-shell</code>、<code>skg-board-rail</code>、<code>skg-glass-card</code>、<code>skg-glass-card--flat</code>、<code>skg-status-orb</code> 等样式。侧栏改为跟随视口拉满工作台可用高度的悬停胶囊，桌面最小 600px，展开时在同一侧栏内承载素材输入抽屉。明暗主题已分开维护 shell、panel、glass、stat、action 和音频波形 token；暗色压低灰雾和面板底色，明亮模式改为暖白工作台，避免指标卡、按钮和波形继续残留黑底/白线；顶部指标卡增加紫、黄绿、琥珀、青绿、绿色光斑变量，接近原版多色玻璃卡效果。主/次按钮、指标卡和空状态继续走统一类，避免各板块散写不同玻璃效果。</td></tr>
                <tr><td><code>web/app/page.tsx</code></td><td>旧 React 单对话框生成台源码仍保留，便于以后回滚或抽能力；当前生产根域名已经由 <code>web/canvas-app/</code> 画布产物覆盖，不再把这个 React 首页作为默认首屏。该页面里的模式也已收敛为文生图、文生视频、图生视频；图生视频只显示“上传图片”，不把“首帧/首尾帧”作为用户入口。旧 TK 复刻工作台组件仍保留在 <code>web/components/ad-recreation-board.tsx</code>，但不再作为默认首页渲染。</td></tr>
-                <tr><td><code>web/canvas-app/</code></td><td>SKG 内部画布应用：从 <code>chatfire-AI/huobao-canvas</code> 交互逻辑改造而来。当前策略是“保留成熟画布能力，替换品牌/路由/API”：Vue Flow 节点画布、项目列表、推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置节点、模型配置和批量下载都保留；可见品牌收敛为 SKG logo，不展示上游注册链接或外部品牌。生产路径固定为根域名 <code>/</code>，内部路由用 <code>/p/:id?</code>；来源说明保存在 <code>THIRD_PARTY_NOTICES.md</code>，不展示给终端用户。</td></tr>
+                <tr><td><code>web/canvas-app/</code></td><td>SKG 内部画布应用：从 <code>chatfire-AI/huobao-canvas</code> 交互逻辑改造而来。当前策略是“保留成熟画布能力，替换品牌/路由/API”：Vue Flow 节点画布、项目列表、推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置节点、模型配置和批量下载都保留；可见品牌收敛为 SKG logo，不展示上游注册链接或外部品牌。生产路径固定为根域名 <code>/</code>，内部路由用 <code>/p/:id?</code>；项目列表和画布 JSON 优先同步到服务端 Postgres，浏览器本地存储只是缓存/导入来源；来源说明保存在 <code>THIRD_PARTY_NOTICES.md</code>，不展示给终端用户。</td></tr>
+                <tr><td><code>web/canvas-app/src/stores/projects.js</code></td><td>画布项目 Pinia store：启动时先读本地 <code>localStorage["ai-canvas-projects"]</code> 作为缓存，再调用 <code>GET /canvas-projects</code> 拉服务端项目；如果发现本地旧项目，会调用 <code>POST /canvas-projects/import</code> 导入到当前登录用户。新建、重命名、画布节点变更、复制和删除会同步到 <code>/canvas-projects</code>，本地缓存只用于快速打开和网络异常兜底。</td></tr>
                <tr><td><code>web/canvas-app/src/views/Canvas.vue</code></td><td>画布主交互：恢复上游底部 prompt composer、<code>AI 润色</code>、<code>自动执行</code>、推荐词、节点菜单、工作流面板、API/模型设置入口和批量下载入口。自动执行会调用 <code>useWorkflowOrchestrator</code> 分析提示词，创建文生图、图转视频、故事板、多角度分镜或绘本节点组；手动模式只创建文本节点，用户自行连接节点。</td></tr>
                <tr><td><code>web/canvas-app/src/config/models.js</code></td><td>画布媒体模型和规格的前端白名单：图片只内置 <code>auto</code>、<code>gpt-image-2</code>、<code>gemini-3-pro-image-preview</code>，尺寸只内置 <code>auto</code>、<code>1024x1536</code>、<code>1024x1024</code>、<code>1536x1024</code>；视频只内置 <code>seedance</code> / <code>Seedance 2.0 Fast</code>，画幅和时长对齐后端 <code>/health</code> 能力边界。<code>useModelConfig.js</code> 和 Pinia 模型 store 会忽略浏览器本地自定义图片/视频模型，防止旧缓存把不可用模型带回生成下拉。</td></tr>
                <tr><td><code>web/canvas-app/src/hooks/useApi.js</code></td><td>画布到本项目后端的适配层：不再读取浏览器 API Key，而是使用当前登录会话 Cookie 调用 <code>/api</code>。文生图 / 图生图先创建轻量 creative job，再调用 <code>/frames/0/generate</code>；文生视频 / 图生视频调用 <code>/storyboard/video</code> 并轮询 <code>/jobs/{id}</code>，完成后把图片或 mp4 URL 写回画布节点。</td></tr>
@@ -640,7 +642,8 @@
            <h3>后端核心</h3>
            <table>
              <tbody>
-                <tr><td><code>api/main.py</code></td><td>FastAPI 单文件后端：登录会话、状态模型、任务恢复、下载、抽帧、Vision、清洗、元素、分镜、原音频转写/翻译、声音与背景音分析、后续口播改写/TTS、文件返回；同时承载全局 <code>prompt_library</code> 和 <code>asset_library</code> 的磁盘索引、CRUD、删除保护和复制到 job API。轻量创作入口 <code>POST /creative/jobs/image</code> 把上传图片或空白底图写成一个只有 0 号关键帧的 <code>Job</code>，让首页直接复用生图/生视频接口；该接口兼容无 body / JSON 空对象 / 正常 multipart 上传，避免无首帧文生图或文生视频时空 multipart 被 FastAPI 在业务前置解析阶段拒绝；<code>/health</code> 返回 <code>image_options</code>、<code>image_size_options</code>、<code>video_options</code>、<code>video_size_options</code>、<code>video_duration_options</code> 和 <code>video_max_duration_seconds</code>；<code>/frames/{idx}/generate</code> 的 <code>model</code> 字段用于图片模型偏好，<code>size</code> 字段用于图片输出尺寸；<code>/storyboard/video</code> 继续使用 <code>model</code> 字段选择视频别名，并先校验画幅与时长能力边界，然后把 <code>GeneratedVideo</code> 写成 <code>queued</code> 占位并进入进程内视频队列。队列默认 <code>VIDEO_QUEUE_MAX_CONCURRENT=2</code>、<code>VIDEO_QUEUE_MAX_CONCURRENT_PER_USER=1</code>，同一用户连续提交不会占满全局并发；排队任务会回写 <code>queue_position</code>、<code>queue_size</code>、<code>queue_message</code>。旧 <code>AgentRun</code> 一键出片状态机、TK 复刻接口和 <code>POST /creative/copy</code> 继续保留。</td></tr>
+                <tr><td><code>api/main.py</code></td><td>FastAPI 单文件后端：登录会话、状态模型、任务恢复、下载、抽帧、Vision、清洗、元素、分镜、原音频转写/翻译、声音与背景音分析、后续口播改写/TTS、文件返回；同时承载全局 <code>prompt_library</code> 和 <code>asset_library</code> 的磁盘索引、CRUD、删除保护和复制到 job API。启动时会初始化 Postgres schema、扫描现有 <code>state.json</code> / 资源库并写入索引；新增 <code>/canvas-projects</code> 系列接口把画布项目按当前登录用户持久化。轻量创作入口 <code>POST /creative/jobs/image</code> 把上传图片或空白底图写成一个只有 0 号关键帧的 <code>Job</code>，让首页直接复用生图/生视频接口；该接口兼容无 body / JSON 空对象 / 正常 multipart 上传，避免无首帧文生图或文生视频时空 multipart 被 FastAPI 在业务前置解析阶段拒绝；<code>/health</code> 返回 <code>database</code>、<code>image_options</code>、<code>image_size_options</code>、<code>video_options</code>、<code>video_size_options</code>、<code>video_duration_options</code> 和 <code>video_max_duration_seconds</code>；<code>/frames/{idx}/generate</code> 的 <code>model</code> 字段用于图片模型偏好，<code>size</code> 字段用于图片输出尺寸；<code>/storyboard/video</code> 继续使用 <code>model</code> 字段选择视频别名，并先校验画幅与时长能力边界，然后把 <code>GeneratedVideo</code> 写成 <code>queued</code> 占位并进入进程内视频队列。队列默认 <code>VIDEO_QUEUE_MAX_CONCURRENT=2</code>、<code>VIDEO_QUEUE_MAX_CONCURRENT_PER_USER=1</code>，同一用户连续提交不会占满全局并发；排队任务会回写 <code>queue_position</code>、<code>queue_size</code>、<code>queue_message</code>。旧 <code>AgentRun</code> 一键出片状态机、TK 复刻接口和 <code>POST /creative/copy</code> 继续保留。</td></tr>
+                <tr><td><code>api/db.py</code></td><td>Postgres 适配层：在 <code>DATABASE_URL</code> 存在且 <code>psycopg</code> 可用时启用；负责建表、健康检查、用户 upsert、审计日志、画布项目 CRUD，以及把 <code>Job</code>、<code>AgentRun</code>、提示词库和素材库写入索引表。数据库不可用时本地开发会降级为 disabled，生产 <code>verify-prod-docker.sh</code> 会要求 <code>database.connected=true</code>。</td></tr>
                <tr><td><code>video_model_options()</code></td><td>视频模型能力出口：如果 <code>seedance</code>、<code>kling</code>、<code>veo3</code>、<code>veo</code> 等业务别名实际都映射到同一个真实模型，会按真实模型去重，只给前端返回一个可用选项；当前生产真实模型为 <code>doubao-seedance-2-0-fast-260128</code>，前端显示为 <code>Seedance 2.0 Fast</code>。后续只有在服务器真的配置了不同可用视频模型时，才应把新的模型重新暴露给画布。</td></tr>
                <tr><td><code>api/product_library/skg-products</code></td><td>内置 SKG 白底产品图库：<code>manifest.json</code> 记录从桌面产品图筛出的 gallery 白底图和桌面 4 张产品角度图，<code>images/</code> 存 45 张参考图。</td></tr>
                <tr><td><code>api/character_library/skg-characters</code></td><td>内置相似主体形象库：从桌面 5 套策划形象导入，<code>manifest.json</code> 记录运动阳光男、都市型男、优雅白领女、运动辣妹、绅士大叔，每套含 7 张透明骨架参考图和一段 <code>prompt_brief</code>。相似主体生成时优先使用文字 brief 作为创意方向，避免把内置图作为强参考图复制。</td></tr>
@@ -664,6 +667,7 @@
  -> 生图：generateImage(job.id, 0, { prompt, mode: text, model }) → jobs/&lt;jobId&gt;/gen
  -> 生视频：generateStoryboardVideo(job.id, 0, { prompt, model, first_image?, duration }) → jobs/&lt;jobId&gt;/storyboard_videos
 	  -> 当前结果：图片 / 视频节点自动排列到画布
+	  -> 画布项目：web/canvas-app/src/stores/projects.js → GET/POST/PUT/DELETE /canvas-projects → Postgres canvas_projects
 	  -> 任务详情页：web/app/detail/page.tsx?job=&lt;id&gt; → getJob → 展示参考图、生成图、视频、提示词、图文方案 → 可继续生成 / 删除 / 复制

 旧版 TK 复刻链路（最后版本保留）：
@@ -681,6 +685,7 @@ web/app/page.tsx
 后端主链路：
 api/main.py
  -> Auth session / Feishu OAuth / Job owner / AgentRun owner / KeyFrame / KeyElement / StoryboardScene / AudioScript
+  -> api/db.py / Postgres: app_users / canvas_projects / job_index / generated_assets / prompt_library_index / asset_library_index / agent_run_index / audit_events
  -> 下载 / 上传 / 音频提取 / ASR / 翻译 / 声音背景音分析 / 抽帧 / Vision brief / GPT 图像生成 / 产品视角识别 / 分镜保存 / 首尾帧生成 / 后续 Azure OpenAI 配音预留
  -> jobs/&lt;jobId&gt;/state.json + agent_runs/&lt;runId&gt;/state.json + 图片文件落盘；API 层按登录用户过滤列表和详情</pre>
      </section>
@@ -774,6 +779,32 @@ api/main.py
  error,
  created_at, updated_at
 }</pre>
+          </div>
+          <div class="card">
+            <h3>CanvasProject</h3>
+            <p>根域名画布的项目持久化模型。前端仍保留本地缓存，但服务端 <code>canvas_projects</code> 是公司内部沉淀的主存储；默认可见性为 <code>private</code>，只有 owner 可改写，后续可扩展 team/company 可见项目。</p>
+<pre>CanvasProject {
+  id,
+  owner_id, owner_name, owner_email, owner_provider, tenant_key,
+  name,
+  thumbnail,
+  visibility: private | team | company,
+  canvas_data: { nodes, edges, viewport, ... },
+  version,
+  created_at, updated_at, deleted_at
+}</pre>
+          </div>
+          <div class="card">
+            <h3>Postgres 索引表</h3>
+            <p>Postgres 不替代大文件和完整 job state；它负责跨用户、跨浏览器和后续后台管理需要的结构化索引。任务详情、媒体文件和资源库原始 manifest 仍保留在现有目录里。</p>
+<pre>app_users
+canvas_projects
+job_index
+generated_assets
+prompt_library_index
+asset_library_index
+agent_run_index
+audit_events</pre>
          </div>
          <div class="card">
            <h3>KeyFrame</h3>
@@ -1048,10 +1079,11 @@ ProductRefStateItem {
          </thead>
          <tbody>
            <tr><td>网页登录 / 飞书免登录</td><td><code>GET /auth/config</code>、<code>GET /auth/feishu/start</code>、<code>GET /auth/feishu/callback</code>、<code>POST /auth/login</code>、<code>GET /auth/check</code>、<code>GET /auth/me</code>、<code>POST /auth/logout</code></td><td><code>web/app/login/page.tsx</code>、Nginx <code>auth_request</code></td><td>登录页先读 <code>/api/auth/config</code> 判断是否显示飞书按钮；飞书客户端内且 <code>feishu_enabled=true</code> 时前端自动跳转授权入口，普通浏览器保留手动按钮和备用账号。飞书 OAuth 成功后后端用 open_id / union_id / email 生成多用户会话并设置 HttpOnly Cookie。账号密码登录保留为备用方式。生产 Nginx 对工作台和 <code>/api/</code> 调 <code>/auth/check</code> 做统一校验，未登录页面跳 <code>/login/?next=$request_uri</code>，API 返回 JSON 401。</td></tr>
-            <tr><td>运行配置 / 模型标注</td><td><code>GET /health</code></td><td><code>getRuntimeHealth</code>、<code>ModelTrace</code></td><td>返回 <code>models</code>：ASR、<code>asr_language</code>（默认 <code>auto</code>，表示中文/英文/多语言自动识别）、<code>asr_base_url</code>、<code>asr_remote_enabled</code>、<code>asr_local_fallback_enabled</code>、<code>asr_audio_fallback_enabled</code>、<code>faster_whisper</code>、本机 ASR、ASR fallback、翻译、GPT 改写、GPT 画面理解、产品视角识别 <code>product_view</code>、主图像模型 <code>gpt-image-2</code>、图片故障兜底 <code>image_fallbacks</code>、图片尺寸 <code>image_size_options</code>、短时熔断状态 <code>image_circuit</code>、主体 6 视图模型链路、Azure OpenAI TTS、视频别名、视频画幅 <code>video_size_options</code>、真实可用视频时长 <code>video_duration_options</code>、单条最大秒数 <code>video_max_duration_seconds</code> 和 Seedance 服务商。当前 <code>REWRITE_MODEL</code>、<code>AUDIO_REWRITE_MODEL</code> 和 <code>VISION_MODEL</code> 默认使用 <code>gpt-4o</code>；如果旧环境变量仍写 <code>gemini-*</code>，后端会归一化回 <code>GPT_TEXT_MODEL</code> / <code>REWRITE_MODEL</code>。语音只走 Azure OpenAI TTS，<code>models.voice_tts_paths</code> 会回传当前尝试的语音路径，方便区分路径错误和语音服务不可用。前端所有当前主路径里会调用模型的按钮旁显示模型名，点击弹出小窗口查看模型链路和输入输出逻辑；不返回 API Key 或敏感凭证。</td></tr>
+            <tr><td>运行配置 / 模型标注</td><td><code>GET /health</code></td><td><code>getRuntimeHealth</code>、<code>ModelTrace</code></td><td>返回 <code>database</code> 健康状态和 <code>models</code>：ASR、<code>asr_language</code>（默认 <code>auto</code>，表示中文/英文/多语言自动识别）、<code>asr_base_url</code>、<code>asr_remote_enabled</code>、<code>asr_local_fallback_enabled</code>、<code>asr_audio_fallback_enabled</code>、<code>faster_whisper</code>、本机 ASR、ASR fallback、翻译、GPT 改写、GPT 画面理解、产品视角识别 <code>product_view</code>、主图像模型 <code>gpt-image-2</code>、图片故障兜底 <code>image_fallbacks</code>、图片尺寸 <code>image_size_options</code>、短时熔断状态 <code>image_circuit</code>、主体 6 视图模型链路、Azure OpenAI TTS、视频别名、视频画幅 <code>video_size_options</code>、真实可用视频时长 <code>video_duration_options</code>、单条最大秒数 <code>video_max_duration_seconds</code> 和 Seedance 服务商。当前 <code>REWRITE_MODEL</code>、<code>AUDIO_REWRITE_MODEL</code> 和 <code>VISION_MODEL</code> 默认使用 <code>gpt-4o</code>；如果旧环境变量仍写 <code>gemini-*</code>，后端会归一化回 <code>GPT_TEXT_MODEL</code> / <code>REWRITE_MODEL</code>。语音只走 Azure OpenAI TTS，<code>models.voice_tts_paths</code> 会回传当前尝试的语音路径，方便区分路径错误和语音服务不可用。前端所有当前主路径里会调用模型的按钮旁显示模型名，点击弹出小窗口查看模型链路和输入输出逻辑；不返回 API Key、数据库密码或敏感凭证。</td></tr>
            <tr><td>历史列表</td><td><code>GET /jobs</code></td><td><code>listJobs</code></td><td>当前登录用户可见 job 精简列表（id/url/status/thumbnail/mtime/owner…），按 state.json mtime 倒序。前端 URL 无 <code>?job=</code> 时拉它回填本人历史；带 <code>limit</code> 可截断。开启数据隔离时，飞书用户只看到自己的任务，历史无 owner 的旧任务只对备用账号可见。</td></tr>
            <tr><td>创建任务</td><td><code>POST /jobs</code></td><td><code>createJob</code></td><td>提交 TK 链接，后台开始下载；后端会把当前登录用户写入 <code>Job.owner_*</code>，后续详情、素材文件、删除和生成接口都通过统一中间件校验归属。下载阶段默认不带 cookies；生产环境必须显式保持 <code>YTDLP_COOKIES_FILE=</code> 和 <code>YTDLP_COOKIES_FROM_BROWSER=</code> 为空，避免容器内误读被打进镜像的开发 <code>api/.env</code>。</td></tr>
-            <tr><td>画布生成</td><td><code>POST /creative/jobs/image</code><br><code>POST /jobs/{id}/frames/upload</code><br><code>POST /jobs/{id}/frames/{idx}/generate</code><br><code>POST /jobs/{id}/frames/{idx}/storyboard/video</code><br><code>GET /jobs/{id}</code></td><td><code>web/canvas-app/src/hooks/useApi.js</code></td><td>根域名画布不单独保存后端画布表，画布项目当前在浏览器 localStorage；一旦生成图片或视频，就通过同一套 creative job / frame / storyboard video 接口写入当前登录用户自己的 job 目录。文生图会创建空白 creative job 后生成图片；图生视频会把上传图转成 frame 并作为视频参考图提交，提交视频后用 <code>skg:{jobId}:{videoId}</code> 作为画布侧任务 id 轮询 <code>/jobs/{id}</code>，直到视频状态完成或失败。</td></tr>
+            <tr><td>画布项目</td><td><code>GET /canvas-projects</code><br><code>POST /canvas-projects</code><br><code>PUT /canvas-projects/{id}</code><br><code>GET /canvas-projects/{id}</code><br><code>DELETE /canvas-projects/{id}</code><br><code>POST /canvas-projects/import</code></td><td><code>web/canvas-app/src/stores/projects.js</code></td><td>根域名画布项目的服务端持久化接口。列表和详情按当前登录用户过滤；写入时保存画布 JSON、缩略图、可见性、版本和更新时间；删除为软删除。首次上线后本地 <code>localStorage</code> 旧项目会通过 import 导入到当前用户，之后服务端 Postgres 是主存储。</td></tr>
+            <tr><td>画布生成</td><td><code>POST /creative/jobs/image</code><br><code>POST /jobs/{id}/frames/upload</code><br><code>POST /jobs/{id}/frames/{idx}/generate</code><br><code>POST /jobs/{id}/frames/{idx}/storyboard/video</code><br><code>GET /jobs/{id}</code></td><td><code>web/canvas-app/src/hooks/useApi.js</code></td><td>画布项目结构保存在 <code>/canvas-projects</code>；一旦生成图片或视频，就通过同一套 creative job / frame / storyboard video 接口写入当前登录用户自己的 job 目录。文生图会创建空白 creative job 后生成图片；图生视频会把上传图转成 frame 并作为视频参考图提交，提交视频后用 <code>skg:{jobId}:{videoId}</code> 作为画布侧任务 id 轮询 <code>/jobs/{id}</code>，直到视频状态完成或失败。</td></tr>
            <tr><td>一键出片终端</td><td><code>POST /agent-runs</code><br><code>GET /agent-runs</code><br><code>GET /agent-runs/{id}</code><br><code>GET /agent-runs/{id}/final.mp4</code><br><code>GET /agent-runs/{id}/contact.jpg</code></td><td><code>web/app/agent/page.tsx</code></td><td>快速出片页的唯一主接口。前端提交 TikTok 链接和最多 6 张产品图；后端创建同 owner 的 <code>Job</code> 与 <code>AgentRun</code>，后台执行下载、产品图归一化、透明骨架主体参考复制、12 段镜头计划、视频生成、失败镜头自动重跑一次、审片接触表和 ffmpeg 最终合成。列表、详情、最终 mp4 和接触表同样按 owner 隔离。</td></tr>
            <tr><td>重试下载</td><td><code>POST /jobs/{id}/download/retry</code></td><td><code>retryJobDownload</code></td><td>用于 TK 链接下载失败且没有 <code>video_url</code> 的素材；清空错误、重新进入下载状态，并在后台再次执行 <code>pipeline_download</code>。上传视频不能重下载，需要重新上传文件。</td></tr>
            <tr><td>上传视频</td><td><code>POST /jobs/upload</code></td><td><code>uploadJob</code></td><td>保存 source.mp4，然后同样进入下载完成状态；当前上传后也加入第一步队列，下载完成后自动解析音频。</td></tr>
@@ -1118,9 +1150,9 @@ ProductRefStateItem {
            </tr>
            <tr>
              <td><span class="tag blue">内容生产画布</span></td>
-              <td>承载个人自由排列的创作空间：用户在画布上通过提示词、推荐词、AI 润色、自动执行、工作流模板或手动节点连接生成文本、图片和视频节点，结果按节点位置沉淀。画布项目先保存在浏览器本地，生成资产进入后端个人 job。</td>
-              <td>当前不做团队共享画布、管理员总览、多人协同编辑或跨浏览器同步；API 设置不能接回上游外部注册链接，生成调用必须继续走本项目后端 <code>/api</code> 和登录会话。</td>
-              <td><code>web/canvas-app/</code>、<code>deploy/nginx.conf</code>、<code>web/scripts/sync-canvas-root.mjs</code></td>
+              <td>承载个人自由排列的创作空间：用户在画布上通过提示词、推荐词、AI 润色、自动执行、工作流模板或手动节点连接生成文本、图片和视频节点，结果按节点位置沉淀。画布项目服务端保存到 Postgres，浏览器本地只缓存，生成资产进入后端个人 job。</td>
+              <td>当前不做实时多人协同编辑或管理员总览；默认项目仍是个人私有，可见性字段先预留 team/company。API 设置不能接回上游外部注册链接，生成调用必须继续走本项目后端 <code>/api</code> 和登录会话。</td>
+              <td><code>web/canvas-app/</code>、<code>web/canvas-app/src/stores/projects.js</code>、<code>api/main.py</code>、<code>api/db.py</code></td>
            </tr>
            <tr>
              <td><span class="tag gray">音频条</span></td>
@@ -1156,7 +1188,7 @@ ProductRefStateItem {
              <li>GPT Image 生图；当前 <code>IMAGE_MODEL</code> 和主体 6 视图链路默认使用 <code>gpt-image-2</code>，单次图片网关请求默认 60 秒超时；主模型超时、429、5xx 或网络错误时允许 <code>gemini-3-pro-image-preview</code> 兜底，并有 2 次失败 / 600 秒短时熔断。</li>
              <li>三字段分镜候选生成：默认行左侧露文案、场景一句话、人物+产品+动作，右侧直接展示横向视频轨；中文镜像失焦后会自动优化英文主值；支持 AI 改写预览、单条选择数量生成、追加生成、选中候选和整片按行排队提交。</li>
              <li>全局资源中心：提示词库和素材库可从顶部“资源库”打开；提示词可复制并计数，素材应用到 job 时会复制成本 job 内普通 asset。</li>
-              <li>画布：<code>https://marketing.skg.com</code> 登录后直接进入个人生成画布，支持文生图、文生视频、图生视频三种节点化生成；生成资产继续写入当前登录用户自己的后端 job。</li>
+              <li>画布：<code>https://marketing.skg.com</code> 登录后直接进入个人生成画布，支持文生图、文生视频、图生视频三种节点化生成；画布项目服务端保存到 Postgres，生成资产继续写入当前登录用户自己的后端 job。</li>
            </ul>
          </div>
          <div class="card">
@@ -1209,6 +1241,20 @@ ProductRefStateItem {
        <h2>变更记录</h2>
        <p>这个记录不是 git log 的替代品。它记录“产品理解发生了什么变化、影响了哪些源码、你以后描述需求时该怎么说”。后续每次改功能都要补一条。</p>
        <div class="changelog">
+          <article class="change">
+            <header>
+              <h3>2026-05-26 · 接入 Postgres 做公司内部沉淀</h3>
+              <span class="tag blue">Backend</span>
+              <span class="tag amber">Deploy</span>
+              <span class="tag green">Data</span>
+            </header>
+            <div class="body">
+              <p><strong>问题：</strong>画布项目只存在浏览器 <code>localStorage</code> 时，换电脑、清缓存或多人长期使用都难以形成公司内部资产沉淀；任务和资源虽然已有文件持久化，但缺少结构化索引和审计。</p>
+              <p><strong>改动：</strong>新增 <code>api/db.py</code> 和 Postgres schema：<code>app_users</code>、<code>canvas_projects</code>、<code>job_index</code>、<code>generated_assets</code>、<code>prompt_library_index</code>、<code>asset_library_index</code>、<code>agent_run_index</code>、<code>audit_events</code>。<code>api/main.py</code> 启动时建表并索引已有 job / AgentRun / 提示词 / 素材；新增 <code>/canvas-projects</code> CRUD 和 import 接口；登录、创建任务、资源库操作、画布保存都会写用户索引或审计。<code>web/canvas-app/src/stores/projects.js</code> 改为服务端项目优先，<code>localStorage</code> 只做缓存和旧项目导入。</p>
+              <p><strong>部署：</strong><code>docker-compose.prod.yml</code> 和 <code>docker-compose.standalone.yml</code> 增加 <code>postgres:16-alpine</code>；生产环境在 <code>deploy/.env.production</code> 写入 <code>DATABASE_URL</code> 和 Postgres 密码，数据目录为服务器 <code>./data/postgres</code>。<code>deploy-prod-safe.sh</code> 会在容器存在时导出 <code>pg_dump</code>，<code>verify-prod-docker.sh</code> 要求 <code>database.connected=true</code>。</p>
+              <p><strong>影响：</strong>画布项目开始具备跨浏览器、跨设备恢复的服务端主存储；默认仍按 owner 私有隔离，后续可在同一表上扩展 team/company 可见性。完整 job state 和媒体文件仍保留在原有文件目录，避免把大文件一次性搬进数据库。</p>
+            </div>
+          </article>
          <article class="change">
            <header>
              <h3>2026-05-25 · 媒体模型选择对齐真实后端能力</h3>
@@ -1325,7 +1371,7 @@ ProductRefStateItem {
            <div class="body">
              <p><strong>问题：</strong>默认首页适合“一次生成一个结果”，但内部多人使用时，用户还需要把多次生成的图片、视频、提示词和参考图放在一个自由空间里整理，避免结果都挤在同一条对话或详情页里。</p>
              <p><strong>改动：</strong>新增 <code>web/canvas-app/</code>，将 huobao-canvas 的 Vue Flow 画布交互改造为 SKG 内部版：可见品牌、GitHub 入口、API Key 设置和外部服务商配置都已移除，保留项目列表、生成画布、节点连接、四模式 prompt composer 和生成结果节点。构建链路新增 <code>pnpm build:canvas</code> 和 <code>web/scripts/sync-canvas-dist.mjs</code>，生产 Nginx 新增受登录保护的 <code>/canvas/</code> fallback 路由；首页顶部增加“生成画布”入口。</p>
-              <p><strong>影响：</strong>画布项目目前保存在浏览器 <code>localStorage</code>，不是团队共享，也不做跨设备同步；生成图片和视频仍调用本项目 <code>/api</code>，按当前登录用户写入个人 job。第三方来源说明只保存在 <code>THIRD_PARTY_NOTICES.md</code>，不进入终端用户 UI。</p>
+              <p><strong>影响：</strong>当时画布项目先保存在浏览器 <code>localStorage</code>，不是团队共享，也不做跨设备同步；2026-05-26 已升级为服务端 Postgres 持久化。生成图片和视频仍调用本项目 <code>/api</code>，按当前登录用户写入个人 job。第三方来源说明只保存在 <code>THIRD_PARTY_NOTICES.md</code>，不进入终端用户 UI。</p>
            </div>
          </article>
          <article class="change">