# FLNXI素材库

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

> ⚠️ 建议先阅读根目录 `config-bianliang.env`，将域名、白名单、S3、钉钉等变量集中管理。系统启动时只会补充“未设置”的变量，不会覆盖已有的系统环境或 `.env/.env.local`。

## 🎯 项目概览
- **目标**：让其他团队能“一键部署 + 秒级迁移”，快速落地到自有 NAS、IDC 或混合网络环境。
- **当前定位**：设计/电商团队素材仓库 + 管理驾驶舱 + AI 实验场。
- **关键原则**：
  - 性能开销优先：组件懒加载、API 分页、S3 断点重试，保证低配服务器也能跑。
  - 稳定性优先：健康检查 `/api/health`、系统仪表盘 `/api/admin/system-status`、部署脚本全程日志。
  - 易部署：配置集中化、Docker Compose 套件、PowerShell/Bash 安全部署脚本、环境备份。

更多编码规范与约束可参考 `./架构设计与编码规范.md`、`./docs/PORTABLE_DEPLOYMENT_GUIDE.md`。

## 🌟 功能亮点（2025/11 最新版）

### 面向素材使用者
- **门户体验**：首页卡片流展示、支持品牌/系列/SKU/渲染参数的多维搜索与筛选，附带点赞、下载、分享、榜单。
- **AI 智能体**：`components/AIChatWidget.tsx` 绑定 Gemini，多模态对话、最多 5 张参考图上传、自动生成 4 张风格稿。
- **实时互动**：`DanmakuWidget` 支持匿名弹幕；`RankingPanel` 展示贡献/下载/点赞排行榜，可拖拽定位。
- **分享场景**：`/share/[id]` 公开链接可曝光素材详情（脱敏流量）；`/complete-profile` 协助钉钉首次登录用户补全部门信息。
- **网络自识别**：`/api/network-status` 根据 IP & 域名判断当前处于内/公网，自动提示内网地址。

### 面向管理员
- **驾驶舱首页**：`/admin` 默认进入“监控仪表板”，展示 30 天新增、部门/角色分布、活跃度、最近上传等。
- **权限与部门**：支持“部门管理员”操控子部门、折叠/搜索组织树、邀请链接 (`/api/invitations`) 与首位用户自动超级管理员 (`verify_first_user.js`)。
- **模板/字段体系**：`TemplateManager` 内置多套电商模板，字段支持拖拽排序、可见性、下拉选项（单行文本规则），并与上传页/筛选器联动。拖拽交互流畅，松开鼠标后立即更新布局。
- **分类配置**：分类/场景/平台均支持自定义下拉列表，后台统一管理（`/api/categories|scenes|platforms`）。
- **素材深度信息**：`Material` 模型新增品牌、系列、SKU、材质、渲染耗时、输出分辨率、色彩模式等字段，全流程读写。
- **系统设置**：LOGO、S3、注册/激活、AI 改图、内网穿透等开关存储于 `SystemSettings`，与 `config-bianliang.env` 协同。
- **数据恢复**：`/api/restore-data` 可结合 S3 桶与本地 `uploads/` 批量匹配预览/压缩包并导入数据库（含管理员账号回填）。
- **Ops 工具**：内置 `/api/tunnel/*` 占位接口用于 FRP/ZeroTier 控制，配合 `featureFlags.tunnelEnabled` 与 SystemSettings。

### 运维、部署与生态
- `config-bianliang.env`：将域名、白名单、S3、钉钉、内外网地址、RESTORE 桶等集中管理，实现“拷贝项目即可部署”。
- `scripts/deploy/`：包含 `安全部署.ps1/.sh`、`deploy-new-fixed.ps1`（阶段化进度）、`deploy-new.ps1`、`local-build-and-upload.ps1` 等脚本。
- Docker 套件：`docker-compose.dev.yml`（带热更新）、`docker-compose.prod.yml`、`docker-compose.standard.yml`、`docker-compose-registry.yml` 等。
- 诊断资源：`docs/guides/`、`docs/reports/`、`env-backups/`、`deploy-artifacts/`、`deploy-log.txt`、`temp_stdout/stderr`，便于回溯问题。

## 🧱 技术栈
- **应用层**：Next.js 14 App Router、React 18、TypeScript、TailwindCSS。
- **认证**：NextAuth.js + 邮箱密码 + 钉钉 OAuth。
- **数据访问**：Prisma 5.22 + PostgreSQL（dev 默认 `prisma/dev.db` SQLite，生产建议 Postgres 15+）。
- **存储**：MinIO / S3 兼容对象存储（预览图）+ 本地/NAS `uploads/`（压缩包）。
- **AI 服务**：Google Gemini API（`GEMINI_API_KEY`），`/api/ai-chat`、`/api/ai/edit`。
- **其他**：Next Middleware CORS、防火墙探测、bcrypt、AWS SDK v3、Formidable 上传、clsx/date-fns/zod。

## 🗂️ 项目结构速览

```
.
├── app/
│   ├── page.tsx                     # 门户首页
│   ├── login|register|complete-profile
│   ├── share/[id]/                  # 公开分享页
│   ├── dingtalk-callback/           # 钉钉扫码落地页
│   ├── admin/
│   │   ├── page.tsx                 # 后台入口 + 标签页
│   │   ├── monitor/                 # 仪表盘视图
│   │   ├── settings/                # 系统设置
│   │   └── _components/TemplateManager.tsx 等
│   └── api/
│       ├── materials|categories|scenes|platforms|rankings
│       ├── admin/…                  # 权限、系统状态、用户
│       ├── dingtalk/…               # 钉钉登录 & 资料完善
│       ├── ai-chat/ | ai/edit/      # Gemini 对话/改图
│       ├── invitations|departments|tunnel|restore-data
│       ├── danmaku|network-status|health
│       └── …（详见 `app/api`）
├── components/                      # UploadModal、EditMaterialModal、AIChatWidget、DanmakuWidget、RankingPanel…
├── lib/                             # `auth.ts`、`prisma.ts`、`s3.ts`、`config.ts`、`network.ts`
├── prisma/                          # schema、migrations、dev.db
├── scripts/                         # deploy、tools、server、update-file-sizes…
├── docs/                            # guides、reports、chats、WORKFLOW
├── config-bianliang.env             # 可迁移化配置示例
├── docker-compose*.yml / Dockerfile
├── deploy-*.ps1                     # 部署脚本
├── env-backups/ / deploy-artifacts/ # 产物与环境备份
└── uploads/                         # 本地压缩包目录
```

## ⚙️ 环境变量与配置

### 基础必填
| 变量 | 用途 |
| --- | --- |
| `DATABASE_URL` | 指向 PostgreSQL 或 SQLite（开发）连接串 |
| `NEXTAUTH_SECRET` | NextAuth 加密密钥 |
| `NEXTAUTH_URL` / `APP_PUBLIC_URL` | 生成绝对链接、OAuth 回调、邀请链接 |
| `S3_ENDPOINT` / `S3_BUCKET` / `S3_PUBLIC_DOMAIN` / `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` / `S3_REGION` | MinIO/S3 上传、预览图读取 |
| `S3_ENV_PREFIX` / `S3_FILE_PATH` | 同桶多环境隔离，前缀自动拼接 |
| `ALLOWED_ORIGINS` | CORS 白名单（逗号分隔） |
| `IMAGE_REMOTE_HOSTS` | Next/Image 远程域名（逗号分隔） |
| `PUBLIC_DOMAINS` / `NEXT_PUBLIC_PUBLIC_DOMAINS` | 公网域名识别（含前端版本） |
| `NEXT_PUBLIC_PORTAL_BASE_URL` / `NEXT_PUBLIC_INTRANET_URL` | 分享 & 网络状态提示 |
| `NEXT_PUBLIC_DEFAULT_HEADER_LOGO_URL` / `NEXT_PUBLIC_DEFAULT_LOGIN_LOGO_URL` | 默认 LOGO |

### 可选增强
| 变量 | 说明 |
| --- | --- |
| `GEMINI_API_KEY` / `GEMINI_API_BASE_URL` / `GEMINI_MODEL` | AI 聊天/生成配置 |
| `DINGTALK_CLIENT_ID` / `DINGTALK_CLIENT_SECRET` | 钉钉扫码登录 |
| `NEXT_PUBLIC_DINGTALK_CALLBACK_URL` | 前端跳转地址 |
| `RESTORE_S3_BUCKET_URL` / `RESTORE_S3_PUBLIC_URL` | `/api/restore-data` 用于扫描历史素材 |
| `AI_EDIT_ENABLED` / `TUNNEL_ENABLED` | Feature Flag（也可在 SystemSettings 开启） |
| `APP_PUBLIC_URL` | 优先用于邀请链接、分享、邮件通知 |

### config-bianliang.env
- 位置：项目根目录。
- 适用：NAS、客户现场多域名切换、Batch 部署。
- 生效顺序：`系统环境 > .env(.local) > config-bianliang.env`。
- 修改后需重启 Node 或容器。

## 🚀 快速开始
1. **安装依赖**
   ```bash
   npm install
   ```
2. **复制环境模板并补齐配置**
   ```bash
   cp .env.example .env   # 若在 Windows，可手动复制
   ```
   > 建议同步编辑 `config-bianliang.env`，以便后续迁移。
3. **数据库初始化**
   ```bash
   npm run prisma:generate
   npm run prisma:push          # 或 `npx prisma migrate deploy`
   ```
4. **创建第一个账号**
   - 前台注册后，将该用户 `role` 更新为 `ADMIN`、`isSuperAdmin = true`。
   - 或运行 `node verify_first_user.js` 检查首位用户权限是否正确。
5. **可选自检**
   ```bash
   npm run check      # type-check + lint + prisma validate
   npm run prisma:studio
   ```
6. **启动开发服务**
   ```bash
   npm run dev
   # http://localhost:3000
   ```
7. **Docker 开发模式**
   ```bash
   docker compose -f docker-compose.dev.yml up --build
   ```

## 🔧 常用脚本 & 工具
- `npm run build`：自动执行 `prisma generate` 后构建 Next。
- `npm run lint` / `npm run type-check`。
- `npm run prisma:studio`、`npm run prisma:push`。
- `node fix_user_permissions.js` / `update-file-sizes*.js` 等工具脚本。
- `scripts/deploy/安全部署.ps1|.sh`：标准部署入口。
- `deploy-new-fixed.ps1`：阶段化本地打包 -> 镜像 -> 推送 -> 远程 compose，自动轮询 `/api/health`。
- `scripts/tools/quick-start.sh`：常用容器编排。

## 🗄️ 数据模型速览
- **User**：`role`, `managedDepartment`, `isSuperAdmin`, `loginType`, `dingtalkUserId`, `canDownload`, `isActive`。
- **Material**：`brandName`, `seriesName`, `skuCode`, `materialTexture`, `platformName`, `renderTime`, `imageResolution`, `colorMode`, `displayImages`, `templateId`。
- **UploadTemplate / UploadField**：模板字段、布局、校验、下拉配置。
- **Category / Scene / Platform**：支持 `options`（文本每行一个值）。
- **Department**：树状管理（`parentId` 在 User 中维护）。
- **Invitation**：多次/过期控制，生成邀请码链接。
- **Danmaku / MaterialLike / FilterItem / SystemSettings**：互动、个性化和系统开关。

完整定义见 `prisma/schema.prisma`。

## 📦 部署与运维
- **一键部署**：`./一键部署快速指南.md`、`./一键部署完整指南.md`、`./docs/guides/安全部署指南.md`。
- **Docker**：`docker-compose.yml`（默认生产）、`docker-compose.prod.yml`（显式生产）、`docker-compose.standard.yml`（多服务）、`docker-compose-registry.yml`（私有镜像仓库）。
- **PowerShell**：`deploy-fixed.ps1`、`deploy-new-fixed.ps1`（推荐）、`deploy-new.ps1`（实验版）。
- **健康检查**：脚本完成后会轮询 `GET /api/health`，也可由外部监控使用 `HEAD /api/health`。
- **日志与产物**：`deploy-log.txt`、`deploy-artifacts/*.tar`、`env-backups/*.env`。
- **网络与安全**：`secure_ssh.ps1`、`scripts/server/*.sh`、`docs/guides/SSH安全评估报告.md`。

## 🆘 自检 & 排障
- 前端浮动面板内含“网络检测”“AI 聊天”“弹幕”；后台仪表盘提供系统状态。
- `logs/` 与 `temp_stdout|stderr.txt` 保存最近脚本输出。
- `docs/guides/上传问题完整解决方案.md`、`docs/guides/FRP服务器诊断修复报告.md` 提供针对性排障。
- `/api/admin/system-status` 若返回 403，检查是否使用管理员或超级管理员登录。
- S3 上传失败将尝试 10 次自动重试（`lib/s3.ts`），最终报错请检查存储桶权限与 `S3_PUBLIC_DOMAIN`。

## 📚 文档入口
- 开发流程：`docs/WORKFLOW.md`
- 部署规范：`docs/PORTABLE_DEPLOYMENT_GUIDE.md`、`docs/guides/安全部署说明.md`
- 需求实现记录：`docs/FEATURE_REQUESTS_IMPLEMENTATION.md`
- 变更日志：`CHANGELOG.md`（示例：2025-11「权限进化 & 电商加成」版本）
- 历史问题：`docs/reports/*`、`.specstory/history/*`

## 📝 License

MIT