gongxiangp2/CLAUDE.md

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 提供项目代码工作的指导说明。

项目概述

由壹点3D素材 - 一个具有 Apple 风格 UI 设计的现代化 3D 素材共享平台。

技术栈：

• Next.js 14 (App Router) + React 18 + TypeScript
• NextAuth.js 身份认证（凭证登录 + 钉钉 OAuth）
• PostgreSQL + Prisma ORM
• MinIO S3（预览图）+ 本地存储（压缩包）
• Redis（上传会话管理）
• TailwindCSS 样式

开发命令

# 开发环境
npm run dev              # 在 :3000 端口启动开发服务器

# 构建与部署
npm run build           # 生成 Prisma 客户端 + Next.js 构建
npm start               # 启动生产服务器

# 数据库
npm run prisma:generate  # 生成 Prisma 客户端
npm run prisma:push      # 推送数据库结构
npm run prisma:studio    # 打开 Prisma Studio

# 测试
npm test                # 运行 Jest 测试
npm run test:watch      # 监视模式
npm run test:coverage   # 覆盖率报告

# 代码检查
npm run lint            # ESLint

网络架构

生产基础设施

物理服务器：

• 生产服务器：192.168.58.20
• 构建服务器：192.168.42.134

Docker 网络：

• 网络名称：youyidian-3d_app-network
• 驱动类型：bridge
• 连接的容器：
  • youyidian-3d-material（生产应用）
  • gongxiangpan-redis（生产 Redis）
  • youyidian-3d-shadow（影子环境应用）

数据库配置

PostgreSQL (192.168.58.20:5432)：

• 数据库用户：gongxiangpan
• 生产数据库：lobechat（5918 条素材记录）✅
• 影子环境数据库：lobechat_stage（4051 条素材记录）
• 默认数据库：gongxiangpan（旧系统，仅 4 个表，未使用）

⚠️ 重要提示：生产数据库名称是 lobechat，不是 gongxiangpan（那只是 PostgreSQL 用户名）

Redis 配置

⚠️ 【重要】Redis 连接依赖 Docker 网络配置

应用容器必须连接到 youyidian-3d_app-network 网络才能访问 Redis。如果 Redis 连接失败，会导致：

• 上传分片无法保存，上传到 100% 后循环重传
• 会话无法持久化，用户频繁掉线

正确的部署命令必须包含 --network 参数：

docker run -d --name youyidian-3d-material \
  --network youyidian-3d_app-network \  # ⚠️ 必须指定网络！
  -p 4320:3000 \
  ...

诊断 Redis 连接问题：

# 1. 检查容器是否在正确网络
docker network inspect youyidian-3d_app-network | grep youyidian-3d-material

# 2. 检查 Redis 连接
docker exec youyidian-3d-material sh -c "ping -c 2 gongxiangpan-redis"

# 3. 检查容器日志中的 Redis 状态
docker logs youyidian-3d-material 2>&1 | grep -i redis | tail -5

# 4. 手动连接到网络（如果遗漏）
docker network connect youyidian-3d_app-network youyidian-3d-material
docker restart youyidian-3d-material

生产环境 Redis：

• 容器名称：gongxiangpan-redis
• 连接地址：redis://gongxiangpan-redis:6379（Docker 网络内）
• 环境变量：USE_REDIS=true、REDIS_URL=redis://gongxiangpan-redis:6379
• 会话 TTL：4 小时（14400 秒）
• 内存限制：128MB（maxmemory-policy: allkeys-lru）
• 无需密码

✅ 已验证：生产环境正在使用 Redis 存储上传会话（不是内存 Map 兜底方案）

• 验证方式：在 Redis 中找到 3 个活跃的上传会话
• 数据格式：{"fileName": "...", "fileSize": N, "totalChunks": N, "chunks": [...], "createdAt": N, "userId": "..."}

开发环境 Redis：

• 连接地址：redis://localhost:6379
• 兜底方案：内存 Map（Redis 不可用时）
• 启用方式：通过 USE_REDIS=true 环境变量

MinIO/S3 存储配置

MinIO 服务器 (192.168.58.20:9000)：

• 访问密钥：GXPAccessKey2025
• 秘密密钥：GXPSecretKey2025SecureMinIO
• 存储桶：gongxiangpan
• 文件路径：由壹点AI/

公网访问域名：

• URL：https://s3.yydd.ai/gongxiangpan
• 预览链接过期时间：7200 秒（2 小时）
• 路径样式：已启用

上传配置

当前设置（截至 2026-01-27）：

• 分片大小：50MB（内网/外网统一）
• 并发数：2-3 个并发上传
• 会话 TTL：4 小时（Redis）
• 超时时间：每个分片 5-10 分钟

容器端口映射

容器	内部端口	外部端口	用途
youyidian-3d-material	3000	4320	生产应用
youyidian-3d-shadow	3000	5320	影子环境应用
gongxiangpan-redis	6379	-	生产 Redis

密码和密钥管理

⚠️ 安全原则：敏感信息存储在服务器上，不提交到 Git。

SSH 密钥配置

本地密钥位置：C:\Users\54972\.ssh

服务器	IP地址	SSH别名	密钥文件	用途
生产服务器	192.168.58.20	prod	youyidian_prod_ed25519	应用容器、数据库、Redis
构建服务器	192.168.42.134	build	id_rsa_build_192.168.42.134	Docker镜像构建
FRP服务器	180.97.221.140	frp	id_rsa_frp_180.97.221.140	内网穿透
License服务器	122.51.149.232	license-server	id_ed25519_license_122.51.149.232	License服务
腾讯云服务器	45.249.208.118	tencent	tencent_server.pem	腾讯云服务器

未识别的密钥：

• id_rsa / id_rsa.pub - 默认密钥（保留不动）
• flnxilicenseserver.pem - 可能是 license 服务器的备用密钥（PEM格式）

连接方式：

# 使用别名（推荐）
ssh prod      # 生产服务器
ssh build     # 构建服务器
ssh frp       # FRP服务器
ssh tencent   # 腾讯云服务器

# 使用IP
ssh 192.168.58.20

配置文件：C:\Users\54972\.ssh\config（已配置好 IdentityFile）

查看密码的方式

方式1：通过 SSH 查看环境变量

# 查看生产环境所有环境变量
ssh root@192.168.58.20 "docker exec youyidian-3d-material printenv | grep -E 'DATABASE|S3|REDIS|NEXTAUTH'"

# 查看特定密码
ssh root@192.168.58.20 "docker exec youyidian-3d-material printenv | grep DATABASE_URL"
ssh root@192.168.58.20 "docker exec youyidian-3d-material printenv | grep S3_"

方式2：查看 docker-compose.yml（服务器端）

# 生产服务器上的配置文件路径
ssh root@192.168.58.20 "cat /root/youyidian-3d/docker-compose.yml | grep -A 20 'environment:'"

方式3：查看 .env 文件（如果存在）

ssh root@192.168.58.20 "cat /root/youyidian-3d/.env 2>/dev/null || echo 'No .env file found'"

需要记录的敏感信息位置

信息类型	存储位置	查看命令
数据库密码	服务器环境变量	docker exec youyidian-3d-material printenv | grep DATABASE_URL
MinIO/S3 密钥	服务器环境变量	docker exec youyidian-3d-material printenv | grep S3_
NextAuth 密钥	服务器环境变量	docker exec youyidian-3d-material printenv | grep NEXTAUTH
钉钉 App 密钥	代码中（已加密）	cat app/api/dingtalk/login/route.ts | grep DINGTALK
管理员 API Key	服务器环境变量	docker exec youyidian-3d-material printenv | grep ADMIN_API_KEY

密码变更记录

当密码变更时，在此处记录：

• 2026-01-27：初始记录，建立密码管理机制

---

部署

项目使用 远程构建部署 方式，通过 PowerShell 脚本：

# 部署到生产环境
.\deploy-remote-build.ps1

# 部署到影子环境
.\deploy-remote-build.ps1 -Target shadow

# 强制重新构建（无缓存）
.\deploy-remote-build.ps1 -NoCache

部署流程：

1. 本地打包代码（排除 node_modules、.next、.git）
2. 上传到构建服务器 (192.168.42.134)
3. 在构建服务器上构建 Docker 镜像
4. 推送到本地镜像仓库 (192.168.42.134:5000)
5. 拉取到生产服务器 (192.168.58.20)
6. 在端口 4320（生产）或 5320（影子）启动容器

架构

目录结构

app/
├── api/                          # API 路由
│   ├── auth/[...nextauth]/       # NextAuth 配置
│   ├── materials/                # 素材增删改查、上传、下载
│   │   ├── upload/               # 上传端点（分片、完成、特定类型）
│   │   └── [id]/                 # 单个素材操作
│   ├── admin/                    # 管理员端点（用户、权限、统计）
│   ├── external/                 # 外部 API 集成
│   └── user/                     # 用户资料操作
├── [id]/share                    # 公开分享页面
├── admin/                        # 管理员后台页面
├── edit/[id]/                    # 素材编辑页面
├── login/                        # 登录页面
└── page.tsx                      # 首页（素材网格）

components/
├── upload/                       # 上传组件
│   ├── UploadModal.tsx           # 主上传弹窗（通用上传）
│   ├── ProductPackageUploader.tsx    # 产品全案
│   ├── TaskPageUploader.tsx          # 任务-页面
│   ├── VideoScreenshotUploader.tsx   # 任务-视频截图
│   ├── ThreeDOriginalUploader.tsx    # 3D原图
│   ├── AIOriginalUploader.tsx        # AI原图
│   ├── RealPhotoUploader.tsx        # 实拍图
│   └── SpecialBatchUploadUI.tsx  # 批量上传界面（音乐、视频、3D、品牌VI等）
├── admin/                       # 管理后台组件
├── home/                        # 首页组件
└── detail/                      # 详情页组件

lib/
├── chunk-upload.ts              # 分片上传（IndexedDB 状态 + 重试）
├── chunk-upload-config.ts       # 分片上传配置（50MB统一分片）
├── upload-sessions.ts           # 内存上传会话 Map（开发环境）
├── upload-sessions-redis.ts     # Redis 上传会话（生产环境）
├── task-material-processor.ts   # 任务类型素材处理逻辑
├── material-validation.ts       # 素材类型验证辅助函数
├── material-type-mapper.ts      # 素材类型常量和映射器
├── pdf-processor.ts             # PDF 处理（预览图提取）
├── image-processor.ts           # 图片压缩和切片
├── video-processor.ts           # 视频转码
├── audio-processor.ts           # 音频元数据提取
├── psd-processor.ts             # PSD 文件处理
├── s3.ts                        # MinIO S3 客户端
├── auth.ts                      # NextAuth 配置
├── prisma.ts                    # Prisma 客户端
└── network.ts                   # 网络检测和带宽监控

素材类型

平台支持多种素材类型，使用不同的上传流程：

类型	中文名称	上传流程	特殊要求
3D场景	3D Scene	标准流程	渲染器 (CR/V5/FB)
详情模板	Detail Template	展示图 + zip	PSD 切片（200KB 分块）
模特	Model	仅模特图片	无需 zip
标准模型	Standard Model	主图 + SKU	SKU 管理
品牌VI灵感	Brand VI	仅 PDF	自动从 PDF 第1页提取预览
任务-详情	Task-Detail	ProductPackageUploader	主图/SKU/详情图/PSD
任务-页面	Task-Page	TaskPageUploader	预览图 → zip
任务-视频截图	Task-Video	VideoScreenshotUploader	截图 → zip
音乐/种草视频/买家秀/小红书	特殊类型	批量上传	特定类型限制

身份认证与授权

用户角色：

• USER - 普通用户
• ADMIN - 管理员（旧版，保留兼容性）
• DEPT_ADMIN - 部门管理员
• SYSTEM_ADMIN - 系统管理员
• isSuperAdmin - 超级管理员标记（最多4人）

钉钉集成：

• OAuth 流程：/api/dingtalk/login
• 回调地址：/dingtalk-callback
• 通过 dingtalkUserId 关联用户
• 首次登录时创建/更新用户资料

会话管理：

• JWT 策略，30天过期
• Token 包含：id、role、department、isSuperAdmin、avatar

部门权限：

• DepartmentMaterialPermission 表控制部门访问权限
• 字段：canView、canDownload、canShare、canDownloadSource
• 通过 linkedToDepartment 实现权限继承

上传系统架构

分片上传流程（lib/chunk-upload.ts）：

1. 初始化 - 生成 uploadId，在 Redis/Map 中创建会话
2. 分片上传 - 顺序上传分片，支持重试
   • 统一分片大小：50MB（内网/外网统一）
   • IndexedDB 持久化状态，支持断点续传
3. 完成 - 服务端合并分片并处理

上传会话管理：

• 开发环境：lib/upload-sessions.ts - 内存 Map
• 生产环境：lib/upload-sessions-redis.ts - Redis，4小时 TTL
• 已完成会话：1小时 TTL
• 关键函数：saveUploadSession、getUploadSession、updateChunk、setCompletedSessionTTL

特殊上传流程：

1. 标准上传 (/api/materials/upload)

   • 预览图 + 可选 zip
   • 直接上传或分片上传（如果超过阈值）

2. 任务-详情 (ProductPackageUploader)

   • /api/materials/upload/product-package/init
   • 上传内容：主图、SKU图、详情图、PSD 文件
   • lib/task-material-processor.ts 处理（6个步骤）

3. 任务-页面 (TaskPageUploader)

   • /api/materials/upload/task-page/init
   • 预览图 → zip 生成

4. 品牌VI（PDF 上传）

   • lib/pdf-processor.ts 提取第1页作为预览
   • lib/pdf-upload-handler.ts 处理上传

文件处理流程

图片处理（lib/image-processor.ts）：

• 预览压缩：最大 200KB，质量 85
• 详情切片：200KB 分块，带重叠
• 支持水印
• 使用 Sharp 库处理

视频处理（lib/video-processor.ts）：

• 原视频 → 540p 预览
• 生成片段（前30秒）
• 提取封面
• 基于 FFMPEG 转码
• 队列式处理

音频处理（lib/audio-processor.ts）：

• 元数据提取（艺术家、专辑、时长）
• 支持格式：MP3、FLAC、M4A、AAC、OGG、WAV

PSD 处理（lib/psd-processor.ts）：

• 图层提取
• 使用 ag-psd 生成预览

API 集成

外部 API（lib/external-api.ts）：

• /api/external/download - 通过 Token 验证下载
• /api/external/product-assets - 任务系统批量资产下载

API Key 系统：

• ApiKey 表用于外部系统身份认证
• ApiCallLog 跟踪所有 API 调用
• 通过 x-api-key 请求头或 ADMIN_API_KEY 环境变量验证

性能优化

分片配置（lib/chunk-upload-config.ts）：

• 统一使用 50MB 分片（内网/外网一致）
• 动态超时时间：根据分片大小自动计算（300KB/s 最低速度）
• 并发控制：2-3 个并发（内网3、外网2）
• 请求数减少：1GB 文件从 100 个请求减少到 20 个（80% 减少）

Redis 优化：

• 会话 TTL：4小时（活跃中）、1小时（已完成）
• 连接池，带重试策略
• 离线队列，增强连接弹性

内存监控（lib/memory-monitor.ts）：

• 跟踪上传期间的堆使用
• 流式合并，避免 Buffer.concat() 溢出

重要文件位置

文件	用途
prisma/schema.prisma	数据库结构（所有模型）
lib/material-validation.ts	类型特定验证规则
lib/material-type-mapper.ts	素材类型常量和映射器
lib/task-material-processor.ts	任务类型处理流程（6个步骤）
lib/chunk-upload.ts	核心分片上传逻辑
middleware.ts	请求拦截和认证检查
app/api/materials/upload/route.ts	旧版上传端点
app/api/materials/upload/chunk/route.ts	分片上传处理

环境变量

.env 中必需的配置：

DATABASE_URL=postgresql://...
NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000

# S3/MinIO
S3_ENDPOINT=...
S3_BUCKET=...
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

# Redis（生产环境）
REDIS_URL=redis://localhost:6379

# 管理员
ADMIN_API_KEY=...

# 钉钉（可选）
DINGTALK_APP_KEY=...
DINGTALK_APP_SECRET=...

常用模式

API 路由认证：

import { getServerSession } from 'next-auth'
import { authOptions } from '@/lib/auth'

const session = await getServerSession(authOptions)
if (!session?.user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })

Prisma 事务：

await prisma.$transaction(async (tx) => {
  const material = await tx.material.create({ ... })
  await tx.materialAsset.createMany({ ... })
  return material
})

错误处理：

import { parseApiError } from '@/lib/error-handler'
try { ... }
catch (error) {
  const { message } = parseApiError(error)
  return NextResponse.json({ error: message }, { status: 500 })
}

已知问题和注意事项

1. 内存溢出 - 在 upload-sessions.ts 中使用流式合并，不要用 Buffer.concat()
2. 竞态条件 - 处理过程中避免重复更新 previewUrl
3. 软删除 - 素材有 deletedAt 字段 - 始终过滤掉这些记录
4. 任务号格式 - 格式：TASK + 12-18位数字 + 可选的 -XX 后缀
5. 预览生成 - 标记上传完成前必须完成预览生成
6. Docker 网络 - 容器必须在 youyidian-3d_app-network 上才能访问 Redis

测试状态

• Jest 已配置，但测试覆盖率较低
• 推荐通过影子环境部署进行手动测试
• 使用 /api/admin/system-status 进行健康检查

---

👤 开发者偏好

⚠️ 沟通偏好

语言：

• 全中文环境：回复、注释、文档、变量命名、思考过程、Git message
• 表达方式：多用自然语言，少用代码堆砌
• 用户背景：非程序员，侧重日常语言解释

回复风格：

• 少代码多文字
• 必要时用少量代码示例
• 优先自然语言说明

🧠 思维方式

方案分析：

• 对比不同方案的优劣
• 用数字和星级量化评价
• 结构化输出，用 emoji 标记章节

问题解决：

• 根因分析：不满足表面修复，深入排查底层原因
• 验证导向：修改后必须验证效果

架构思维：

• 优先考虑稳定性和可扩展性
• 模块化设计，构建稳定基础
• 统一 UI 组件和页面风格
• 抽取通用工具函数和样式
• 减少重复代码，降低维护成本

💼 工作风格

代码原则：

• 不写不重要的文档
• 保持代码简洁，避免过度工程化
• 优先使用现有组件和方案

垃圾文件清理（开发时即时清理，不留尾巴）：

• 更新脚本/文档时删除旧版本
• 测试完成后删除临时文件
• 一次性脚本用完即删
• 用 Git 管理版本，不创建备份文件
• 清理无用的会话数据、缓存、临时文件

执行偏好：

• 能自动执行的不让用户手动操作
• 能批量处理的不让用户逐个处理

⚡ 性能意识

内存：

• 避免内存泄漏（事件监听器、定时器、闭包）
• 优化缓存策略（TTL、上限控制）
• 流式处理大文件，避免全量加载

🔒 数据安全

• 绝不删除重要数据目录
• 修改前备份数据

📋 工作习惯

Git：

• 只有明确要求时才创建 commit
• Commit message 使用中文，简洁明了

文件操作：

• 修改前先读取文件内容
• 创建新文件前检查是否已存在