Swee-管理后台

Swee Admin 是 Swee AI 社交娱乐平台的运营管理后台，基于 UmiJS 4 + Ant Design Pro 构建。涵盖 AI 内容管理（AIGC、角色模板、剧情生成）、KOL 运营、薪资结算、多语言文案管理、内容审核、素材库等 13 个核心模块，是支撑平台日常运营的中枢系统。

一、项目技术架构

1.1 整体架构图

1.2 核心技术栈

领域	技术选型	版本
框架	UmiJS Max (@umijs/max)	4.x
UI 库	Ant Design Pro + Ant Design	5.x
语言	TypeScript	5.7.2
状态管理	UmiJS Model + ahooks useRequest	- / 3.7.8
高性能表格	@visactor/react-vtable	1.16.2
财务计算	bignumber.js	9.1.1
Excel 处理	xlsx	0.18.5
JSON 编辑	jsoneditor	9.7.4
文件存储	ali-oss	6.21.0
加密	crypto-js	4.1.1
压缩	jszip	3.10.1
样式	Tailwind CSS + Ant Design 主题	3.4.x

二、菜单模块架构

2.1 13 大功能模块

2.2 路由权限控制

三、AI 内容管理体系

3.1 AIGC 内容管理

3.2 AI 剧情生成系统

架构说明

这是管理后台最具技术亮点的 AI 功能模块，采用异步生成 + 轮询的架构模式，由运营人员配置参数后 AI 自动生成多组剧情方案。

关键技术实现：

异步生成 + 轮询：useRequest 配合 pollingInterval: 5000 实现 5 秒轮询
状态机管理：生成中(1) → 成功(2) / 失败(3) 三态切换
标签系统：支持主题标签和地区标签，通过 allTags() 动态加载
模型选择：通过 listModel() 获取可用 AI 模型列表

3.3 智能封面生成

3.4 角色模板与互动挑战

模块	功能	组件
角色模板	角色人设配置管理	`RoleTemplateModalForm`
互动挑战	挑战模板创建/编辑	`ChallengeTemplateModalForm`
AI 人设标签	标签分类管理	ProTable + Tag 组件
全局模型设置	AI 模型参数配置	表单 + JSON 编辑器

四、薪资结算系统

浮点精度陷阱

薪资结算涉及真实资金流转，JavaScript 的浮点精度问题（如 0.1 + 0.2 !== 0.3）在财务场景中不可接受。项目使用 BigNumber.js 进行所有金额运算，确保结算数据的精确性。

4.1 财务精确计算

三大薪资状态管理：

状态类型	状态值	说明
创作奖励	FROZEN / UNREACHED / REACHED / PAID	冻结→未完成→已创建未发放→已发放
分成状态	0 / 1 / 2	未填写→有效→无效
分成奖励	0 / 1 / 2	未完成→已完成未发放→已发放

Excel 导出实现：

pages/Operation/SalaryData.tsx
// Blob 响应 + 客户端下载
const data = await liveEarningExport(params, { responseType: 'blob' });
const url = window.URL.createObjectURL(data.data);
const a = document.createElement('a');
a.href = url;
a.download = `薪酬数据(${startDate}-${endDate}).xlsx`;
a.click();

五、数据管理 — 埋点事件追踪系统

数据管理模块是一套完整的埋点事件定义与上报数据查询系统，支持事件集合管理、事件定义（含自定义属性和枚举值）、事件发布、上报数据查看和埋点代码自动生成。

5.1 事件建模与发布状态机

核心难点 — 三层嵌套编辑

事件自定义属性系统（EventModalForm）：

事件支持定义自定义属性，每个属性有三种类型：String（字符串）、Int（数值）、Enum（枚举）。其中枚举类型使用嵌套的 EditableProTable 管理 key-value 对，实现了「表单中嵌套可编辑表格，表格中又嵌套可编辑子表格」的三层嵌套编辑：

ModalForm（事件表单）
  → EditableProTable（自定义属性列表）
    → 当 type=Enum 时 → renderFormItem 渲染嵌套 EditableProTable（枚举值表）

枚举值序列化存储：枚举值以 "key1-描述1;key2-描述2" 字符串格式存储，前端负责序列化/反序列化。

自动前缀机制：事件名自动加集合名前缀（如 tracking_click），保证跨集合唯一性。

严格的验证规则：

事件名/属性名：仅小写英文和下划线（/^[a-z_]+$/）
属性名不能与 13 个基础属性（uid, d_id, plat, event_time 等）重复
枚举值 key：仅小写字母数字和下划线

5.2 动态列生成 — 上报数据查看

事件详情页（Event/Detail）根据事件定义动态生成表格列：

固定列（13个基础属性：uid, d_id, plat, event_time...）
  + 动态列（自定义属性，从事件定义中读取 customProps 动态生成）

表格设置 scroll={{ x: 2200 }}，左侧固定 uid 列，右侧固定自定义属性列和上报时间，中间列可水平滚动。所有列支持 copyable: true 一键复制。

5.3 埋点代码自动生成

集成 @swee/codegen 包，选择多个事件后可批量生成埋点代码（CodegenModalForm），减少开发者手动编写埋点代码的工作量。

六、配置管理 — JSON 可视化编辑与版本回退

配置管理模块提供系统级通用配置的管理能力，核心亮点在于智能类型推断的可视化编辑器和配置版本回退机制。

6.1 JSONEditor 多模式编辑

集成 jsoneditor 库，支持 6 种编辑模式：tree（树形）、view（只读）、form（表单）、code（代码）、text（文本）、preview（预览）。运营人员可根据数据复杂度自由切换。

支持从 XLSX 导入转 JSON：FileReader.readAsArrayBuffer() → XLSX.read() → sheet_to_json() → 导入编辑器。

6.2 智能类型推断的可视化编辑器（核心亮点）

配置的可视化编辑页面（Setting/General/Edit.tsx）实现了一套根据数据内容自动推断列类型的动态表格：

解析 JSON 配置第一行数据 → 遍历所有字段
  → isImageUrl(value)  → 渲染 Image 预览 + Upload 上传组件
  → isVideoUrl(value)  → 渲染 video 预览 + Upload 上传组件
  → isAudioUrl(value)  → 渲染 audio 预览 + Upload 上传组件
  → isUrl(value)       → 渲染链接字段
  → 其他               → 渲染 Textarea 输入框

核心亮点 — 零配置智能表格

实际效果：运营人员上传一个包含图片 URL、视频 URL、文本字段的 JSON 配置后，系统自动生成一个可编辑的多媒体表格——图片列可预览/上传替换，视频列可播放/上传替换，文本列可直接编辑。无需手动配置列类型。

6.3 配置版本管理

版本回退：rollbackGeneral() 支持将配置回退到任意历史版本
权限管控：authorizedUserList 控制哪些管理员可以编辑特定配置
缓存延迟提示：配置修改后有 60 秒缓存延迟，UI 主动提醒运营人员

七、多语言文案管理 — VTable V1→V2 演进

这是管理后台最具工程复杂度的模块，经历了从 EditableProTable（V1）到 VTable（V2） 的技术演进，支持数万行 8 语言文案的高效编辑。

7.1 V1 → V2 技术演进

维度	V1（EditableProTable）	V2（VTable）
数据量上限	~1000 行后明显卡顿	10000+ 行流畅
编辑方式	行编辑模式（整行进入编辑态）	单元格编辑器（点击即编辑）
搜索	ProTable 内置筛选	`SearchComponent` + Ctrl+F 快捷键
状态标记	难以实现	单元格背景色（绿=新增、黄=编辑、红=错误）
验证	ProForm 字段级	自定义 `TextAreaEditorWithValidator`
操作列	Ant Design 按钮	VTable Group + React 组件嵌入

性能提升数十倍

选择 VTable 的原因：文案集合动辄上万条，8 种语言并排显示意味着每行 10+ 列，V1 的 DOM 渲染无法承受。VTable 基于 Canvas 渲染 + 虚拟滚动，只渲染可视区域，性能提升数十倍。

7.2 VTable 编辑器架构

8 种语言支持：zh-CN（必填）、zh-TW、en-US、ja-JP、pt-BR、id-ID、bn-BD、fa-IR，覆盖中国、日本、巴西、东南亚、南亚、中东市场。

7.3 自定义编辑器 — TextAreaEditorWithValidator

实现 VTable 的 IEditor 接口，核心特性：

动态创建 textarea：点击单元格时创建 <textarea> DOM 元素，支持多行输入
实时验证：编辑完成后调用 validateValue() 校验，失败时单元格标红 + 添加 error CSS 类
快捷键支持：Ctrl+A 全选、Shift+Enter 换行
状态流转：编辑成功 → 标记 edited: true（黄色背景）；验证失败 → 标记 error: true（红色背景）

7.4 搜索组件 — SearchComponent

集成 @visactor/vtable-search，配置：

autoJump: true：搜索后自动跳转到匹配单元格
skipHeader: true：跳过表头行
queryMethod：支持大小写敏感/不敏感切换
快捷键：Ctrl+F 打开搜索、Enter 下一条、Shift+Enter 上一条

7.5 操作列 — React 组件嵌入 VTable

在 Canvas 渲染的 VTable 中嵌入 React 组件（Operation.tsx），通过 VTable 的 Group + react 属性注入：

pages/Copywriting/components/Operation.tsx
customRender: (row, col) => (
  <Group attribute={{
    react: {
      container: table.bodyDomContainer,
      element: <div>
        <TranslationOutlined onClick={handleTranslate} />
        <Popconfirm onConfirm={handleDelete}><DeleteOutlined /></Popconfirm>
        {overLengthLanguage.length > 0 && <ExceptionOutlined />}  // 超长警告
      </div>
    }
  }} />
)

字符超长检测：对比每种语言的翻译文本长度与默认语言（中文），超长时显示橙色警告图标。

7.6 批量保存优化

保存时分离新增和编辑数据，调用不同 API 并行执行：

hasUnsavedChanges = dataSource.some(r => r.edited || r.newLine)
  → 过滤 edited 行 → updateCopywriting()  ─┐
  → 过滤 newLine 行 → addCopywritingList() ─┤ Promise.all() 并行

保存前校验：如果存在 error 标记的行，阻止保存并提示"请先完善必填项"。

7.7 操作审计日志

所有文案操作记录完整的审计链（Copywriting/Log.tsx）：

操作类型：新增(1, 绿色) / 修改(2, 蓝色) / 删除(3, 红色)
前后对比：使用 ReactJson 组件展示操作前后的 JSON 内容，将 languageId 映射为语言名称便于阅读
审计信息：操作人、操作 IP、操作时间

八、素材管理 — 树形文件管理系统

素材管理模块（Material/Library.tsx，25KB 单文件实现）是一个完整的树形目录文件管理系统，支持多级文件夹嵌套、多类型文件上传/预览/编辑/替换。

8.1 树形导航 — 文件夹栈

使用 folders: MaterialLibraryDto[] 数组作为导航栈实现面包屑式的树形浏览：

点击文件夹 → folders.push(item) + setParentId(item.id) + reload()
点击返回   → folders.pop() + setParentId(parent?.id) + reload()
面包屑     → 渲染 folders 数组中每个节点的名称，可点击跳转任意层级

API 查询时传入 parentId 参数，只返回当前目录下的文件和文件夹。

8.2 文件类型智能识别

根据文件扩展名自动识别类型并渲染对应图标和预览：

类型	扩展名	图标	预览方式
图片	gif, jpg, jpeg, png, ico, bmp, webp, svg	`FileImageOutlined`（粉色）	`<Image>` 缩略图
Excel	xlsx, xls	`FileExcelOutlined`（绿色）	点击打开
APK	apk	`AndroidOutlined`（绿色）	点击下载
文件夹	-	`FolderOpenOutlined`（黄色）	点击进入
其他	-	`FileOutlined`（默认）	点击打开

8.3 多种文件操作

拖拽上传：Upload.Dragger 组件，支持批量（最多 10 个）、进度条显示（onUploadProgress 回调）、1 小时超时。

文本文件在线编辑（亮点）：检测到 .txt 文件时，支持远程获取文件内容 → 在线编辑 → 重新上传替换的完整流程：

fetch(url) 获取远程文件内容（text/plain）
在 ModalForm 的 TextArea 中编辑
保存时 new Blob([content]) → new File([blob]) 构造文件对象
调用 materialLibraryControllerUpdateFile() 上传替换

文件替换：非文本文件支持通过 Upload 组件直接选择新文件替换，保持原 ID 和元信息不变。

文件大小格式化：getReadableSize() 自动转换为 B / KB / MB / GB 易读格式。

九、数据导入导出

9.1 XLSX 白名单导入

9.2 OSS 文件上传

安全与去重策略

STS 临时授权：安全的临时凭证，避免暴露 AccessKey
MD5 内容寻址：MD5(file.name + file.size + file.lastModified) 确保文件唯一性
宽高比验证：isImageAspectRatio({ ratio, file }) 校验图片比例

十、表格组件体系

10.1 四种表格方案

根据不同业务场景选择不同的表格方案，形成表格矩阵：

表格方案	适用场景	数据量	使用模块
ProTable	标准数据展示（搜索+分页+工具栏）	< 10K	薪酬数据、用户管理、集合列表
DragSortTable	拖拽排序	< 1K	AIGC 内容排序、角色模板排序
EditableProTable	行内编辑	< 1K	文案编辑 V1、事件自定义属性
VTable	大数据量单元格编辑	10K+	文案编辑 V2（数万行 8 语言）

十一、API 服务层架构

11.1 双后端 API 架构

11.2 API 代码生成

API 代码自动生成
pnpm openapi  # 从 Swagger 自动生成 TypeScript 类型和 API 函数

十二、技术亮点总结

12.1 AI 驱动的运营工具

AI 剧情自动生成：运营人员配置参数后，AI 自动生成多组剧情方案，useRequest + pollingInterval: 5000 实现 5 秒轮询
智能封面生成：基于 AI 的封面图自动生成，支持取消操作
AI 人设标签系统：支撑 AI 伴侣的个性化配置

12.2 VTable 大规模多语言编辑

Canvas 虚拟表格：VTable 基于 Canvas 渲染 + 虚拟滚动，数万行 × 10+ 列流畅编辑
V1→V2 演进：从 EditableProTable（DOM 渲染，~1K 行瓶颈）升级到 VTable（Canvas 渲染，10K+ 行无压力）
自定义编辑器：TextAreaEditorWithValidator 实现单元格级验证 + 三色状态标记（新增/编辑/错误）
React in Canvas：通过 VTable Group + react 属性在 Canvas 表格中嵌入 React 操作按钮
微软翻译器集成：一键批量翻译，字符超长检测与警告

12.3 配置可视化编辑

智能类型推断：根据 JSON 数据值自动识别图片/视频/音频 URL，动态生成对应的预览+上传组件
JSONEditor 6 模式：tree / view / form / code / text / preview 自由切换
版本回退：支持配置回退到任意历史版本

12.4 埋点事件管理

三层嵌套编辑：ModalForm → EditableProTable（自定义属性）→ EditableProTable（枚举值）
动态列生成：上报数据表格根据事件定义的 customProps 动态生成列
埋点代码生成：@swee/codegen 集成，批量选择事件后自动生成代码

12.5 树形素材库

文件夹栈导航：folders[] 数组实现面包屑式多级目录浏览
文件类型智能识别：正则匹配扩展名，自动渲染对应图标和预览
文本在线编辑：.txt 文件支持远程获取 → 在线编辑 → Blob 构造 → 上传替换

12.6 财务级精确计算

BigNumber.js：避免 JavaScript 浮点精度问题
多维度薪资状态：创作奖励、分成状态、分成奖励三维度管理
Excel 导出：Blob 响应 + 客户端下载

12.7 完善的权限体系

三级权限控制：路由级（access）→ 组件级（useAccess）→ API 级（@Auth）
菜单级权限：动态菜单根据用户角色渲染
超级管理员：uid=1 可见所有配置

12.8 OSS 直传

前端直传阿里云 OSS，绕过服务端，减少服务器压力
STS 临时授权保证安全性
MD5 内容寻址避免重复上传

12.9 操作审计日志

所有文案操作记录前后内容 JSON 对比（ReactJson 渲染）
支持操作人、IP、时间的完整审计链
类型覆盖：新增(ADD)、修改(UPDATE)、删除(DELETE)

十、项目数据概览

指标	数据
TypeScript 源文件	385+
页面模块	19 个 Pages
视图组件	49 个 Views
API 模块	16 个（12 Java + 4 Node）
API 文件	150+
一级菜单	13 个
子路由	40+
国际化语言	8 种
自定义组件	15+
表格方案	4 种（ProTable / DragSort / Editable / VTable）

一、项目技术架构​

1.1 整体架构图​

1.2 核心技术栈​

二、菜单模块架构​

2.1 13 大功能模块​

2.2 路由权限控制​

三、AI 内容管理体系​

3.1 AIGC 内容管理​

3.2 AI 剧情生成系统​

3.3 智能封面生成​

3.4 角色模板与互动挑战​

四、薪资结算系统​

4.1 财务精确计算​

五、数据管理 — 埋点事件追踪系统​

5.1 事件建模与发布状态机​

5.2 动态列生成 — 上报数据查看​

5.3 埋点代码自动生成​

六、配置管理 — JSON 可视化编辑与版本回退​

6.1 JSONEditor 多模式编辑​

6.2 智能类型推断的可视化编辑器（核心亮点）​

6.3 配置版本管理​

七、多语言文案管理 — VTable V1→V2 演进​

7.1 V1 → V2 技术演进​

7.2 VTable 编辑器架构​

7.3 自定义编辑器 — TextAreaEditorWithValidator​

7.4 搜索组件 — SearchComponent​

7.5 操作列 — React 组件嵌入 VTable​

7.6 批量保存优化​

7.7 操作审计日志​

八、素材管理 — 树形文件管理系统​

8.1 树形导航 — 文件夹栈​

8.2 文件类型智能识别​

8.3 多种文件操作​

九、数据导入导出​

9.1 XLSX 白名单导入​

9.2 OSS 文件上传​

十、表格组件体系​

10.1 四种表格方案​

十一、API 服务层架构​

11.1 双后端 API 架构​

11.2 API 代码生成​

十二、技术亮点总结​

12.1 AI 驱动的运营工具​

12.2 VTable 大规模多语言编辑​

12.3 配置可视化编辑​

12.4 埋点事件管理​

12.5 树形素材库​

12.6 财务级精确计算​

12.7 完善的权限体系​

12.8 OSS 直传​

12.9 操作审计日志​

十、项目数据概览​