docs: 补充前后端架构说明
This commit is contained in:
hh
@@ -1,5 +1,8 @@
|
|||||||
# AirShelf 技术架构方案
|
# AirShelf 技术架构方案
|
||||||
|
|
||||||
|
> 文档说明（2026-07-17）：本文完整保留 2026-05-29 的顶层架构决策、目标模型与开发路线，其中部分名称和部署形态属于早期规划，不代表当前代码已经按原方案实现。
|
||||||
|
> 当前实现请以 [后端架构](backend/ARCHITECTURE.md) 和 [前端架构](frontend/ARCHITECTURE.md) 为准；系统演进时应同时维护“原始决策背景”和“当前实现说明”。
|
||||||
|
|
||||||
> 版本：v1.0
|
> 版本：v1.0
|
||||||
> 日期：2026-05-29
|
> 日期：2026-05-29
|
||||||
> 定位：从原型走向真实可运营产品的顶层技术架构决策文档
|
> 定位：从原型走向真实可运营产品的顶层技术架构决策文档
|
||||||
|
|||||||
@@ -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 或部署方式变化。
|
||||||
@@ -2,6 +2,8 @@
|
|||||||
|
|
||||||
All backend code lives under `AirShelf/core/backend` by project decision.
|
All backend code lives under `AirShelf/core/backend` by project decision.
|
||||||
|
|
||||||
|
Architecture and module boundaries: [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||||
|
|
||||||
## Local bootstrap
|
## Local bootstrap
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -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 部署变化。
|
||||||
Reference in New Issue
Block a user