# yedir-ai 架构说明

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

## 高层边界

```text
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 check:quality`
- `pnpm smoke:routes`，需要先启动目标环境

`pnpm check:quality` 会统一执行 lint、日志脱敏门禁、类型检查、diff hygiene 和 tracked 污染物检查。

日志通过 `lib/observability` 结构化输出并脱敏。当前已纳管 `/api/chat` 主路由与拆分模块、存储/上传、认证、AI provider、Canvas 服务、图像标注、Scene Fusion、Pick Object、Tripo 3D、World Labs 等高风险链路。后续如果继续治理 Enhance、Angle Edit、Prompt Optimizer 等历史接口，应先加入 `scripts/check-log-hygiene.mjs`，再替换裸 `console.*`。