78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
# 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.*`。
|