体验层
面向转化与操作的端面：营销页、用户应用页、管理后台。
- /营销页面与多语言路由
- /用户工作台与任务流
- /后台运营与模型管理界面
请求生命周期
从用户动作到业务结果，以下流程概括了关键请求如何在系统中被处理。
- 01
入口层
请求从营销页、应用页或后台页面进入，并通过多语言 App Router 路由段分发。
- 02
校验与鉴权
在进入业务服务前，先完成会话解析、角色权限检查与参数 schema 校验。
- 03
业务执行
定价、订单、内容与 AI 生成模块按域执行规则，避免横向耦合。
- 04
数据与外部层
通过 Drizzle 持久化状态，并协调外部供应商调用、重试与限流。
- 05
结果反馈
前端获取确定性的成功、失败与加载状态，同时更新积分与计费结果。
设计原则
- 业务逻辑归属功能模块，共享契约归属基础包。
- 关键流程默认幂等（支付、退款、重试）。
- 明确运行时边界：UI、服务层、持久层、外部层。
- 主流程必须具备可观测的成功、失败与降级状态。
应用分层
每一层只做单一职责，保证系统在增长时仍然可预测、可维护。
业务域层
承载定价、订阅、内容与 AI 生成的核心业务规则。
- /订单、积分与订阅逻辑
- /CMS 与组件分发
- /AI 参数 schema 与生成规则
集成层
连接认证、支付、存储与模型供应商的适配层。
- /Better Auth 会话集成
- /支付与发票编排
- /FAL / Replicate / KIE 供应商连接
数据层
通过工作区共享包统一管理持久化结构与类型访问。
- /Drizzle schema 与迁移
- /类型安全查询工具
- /种子数据与环境初始化
多云存储
S3 多提供商上传架构
上传链路通过 provider 工厂动态选择存储后端，支持同一实例按用户切换 provider 与 bucket。
支持的 S3 兼容提供商
- /Cloudflare R2
- /AWS S3
- /Backblaze B2（S3）
- /Tigris
- /DigitalOcean Spaces
- /MinIO
- /Wasabi
- /Custom（含 OSS 场景）
核心入口路由
C 端上传
POST /api/v1/s3/upload
根据当前用户解析 provider + bucket 后执行上传。
Admin 上传
POST /api/v1/admin/s3/upload
后台素材与运营文件上传，复用同一 provider 解析逻辑。
Provider 工厂
apps/ship-api/src/services/upload/provider.ts
统一解析默认配置、用户覆盖与环境变量兜底。
配置优先级
- 1.UPLOAD_PROVIDER_OVERRIDES（用户级覆盖）
- 2.UPLOAD_PROVIDER_DEFAULT（系统默认）
- 3.BETTER_UPLOAD_PROVIDER（环境变量兜底）
任务队列保障
生成与供应商调用由调度器驱动的任务队列统一编排，确保吞吐可控、失败可恢复、计费副作用可幂等。
吞吐
并发槽位 + QPS 限流
同时约束 worker 并发与 provider 级 QPS 窗口，突发流量不会冲垮上游接口。
控制
超时 + 主动取消
AbortController 从队列任务透传到 submit/poll HTTP 请求，确保超时与取消具备确定性。
恢复
重试预算与退避
瞬时错误走有上限的重试与退避策略，不可恢复错误直接进入终态避免资源浪费。
财务
退款幂等保护
积分补偿依赖幂等键，避免重试和并发竞争导致重复退款。
技术栈矩阵
面向生产实践的核心栈分布图。
运行时与框架
Next.js 16React 19BunTurborepo
产品基础能力
Better AuthDrizzle ORMnext-intlshadcn/ui 基础层
业务模块
定价与计费订单生命周期CMS + 组件库AI 生成能力
运维与稳定性
后台模型管理积分与退款队列与重试供应商降级策略
准备基于这套架构开始构建？
你可以直接复用现有基础，按业务需要扩展模块、供应商与工作流。