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. 安装依赖

   npm install
   

2. 复制环境模板并补齐配置

   cp .env.example .env   # 若在 Windows，可手动复制
   

   建议同步编辑 config-bianliang.env，以便后续迁移。

3. 数据库初始化

   npm run prisma:generate
   npm run prisma:push          # 或 `npx prisma migrate deploy`
   

4. 创建第一个账号
   • 前台注册后，将该用户 role 更新为 ADMIN、isSuperAdmin = true。
   • 或运行 node verify_first_user.js 检查首位用户权限是否正确。
5. 可选自检

   npm run check      # type-check + lint + prisma validate
   npm run prisma:studio
   

6. 启动开发服务

   npm run dev
   # http://localhost:3000
   

7. Docker 开发模式

   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