docs: 补充前后端架构说明

2026-07-17 18:11:10 +08:00
parent 81fdb02517
commit 2daf9b77e9
4 changed files with 845 additions and 0 deletions
@@ -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。
+- 挂载 `<App />`。
+- 集中导入全局、设计系统和页面 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 部署变化。