# 云函数部署指南

本目录是 fmode 云函数源码。前端通过 `src/app/services/cloud-functions.ts` 里的函数 ID 调用这些函数。

## 部署清单

| 字段 | 文件 | 状态 | 主要 action / 能力 |
|---|---|---|---|
| `manifest` | `01-manifestManager.js` | 已配置 | list / get / create / update / delete |
| `task` | `02-taskManager.js` | 已配置 | list / get / create / update / delete |
| `history` | `03-historyManager.js` | 已配置 | list / create / delete / clearAll |
| `result` | `04-resultManager.js` | 已配置 | list / get / create / update / delete |
| `remix` | `05-remixManager.js` | 已配置 | listAll / listByVideo / upsert / delete |
| `voice` | `06-voiceManager.js` | 已配置 | autoSpeakerId / syncProfile / listProfiles / initPool / deleteProfile |
| `quickly` | `07-quicklyVideo.js` | 待部署 | create / query |
| `proxy` | `08-proxyHub.js` | 已配置 | llmChat / geminiChat / llmChatStream |
| `upload` | `09-uploadManager.js` | 已配置 | createUploadToken |
| `authCredit` | `10-authCreditManager.js` | 待部署/暂未启用 | register / login / me / reserve / commit / refund / ledger |
| `jimeng` | `11-jimengManager.js` | 已配置 | 即梦图片、视频、数字人、动作迁移代理 |
| `douyin` | `12-douyinManager.js` | 已配置 | TikHub 抖音搜索、详情、评论、博主数据代理 |
| `douyinInsight` | `13-douyinInsightManager.js` | 已配置 | 爆款分析、选题池、日报资产持久化 |

## 部署步骤

1. 打开 fmode 云函数管理平台。
2. 新建或更新云函数，名称建议与文件名一致。
3. 粘贴对应 `.js` 文件完整内容。
4. 在平台配置该函数需要的环境变量。
5. 保存并部署，复制返回的 10 位函数 ID。
6. 更新 `src/app/services/cloud-functions.ts` 对应字段。
7. 执行 `npm run smoke:cloud` 验证已配置函数是否可调用。
8. 执行 `npm run build` 验证前端编译。

## 外部凭证清单

| 函数 | 必需凭证/配置 | 说明 |
|---|---|---|
| `06-voiceManager.js` | `VOICE_TOKEN`, `VOICE_TTS_BASE_URL` | 火山 TTS/音色训练代理；`listProfiles` 不需要调用上游。 |
| `07-quicklyVideo.js` | `QUICKLY_APP_KEY`, `QUICKLY_APP_SECRET`, `QUICKLY_ACCOUNT_ID`, `QUICKLY_CALLBACK_URL`, `QUICKLY_RELAY_URL`, `QUICKLY_UPSTREAM_FN_ID` | 一键成片。如不用该功能可保持 `quickly` 为空。 |
| `08-proxyHub.js` | `LLM_BASE_URL`, `LLM_API_KEY` | LLM/Gemini 代理。 |
| `09-uploadManager.js` | `QINIU_AK`, `QINIU_SK`, `QINIU_BUCKET`, `QINIU_CDN_DOMAIN`, `QINIU_CDN_PREFIX`, `QINIU_UPLOAD_URL` | 七牛直传 token。 |
| `10-authCreditManager.js` | Parse session 可用即可；无第三方密钥 | 账号、积分、充值框架。商业化恢复前再启用。 |
| `11-jimengManager.js` | `JIMENG_TOKEN`, `JIMENG_BASE_URL`, `PARSE_BASE_URL`, `PARSE_APP_ID` | 即梦真实生成代理。 |
| `12-douyinManager.js` | `TIKHUB_BASE_URL`, `TIKHUB_TOKEN` | 抖音真实平台数据抓取。 |
| `13-douyinInsightManager.js` | `PARSE_API_HOST`, `PARSE_APP_ID` | 业务资产持久化和用户隔离。 |

以上变量均已在云函数源码中改为“环境变量优先、当前兼容值兜底”。正式部署时应在 fmode 云函数平台配置环境变量，并在确认新变量生效后轮换旧凭证。

## 当前前端函数 ID

见 `src/app/services/cloud-functions.ts`。当前仍为空的字段：

- `quickly`: 一键成片云函数未启用。
- `authCredit`: 账号/积分云函数未启用；试运营阶段积分扣费仍关闭。

## 验证命令

```bash
npm run smoke:cloud
npm run build
```

`smoke:cloud` 会跳过函数 ID 为空的项目；对于 `jimeng`、`douyin`、`proxy` 会用预期失败请求验证函数可达和路由校验是否生效，避免触发真实生成或真实扣费。

2026-06-01 联网冒烟结果：

- 最终通过：`manifest.list`、`task.list`、`history.list`、`result.list`、`remix.listAll`、`voice.listProfiles`、`upload.token.probe`、`jimeng.unknownAction`、`douyin.unknownRoute`、`douyinInsight.authGuard`、`proxy.unknownAction`。
- 权限保护符合预期：`douyinInsight.listTopics` 未带 session token 时返回“请先登录”。
- 首轮曾出现 `manifest.list`、`task.list` 偶发 `fetch failed`，复跑通过；后续生产运维需要继续观察函数平台网络稳定性。
- 待部署填 ID：`quickly`、`authCredit`。

## 首次部署后的特殊步骤

`voiceManager` 需要初始化 speaker_id 池：

```js
await fetch('https://server.fmode.cn/api/functions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Parse-Application-Id': 'ncloudmaster',
  },
  body: JSON.stringify({
    id: 'voice 函数 ID',
    _ApplicationId: 'ncloudmaster',
    action: 'initPool',
    speakerIds: ['S_xxx', 'S_yyy'],
  }),
});
```

## 上线前检查

- `cloud-functions.ts` 不允许留错函数 ID。
- 必需凭证要配置在云函数平台环境变量中。
- `npm run smoke:cloud` 通过。
- `npm run build` 通过。
- 批量真实生成、素材归档、发布复盘抓取各跑一条端到端样例。