WuYongJie/flnxi-Wu
WuYongJie/flnxi-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
flnxi-Wu/docs/archive/项目说明-由壹点3D素材.md
WuYongJie 63ec6b7dfb fix: 修复排行榜按钮消失、tag排序和输入框浅色模式问题 
1. 排行榜悬浮窗关闭后小按钮消失问题
   - 修复面板居中模式关闭时按钮位置错误
   - 保存并恢复按钮的居中状态

2. 首页tag按钮按素材数量排序
   - 添加按素材数量降序排序逻辑

3. 上传弹窗输入框浅色模式文字不可见
   - 添加 text-slate-900 确保浅色模式下文字可见
   - 添加 placeholder 样式确保占位符正确显示
2025-12-14 21:41:29 +08:00

7.1 KiB
Raw Blame History

FLNXI素材库项目说明

本说明整理了当前项目的关键架构、模块划分、术语约定及日常操作规范，便于在需求沟通或交接时快速对齐背景。可直接复制内容给其他 AI 翻译或润色。

一、整体概览

  • 框架：Next.js 14（App Router）+ Prisma + PostgreSQL + S3/MinIO 对象存储
  • 核心能力：素材上传、模板管理、分类管理、筛选、权限控制、下载/流媒体播放
  • 部署：推荐脚本 scripts/deploy/deploy-new-fixed.ps1（本地构建 → 镜像推送 Registry → 远程 docker compose 滚动更新）
  • 存储策略：所有素材文件只走 S3/MinIO（lib/s3.ts），本地磁盘仅保留兼容读取

二、架构拆解

  1. 前端层（Next.js App Router）
    • UI 组件集中在 app/admin/_components、components 目录，采用 Client + Server 组件混合模式
    • 状态管理以 React hooks 为主，配合 useThemeStyles、DialogProvider 等自定义 hooks
  2. 服务层（API Routes）
    • 位于 app/api/*，每个目录一个 Route Handler，依赖 @/lib/prisma、@/lib/s3、@/lib/field-pool
    • 所有需要权限的接口都通过 getServerSession(authOptions) 校验
  3. 数据层（Prisma + PostgreSQL）
    • Prisma schema 管理所有表结构；通过 prisma/migrations/* 记录历史
    • 字段池相关表：FieldDefinition、FieldOption
  4. 存储层（S3/MinIO）
    • lib/s3.ts 封装上传、删除、预签名下载
    • Docker Compose 中默认启动 MinIO + 初始化服务，确保环境一致
  5. 部署 & 运维
    • PowerShell 脚本封装构建、推送、远程部署、健康检查
    • Registry + 服务器 Compose 目录 /root/deploy 统一管理容器

二、角色与权限

  • 用户划分为普通用户、管理员、超级管理员
  • 管理端入口 /admin，包含：仪表盘、素材库、模板管理、分类管理、系统设置等模块
  • 所有管理 API 通过 next-auth session 鉴权，管理员及以上才可操作分类管理

三、字段池与分类管理

核心概念

  • 字段池：FieldDefinition 与 FieldOption 两张表，集中维护各模板字段及其选项
  • 字段同步：模板字段勾选“添加到分类”后写入字段池；字段定义保持不删，只清理字段对应的数据记录
  • 启用/禁用：isFilterEnabled 控制字段是否出现在分类列表及首页筛选

关键逻辑

  • syncFieldPoolFromTemplates()（lib/field-pool.ts）在 GET /api/template-categories 前执行，确保字段池与模板同步
  • 选项清洗：stripRedundantBrackets、normalizeFieldOptionValue、expandOptionValue 消除 [[[xxx]]]、[a,b] 类脏数据；formatFieldOptionValues 去重
  • 前端 CategoriesTab.tsx 用 sanitizeOptionLabel 再次兜底，保证展示干净

四、分类管理前端交互（app/admin/_components/CategoriesTab.tsx）

左侧“分类列表”卡片

  • 编辑模式启用 @dnd-kit/core + SortableContext，允许拖拽调整顺序；顺序写入 filterOrder，同步首页筛选
  • 卡片包含：拖拽手柄（方形 8x8）、标题、字段信息、重命名按钮（方形图标按钮，调用全局 Prompt）、禁用按钮
  • 重命名只修改显示名（filterDisplayName），字段 key 不变

右侧“选项卡片”区域

  • 展示字段选项，并支持新增/重命名/删除
  • 选项重命名同样使用全局 Prompt 弹窗
  • “添加新选项”卡片输入后写回字段池数据

顶部操作

  • “编辑/保存/取消/刷新”按钮：
    • 保存 → PUT /api/category-fields 批量写入 filterOrder、filterDisplayName
    • 取消 → 退出编辑并重新拉取数据
    • 刷新 → 在非编辑状态下重新获取分类与字段

五、API 速览

路径 方法 说明
/api/template-categories GET 拉取已启用分类字段，返回 fieldKey / 显示名 / 默认名 / 顺序 / 选项
/api/category-fields PUT 批量更新分类字段顺序与显示名（管理员权限）
/api/materials/upload POST 上传素材；文件直接写入 S3，记录 URL
/api/materials/download GET 下载素材；S3 文件走 createPresignedDownloadUrl 302 跳转
/api/materials/stream GET 视频流式播放，同样用预签名 URL
/api/admin/cleanup-database POST 清理数据库记录（不再删除本地文件）

六、上传/下载链路要点

  • 上传接口接收表单（素材文件/缩略图/字段 JSON），生成唯一文件名后上传 S3
  • 下载与流媒体接口检测 zipFilePath 是否为 S3 URL：
    • 是 → 创建预签名链接并 302
    • 否 → 走兼容逻辑读取本地旧文件
  • cleanup-database 操作只处理数据库，已移除本地文件删除代码

七、部署与运维

  • 首选脚本：deploy-new-fixed.ps1（Windows PowerShell），使用私有 Registry
  • Compose：docker-compose.standard.yml 包含 postgres、minio、minio-init、app；MinIO 初始化自动建桶并开放下载
  • 健康检查：部署脚本最终轮询 /api/health，确保上线成功
  • 辅助脚本：scripts/deploy 目录下 check-*、fix-*、setup-*、manual-import-image.ps1 等，用于诊断、离线包、镜像导入

八、统一术语

  • “分类列表”：左侧字段列表（可排序、重命名、禁用/启用）
  • “小卡片”：右侧具体选项卡片
  • “字段池”：FieldDefinition/FieldOption 数据体系
  • “模板”：上传模板（定义字段的来源）
  • “启用/禁用”：是否参与分类列表与首页筛选
  • “Prompt 弹窗”：DialogProvider 提供的统一输入弹窗

九、统一 UI 与风格规范

  • 主题系统：依赖 useThemeStyles、useTheme 输出 styles 对象，集中管理按钮、输入框、卡片、文本颜色等
  • 布局
    • 管理端页面通用：左侧固定 Sidebar（240px+），右侧内容区滚动
    • 分类管理左侧列表为滚动容器，右侧内容随页面滚动
  • 按钮 & 动画
    • 使用 cardAnimations、buttonAnimations 定义 hover/active/入场效果
    • 可交互部件默认有最小点击区域（>=32px），方形图标按钮保持 8x8（tailwind 单位）
  • 弹窗
    • 全部走 DialogProvider（confirm/alert/prompt），禁止单独实现模态框
    • 提示文案统一使用简体中文，按钮文案保持“确定/取消/保存/禁用”等常用词
  • 拖拽
    • 基于 @dnd-kit，拖动元素配“九宫格”图标作为手柄，拖拽过程加 ring-indigo 高亮
  • 表单输入
    • 优先使用 styles.inputStyles.base，禁用手动 inline 样式，保持焦点态一致
    • Placeholder 以描述性文案为主，例如“请输入显示名称”
  • 空状态
    • 使用 text-xs text-slate-500 描述，无数据时文案统一采用“暂无 XXX”格式
  • 命名
    • 组件/变量遵循英文语义命名；对用户展示的字段使用中文

如需追加更细的 API 参数、数据库字段说明或交互流程，请在此文档基础上补充。***