yedir-ai 架构说明

yedir-ai 是一个以 AI 设计工作台为核心的 Next.js 应用，主要由首页体验、Canvas/Agent 创作链路、后台设置中心、内部生成 API、公开轻量 API 和基础设施治理组成。

高层边界

Browser
  |
  |-- /                         Lovart-style home shell
  |-- /canvas/*                 Canvas and Agent workspace
  |-- /settings                 Admin settings center
  |-- /api/site-settings        Public lightweight settings API
  |-- /api/featured             Public featured gallery API
  |-- /api/chat                 Internal generation API
  |
Next.js App Router
  |
  |-- Auth.js                   session, admin access, OAuth
  |-- Drizzle/Postgres          projects, settings, users, tasks
  |-- Storage service           DB S3 config, env S3, Vercel Blob fallback
  |-- AI providers              image, video, 3D, CAD, agent workflows
  |-- Observability             structured logs and redaction

首页

首页 / 优先渲染静态轻量壳，不在服务端阻塞等待 session、站点配置或个性化数据。站点配置、精选图、项目、会员和教程等数据通过客户端渐进加载。

公开首页接口应具备缓存、降级和观测头，避免数据库或外部服务波动拖慢首屏。

Canvas / Agent

Canvas 是主要创作工作区，承载图像生成、编辑、素材编排、Agent 自动规划、多模态输入和项目化保存。

Agent 能力依赖内部生成链路、模型供应商配置和素材/PSD 等领域模块。相关巨型模块仍是后续治理重点，拆分时应保持 API shape 和保存逻辑不变。

后台设置中心

/settings 是管理员配置入口。本地 AI 设置已按领域拆分为 planning、model3d、image-pipeline、runtime 等组件，并保留统一 section shell、状态摘要、快捷目录和折叠持久化。

后台保存逻辑、数据库 setting key 和 SWR key 应保持稳定，避免配置迁移风险。

内部生成 API

/api/chat 目前不再对应旧 Chat UI，而是 Canvas/Agent 的内部生成 API。旧页面 /classic 和 /chat/[id] 已重定向到 /。

未来若要彻底替换 /api/chat，应先把 Canvas/Agent 调用方迁移到专用生成接口，再删除旧协议。

公开轻量 API

首页相关公开接口包括：

/api/site-settings?scope=home
/api/featured
/api/nav-links
/api/home-animation
/api/auth-settings

这些接口应快速返回，必要时使用 stale cache 或 fallback。响应头应保留 X-Cache、X-Fallback、Server-Timing，方便判断慢点来自缓存、DB 还是降级。

数据与存储

Postgres 是主数据源。连接池默认使用有限连接数、短连接超时和 prepare: false，避免数据库不可用时拖垮公开接口。

对象存储优先使用数据库中的 S3 配置；环境变量 S3 和 Vercel Blob 是 fallback。日志中不应输出完整 endpoint、bucket key、签名 URL 或原图 URL。

质量与安全治理

主质量门禁包括：

pnpm lint
pnpm check:logs
pnpm exec tsc --noEmit --pretty false
git diff --check
tracked 污染物检查

日志通过 lib/observability 结构化输出并脱敏。当前只治理了第一批高风险链路，Canvas 和 /api/chat 日志二期仍待推进。

3.3 KiB Raw Blame History Unescape Escape