flnxi-Wu/docs/参考源码功能吸收整理_20260513.md

参考源码功能吸收整理（2026-05-13）

本文档替代旧的两份对比文档：

• docs/当前项目与参考源码对比记录_20260309.md
• docs/参考目录差异总结_20260413.md

原因很简单：那两份文档指向的参考目录当前文件系统中已经不存在，继续保留会误导后续判断。

1. 当前真实参考对象

当前实际存在并被用户指定用于对比的参考源码目录是：

D:\AI Code\sucaiku\flnxi_sucai\gongxiangp2-source-reference-old-style-20260513-132942

2026-05-13 已做只读定点核验：任务、SKU、商品套包、外部 API、部门权限、数据统计、网络诊断、转码队列等下文列出的关键路径在该目录中真实存在。该核验只用于确认能力边界，不代表可以直接复制旧实现。

使用边界：

• 只读
• 不修改
• 不参与主项目构建
• 不参与主项目测试
• 只在需要查实现、做功能差异、评估迁移时进入

2. 总判断

当前项目和 old-style 参考源码不是简单的新旧版本关系，而是两条侧重点不同的分支。

当前项目主轴：

• 企业 / 团队私有化交付
• 模板化素材上传
• 动态字段、字段池、首页动态筛选
• 许可证激活、免费版 / 付费版限制
• 系统初始化、邀请、安装 Agent、Docker / NAS 交付

old-style 参考源码主轴：

• 已在线运行过的内部素材业务系统
• 任务号、SKU、商品套包、多资产、白底图
• 外部 API、API Key、调用日志、外部导入
• 部门素材类型权限
• 数据统计、回收站、运维诊断、转码队列持久化

所以后续不应该“整套合并”，更适合按模块吸收能力。

2026-05-13 用户已明确排除：

• 不做任务号管理
• 不做白底图
• 不做条码绑定
• 不做成套完整性判断
• 不做外部系统对接 / 外部 API
• 前端必须保持当前项目自己的视觉风格，不搬 old-style 旧 UI

3. 当前项目能力地图

当前项目已经具备的核心能力：

• 素材上传、搜索、预览、下载、分享、收藏、点赞
• 上传模板、动态字段、字段池、筛选项配置
• 用户、部门、邀请、管理员后台
• 授权激活、许可证校验、免费版 / 付费版功能限制
• 系统设置、Logo / 外观设置、系统初始化、完整性检查
• 钉钉登录、AI 聊天 / AI 编辑相关接口
• 主应用、独立 license-server/、Node 版 flnxi-agent/、Go 版 flnxi-agent-go/

当前项目尚未具备的完整模型：

• 独立 SKU 主模型：当前只有 Material.skuCode 字段，没有 MaterialSku 全链路
• 任务号主线：当前没有 task/detail 全套业务模型
• 外部 API Key / 调用日志业务链路：当前主应用没有 old-style 那套 app/api/external/ 和后台 API Key 管理
• 部门素材类型权限矩阵：当前有部门和用户管理，但没有 old-style 那套按部门、素材类型控制查看/下载/分享的矩阵

关键证据：

• prisma/schema.prisma
• app/api/materials/upload/route.ts
• app/api/admin/upload-templates/
• app/api/license/
• lib/license/
• components/UploadModal.tsx
• app/admin/_components/TemplateManager.tsx
• prisma/schema.prisma 中的 Material.skuCode

4. old-style 参考源码能力地图

old-style 更完整的能力主要集中在业务素材全链路。

4.1 任务型素材

包含任务号、任务详情、任务页面、任务原图、任务视频截图等链路。它的重点不是“上传一个文件”，而是围绕一个任务交付一组资产。

相关路径：

• gongxiangp2-source-reference-old-style-20260513-132942/lib/task-material-processor.ts
• gongxiangp2-source-reference-old-style-20260513-132942/lib/task-detail-full-set.ts
• gongxiangp2-source-reference-old-style-20260513-132942/components/detail/TaskPageDetail.tsx

4.2 SKU / 白底图 / 条码

包含 MaterialSku、SKU 文件管理、排序、单 SKU 下载、批量下载、标准模型白底图、条码绑定。

相关路径：

• gongxiangp2-source-reference-old-style-20260513-132942/components/SkuList.tsx
• gongxiangp2-source-reference-old-style-20260513-132942/components/SkuEditModal.tsx
• gongxiangp2-source-reference-old-style-20260513-132942/lib/standard-model-white-background.ts
• gongxiangp2-source-reference-old-style-20260513-132942/prisma/schema.prisma

4.3 多资产 / 商品套包

包含主图、SKU 图、详情图、PSD、证书报告等资产拆分，适合支撑商品素材成套管理。

相关路径：

• gongxiangp2-source-reference-old-style-20260513-132942/components/upload/ProductPackageUploader.tsx
• gongxiangp2-source-reference-old-style-20260513-132942/lib/product-package.ts
• gongxiangp2-source-reference-old-style-20260513-132942/lib/material-cleanup.ts

4.4 外部 API / API Key / 调用日志

包含 API Key 鉴权、调用日志、外部下载令牌、外部导入任务、钉钉物料匹配与选项接口。

相关路径：

• gongxiangp2-source-reference-old-style-20260513-132942/lib/external-api.ts
• gongxiangp2-source-reference-old-style-20260513-132942/app/api/external/
• gongxiangp2-source-reference-old-style-20260513-132942/app/api/admin/api-keys/
• gongxiangp2-source-reference-old-style-20260513-132942/app/api/admin/api-logs/

4.5 部门素材权限

包含按部门、素材类型控制查看、下载、分享、源文件下载，并支持批量、复制、继承、关联。

相关路径：

• gongxiangp2-source-reference-old-style-20260513-132942/lib/department-permission.ts
• gongxiangp2-source-reference-old-style-20260513-132942/components/DepartmentPermissionsTab.tsx
• gongxiangp2-source-reference-old-style-20260513-132942/app/api/admin/department-permissions/

4.6 数据统计与运维诊断

包含数据统计导出、素材操作日志、系统日志、网络测速、网络诊断、健康检查、内存检查、转码队列。

相关路径：

• gongxiangp2-source-reference-old-style-20260513-132942/components/admin/DataStatisticsTab.tsx
• gongxiangp2-source-reference-old-style-20260513-132942/app/api/admin/data-stats/
• gongxiangp2-source-reference-old-style-20260513-132942/app/api/network/
• gongxiangp2-source-reference-old-style-20260513-132942/lib/video-transcode-queue.ts

5. 差异对比

方向	当前项目	old-style 参考源码	判断
产品定位	私有化交付产品	内部在线业务系统	当前项目定位更适合商业交付
上传模型	模板化上传、动态字段	固定业务类型、专用上传器、分片上传	可吸收分片和批量体验，保留当前模板体系
任务型素材	暂无任务号主线	任务号、多资产、整套判断	用户已明确不需要，不纳入吸收目标
SKU / 白底图	暂无完整 SKU 模型	SKU、白底图、条码、批量下载	白底图、条码已明确不需要；SKU 是否扩展需另行确认
多资产	主要是预览图、展示图、压缩包	主图、SKU 图、详情图、PSD、证书	可只参考“多类文件分组”思路，不做任务号和成套完整性判断
外部 API	主要是站内 API 和许可证代理	API Key、日志、外部查询、导入	用户已明确不需要，不纳入吸收目标
部门权限	有部门和用户管理	有部门 + 素材类型权限矩阵	有价值，但要和许可证边界重整
数据统计	有监控和基础统计	运营统计、导出、日志更完整	可吸收后台统计能力
部署交付	有许可证服务、Agent、Compose	偏在线单体部署	不能照搬 old-style 部署假设
UI 风格	正在形成统一产品化 UI	更偏内部运营平台	不建议直接搬旧视觉

6. 吸收优先级

P0：优先吸收

1. 多类文件分组管理

   • 价值：让一个素材下可以更清楚地区分源文件、预览图、详情图、PSD、附件等。
   • 边界：只吸收“素材下面挂多类文件”的产品思路，不做任务号、不做成套完整性判断、不搬旧上传器视觉。

2. 批量上传和上传体验增强

   • 价值：减少一次性上传多文件、多预览图、多附件时的人工操作。
   • 边界：继续沿用当前项目的模板化上传和视觉风格，只改善体验和稳定性。

P1：建议吸收

1. 部门素材类型权限

   • 价值：私有化团队常见需求，能控制不同部门能看什么、能不能下载源文件。
   • 风险：会影响当前许可证功能边界和部门模型，不能直接搬旧角色体系。

2. 数据统计与操作日志

   • 价值：便于客户验收、团队管理、追责和运营统计。
   • 建议：优先补后台统计页和导出能力，不先改主业务链路。

P2：按需吸收

1. 批量上传体验、断点续传、上传会话 Redis / 内存双态
2. SPU 自动解析、产品品类
3. 网络诊断、测速、快速性能检查
4. 转码队列持久化与恢复

这些能力有价值，但要结合 NAS 性能、客户部署复杂度和当前模板体系逐步接入。

暂不建议吸收

• 任务号管理
• 白底图
• 条码绑定
• 成套完整性判断
• 外部 API / API Key / 外部导入 / 外部下载
• old-style 整套旧 UI
• 绑定特定公网域名、固定服务器、固定外部平台的部署假设
• 强绑定钉钉或 AI 生图平台的默认流程；这类能力必须依赖真实外部服务、密钥和回调地址，不作为默认客户验收项
• old-style 的完整角色体系和超级管理员体系

7. 后续落地建议

推荐分三期处理：

1. 先做模型设计

   • 明确 素材、多类文件/附件、SKU 字段或 SKU 扩展 和当前 Material、UploadTemplate 的关系。
   • 不引入任务号主线，不设计白底图、条码或成套完整性判断。
   • 确认哪些能力作为免费版 / 付费版边界。

2. 再做低风险能力迁移

   • 后台统计
   • 操作日志增强
   • 批量上传体验
   • 转码队列持久化

3. 最后接重业务链路

   • 多类文件分组
   • 如后续确认需要，再单独评估 SKU 扩展
   • 部门素材权限矩阵

一句话：当前项目继续作为主产品，old-style 只作为能力参考库。吸收的是少量适合当前产品的业务思路和工程经验，不吸收任务号、白底图、条码、成套判断、外部系统对接，也不吸收旧视觉、旧部署和旧环境假设。