flnxi-Wu/scripts/README.md

脚本说明

scripts/ 目录里既有当前仍在使用的脚本，也有历史遗留的人工运维脚本。这个文件只列“当前还应当优先关注”的入口。

一、通过 package.json 直接调用的脚本

migrate-template-data.ts

用途：

• 修复历史模板数据
• 为素材补齐模板关联
• 做模板体系迁移后的收尾处理

运行：

npm run migrate:template-data

verify-template-data.ts

用途：

• 校验模板、字段、素材之间的数据一致性
• 在部署后或修复后做确认

运行：

npm run verify:template-data

二、当前保留的手动脚本

构建相关

• build-material-image.ps1 构建主应用镜像。它属于历史/内部维护备用入口，保留旧的测试/正式分层规则，但仍带 Harbor / latest 旧口径；客户正式交付、升级、回滚优先用根目录的 deploy-registry.ps1，不要把它当成客户升级主线。若确需用它推送旧 Harbor，必须显式追加 -AcknowledgeLegacyHarborPush。
• build-obfuscated.js 生产构建后的服务端混淆处理。客户交付镜像通过 Dockerfile 执行 npm run build:prod 时会自动调用；混淆依赖或配置缺失会直接失败，不能静默跳过。
• docker-entrypoint.sh 主应用容器启动入口
• generate-shared-test-env.ps1 为共享测试机生成隔离后的 .env，避免容器名、卷名、网络名与其他项目冲突

数据检查/修复相关

• check-templates.ts 检查模板缺失或异常
• fix-missing-templates.ts 修复缺失模板
• update-audio-template-fields.ts 更新音频模板字段
• migrate-ai-to-other-template.ts 处理 AI 模板迁移
• trigger-video-transcode.ts 手工触发视频转码

三、使用原则

1. 能通过 package.json 跑的，优先不要手敲文件路径。
2. 手动脚本通常带环境假设，执行前先读内容。
3. 带固定服务器地址、固定账号、一次性交付信息的脚本，不应继续当成通用入口。
4. build-material-image.ps1 和 generate-shared-test-env.ps1 都偏内部维护，客户交付只在确实需要时使用。
5. 看到 Harbor、固定服务器、latest 的脚本，默认先当历史/内部入口处理，不要直接用于客户安装或升级。

四、常见流程

模板数据修复

npm run prisma:generate
npm run migrate:template-data
npm run verify:template-data

检查并修复模板缺失

npx tsx scripts/check-templates.ts
npx tsx scripts/fix-missing-templates.ts

为共享测试机生成环境文件

.\scripts\generate-shared-test-env.ps1 `
  -OutputPath "$env:TEMP\flnxi_sucai-test.env" `
  -LicenseServerUrl "https://your-license-server.example.com"

说明：

• LicenseServerUrl 不再内置默认值，必须显式传入。
• 示例地址只是占位，执行前必须替换为当前真实可用的许可证服务地址。
• https://license.flnxi.com 不能默认当作当前可用入口。

手工触发单个视频转码

npx tsx scripts/trigger-video-transcode.ts <素材ID>

五、相关文档

• ../README.md
• ../docs/README.md
• ../docs/deployment/部署说明.md