# Giyph AI 文档

> 一站式多模态 AI Agents 短剧 / 广告创作 + 创作者接单分销平台。内置 8 款视频大模型、5 款数字人模型，累计生成 328,542+ 份作品、127+ 团长、651+ 在售订单。基于 React 19.2.0，采用双组件响应式架构，768px 断点自动切换 PC/移动端。

Disallow training: true

## Docs

核心文档，涵盖项目总览。

- [README.md](README.md): 项目总览、技术栈与快速开始指南
- [package.json](package.json): 依赖清单与脚本定义

## 技术架构

Giyph AI 是一个 React 19.2.0 单页应用，采用**双组件响应式架构**，通过 `ResponsiveContainer` 包装器在 768px 断点自动切换。

### Legacy 响应式应用

- **PC 端**：`src/pages/PC/` — 22 个页面，使用 Ant Design 6.x
- **移动端**：`src/pages/Mobile/` — 13 个页面，使用 Ant Design Mobile 5.x
- **状态管理**：React Context（Auth、Language、Player、Cost、Notification、Theme、WebSocket、RechargeConfig）
- **HTTP 客户端**：`src/utils/request.js` — 统一封装，支持请求去重、无感 Token 刷新、自动添加 `tenant-id` 和 `Authorization` 头
- **样式系统**：CSS 变量（`src/themes/variables.css`）+ BEM 命名约定 + CSS Modules

### InfiniteCanvas 模块

- **技术栈**：TypeScript + Tailwind CSS v4 + Zustand + React Query
- **路由**：`/infinite_canvas`、`/infinite_canvas/list`、`/infinite_canvas/:canvasId`
- **仅 PC 端**，独立于 Legacy 技术栈
- 80+ 组件文件，包含 canvas 核心、节点编辑、设置面板、提示词库等

## 项目结构

```
src/
├── api/                    # 26 个 API 模块（JS + TS）
│   ├── infiniteCanvas/     # 画布模块 API（TS：admin, assets, audio, auth, canvas, image, prompts, video, element-generation）
│   ├── asset/              # 素材库 API
│   ├── banner/             # Banner 广告 API
│   ├── consumption/        # 消费记录 API
│   ├── cost/               # 费用配置 API
│   ├── drama/              # 漫剧 API
│   ├── file/               # 文件 API
│   ├── follow/             # 关注 API
│   ├── generate/           # AI 生成 API
│   ├── job/                # 任务 API
│   ├── like/               # 点赞 API
│   ├── login/              # 登录注册 API
│   ├── media/              # 媒体资源 API
│   ├── message/            # 消息 API
│   ├── opc/                # OP 创作 API
│   ├── orderSquare/        # 需求广场 API
│   ├── picture/            # 图片 API
│   ├── points/             # 积分 API
│   ├── recharge/           # 充值 API
│   ├── team/               # 团队 API
│   ├── upload/             # 上传 API
│   ├── user/               # 用户 API
│   └── video/              # 视频 API
├── components/             # 通用组件
│   ├── business/           # 业务组件（AssetLibraryModal、AssetLibrarySelector、PaymentCodeModal、PaymentConfirmModal、PaymentMethodSelector、RechargeModal、RechargePlanCard、TeamRechargeModal、VideoGenerationPanel）
│   ├── common/             # 通用组件（AdCarousel、AssetPreview、BannerCarousel、ConfirmModal、DemoUploader、DownloadConfirmModal、GlobalPlayer、GroupSelect、ImageSelector、LoginModal、MediaGrid、MediaList、MediaPreviewModal、Notification、Pagination、PreviewVideo、ResponsiveContainer、SimplePagination、Tabs、UnauthenticatedPopup、VideoPlayer、VideoThumbnail、VideoWatermark、WebSocketDebugger）
│   ├── custom/             # 定制组件（rightScroll、statCard）
│   └── layout/             # 布局组件（ChatMessages、CustomerCommunication、Header、LeftSidebar、NotificationModal、PCFooter、PCLayout、SystemMessages）
├── config/                 # 配置文件
│   ├── pageConfig.js       # 页面显示配置（页脚、侧边栏控制）
│   └── rechargeConfig.js   # 充值比例配置
├── config.js               # 全局配置（API 地址、WebSocket、租户 ID、环境判断）
├── contexts/               # 8 个 React Context
│   ├── AuthContext.js       # 认证状态（用户、Token、登录弹窗、无感刷新）
│   ├── LanguageContext.js   # 国际化（中文/英文）
│   ├── PlayerContext.js     # 全局视频播放器
│   ├── CostContext.js       # 积分消耗配置
│   ├── NotificationContext.js # 全局通知
│   ├── ThemeContext.js      # 主题管理（暗黑/亮色）
│   ├── WebSocketContext.js  # WebSocket 连接管理
│   └── RechargeConfigContext.js # 充值配置
├── locales/                # 国际化文件
│   ├── zh.json             # 中文翻译
│   ├── en.json             # 英文翻译
│   └── index.js            # 翻译工具函数（getTranslation、t、createTranslator）
├── pages/
│   ├── PC/                 # 22 个 PC 端页面
│   │   ├── Home/           # 首页（瀑布流、内容区、输入区、侧边栏）
│   │   ├── NewHome/        # 新版首页（FeatureGrid、FloatingInput、Banner、ShareRewardModal）
│   │   ├── OpcHome/        # OP 创作首页
│   │   ├── AICreation/     # AI 创作入口
│   │   ├── ProductWorksCreation/ # 产品视频生成（Model/Product 子模块）
│   │   ├── HighResWorksCreation/ # 高清视频（T2V 文生视频/I2V 图生视频）
│   │   ├── DramaWorksCreation/   # 漫剧生成（ScriptEditor、CharacterSceneGenerator、ShotGenerator、PostProcessEditing/SubtitleSetting/TitleSetting/MergeEverything、ProgressBar）
│   │   ├── InfiniteCanvas/ # 无限画布编辑器（独立 TS 技术栈）
│   │   ├── OrderSquare/    # 需求广场（CreateForm、OrderCard、TakeOrder、ConfirmOrder、PostReviews、ContactService、DatePicker）
│   │   ├── MyProfile/      # 个人中心（作品、订单、团队、海报）
│   │   ├── UserProfile/    # 他人主页（OP 创作申请/审批）
│   │   ├── TaskList/       # 任务列表
│   │   ├── ConsumptionRecords/ # 消费记录
│   │   ├── RecordsList/    # 记录列表（积分变更、充值记录、团队充值、OP 提现、我的账户）
│   │   ├── RechargeRecords/ # 充值记录
│   │   ├── Recharge/       # 积分充值
│   │   ├── RechargeRegister/ # 充值注册
│   │   ├── WorkDetail/     # 作品详情
│   │   ├── VideoPlay/      # 视频播放页
│   │   ├── OpCreationDetail/ # OP 创作详情
│   │   ├── OpCreationList/ # OP 创作列表
│   │   ├── UserAgreement/  # 用户协议
│   │   └── PrivacyPolicy/  # 隐私政策
│   └── Mobile/             # 13 个移动端页面
│       ├── NewHome/        # 新版首页
│       ├── OldHome/        # 旧版首页（兼容）
│       ├── ProductWorksCreation/ # 产品作品创作
│       ├── HighResWorksCreation/ # 高清作品创作
│       ├── DramaWorksCreation/   # 漫剧生成
│       ├── MyProfile/      # 个人中心
│       ├── UserProfile/    # 他人主页
│       ├── TaskList/       # 任务列表
│       ├── ConsumptionRecords/ # 消费记录
│       ├── Login/          # 移动端登录
│       ├── Register/       # 移动端注册
│       ├── VideoPlay/      # 视频播放
│       └── MobileBottomNav/ # 底部导航栏（共享组件）
├── styles/                 # 全局样式（Button、Card、Input、Modal、Navigation、animations、scrollbars、common-select）
├── themes/                 # 主题系统
│   ├── variables.css       # CSS 变量定义（颜色、间距、圆角、过渡、阴影）
│   └── themeUtils.js       # 主题工具函数
├── utils/                  # 工具函数库
│   ├── request.js          # Axios 封装（请求去重、Token 刷新、统一错误处理）
│   ├── deviceDetector.js   # 设备检测（768px 断点）
│   ├── assetPath.js        # 静态资源路径处理（getAssetUrl、getIconUrl）
│   ├── websocket.js        # WebSocket 连接管理
│   ├── enums.js            # 枚举常量
│   ├── enumUtils.js        # 枚举工具函数
│   ├── dateUtils.js        # 日期工具
│   ├── mediaUtils.js       # 媒体工具
│   ├── download.js         # 下载工具
│   ├── formatNumber.js     # 数字格式化
│   └── cn.ts               # 类名合并工具（Tailwind）
├── App.js                  # 主应用入口（Context 嵌套、路由渲染）
├── App.css                 # 全局应用样式
├── index.js                # ReactDOM 入口
├── index.css               # 全局基础样式
└── routes.js               # 路由定义（React.lazy + createResponsiveComponent）
```

## 主要路由

- `/home` — 首页，导航卡片与内容展示
- `/ai_creation` — AI 创作功能聚合入口
- `/product_works_creation` — 产品视频生成
- `/high_res_works_creation` — 高清视频（文生视频/图生视频）
- `/drama_works_creation` — 漫剧生成（脚本编辑 → 角色场景生成 → 镜头生成 → 后期处理）
- `/infinite_canvas` — 无限画布编辑器首页
- `/infinite_canvas/list` — 画布项目列表
- `/infinite_canvas/:canvasId` — 画布编辑器工作区
- `/task_list` — 任务管理与进度跟踪
- `/my_profile/:user_key?` — 个人中心（作品、订单、团队）
- `/user_profile/:user_key` — 他人主页
- `/consumption_records` — 消费记录
- `/records_list` — 记录列表（积分、充值、提现、团队）
- `/recharge` — 积分充值
- `/recharge_records` — 充值记录
- `/order_square` — 需求广场
- `/opc_home` — OP 创作首页
- `/op_creation_detail/:id` — OP 创作详情
- `/op_creation_list` — OP 创作列表
- `/work_detail` — 作品详情
- `/video_play` — 视频播放页
- `/user_agreement` — 用户协议
- `/privacy_policy` — 隐私政策

## API 集成

项目使用 `src/utils/request.js` 统一封装所有 HTTP 请求，遵循以下模式：

- **请求去重**：相同请求（方法、URL、参数）同时只执行一次，基于 `method_url_params_data` 生成唯一 Key
- **Token 管理**：双 Token 机制 — `authToken`（访问令牌）+ `pyAccessToken`（Python 后端令牌），支持无感刷新
- **统一错误处理**：网络超时、401/403/500 等错误统一处理并触发全局 `apiError` 事件
- **自动请求头**：`tenant-id`（默认 `'164'`）和 `Authorization` 自动添加
- **路径别名**：使用 `@/utils/request` 导入

### API 模块

- [api/login/index.js](src/api/login/index.js): 登录注册（邮箱登录、手机登录、注册、发送验证码）
- [api/user/index.js](src/api/user/index.js): 用户信息（详情、更新、简介）
- [api/generate/index.js](src/api/generate/index.js): AI 生成（提交生成任务、费用查询）
- [api/media/index.js](src/api/media/index.js): 媒体资源（作品列表、详情、删除）
- [api/video/index.js](src/api/video/index.js): 视频相关
- [api/picture/index.js](src/api/picture/index.js): 图片相关
- [api/drama/index.js](src/api/drama/index.js): 漫剧生成
- [api/upload/index.js](src/api/upload/index.js): 文件上传
- [api/file/index.js](src/api/file/index.js): 文件管理
- [api/consumption/index.js](src/api/consumption/index.js): 消费记录
- [api/cost/index.js](src/api/cost/index.js): 费用/积分消耗配置
- [api/recharge/index.js](src/api/recharge/index.js): 充值（比例配置、下单）
- [api/points/index.js](src/api/points/index.js): 积分管理
- [api/banner/index.js](src/api/banner/index.js): Banner 广告
- [api/asset/index.js](src/api/asset/index.js): 素材库
- [api/job/index.js](src/api/job/index.js): 任务管理
- [api/team/index.js](src/api/team/index.js): 团队管理
- [api/follow/index.js](src/api/follow/index.js): 关注/粉丝
- [api/like/index.js](src/api/like/index.js): 点赞
- [api/message/index.js](src/api/message/index.js): 消息通知
- [api/orderSquare/index.js](src/api/orderSquare/index.js): 需求广场
- [api/opc/index.js](src/api/opc/index.js): OP 创作
- [api/infiniteCanvas/](src/api/infiniteCanvas/): 画布模块 API（TS，含 admin、assets、audio、auth、canvas、image、prompts、video、element-generation、request）

### API 使用规范

```javascript
import request from '@/utils/request';

// GET 请求
const data = await request({ method: 'GET', url: '/giyph_ai/api/user_app/get_user_detail', params: { userId: 1 } });

// POST 请求
const data = await request({ method: 'POST', url: '/giyph_ai/api/endpoint', data: { key: 'value' } });

// 跳过 code 检查（返回完整响应）
const response = await request({ method: 'POST', url: '/api/special', data: {}, skipCodeCheck: true });
```

## 认证系统

- **Token 存储策略**：
  - `localStorage.getItem('authToken')` — 持久登录（记住我）
  - `sessionStorage.getItem('authToken')` — 会话登录
  - `localStorage.getItem('refreshToken')` — 刷新令牌
  - `localStorage.getItem('pyAccessToken')` — Python 后端访问令牌
- **AuthContext** (`src/contexts/AuthContext.js`)：统一管理认证状态
  - `user` / `userAvatar` / `points` / `userInfo` — 用户基本信息
  - `isGuest` — 访客判断（`user === '游客'`）
  - `isLoadingUser` — 用户加载状态
  - `login()` / `logout()` — 登录/登出
  - `callLoginModal()` / `setShowLoginModal()` — 登录弹窗控制
  - `refreshUserInfo()` / `fetchUserDetail()` / `updateUserInfo()` — 用户信息刷新
- **Token 工具函数**（从 `request.js` 导入）：`getAccessToken()`、`getRefreshToken()`、`setToken()`、`removeToken()`
- **受保护操作模式**：操作前通过 `isGuest` 判断，访客则调用 `callLoginModal()`

## 状态管理

不使用 Redux/Zustand（InfiniteCanvas 除外），使用 React Context + 本地状态：

- [AuthContext.js](src/contexts/AuthContext.js): 认证状态（用户、Token、登录弹窗、无感刷新）
- [LanguageContext.js](src/contexts/LanguageContext.js): 国际化语言切换（中文/英文），存储在 `localStorage.preferredLanguage`
- [PlayerContext.js](src/contexts/PlayerContext.js): 全局视频播放器（跨组件共享播放状态）
- [CostContext.js](src/contexts/CostContext.js): 积分消耗配置（从 `/api/generate_app/generation_cost_info` 获取）
- [NotificationContext.js](src/contexts/NotificationContext.js): 应用级通知管理
- [ThemeContext.js](src/contexts/ThemeContext.js): 主题管理（暗黑/亮色），通过 `data-theme` 属性应用到 document，存储在 `localStorage.app-theme`
- [WebSocketContext.js](src/contexts/WebSocketContext.js): WebSocket 连接生命周期管理
- [RechargeConfigContext.js](src/contexts/RechargeConfigContext.js): 充值配置上下文

## 国际化 (i18n)

- **语言文件**：[zh.json](src/locales/zh.json)（中文）、[en.json](src/locales/en.json)（英文）
- **翻译工具**（[locales/index.js](src/locales/index.js)）：
  - `getTranslation(key, lang, page)` — 基础翻译
  - `t(key, page)` — 自动获取当前语言
  - `createTranslator(page)` — 创建页面专用翻译函数
- **语言切换事件**：`window.dispatchEvent(new CustomEvent('languageChanged', { detail: 'en' }))`
- **添加新功能时必须同时更新 zh.json 和 en.json**

## 主题系统

- **CSS 变量**（[themes/variables.css](src/themes/variables.css)）：
  - 主色调：`--primary-color`（翠绿 `#10b981`）
  - 背景色：`--bg-black`、`--bg-dark`、`--bg-darker`
  - 文本色：`--text-primary`、`--text-secondary`、`--text-muted`
  - 间距：`--spacing-xs` ~ `--spacing-xl`
  - 圆角：`--radius-sm`、`--radius-md`、`--radius-lg`
  - 过渡：`--transition-fast`（0.2s）、`--transition-normal`（0.3s）、`--transition-slow`（0.5s）
  - 阴影：`--shadow-sm`、`--shadow-md`
- **主题工具**（[themes/themeUtils.js](src/themes/themeUtils.js)）：主题切换辅助函数
- **ThemeContext**：管理暗黑/亮色模式，通过 `data-theme` 属性切换

## InfiniteCanvas 模块

AI 驱动的无限画布编辑器，仅 PC 端，独立技术栈：

- **技术栈**：TypeScript + Tailwind CSS v4 + Zustand（状态管理）+ React Query（数据获取）
- **路由**：`/infinite_canvas`（首页）→ `/infinite_canvas/list`（项目列表）→ `/infinite_canvas/:canvasId`（编辑器）

### 组件架构

- **canvas/** — 画布核心（infinite-canvas、canvas-connections、canvas-mini-map）
- **canvas-chrome/** — 画布外壳（toolbar、top-bar、zoom-controls、context-menu、asset-picker-modal、connection-create-menu）
- **node/** — 节点系统（canvas-node、canvas-node-generation）
- **node-overlays/** — 节点覆盖层（hover-toolbar、image-toolbar-settings、image-toolbar-tools）
- **node-dialogs/** — 节点对话框（angle、crop、mask-edit、split、upscale）
- **panels/** — 功能面板（config-composer、config-node-panel、node-prompt-panel、prompt-library、assistant-panel、resource-mention-textarea、image-generation-pending）
- **settings/** — 设置组件（image-settings、video-settings、audio-settings、model-picker、size-picker、cost-summary）
- **prompts/** — 提示词库（prompt-card、prompt-detail-dialog、prompt-select-dialog、use-prompt-list）
- **project/** — 项目管理（project-card、delete-projects-dialog）
- **layout/** — 布局组件（app-providers、app-top-nav、app-config-modal、user-status-actions、version-release-modal、client-root-init）
- **ui/** — UI 组件（animated-theme-toggler、dia-text-reveal、menu-helpers、select）

### 数据层

- **stores/** — Zustand 状态管理（canvas、config、ui、asset、theme、user）
- **hooks/** — 自定义 Hooks（image-generation-options、video-cost、picture-point-config、copy-text、version-check）
- **infra/** — 基础设施（app-sync、file-storage、image-storage、webdav-sync）
- **lib/** — 工具库（app-theme、canvas-theme、audio-generation、image-reference-prompt、seedance-video、image-utils、zip、release、localforage-storage）
- **utils/** — 画布工具（export、generation-image、generation-video、image-data、node-metadata、node-size、resource-references）
- **types/** — TypeScript 类型定义（export、image、media、index）
- **constants/** — 常量定义（credits、env、navigation-tools）
- **api/** — API 模块（admin、assets、audio、auth、canvas、image、prompts、video、element-generation、request）

## 组件库

### 业务组件 (business)

- [AssetLibraryModal](src/components/business/AssetLibraryModal/): 素材库弹窗（含 GroupManageModal、UploadAssetModal）
- [AssetLibrarySelector](src/components/business/AssetLibrarySelector/): 素材选择器
- [PaymentCodeModal](src/components/business/PaymentCodeModal/): 支付码弹窗
- [PaymentConfirmModal](src/components/business/PaymentConfirmModal/): 支付确认弹窗
- [PaymentMethodSelector](src/components/business/PaymentMethodSelector/): 支付方式选择器
- [RechargeModal](src/components/business/RechargeModal/): 充值弹窗
- [RechargePlanCard](src/components/business/RechargePlanCard/): 充值套餐卡片
- [TeamRechargeModal](src/components/business/TeamRechargeModal/): 团队充值弹窗
- [VideoGenerationPanel](src/components/business/VideoGenerationPanel/): 视频生成面板

### 通用组件 (common)

- [AdCarousel](src/components/common/AdCarousel/): 广告轮播
- [AssetPreview](src/components/common/AssetPreview/): 素材预览
- [BannerCarousel](src/components/common/BannerCarousel/): Banner 轮播
- [ConfirmModal](src/components/common/ConfirmModal/): 确认弹窗
- [DemoUploader](src/components/common/DemoUploader/): 示例上传组件
- [DownloadConfirmModal](src/components/common/DownloadConfirmModal/): 下载确认弹窗
- [GlobalPlayer](src/components/common/GlobalPlayer/): 全局视频播放器
- [GroupSelect](src/components/common/GroupSelect/): 分组选择器
- [ImageSelector](src/components/common/ImageSelector/): 图片选择器
- [LoginModal](src/components/common/LoginModal/): 登录弹窗
- [MediaGrid](src/components/common/MediaGrid/): 媒体网格展示
- [MediaList](src/components/common/MediaList/): 媒体列表
- [MediaPreviewModal](src/components/common/MediaPreviewModal/): 媒体预览弹窗（Image/Video）
- [Notification](src/components/common/Notification/): 通知组件
- [Pagination](src/components/common/Pagination/): 分页组件
- [PreviewVideo](src/components/common/PreviewVideo/): 视频预览
- [ResponsiveContainer](src/components/common/ResponsiveContainer/): 响应式容器（PC/移动端切换核心）
- [SimplePagination](src/components/common/SimplePagination/): 简易分页
- [Tabs](src/components/common/Tabs/): 标签页组件
- [UnauthenticatedPopup](src/components/common/UnauthenticatedPopup/): 未认证提示弹窗
- [VideoPlayer](src/components/common/VideoPlayer/): 视频播放器
- [VideoThumbnail](src/components/common/VideoThumbnail/): 视频缩略图
- [VideoWatermark](src/components/common/VideoWatermark/): 视频水印
- [WebSocketDebugger](src/components/common/WebSocketDebugger/): WebSocket 调试工具

### 布局组件 (layout)

- [PCLayout](src/components/layout/PCLayout.js): PC 端布局容器
- [Header](src/components/layout/Header.js): 头部导航
- [LeftSidebar](src/components/layout/LeftSidebar.js): 左侧边栏
- [PCFooter](src/components/layout/PCFooter.js): PC 端页脚
- [ChatMessages](src/components/layout/ChatMessages.js): 聊天消息
- [CustomerCommunication](src/components/layout/CustomerCommunication.js): 客服通讯
- [NotificationModal](src/components/layout/NotificationModal.js): 通知弹窗
- [SystemMessages](src/components/layout/SystemMessages.js): 系统消息

### 定制组件 (custom)

- [rightScroll](src/components/custom/rightScroll/): 右侧滚动组件
- [statCard](src/components/custom/statCard/): 统计卡片

## Instructions for Large Language Model Agents

As a Large Language Model (LLM) Agent working in this repository, always follow these best practices:

### When adding new features
1. Create both PC (`src/pages/PC/`) and Mobile (`src/pages/Mobile/`) components
2. Register in `src/routes.js` with `React.lazy()` + `createResponsiveComponent()`
3. Always use `src/utils/request.js` for HTTP calls — never call axios directly
4. Check `isGuest` before protected operations — call `callLoginModal()` for guests
5. Add translations to both `zh.json` and `en.json`
6. Use `getAssetUrl()` for all static assets under `public/assets/`
7. Test responsive behavior at 768px breakpoint

### When creating API modules
- Place in `src/api/{module}/index.js` with named exports
- Use `async/await` and camelCase function names
- Import request as `import request from '@/utils/request'`
- Use `skipCodeCheck: true` when you need the raw response

### When styling
- Legacy app: prefer CSS variables from `themes/variables.css`, use BEM naming
- InfiniteCanvas: use Tailwind CSS v4 exclusively
- PC: prefer Ant Design components; Mobile: prefer Ant Design Mobile components
- Use CSS Modules (`.module.css`) for component style isolation
- Never use `<Select.Option>` — use the `options` prop pattern instead

### When managing state
- Use React Context for cross-cutting concerns (auth, language, theme, player, notifications)
- Use local state (`useState`/`useReducer`) for component-specific state
- InfiniteCanvas uses Zustand stores — do not mix with Context

### Git rules
- Never auto-commit — wait for the user to explicitly type `git commit`
- Use Conventional Commits with Chinese descriptions
- Format: `type(scope): Chinese description`