63ec6b7dfb
1. 排行榜悬浮窗关闭后小按钮消失问题 - 修复面板居中模式关闭时按钮位置错误 - 保存并恢复按钮的居中状态 2. 首页tag按钮按素材数量排序 - 添加按素材数量降序排序逻辑 3. 上传弹窗输入框浅色模式文字不可见 - 添加 text-slate-900 确保浅色模式下文字可见 - 添加 placeholder 样式确保占位符正确显示
290 lines
7.8 KiB
Markdown
290 lines
7.8 KiB
Markdown
# 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
|