migrate-app-to-flows

将应用迁移到 Flows 基础设施

协调将旧版 Dune 应用完整迁移到新的 Flows 应用托管（appsApi）。按顺序处理各个部分，跳过任何已处于正确状态的部分。

第 1 步 — 审核当前状态

读取 app.json、package.json、vite.config.ts 和 manifest.json（如果存在）。

进行任何更改前，先简要总结：

Migration audit:
✗ app.json: missing infra field → will add "infra": "appsApi"
✗ Auth: DuneAuthProvider in use → will run setup-flows-auth
✗ manifest.json: missing → will create
✓ Deploy script: already uses @cognite/cli

然后继续执行第 2–5 步。

---

第 2 步 — 更新 app.json

如果 infra 已经是 "appsApi"，则跳过此步骤。否则：

先修正旧版部署键格式。 许多 POC 应用使用 "deployment"（单数、普通对象）。CLI 要求使用 "deployments"（复数、数组）。如果文件使用旧格式，请先重命名键并将值包装在数组中，然后再继续：

// Before (legacy)
{
  "deployment": { "org": "...", "project": "...", ... }
}

// After (correct)
{
  "deployments": [{ "org": "...", "project": "...", ... }]
}

然后添加 "infra": "appsApi"：

{
  "name": "My App",
  "externalId": "my-app",
  "versionTag": "0.0.1",
  "infra": "appsApi",
  "deployments": [...]
}

---

第 3 步 — 设置 Flows 身份验证

现在运行 setup-flows-auth 技能。它会处理所有身份验证相关事项：安装软件包、更新 Vite 插件、修改入口文件，以及接入 connectToHostApp。

---

第 4 步 — 创建或更新 manifest.json

Flows 主机使用 manifest.json 为应用实施内容安全策略。该文件必须位于仓库根目录。

如果文件不存在，则创建：

{
  "manifestVersion": 1,
  "permissions": {
    "network": []
  }
}

扫描对外部域名的出站调用，填充网络权限：

grep -rn "fetch\|axios\|new XMLHttpRequest" src/ --include="*.ts" --include="*.tsx"

对于找到的每组外部 URL，使用 sources/directives 结构在 network 数组中添加一个条目：

{
  "manifestVersion": 1,
  "permissions": {
    "network": [
      {
        "sources": ["https://api.example.com", "https://maps.googleapis.com"],
        "directives": ["connect-src"]
      }
    ]
  }
}

规则：

• sources 中使用完整来源（协议 + 主机名），而不仅是主机名。
• "connect-src" 覆盖 fetch/XMLHttpRequest。图片 URL 使用 "img-src"，字体使用 "font-src"。
• CDF 集群 URL 会自动允许；不要将其列出。
• 如果不存在外部调用，则保留 "network": []。
• 标记所有需要用户手动核实的动态 URL。

---

第 5 步 — 更新部署脚本

替换 package.json 中的任何 dune deploy 或 npx @cognite/dune 命令：

{
  "scripts": {
    "deploy": "npx @cognite/cli@latest apps deploy --interactive",
    "deploy-preview": "npx @cognite/cli@latest apps deploy --interactive"
  }
}

其他所有脚本（start、build、test 等）保持不变。

---

第 6 步 — 最终检查

grep -rn "DuneAuthProvider\|useDune\|@cognite/dune" src/ vite.config.ts 2>/dev/null

列出所有剩余匹配项，供用户处理。然后报告：

Migration complete:
✓ app.json: infra set to "appsApi", deployments key is an array
✓ Auth: setup-flows-auth applied
✓ manifest.json: network permissions set
✓ Deploy scripts: updated to @cognite/cli

然后明确告知用户下一步要做什么：

Next steps:
1. Run `npm run dev` to start the dev server
2. Open Fusion and verify the app loads and CDF data appears correctly
3. When happy, deploy with: npx @cognite/cli@latest apps deploy --interactive