# FLNXI素材库

一个遵循苹果设计语言的 3D 素材协作平台，专注企业/团队的私有化部署场景，内置 AI 辅助、部门权限、模板化元数据与可移植部署工具链。

## 🎯 项目概览

- **目标**：让团队能"一键部署 + 秒级迁移"，快速落地到自有 NAS、IDC 或混合网络环境
- **定位**：设计/电商团队素材仓库 + 管理驾驶舱 + AI 实验场
- **原则**：性能优先、稳定性优先、易部署

## 🌟 核心功能

### 素材管理
- **智能搜索**：多维度筛选（品牌/系列/SKU/渲染参数）
- **模板系统**：自定义字段、拖拽排序、动态表单
- **批量操作**：上传、下载、分享、标签管理
- **版本控制**：并发冲突检测、自动版本递增

### 权限管理
- **部门体系**：树状组织结构、部门管理员
- **角色权限**：超级管理员、管理员、普通用户
- **邀请系统**：邀请链接、多次使用、过期控制

### AI 功能
- **智能对话**：Gemini 多模态对话
- **图像生成**：自动生成风格稿
- **智能标签**：自动提取素材信息

### 系统特性
- **健康检查**：`/api/health` 端点
- **系统监控**：资源使用、性能指标
- **数据恢复**：S3 桶扫描、批量导入
- **网络自识别**：内外网自动切换

## 🧱 技术栈

- **前端**：Next.js 14 App Router、React 18、TypeScript、TailwindCSS
- **认证**：NextAuth.js + 邮箱密码 + 钉钉 OAuth
- **数据库**：Prisma 5.22 + PostgreSQL
- **存储**：MinIO / S3 兼容对象存储
- **AI**：Google Gemini API
- **测试**：Jest + React Testing Library（118个单元测试）

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

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

编辑 `.env` 文件，配置必要的环境变量：

```env
# 数据库
DATABASE_URL=postgresql://user:password@localhost:5432/flnxi_material

# 认证
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

# S3存储
S3_ENDPOINT=https://s3.example.com
S3_BUCKET=your-bucket
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
```

### 3. 初始化数据库

```bash
npm run prisma:generate
npm run prisma:push
```

### 4. 启动开发服务

```bash
npm run dev
# 访问 http://localhost:3000
```

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

首次注册的用户会自动成为超级管理员。

## 🔧 开发命令

```bash
# 开发
npm run dev              # 启动开发服务器
npm run build            # 构建生产版本
npm start                # 启动生产服务器

# 测试
npm test                 # 运行测试
npm run test:watch       # 监听模式
npm run test:coverage    # 生成覆盖率报告

# 代码质量
npm run lint             # ESLint检查
npm run type-check       # TypeScript类型检查
npm run check            # 完整检查（类型+lint+prisma）

# 数据库
npm run prisma:generate  # 生成Prisma客户端
npm run prisma:push      # 推送schema到数据库
npm run prisma:studio    # 打开Prisma Studio
npm run prisma:validate  # 验证schema

# 数据迁移
npm run migrate:template-data  # 迁移模板数据
npm run verify:template-data   # 验证数据完整性
```

## 📦 生产部署

### 使用Harbor部署（推荐）

```powershell
# 1. 本地构建并推送到Harbor
.\deploy-new-fixed.ps1 -Registry harbor

# 2. SSH到服务器执行数据迁移
ssh root@your-server
cd /root/deploy
docker exec flnxi-material npx prisma migrate deploy
docker exec flnxi-material npm run migrate:template-data
docker exec flnxi-material npm run verify:template-data

# 3. 验证部署
# 访问 http://your-server:4320
```

### Docker Compose部署

```bash
# 生产环境
docker-compose -f docker-compose.prod.yml up -d

# 开发环境
docker-compose -f docker-compose.dev.yml up -d
```

详细部署文档：
- [完整部署说明](docs/deployment/DEPLOYMENT.md)
- [快速部署指南](docs/deployment/quick-deployment-guide.md)
- [部署前检查清单](docs/deployment/pre-deployment-checklist.md)

## 🗂️ 项目结构

```
.
├── app/                          # Next.js App Router
│   ├── page.tsx                  # 首页
│   ├── admin/                    # 管理后台
│   └── api/                      # API路由
├── components/                   # React组件
├── lib/                          # 工具库
│   ├── template-validator.ts    # 模板验证器
│   ├── field-pool.ts            # 字段池管理
│   └── hooks/                   # 自定义Hooks
├── prisma/                       # 数据库
│   ├── schema.prisma            # 数据模型
│   └── migrations/              # 迁移文件
├── scripts/                      # 脚本工具
│   ├── migrate-template-data.ts # 数据迁移
│   └── verify-template-data.ts  # 数据验证
├── docs/                         # 文档
│   ├── api/                     # API文档
│   ├── deployment/              # 部署文档
│   └── user-guide/              # 用户手册
└── tests/                        # 测试文件
```

## 📚 文档

### 用户文档
- [用户手册](docs/user-guide/template-system-guide.md) - 如何使用模板系统
- [API文档](docs/api/template-system-api.md) - API接口说明

### 开发文档
- [项目总结](docs/template-system-optimization-summary.md) - 最新优化总结
- [数据迁移脚本](scripts/README.md) - 脚本使用说明

### 部署文档
- [完整部署说明](docs/deployment/DEPLOYMENT.md) - 详细部署步骤
- [快速部署指南](docs/deployment/quick-deployment-guide.md) - 快速上手
- [部署前检查清单](docs/deployment/pre-deployment-checklist.md) - 检查清单

## 🧪 测试

项目包含118个单元测试，覆盖核心功能：

- 模板验证器（25个测试）
- 字段池管理器（34个测试）
- 模板CRUD API（13个测试）
- 防抖Hooks（17个测试）
- UI组件（29个测试）

```bash
# 运行所有测试
npm test

# 查看覆盖率
npm run test:coverage
```

核心模块覆盖率：
- template-validator.ts: 92.62%
- useDebounce.ts: 100%
- upload-templates API: 85.88%

## 🔐 环境变量

### 必需变量

| 变量 | 说明 |
|------|------|
| `DATABASE_URL` | PostgreSQL连接字符串 |
| `NEXTAUTH_SECRET` | NextAuth加密密钥 |
| `NEXTAUTH_URL` | 应用URL |
| `S3_ENDPOINT` | S3端点 |
| `S3_BUCKET` | S3桶名称 |
| `S3_ACCESS_KEY_ID` | S3访问密钥 |
| `S3_SECRET_ACCESS_KEY` | S3密钥 |

### 可选变量

| 变量 | 说明 |
|------|------|
| `GEMINI_API_KEY` | Gemini AI密钥 |
| `DINGTALK_CLIENT_ID` | 钉钉客户端ID |
| `DINGTALK_CLIENT_SECRET` | 钉钉客户端密钥 |

完整配置说明请参考 `.env.example`

## 🆘 故障排除

### 常见问题

**Q: Docker构建失败？**  
A: 检查 `.env.production` 文件是否存在，或使用 `-EnvFile` 参数指定环境变量文件。

**Q: 数据库连接失败？**  
A: 确认 `DATABASE_URL` 配置正确，数据库服务正在运行。

**Q: S3上传失败？**  
A: 检查S3配置和网络连接，查看错误日志。

**Q: 测试失败？**  
A: 运行 `npm run prisma:generate` 重新生成Prisma客户端。

更多问题请查看：
- [部署故障排除](docs/deployment/DEPLOYMENT.md#常见问题)
- [脚本故障排除](scripts/README.md#故障排除)

## 📈 性能指标

| 操作 | 目标时间 | 实际时间 |
|------|---------|---------|
| 模板列表加载 | < 500ms | ~300ms |
| 素材上传验证 | < 100ms | ~50ms |
| 字段池同步 | < 1s | ~500ms |
| 首页Tag响应 | < 100ms | ~50ms |

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📝 License

MIT

## 📞 联系方式

- 项目地址：[GitHub](https://github.com/your-repo)
- 问题反馈：[Issues](https://github.com/your-repo/issues)

---

**最后更新**: 2025年12月13日  
**版本**: 1.0.0