# 由壹点3D素材

一个现代化的3D素材分享平台，采用苹果官方UI设计规范。

> ⚠️ 强烈建议：可迁移化部署时只需编辑根目录的 `config-bianliang.env`
>
> - 将你的域名、内网地址、图片域名白名单、CORS 白名单、钉钉回调、对象存储等统一填在该文件中
> - 系统启动会自动读取该文件：仅在变量“未设置”时注入，不会覆盖系统环境或 `.env/.env.local`
> - 修改后重启服务生效（重启 Node 或对应容器）
> - 前端可读变量以 `NEXT_PUBLIC_` 开头，服务端变量无需此前缀

## 🎯 项目目标

**让其他公司能够一键部署或一条命令从Docker部署到自己的NAS或服务器上**

### 核心设计原则
- **性能开销优先** - 最小化资源消耗，确保在低配置设备上也能稳定运行
- **稳定性优先** - 确保长期稳定运行，减少崩溃和错误
- **易于部署** - 零配置或最小配置即可运行

详细规范请参考：[架构设计与编码规范](./架构设计与编码规范.md)

## 一键式可迁移配置（推荐）

不想到处找变量？只需编辑根目录的 `config-bianliang.env`，填好注释中的值并重启服务即可。
系统在启动时会自动读取该文件，只有当某个变量"未设置"时才会注入，绝不会覆盖你在系统环境或 `.env/.env.local` 中已设置的值。

适合场景：不同公司、不同域名、NAS/内外网混合环境的快速切换与迁移。

**快速部署指南**：[一键部署快速指南](./一键部署快速指南.md)

包含的关键项（全部已带中文注释）：
- 站点/域名：`APP_PUBLIC_URL`, `NEXTAUTH_URL`, `PUBLIC_DOMAINS`, `NEXT_PUBLIC_PUBLIC_DOMAINS`, `NEXT_PUBLIC_PORTAL_BASE_URL`, `NEXT_PUBLIC_INTRANET_URL`
- 默认 LOGO：`NEXT_PUBLIC_DEFAULT_HEADER_LOGO_URL`, `NEXT_PUBLIC_DEFAULT_LOGIN_LOGO_URL`
- 钉钉回调：`NEXT_PUBLIC_DINGTALK_CALLBACK_URL`
- 图片域名白名单（Next/Image）：`IMAGE_REMOTE_HOSTS`
- CORS 白名单：`ALLOWED_ORIGINS`
- 数据恢复/对象存储：`RESTORE_S3_BUCKET_URL`, `RESTORE_S3_PUBLIC_URL`

提示：前端需要读取的变量以 `NEXT_PUBLIC_` 开头；服务端专用变量不需要此前缀。

## 技术栈

- **前端**: Next.js 14 + React 18 + TypeScript + TailwindCSS
- **认证**: NextAuth.js
- **数据库**: PostgreSQL + Prisma ORM
- **存储**: MinIO S3 (预览图) + 本地存储 (压缩包)

## 功能特性

- ✅ 用户注册/登录系统
- ✅ 素材上传（预览图 + 压缩包）
- ✅ 素材浏览与下载
- ✅ 管理员后台管理
- ✅ 用户管理
- ✅ 苹果风格UI设计

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并按需填写；部署时可结合 `config-bianliang.env` 管理差异化配置。

```bash
cp .env.example .env
```

- 如需在同一存储桶隔离测试与生产数据，可以设置 `S3_ENV_PREFIX`（例如 `testing/`），系统会自动在上传路径前添加该命名空间。

### 3. 初始化数据库

```bash
# 生成 Prisma Client
npm run prisma:generate

# 推送数据库模式
npm run prisma:push
```

### 4. 创建管理员账号

首次运行后，注册一个账号，然后在数据库中手动将该用户的 `role` 字段设置为 `ADMIN`。

```sql
UPDATE users SET role = 'ADMIN' WHERE email = 'your@email.com';
```

### 4. 快速自检（可选）

```bash
npm run check
```

### 5. 启动开发服务器（Node 环境）

```bash
npm run dev
```

访问 http://localhost:3000

## 🚀 部署到服务器

### 安全部署流程

**重要：** 使用安全部署工具，确保不影响正式服务器的正常使用。

> 可移植生产部署请优先参考：
> - [可移植部署与生产规范（权威版）](./docs/PORTABLE_DEPLOYMENT_GUIDE.md)

**快速部署：**

1. **本地测试**
   ```bash
   npm run dev
   # 测试所有功能正常
   ```

2. **部署前检查**
   ```bash
   # Windows
   .\部署前检查清单.bat
   ```

3. **执行部署**
   ```bash
   # Windows PowerShell
   .\scripts\deploy\安全部署.ps1
   
   # Linux/Mac
   bash scripts/deploy/安全部署.sh
   ```

**详细部署指南：**
- [安全部署流程](./docs/guides/安全部署流程.md)
- [安全部署说明](./docs/guides/安全部署说明.md)
- [安全部署指南](./docs/guides/安全部署指南.md)

**部署检查清单：**
- [部署前检查清单](./部署前检查清单.bat)

## 项目结构

```
gongxiangp2/
├── app/                    # Next.js App Router
│   ├── api/               # API 路由
│   │   ├── auth/         # 认证相关
│   │   ├── materials/    # 素材相关
│   │   └── admin/        # 管理员相关
│   ├── login/            # 登录页面
│   ├── register/         # 注册页面
│   ├── admin/            # 管理员页面
│   └── page.tsx          # 首页
├── components/            # React 组件
│   ├── Header.tsx
│   └── UploadModal.tsx
├── lib/                   # 工具库
│   ├── prisma.ts         # Prisma 客户端
│   ├── auth.ts           # NextAuth 配置
│   └── s3.ts             # S3 存储服务
├── prisma/               # Prisma 配置
│   └── schema.prisma     # 数据库模式
└── uploads/              # 本地上传文件存储
```

## 数据库模型

### User (用户)
- id: UUID
- email: 邮箱
- username: 用户名
- password: 密码 (加密)
- role: 角色 (USER/ADMIN)

### Material (素材)
- id: UUID
- previewUrl: 预览图URL (S3)
- productModel: 商品型号
- sceneName: 场景名称
- authorName: 作者花名
- zipFileName: 压缩包文件名
- zipFilePath: 压缩包本地路径
- userId: 用户ID (外键)

## 部署

### 开发环境（Docker）

```bash
docker compose -f docker-compose.dev.yml up --build
```

### 生产环境构建

```bash
docker compose build
docker compose up -d
```

### 环境变量

确保在生产环境中设置所有必要的环境变量，特别是：
- `NEXTAUTH_SECRET`: 使用强随机字符串
- `NEXTAUTH_URL`: 设置为生产域名
- `APP_PUBLIC_URL`：可选，按公司部署时的对外访问地址（如 `https://corp.example.com`）。若不设置，系统会自动从请求头推断；该变量优先用于生成邀请链接等需要完整站点URL的功能。

## License

MIT