docs: document ai model registry, detail generator, purge outbox and roster identity changes
This commit is contained in:
parent
b93a7647d4
commit
b924735235
3
.gitignore
vendored
3
.gitignore
vendored
@ -149,6 +149,9 @@ Relay私密接管清单*
|
||||
*对话续接说明*
|
||||
*.ison.md
|
||||
|
||||
# 根目录会话交接文档（本地参考，不入 git）
|
||||
/*功能交接-*.md
|
||||
|
||||
# 根目录运维临时脚本
|
||||
/tmp-*.sh
|
||||
/tmp-simulate.mjs
|
||||
|
||||
46
CLAUDE.md
46
CLAUDE.md
@ -179,6 +179,12 @@ scgi_temp_path <proxy_dir>/tmp/scgi;
|
||||
- `Material.custodyDepartmentId`（托管部门）：人离职后由部门接手维护，**不改 userId 与 authorName**
|
||||
- 首页卡片显示的作者读的是 `user.realName || username`，托管不影响显示
|
||||
|
||||
### 权限组绑定花名册身份与团队职能（2026-10-08）
|
||||
|
||||
- 权限组的部门关联已从"路径字符串"改为绑定 `OrganizationUnit.id` 外键（迁移 `20261008_permission_group_department_identity`，生产 17 条已回填）。`departmentPath` 降级为失效关联的展示快照；**鉴权一律用绑定部门的当前有效路径**；一个部门只属一个组（DB 唯一索引），一人多部门取各任职权限组的并集；删除"按名称自动挂默认组"的旧逻辑。
|
||||
- 品牌中心"团队职能"已数据库化：`TeamFunctionConfig`（迁移 `20261008_team_function_configs`）每组织单元一条，负责人 = 花名册员工 profile ID，branches JSON，revision + 审计表。API `app/api/organization/team-functions`（GET 品牌中心可读、PUT 仅超管），UI `TeamFunctionsDashboard.tsx`，初始内容由 `scripts/seed-team-function-config.ts` 从 `data/team-function-initial-content.json` 导入。
|
||||
- 权限组与用户权限管理界面已合并简化（`PermissionGroupsDashboard.tsx`、`UserPermissionsDashboard.tsx`）。
|
||||
|
||||
### 定时同步
|
||||
|
||||
`ensureDailyOrganizationSyncStarted()` 在考核调研上下文中懒启动，每 24 小时执行：组织架构 → 在职状态 → 离职联动。
|
||||
@ -494,6 +500,9 @@ lib/
|
||||
| 抖音-千川素材 | Douyin Qianchuan | 批量上传 | 新增类型 |
|
||||
| 抖音-账号维护 | Douyin Account | 批量上传 | 新增类型 |
|
||||
| 音乐/买家秀/小红书 | 特殊类型 | 批量上传 | 特定类型限制 |
|
||||
| 直播切片 | Live Clip | 批量上传（仅视频，复用视频转码链路） | 标题必填；直播日期（默认当天）/主播（可关联用户）/平台（抖音、快手、视频号、淘宝直播、B站）；**豁免 15 天视频下载保护期**（站内与外部接口同时生效，`lib/video-download-policy.ts`） |
|
||||
|
||||
**证书-检测报告元数据（2026-09-23 起）：** 报告标题（兼作素材名）、报告类型（成品 / 原材料）、检测日期、到期日期（**默认 = 检测日期 + 1 年**，`lib/certificate-report.ts`）、证书编号、使用说明与内置使用规则。迁移 `20260923_add_certificate_report_metadata`、`20260924_add_certificate_tested_on`。
|
||||
|
||||
**视频类型改名说明（2026-04-30）：**
|
||||
- `主图视频` → `淘系-主图视频`
|
||||
@ -572,6 +581,29 @@ lib/
|
||||
- 支持中文文件名（使用 execFile 调用 pdftoppm）
|
||||
- 核心提交成功后，收尾步骤失败不影响整体成功
|
||||
|
||||
## AI 模型接入与详情页生成器（2026-10 新增，灰度中）
|
||||
|
||||
### AI 模型管理（仅超管）
|
||||
|
||||
- 管理界面：`/admin` 超级管理员 → AI 模型接入（`components/admin/AiModelManagementPanel.tsx`）；API 在 `app/api/admin/ai-models/`；领域逻辑 `lib/ai-model-protocol.ts` 等。
|
||||
- 管四类对象：上游服务商（API Key AES-256-GCM 加密存储）、模型目录（含能力元数据）、按用途的真实测试记录、三阶段配置（资料分析 / 卖点文案 / 生图）+ 操作审计。
|
||||
- **核心纪律：只有"真实协议测试"通过的用途才允许开放**——资料分析要真读测试图并返回指定位置颜色 JSON，文案要返回合规大纲 JSON，生图要可解码、尺寸有效、非空白；连接 / 密钥 / 能力 / 路由 / 适配版本任一变化即要求重新测试。
|
||||
- 测试与详情页生成共享配额：每人 1 并发、全局 2。上游已下架（present=false）的模型允许直接"停用"保存，不再被"需验证"卡住。
|
||||
- 表：`AiModelProvider / AiModelCatalog / AiModelVerification / AiModelConfiguration / AiModelAudit`（迁移 `20261012_ai_model_registry`、`20261013_ai_model_capabilities`、`20261013_ai_model_verifications`）。文档：`docs/ai-model-management.md`。
|
||||
|
||||
### 详情页生成器（正式验收前仅超管可见）
|
||||
|
||||
- 页面 `/assets/detail-generator`；API `app/api/detail-generator/*`；业务逻辑 `lib/detail-generator/`；表 `DetailGeneratorProject / BrandProfile / Asset / Job`（迁移 `20261012_detail_generator`，job 带幂等键、租约、checkpoint）。
|
||||
- 两级 worker：进程内队列（instrumentation 每 2 秒 tick，`DETAIL_GENERATOR_ENABLED==='true'` 才启动，全局并发 2，与模型测试共享）；渲染走**独立子进程** `workers/detail-renderer/cli.mjs`——自带依赖锁（Fabric 7 / Canvas 3 / Sharp 0.34，与主应用 Canvas 2 隔离）、768MB 独立堆、非守护服务不监听端口，生产由 `DETAIL_RENDERER_NODE` / `DETAIL_RENDERER_ENTRY` / `DETAIL_FONT_DIR` 指定。
|
||||
- 存储必须用独立私有卷 `DETAIL_GENERATOR_STORAGE_DIR`，不得复用 uploads/公开展示目录；生产 Docker 有独立 stage 与中文渲染 smoke 测试。
|
||||
- 显式未验收项：PSD 在 Photoshop 应用内改字保存、品牌风格一致性、多屏完整生成。带 `unknown` 状态的模型调用需人工到上游核对计费。
|
||||
|
||||
## 回收站永久删除（2026-10 重做为 outbox 任务）
|
||||
|
||||
- 入口 `POST /api/admin/materials/batch-delete`（`permanent:true`，单次上限 100）：请求路径只落 `MaterialPurgeJob`（文件清单快照 JSON）+ `MaterialPurgeAudit` 并删素材记录，**不做物理删除**；物理删除由 instrumentation 启动的 worker 执行（租约 10 分钟、最多 3 次尝试、每批 8 个文件、per-file outcome 写回快照，重启可续跑，可经 `POST /api/admin/materials/purge-jobs` 重试）。核心逻辑 `lib/material-purge.ts`，进度 UI `components/admin/MaterialPurgeStatus.tsx`。
|
||||
- 引用检查依赖 9 张表上的 GIN 表达式索引（规范化路径 md5，迁移 `20261009_material_purge_reference_indexes`；`lib/material-purge-reference-query.ts` 用 MATERIALIZED / OFFSET 0 钉住计划）；S3 派生文件用 `derived:` 键参与判断，共享派生文件不会被误删。
|
||||
- ⚠️ `material_logs` / `material_download_logs` 的 materialId 外键已为 purge 移除，**不要加回去**。备份恢复演练脚本：`scripts/verify-purge-backup-restore.mjs`。
|
||||
|
||||
### 文件处理流程
|
||||
|
||||
**图片处理**（`lib/image-processor.ts`）：
|
||||
@ -681,6 +713,20 @@ ADMIN_API_KEY=...
|
||||
# 钉钉（可选）
|
||||
DINGTALK_APP_KEY=...
|
||||
DINGTALK_APP_SECRET=...
|
||||
|
||||
# AI 详情页生成器（默认关；开启需独立私有持久卷，不得用 uploads）
|
||||
DETAIL_GENERATOR_ENABLED=false
|
||||
DETAIL_GENERATOR_BASE_URL=...
|
||||
DETAIL_GENERATOR_API_KEY=...
|
||||
DETAIL_GENERATOR_STORAGE_DIR=...
|
||||
|
||||
# 详情渲染子进程（生产镜像已固定 /opt/detail-renderer/...，一般无需覆盖）
|
||||
DETAIL_RENDERER_NODE=
|
||||
DETAIL_RENDERER_ENTRY=
|
||||
DETAIL_FONT_DIR=
|
||||
|
||||
# AI 上游密钥加密（≥32 字符；与 API Key 加密密钥独立生成、稳定保存）
|
||||
API_KEY_ENCRYPTION_KEY=...
|
||||
```
|
||||
|
||||
### 常用模式
|
||||
|
||||
14
README.md
14
README.md
@ -41,6 +41,8 @@
|
||||
- 标准模特白底图
|
||||
- SKU 维度文件管理、排序、批量下载
|
||||
- 详情图 / 素材资产管理
|
||||
- 直播切片（仅视频）：直播日期 / 主播 / 平台元数据，批量多选上传，关键词搜主播与平台，按平台与日期区间筛选，豁免 15 天视频下载保护期
|
||||
- 证书-检测报告元数据：报告标题、报告类型（成品 / 原材料）、检测与到期日期（到期默认检测日期 + 1 年）
|
||||
- 商品套包未完成上传的中止与回滚
|
||||
- 视频转码、封面 / 预览片段生成、PostgreSQL 租约任务恢复与重试
|
||||
- 默认生成 720P H.265 主预览和 10 秒片段；素材建档后异步经历 `pending → processing → done/failed`
|
||||
@ -50,6 +52,8 @@
|
||||
- 素材管理、用户管理、分类管理
|
||||
- 部门管理与部门素材权限控制
|
||||
- 数据统计、统计导出、素材操作日志
|
||||
- 回收站永久删除：数据库 outbox 任务 + 应用内 worker（租约、重试、断点续跑、审计），引用检查走 GIN 表达式索引
|
||||
- 权限组绑定花名册组织身份；品牌中心"团队职能"数据库化配置
|
||||
- API Key、API 日志、系统设置、回收站、超级管理员相关能力
|
||||
|
||||
### 5. 运行与诊断
|
||||
@ -59,6 +63,11 @@
|
||||
- 快速性能检查接口
|
||||
- 内外网 URL 重写与下载链路适配
|
||||
|
||||
### 6. AI 能力（灰度中，默认关闭）
|
||||
|
||||
- AI 模型接入管理（仅超管）：上游服务商与模型注册表，按用途做"真实协议测试"（真读图、真出图）后才允许开放；能力变更即要求重新验证
|
||||
- AI 商品详情页生成器（正式验收前仅超管）：资料分析 → 卖点大纲 → 逐屏生成 → 导出 PNG / 长图 / 分层 PSD；渲染走独立子进程 `workers/detail-renderer`（自带依赖锁，与主应用隔离）
|
||||
|
||||
## 技术栈
|
||||
|
||||
- 前端：Next.js 14、React 18、TypeScript、Tailwind CSS
|
||||
@ -87,6 +96,7 @@ gongxiangp2/
|
||||
├── lib/ # 业务工具、上传/下载/转码/权限逻辑
|
||||
├── prisma/ # Prisma schema
|
||||
├── scripts/ # 运维/修复/清理脚本
|
||||
├── workers/ # 独立子进程：detail-renderer（详情页渲染）、database-migrator（精简迁移镜像）
|
||||
├── docs/ # 网络、接口与部署等项目文档
|
||||
├── uploads/ # 本地上传与处理中间文件
|
||||
└── README.md
|
||||
@ -108,6 +118,10 @@ gongxiangp2/
|
||||
- `ApiCallLog`
|
||||
- `VideoTranscodeProgress`
|
||||
- `SystemSettings`
|
||||
- AI 模型注册表：`AiModelProvider` / `AiModelCatalog` / `AiModelVerification` / `AiModelConfiguration` / `AiModelAudit`
|
||||
- 详情页生成器：`DetailGeneratorProject` / `DetailGeneratorBrandProfile` / `DetailGeneratorAsset` / `DetailGeneratorJob`
|
||||
- 回收站永久删除：`MaterialPurgeJob` / `MaterialPurgeAudit`
|
||||
- 组织与团队职能：`TeamFunctionConfig` / `TeamFunctionConfigAudit`
|
||||
|
||||
角色枚举当前包含：
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user