# 云函数部署指南

本目录包含 8 个云函数，部署到 fmode 平台后可替代 31 个 Express 接口。

## 部署清单

| # | 文件 | 替代的 Express 接口数 | actions |
|---|---|---|---|
| 01 | `01-manifestManager.js` | 4（GET/POST/PUT/DELETE /api/manifest） | list / get / create / update / delete |
| 02 | `02-taskManager.js` | 4（/api/tasks） | list / get / create / update / delete |
| 03 | `03-historyManager.js` | 3（/api/history） | list / create / delete / clearAll |
| 04 | `04-resultManager.js` | 4（/api/results） | list / get / create / update / delete |
| 05 | `05-remixManager.js` | 4（/api/remixes） | listAll / listByVideo / upsert / delete |
| 06 | `06-voiceManager.js` | 2（/api/voice/*） | autoSpeakerId / syncProfile / listProfiles / initPool / deleteProfile |
| 07 | `07-quicklyVideo.js` | 2（/api/quickly/*） | create / query |
| 08 | `08-proxyHub.js` | 2（/api/llm/*） | llmChat / geminiChat |

**合计：8 个云函数覆盖 25 个 CRUD + 6 个代理 = 31 个接口** ✅

> ⚠️ `docs/云函数/筷子一键成片.json` 是**别项目**的参考样本，**不要直接部署**。本目录的 `07-quicklyVideo.js` 才是本项目自己的实现。

## 部署步骤（每个文件）

1. 打开 fmode 云函数管理平台
2. 新建云函数，命名建议跟文件名一致（如 `manifestManager`）
3. 粘贴 `.js` 文件的完整代码（**不要包含外层 markdown**）
4. 保存 → 部署 → **复制返回的函数 ID**（10 位字符串）
5. 把 ID 填入 `src/app/services/cloud-functions.ts` 对应字段

## 前端依赖安装

部署完云函数后，前端需要安装 SDK：

```bash
npm install fmode-ng
```

安装后 `src/app/services/parse.service.ts` 的导入错误会自动消失。

## 验证云函数部署成功

每个云函数支持 `debug` 之外的 action 调用即可验证。示例：

```javascript
// 在浏览器 console 或一个临时按钮里测试
const Parse = FmodeParse.initialize({
  appId: 'ncloudmaster',
  serverURL: 'https://server.fmode.cn/parse',
});

// 测试 manifestManager（应该返回空数组 [])
await Parse.Cloud.function({ id: '你的函数ID', action: 'list' });
// 期望响应：{ code: 200, success: true, data: [] }
```

## ⚠️ voiceManager 首次部署后必做

`voiceManager` 需要灌入 speaker_id 池才能工作。原本 `docs/音色创建/speaker_id.md` 里的池要一次性导入：

```javascript
await Parse.Cloud.function({
  id: '你的voiceManager函数ID',
  action: 'initPool',
  speakerIds: ['S_xxx', 'S_yyy', ...], // 把现有池里所有 speaker_id 传进来
});
```

灌入后才能调用 `autoSpeakerId` 自动分配。

## 数据迁移（可选）

新云函数建的是空表。如果想保留现有 `data/*.json` 数据：

1. 把 `data/manifest.json` 内容转成数组 → 循环调 `manifestManager` 的 `create` action
2. 同理迁移 tasks / history / results / voice-profiles
3. `remixes/*.json` → 每个 videoId 文件循环调 `remixManager` 的 `upsert`

也可以**不迁移**，直接从云函数版本重新开始用。

## 表设计统一约定

所有 CRUD 类云函数遵循同一表结构：

```sql
CREATE TABLE "<ResourceName>" (
  "objectId"  VARCHAR(50) PRIMARY KEY,     -- 10位随机ID（云函数生成）
  "bizId"     VARCHAR(255),                -- 业务 ID（原 video.id / task.id 等）
  "data"      JSONB NOT NULL DEFAULT '{}', -- 完整业务字段
  "userId"    VARCHAR(255) DEFAULT '',     -- 可选，用户隔离
  ... (常用索引字段)
  "createdAt" TIMESTAMPTZ,
  "updatedAt" TIMESTAMPTZ
)
```

好处：
- 业务字段加减不用改 schema（全在 JSONB 里）
- 公共字段（id / status / type）单独提出来便于查询和索引
- 跟 Parse 自动 `objectId` 兼容

## 统一响应格式

```json
// 成功
{ "code": 200, "success": true, "data": ... }

// 失败
{ "code": 400 或 500, "success": false, "error": "错误信息" }
```

前端 `ParseService.callOrThrow()` 已封装错误处理。