diff --git a/core/ARCHITECTURE.md b/core/ARCHITECTURE.md index 312eea1..6000488 100644 --- a/core/ARCHITECTURE.md +++ b/core/ARCHITECTURE.md @@ -1,5 +1,8 @@ # AirShelf 技术架构方案 +> 文档说明（2026-07-17）：本文完整保留 2026-05-29 的顶层架构决策、目标模型与开发路线，其中部分名称和部署形态属于早期规划，不代表当前代码已经按原方案实现。 +> 当前实现请以 [后端架构](backend/ARCHITECTURE.md) 和 [前端架构](frontend/ARCHITECTURE.md) 为准；系统演进时应同时维护“原始决策背景”和“当前实现说明”。 + > 版本：v1.0 > 日期：2026-05-29 > 定位：从原型走向真实可运营产品的顶层技术架构决策文档 diff --git a/core/backend/ARCHITECTURE.md b/core/backend/ARCHITECTURE.md new file mode 100644 index 0000000..1b2ba57 --- /dev/null +++ b/core/backend/ARCHITECTURE.md @@ -0,0 +1,445 @@ +# AirShelf 后端架构 + +> 适用目录：`core/backend`。 +> 最后核对：2026-07-17。 +> 本文描述当前代码结构；系统级拓扑见 [core/ARCHITECTURE.md](../ARCHITECTURE.md)。 + +## 1. 定位 + +后端是 AirShelf 的业务与数据中枢，负责： + +- 用户、团队、成员、邀请码和权限。 +- 商品、项目、资产和五阶段生产状态。 +- AI Provider、模型配置和生成任务编排。 +- 积分预留、结算、释放和额度限制。 +- TOS 文件、素材审核、资产引用和垃圾桶生命周期。 +- Celery 异步任务、脚本 SSE、视频轮询和 FFmpeg 导出。 +- 通知中心和平台超管治理接口。 + +## 2. 目录结构 + +```text +core/backend/ +├─ airshelf/ +│ ├─ settings/ +│ │ ├─ base.py 公共配置、数据库、Redis、Provider 环境变量 +│ │ ├─ development.py 本地开发配置 +│ │ ├─ production.py 生产安全和 WhiteNoise 配置 +│ │ └─ test.py 测试配置 +│ ├─ urls.py API 总路由 +│ ├─ celery.py Celery 应用入口 +│ ├─ wsgi.py +│ └─ asgi.py +├─ apps/ +│ ├─ common/ +│ ├─ accounts/ +│ ├─ products/ +│ ├─ assets/ +│ ├─ projects/ +│ ├─ ai/ +│ ├─ billing/ +│ ├─ ops/ +│ └─ adminpanel/ +├─ skills/ 脚本生成、实体提取等 AI Skill 资料 +├─ manage.py +├─ requirements.txt +├─ Dockerfile +├─ docker-entrypoint.sh +└─ README.md 本地启动与常用命令 +``` + +## 3. Django 工程入口 + +### 3.1 Settings + +`airshelf/settings/base.py` 统一声明： + +- Django apps 和中间件。 +- DRF 鉴权、权限、分页和过滤。 +- SQLite/MySQL 数据库切换。 +- Redis cache、Celery broker/result 和业务锁。 +- TOS、火山 ARK、火山 TTS、YunQi、TokenSSR 配置。 +- AI 功能开关和灰度团队配置。 +- 积分赠送等平台参数。 + +敏感凭证只从环境变量或部署 Secret 读取，不应写入架构文档和仓库代码。 + +### 3.2 路由 + +API 总入口： + +```text +/api/health/ 健康检查 +/api/auth/ 用户、团队、登录、邀请码 +/api/products/ 商品 +/api/assets/ 资产 +/api/models/ 模特库 +/api/projects/ 项目和五阶段流水线 +/api/billing/ 账户、额度和流水 +/api/ai/ AI 任务、生成、模型配置 +/api/ops/ 通知 +/api/admin/ 平台超管 API +/django-admin/ Django Admin +``` + +`/admin/*` 留给前端平台后台，Django 自带后台使用 `/django-admin/`。 + +### 3.3 鉴权 + +当前 DRF 支持： + +- Token Authentication：前端主流程使用 `Authorization: Token ...`。 +- Session Authentication：Django Admin 和部分浏览器会话。 +- Basic Authentication：保留的 DRF 兼容入口。 + +当前不是 JWT 架构，不存在 refresh token 轮换链路。 + +## 4. 应用模块 + +### 4.1 `common` + +提供基础设施型公共代码： + +- `UUIDModel` +- `TimeStampedModel` +- `TeamOwnedModel` +- `TeamScopedViewSetMixin` +- 默认分页 +- 健康检查 + +业务 app 应复用这些基类，避免自行实现团队过滤和通用字段。 + +### 4.2 `accounts` + +负责身份和租户： + +- 自定义 `User` +- `Team` +- `TeamMember` +- `Invitation` +- `UserPreference` +- `LoginSession` +- `AdminAuditLog` + +团队角色主要包括 owner、admin、member；平台超管通过用户字段识别，与团队角色是两个维度。 + +成员可配置日、月、累计总积分限制；团队可配置月积分限制。 + +### 4.3 `products` + +负责生产链输入： + +- `Product` +- `ProductImage` +- `ProductSellingPoint` + +商品包含标题、品牌、类目、目标人群、规格、描述、图片和卖点，为脚本及后续资产生成提供上下文。 + +### 4.4 `assets` + +负责业务资产和文件元数据： + +- `Asset` +- `AssetFile` +- `Model` +- `AssetReviewGroup` +- `AssetTag` / `AssetTagging` +- `AssetUsage` +- `FreeAssetGroup` / `FreeAsset` + +`Asset` 表达业务语义、归属、分类、状态和审核信息；`AssetFile` 保存 TOS 对象键、bucket、content type、文件大小、checksum、宽高、时长、预览地址等。 + +资产模块还负责： + +- 模特立绘和三视图。 +- 人像素材审核提交与状态查询。 +- 项目资产使用关系。 +- 图片/视频资产库展示。 +- 自由创作资产归组。 +- 软删除、垃圾桶和恢复相关数据。 + +### 4.5 `projects` + +负责视频项目和五阶段数据结构： + +- `Project` +- `ProjectStage` +- `ScriptVersion` / `ScriptSegment` +- `BaseAssetGroup` +- `StoryboardVersion` / `StoryboardFrame` +- `StoryboardShot` / `StoryboardShotVersion` +- `VideoSegment` / `VideoSegmentVersion` +- `Timeline` / `TimelineClip` +- `SubtitleTrack` +- `BgmTrack` +- `ExportJob` + +`projects` 负责业务状态和资源关系；具体 AI 外部请求应委托 `ai` 模块，积分动作应委托 `billing` 模块。 + +### 4.6 `ai` + +负责所有模型和生成编排： + +- `ModelProvider` +- `ModelConfig` +- `AITask` +- `ImageConversation` +- `QualityWord` +- `PromptTemplate` +- Provider 适配器 +- 脚本 Agent 与 Skill 装配 +- 实体提取、基础资产、三视图、生图、生视频和 TTS +- 用户错误转换和生成通知 + +主要目录和文件： + +```text +apps/ai/ +├─ providers/ Provider 适配层 +├─ services.py 多生成场景编排 +├─ tasks.py Celery 任务入口 +├─ script_agent.py 脚本 Agent 和 SSE 编排 +├─ free_video.py 自由视频任务 +├─ generation_errors.py 对外错误语义 +├─ pricing.py 通用模型计价 +├─ video_pricing.py 视频计价 +└─ model_library.py 模型/模特相关生成能力 +``` + +`services.py` 是当前复杂度中心。新增场景应优先复用 Provider、任务、计费、错误转换和资产落库逻辑，避免继续堆叠重复流程。 + +### 4.7 `billing` + +负责积分和额度： + +- `CreditAccount`：团队余额与预留余额。 +- `CreditLedger`：充值、预留、释放、扣费、调整、退款流水。 +- `CreditReservation`：与计费型 `AITask` 关联的预留记录。 +- `BillingConfig`：积分换算、视频毛利和预留 buffer。 +- `QuotaPolicy`：团队、项目和单任务策略。 + +核心服务函数： + +```text +reserve_credit +charge_reserved_credit +release_credit +``` + +这些函数负责事务、行锁、幂等、额度检查和流水。其他模块禁止直接改余额来模拟扣费。 + +### 4.8 `ops` + +当前主要负责 `Notification`、消息列表和通知补齐任务。生成失败、额度变化和重要任务状态可以通过该模块形成用户消息。 + +### 4.9 `adminpanel` + +为 React 平台超管后台提供跨团队治理 API，包括： + +- 邀请码、团队和用户。 +- 提示词、质量词和模型配置。 +- 资产审核。 +- AI 任务查询、重试和回收。 +- 积分流水、计费配置和额度策略。 +- 项目和平台完整性检查。 + +跨团队查询必须限制为平台超管，并保留必要审计信息。 + +## 5. 核心业务链 + +### 5.1 注册与团队 + +```text +校验邀请码 + → 注册或加入团队 + → 创建 TeamMember + → 初始化团队积分账户 + → 返回 Token、User、Team、Role +``` + +### 5.2 商品到项目 + +```text +Product + → 创建 Project + → 初始化 ProjectStage + → 进入 script 阶段 +``` + +### 5.3 五阶段 + +```text +script + ScriptVersion → ScriptSegment + +base_assets + 生成/上传商品、人物、场景 → Asset / BaseAssetGroup + +storyboard + StoryboardShot → 多个 ShotVersion → 采用版本 + +video + VideoSegment → 外部视频任务 → VideoSegmentVersion + +export + Timeline + 字幕 + BGM + 配音 → ExportJob → 最终 Asset +``` + +## 6. AI Provider 架构 + +### 6.1 数据配置 + +`ModelProvider` 保存供应商名称、地址、状态和元数据；`ModelConfig` 保存模型名称、能力、价格、默认状态和模型参数。 + +Provider 地址和密钥的解析顺序由服务层控制：数据库配置优先，缺失时回退到环境变量。密钥不应写入数据迁移和普通日志。 + +### 6.2 适配层 + +```text +AIProvider Protocol +├─ VolcanoArkProvider +├─ OpenAICompatibleProvider +├─ YunqiProvider +└─ VolcanoTtsProvider +``` + +通用 OpenAI-compatible 适配器承担 YunQi、TokenSSR 及类似网关的共性协议；Provider 特殊差异通过元数据和适配器处理。 + +### 6.3 默认模型 + +默认模型可能由数据迁移、后台配置和 Provider 状态共同决定。业务代码不应长期硬编码某个供应商为唯一默认模型；架构文档也不复制易变化的默认模型名单。 + +## 7. 任务执行模型 + +### 7.1 Celery + +当前 Celery 任务包括： + +- AI 任务提交与轮询。 +- 独立生图。 +- 实体提取。 +- 基础资产生成。 +- 商品、人物三视图生成。 +- 自由视频轮询。 +- 项目视频片段轮询。 +- FFmpeg 导出。 +- 通知补齐。 + +任务必须使用数据库状态作为事实来源，不能只依赖 Celery result backend。 + +### 7.2 SSE + +脚本 Agent 使用 SSE 在单个 HTTP 流中发送分析、生成、自检、草稿、保存和完成事件。断连、异常和计费释放由脚本 Agent 编排层兜底。 + +### 7.3 审核轮询 + +素材审核提交可在 AI 资产落库后触发。目前审核状态轮询主要由项目 API 和超管 API 请求调用，不是独立 Celery 周期任务。 + +### 7.4 前端轮询 + +前端通过任务和项目 API 获取进度。前端展示进度不是最终事实，后端任务状态、外部任务标识和数据库资产才是恢复依据。 + +## 8. 计费生命周期 + +计费型任务的标准流程： + +```text +创建 AITask + → 计算报价 + → 检查团队、成员、项目、单任务额度 + → reserve_credit + → 提交任务 + → 执行/轮询 + ├─ 成功：写资产和业务版本 → charge_reserved_credit + └─ 失败：记录错误 → release_credit +``` + +额度层级： + +- `Team.monthly_credit_limit` +- `TeamMember.daily_credit_limit` +- `TeamMember.monthly_credit_limit` +- `TeamMember.total_credit_limit` +- `QuotaPolicy.monthly_limit` +- `QuotaPolicy.project_limit` +- `QuotaPolicy.per_task_limit` + +预留、结算和释放均需要幂等。删除仍处于 ACTIVE 的任务时，信号会尝试释放预留，避免余额永久冻结。 + +## 9. 资产与审核 + +### 9.1 文件存储 + +文件上传 TOS 后，数据库保存对象定位和元数据。对外访问使用后端生成或保存的可访问 URL，不把云存储密钥交给前端。 + +### 9.2 人像审核 + +需要审核的资产保存： + +- `review_status` +- `review_remote_id` +- `review_error` + +审核提交失败必须如实返回，不能把未提交成功的资产误标成 processing。轮询只更新发生变化的状态，避免刷新时间导致超时判断失效。 + +### 9.3 删除 + +删除需要区分： + +- 业务记录软删除。 +- 垃圾桶展示与恢复。 +- 项目或会话引用解绑。 +- TOS 对象最终删除。 +- 任务和计费审计保留。 + +物理清理前必须检查资产引用，避免删除仍被商品、项目、模特或生成任务使用的文件。 + +## 10. 部署 + +### 10.1 API + +后端镜像默认以 Gunicorn 启动。当前配置使用多个 worker 和线程，避免慢 AI/TOS 请求占满全部请求槽并饿死健康检查。 + +### 10.2 Worker + +Celery Worker 复用 API 镜像，通过启动参数切换进程。当前 K8s 使用一个 Worker Deployment、并发 4，AI 和媒体任务尚未拆分独立队列。 + +### 10.3 Migration + +`docker-entrypoint.sh` 只在 Gunicorn 启动时执行 migration 和 collectstatic。MySQL 使用 `GET_LOCK` 串行化迁移，Worker 明确跳过数据库结构变更。 + +### 10.4 FFmpeg + +后端镜像安装 FFmpeg 和 Noto CJK 字体，用于视频拼接、字幕、BGM 和配音混合。 + +## 11. 测试与验证 + +常用验证： + +```bash +python manage.py check +python manage.py makemigrations --check --dry-run +python manage.py test +``` + +测试环境使用独立 settings，并可让 Celery eager 执行。涉及计费、删除、任务重试和数据迁移的改动必须补回归测试。 + +## 12. 当前风险与维护边界 + +- `apps/ai/services.py` 体积较大，场景边界需要渐进拆分。 +- AI 默认模型会通过迁移和后台配置变化，文档不能写死。 +- 同步请求、SSE、Celery 和 API 轮询并存，新增流程必须明确执行模型。 +- 单 Worker Deployment 可能导致 AI 和导出资源争用。 +- 资产删除与任务删除涉及引用、计费和 TOS，不能只删除单表记录。 +- 数据迁移可能包含业务数据变换，必须保证幂等或通过迁移锁串行执行。 + +## 13. 文档同步规则 + +出现以下变化时必须更新本文： + +- Django app、核心模型或模块职责变化。 +- API 一级路由或鉴权机制变化。 +- AI Provider 适配机制变化。 +- Celery/SSE/同步执行边界变化。 +- 计费、额度或资产删除生命周期变化。 +- 数据库、Redis、TOS、FFmpeg 或部署方式变化。 diff --git a/core/backend/README.md b/core/backend/README.md index c20211e..8279de1 100644 --- a/core/backend/README.md +++ b/core/backend/README.md @@ -2,6 +2,8 @@ All backend code lives under `AirShelf/core/backend` by project decision. +Architecture and module boundaries: [ARCHITECTURE.md](ARCHITECTURE.md). + ## Local bootstrap ```bash diff --git a/core/frontend/ARCHITECTURE.md b/core/frontend/ARCHITECTURE.md new file mode 100644 index 0000000..a6c5cbb --- /dev/null +++ b/core/frontend/ARCHITECTURE.md @@ -0,0 +1,395 @@ +# AirShelf 前端架构 + +> 适用目录：`core/frontend`。 +> 最后核对：2026-07-17。 +> 本文描述当前代码结构；系统级拓扑见 [core/ARCHITECTURE.md](../ARCHITECTURE.md)。 + +## 1. 定位 + +`core/frontend` 是 AirShelf 正式业务前端，是独立的 Vite + React + TypeScript 单页应用，不是 Next.js。 + +主要覆盖： + +- 登录注册、团队和账户。 +- 工作台、商品库、模特库、视频项目。 +- 五阶段生产管线。 +- 资产库和垃圾桶。 +- 图片创作、模特上身图、平台套图。 +- 自由视频创作。 +- 通知、设置和平台超管后台。 + +设计稿位于 `public/exact`；正式业务页面位于 `src/routes`。设计稿用于视觉对照，不承载线上业务逻辑。 + +## 2. 技术栈 + +| 类别 | 当前实现 | +| --- | --- | +| UI 框架 | React 19 | +| 类型系统 | TypeScript strict | +| 构建工具 | Vite 7 | +| 图标 | Lucide React + 项目图标组件 | +| 路由 | 自研 History API 路由 | +| 状态 | React state/effect，未引入 Redux/Zustand | +| 请求 | 原生 fetch 的统一封装 | +| 请求缓存 | 无 TanStack Query 等统一缓存层 | +| 样式 | 全局 CSS、页面 CSS、共享设计系统 CSS | +| 部署 | 两阶段 Docker 构建 + Nginx | + +## 3. 目录结构 + +```text +core/frontend/ +├─ src/ +│ ├─ main.tsx React 挂载和全局样式入口 +│ ├─ App.tsx 应用总控制器 +│ ├─ api.ts 用户侧和超管侧 API SDK +│ ├─ types.ts 前后端数据契约类型 +│ ├─ generation-error.ts 生成错误展示语义 +│ ├─ model-display.ts 模型展示辅助 +│ ├─ routes/ +│ │ ├─ route-config.ts 路由解析、路径生成、导航定义 +│ │ ├─ stage-config.ts 五阶段顺序、状态和积分格式 +│ │ ├─ auth-screen.tsx 登录注册 +│ │ ├─ dashboard.tsx 工作台 +│ │ ├─ products.tsx 商品列表、商品详情、商品创建入口 +│ │ ├─ models.tsx 模特库 +│ │ ├─ projects.tsx 项目列表和项目创建向导 +│ │ ├─ pipeline.tsx 五阶段生产管线 +│ │ ├─ library.tsx 资产库 +│ │ ├─ ai-tools.tsx 图片创作工作台 +│ │ ├─ free-create.tsx 自由视频创作 +│ │ ├─ account.tsx 账户和积分 +│ │ ├─ team.tsx 团队成员和额度 +│ │ ├─ messages.tsx 消息中心 +│ │ ├─ settings.tsx 设置 +│ │ ├─ trash.tsx 垃圾桶 +│ │ └─ admin/ 平台超管后台 +│ ├─ components/ +│ │ ├─ app-shell.tsx 左侧导航、顶栏和应用外壳 +│ │ ├─ overlays.tsx Modal、Drawer、Confirm、Lightbox +│ │ ├─ product-create-drawer.tsx +│ │ ├─ model-library.tsx 模特选择与模特库交互 +│ │ ├─ pipeline-stage.tsx 管线阶段组件 +│ │ ├─ pager.tsx 分页 +│ │ ├─ loading.tsx 加载状态 +│ │ ├─ review-badge.tsx 审核状态标记 +│ │ ├─ use-view-mode.ts 网格/列表视图持久化 +│ │ └─ free-create/ 自由创作子组件 +│ ├─ design-restraint.css 共享 token 和组件样式 +│ ├─ styles.css 全局布局和通用样式 +│ └─ *-page.css 页面级样式 +├─ public/ +│ ├─ assets/ 字体、图标和静态素材 +│ └─ exact/ HTML 设计稿基线与 mock 素材 +├─ package.json +├─ tsconfig.json +├─ vite.config.ts +├─ Dockerfile +└─ nginx.conf +``` + +## 4. 应用入口 + +### 4.1 `main.tsx` + +`main.tsx` 负责： + +- 创建 React Root。 +- 挂载 ``。 +- 集中导入全局、设计系统和页面 CSS。 + +当前没有 CSS Modules。页面样式通过类名和统一导入生效，因此新增通用类时必须注意跨页面污染。 + +### 4.2 `App.tsx` + +`App.tsx` 是当前应用总控制器，主要负责： + +- 当前 URL 和认证模式。 +- Token 启动恢复。 +- User、Team、Role。 +- 商品和项目列表及总数。 +- 模型配置、积分摘要、通知未读数。 +- 当前商品、当前项目和项目详情。 +- 全局 loading、notice 和页面分发。 +- 用户侧与平台超管侧入口守卫。 + +页面组件通过 props 获取全局数据和操作函数；页面自己的重数据、轮询和交互状态通常保留在页面内部。 + +`App.tsx` 已经承担较多职责。新增全局状态前，应先判断它是否真正跨页面共享，避免继续把页面局部状态上提。 + +## 5. 路由架构 + +前端没有使用 React Router。`routes/route-config.ts` 负责： + +- 读取 `window.location.pathname`、query 和 hash。 +- 将路径解析成内部 `Page`。 +- 用 `history.pushState` / `replaceState` 切换地址。 +- 处理浏览器前进和后退。 +- 生成商品详情、项目管线等带参数路径。 +- 提供导航项、页面标签和父级导航关系。 + +主要业务路径： + +```text +/dashboard +/products +/products/new +/products/:id +/models +/projects +/projects/new +/pipeline +/pipeline/:id +/library +/account +/team +/messages +/asset-factory +/free-create +/image-optimize +/model-photo +/platform-cover +/settings +/trash +/admin/* +``` + +Nginx 对未知前端路径执行 `try_files ... /index.html`，因此刷新 SPA 路径时仍由同一前端入口解析。 + +## 6. API 层 + +`src/api.ts` 是统一 API SDK： + +- 使用 `VITE_API_BASE_URL`；为空时调用同源 `/api`。 +- 自动读取登录 Token。 +- 自动添加 `Authorization: Token ...`。 +- JSON 请求自动添加 content type。 +- FormData 请求跳过 JSON header，让浏览器生成 multipart boundary。 +- 将 DRF 的 `detail`、字段错误和常见权限错误转换成可读消息。 +- 将用户侧接口收敛到 `api`。 +- 将平台超管接口收敛到 `adminApi`。 + +页面不应自行复制 Token、基础 URL 和错误解析逻辑。新接口优先加入 `api.ts` 并在 `types.ts` 声明返回类型。 + +当前没有统一请求缓存层。数据刷新、轮询、请求去重和乐观更新主要由各页面自行处理。 + +## 7. 登录、存储与权限 + +### 7.1 Token + +- 勾选“记住我”时：Token 和用户名信息写入 `localStorage`，有效期七天。 +- 不勾选时：Token 写入 `sessionStorage`，关闭浏览器会话后失效。 +- 过期后清除 Token 和记住信息，并要求重新登录。 + +### 7.2 权限 + +- owner 才能访问团队和账户级页面。 +- `is_platform_admin` 决定是否可以访问 `/admin`。 +- 普通用户访问超管路由会回到用户侧工作台。 +- 无团队的平台超管登录后进入超管后台。 + +前端守卫只负责体验，后端仍必须执行真实权限校验和团队数据隔离。 + +### 7.3 其他本地状态 + +项目还使用本地存储保存部分体验状态，例如： + +- 侧栏折叠。 +- 网格/列表视图。 +- 图片工作台模型和临时状态。 +- 管线场景草稿。 +- 待重试删除队列。 +- 部分聊天或进度恢复信息。 + +本地状态不能替代后端事实。需要跨浏览器、跨成员或长期保存的数据必须进入后端。 + +## 8. 页面模块 + +### 8.1 商品 + +`products.tsx` 当前同时导出： + +- 商品列表页。 +- 商品卡片。 +- 上传创建商品页。 +- 商品详情页。 + +商品页处理搜索、筛选、视图切换、创建、详情、商品图、关联项目和批量删除。 + +### 8.2 视频项目 + +`projects.tsx` 包含： + +- `ProjectsPage`：项目列表、状态筛选、时间筛选和删除。 +- `ProjectWizardPage`：选择或创建商品、填写项目参数并创建项目。 + +项目创建后进入 `/pipeline/:id`。 + +### 8.3 生产管线 + +`pipeline.tsx` 是核心业务页面，覆盖： + +- 脚本 Agent 流式生成和改稿。 +- 脚本段编辑和实体引用。 +- 人物、场景、商品基础资产。 +- 三视图、审核和版本采用。 +- 故事板镜头和候选版本。 +- 视频片段生成和轮询。 +- 配音、BGM、字幕、时间线和导出。 +- 本地草稿、删除重试和刷新恢复。 + +五阶段顺序由 `stage-config.ts` 定义： + +```text +script → base_assets → storyboard → video → export +``` + +该文件是当前前端最大复杂度中心。后续拆分应按阶段、领域状态和副作用边界进行，不能只按 JSX 长度机械拆组件。 + +### 8.4 图片创作 + +`ai-tools.tsx` 覆盖： + +- 图片创作。 +- 模特上身图。 +- 平台套图。 +- 商品关联。 +- 模型选择。 +- 图片会话、批次、历史结果和任务中心。 +- 删除、恢复、收藏等任务操作。 + +生成结果通过 `batch_id`、会话和任务关系归组。页面需要同时处理提交、后端恢复、轮询和用户操作，是第二个主要复杂度中心。 + +### 8.5 自由视频创作 + +`free-create.tsx` 支持： + +- 图片、视频和音频参考素材。 +- 首尾帧等模式约束。 +- 模型、比例、分辨率、时长和 seed。 +- 上传、任务提交、重新生成和下载。 +- 分页/继续加载。 +- 渐进轮询和平滑进度展示。 +- 全屏视频详情。 + +前端显示的平滑进度是体验层估计，任务终态必须以后端返回为准。 + +### 8.6 资产库与垃圾桶 + +`library.tsx` 聚合可复用和成品资产；`trash.tsx` 展示已删除的图片会话、任务或资产批次，并调用后端执行恢复或最终删除。 + +垃圾桶展示必须与后端软删除语义一致，不能仅靠前端数组过滤模拟删除。 + +### 8.7 平台超管后台 + +`routes/admin/admin-app.tsx` 提供独立后台壳，子页面覆盖： + +- 邀请码。 +- 团队和用户。 +- 提示词和质量词。 +- 资产审核。 +- AI 任务监控。 +- 模型供应商和模型配置。 +- 积分流水、计费配置和额度策略。 +- 项目治理和完整性检查。 + +后台使用 `adminApi`，并依赖后端的平台超管权限校验。 + +## 9. AI 慢任务交互 + +前端面对多种执行方式： + +- 脚本 Agent：SSE 流式事件。 +- 生图和视频：创建任务后轮询。 +- 自由视频：渐进轮询并恢复页面进度。 +- 导出：轮询 ExportJob。 +- 审核：调用项目/后台审核状态接口。 + +轮询实现需要满足： + +- 页面卸载后清理 timer。 +- 同一任务避免重复启动多个 timer。 +- 终态及时停止。 +- 网络错误采用退避或可控重试。 +- 刷新后可从后端任务恢复。 +- 失败时显示后端标准化的用户错误。 +- 不使用前端进度推断扣费是否成功。 + +## 10. 样式与设计稿关系 + +### 10.1 正式样式 + +- `design-restraint.css`：共享设计 token 和基础组件。 +- `styles.css`：应用全局结构与通用样式。 +- `*-page.css`：页面级布局和状态。 + +设计相关修改必须遵守仓库 `AGENTS.md` 和 `电商AI平台/design.md`，优先复用共享类和 token。 + +### 10.2 `public/exact` + +`public/exact` 保留原始 HTML、视觉规范、mock 数据和静态素材，用于像素级对照。它不是第二套业务前端，也不应接入真实 API。 + +## 11. 构建与部署 + +### 11.1 本地 + +```bash +npm install +npm run dev +``` + +Vite 开发环境根据配置将 API 请求转发到本地 Django。 + +### 11.2 构建 + +```bash +npm run build +``` + +构建先执行 TypeScript 校验，再由 Vite 生成 `dist`。 + +### 11.3 容器 + +Docker 第一阶段使用 Node 构建，第二阶段使用 Nginx 托管产物。生产默认同源调用 `/api`，避免额外 CORS 配置。 + +Nginx 还负责： + +- `/api/` 反代 Django。 +- `/django-admin/` 和 `/static/` 反代 Django。 +- 静态 assets 长缓存。 +- `index.html` 禁止长期缓存。 +- SPA 路由回落。 + +## 12. 当前风险与演进原则 + +### 12.1 超大页面 + +`pipeline.tsx`、`ai-tools.tsx` 和 `App.tsx` 同时承担状态、副作用和渲染，维护成本较高。拆分优先级： + +1. 提取独立领域 hook。 +2. 提取任务轮询和恢复逻辑。 +3. 提取阶段或工作台容器。 +4. 最后拆纯展示组件。 + +### 12.2 无统一服务端状态层 + +当前未使用 TanStack Query 等库。是否引入应以重复请求、缓存一致性和轮询复杂度为依据，不应只为了技术栈完整度引入。 + +### 12.3 全局 CSS + +页面 CSS 全局生效。新增类名应使用清晰的页面或组件前缀；共享类只在设计系统文件维护，避免页面覆盖造成回归。 + +### 12.4 前后端类型漂移 + +`types.ts` 是手写契约，后端没有 OpenAPI 自动生成。接口字段变化时必须同步 serializer、`api.ts`、`types.ts` 和调用页面。 + +## 13. 文档同步规则 + +出现以下变化时必须更新本文： + +- 一级目录、页面路由或核心组件重命名。 +- `App.tsx` 全局状态边界变化。 +- API SDK、Token 保存或权限守卫变化。 +- 五阶段流程和慢任务交互变化。 +- 图片会话、任务归组、垃圾桶或恢复逻辑变化。 +- CSS 组织、构建或 Nginx 部署变化。