# CloudCC 自定义 HTML 组件开发指南

## 1. 功能范围

HTML 模块支持以下能力：

- 创建本地 HTML 组件目录与默认 `index.html`。
- 发布 HTML 内容到平台。
- 发布成功后通过内置 iframe 组件自动创建承载页面。
- 查询 HTML 组件列表。
- 查询 HTML 组件详情。
- 删除 HTML 组件。

## 2. 页面开发规范

- 使用单 HTML 文件作为页面入口，默认入口文件为 `index.html`。
- 页面标题、显示名和 API 名应保持可识别，避免使用临时名称。
- 外部依赖优先使用稳定的 HTTPS 地址。
- 私有云或内网环境应优先使用 CloudCC 静态资源地址，不依赖公网 CDN。
- 页面脚本使用 `$CCDK` 前必须判断对象是否存在。

## 3. 发布前约束

- 发布依赖有效的项目配置和 `accessToken`。
- 发布环境必须能查询到内置组件 `cloudcc-iframe`。
- 本地目录中必须存在 `config.json` 和 `index.html`。
- `config.json` 至少应包含 `apiName` 与 `htmlLabel`。

## 4. 自动挂载行为

HTML 组件保存成功后，平台返回组件详情和访问路径。后续会使用内置 `cloudcc-iframe` 组件创建自定义页面，并将 iframe 地址指向 HTML 组件访问路径。

访问路径处理规则：

- 若返回路径已经以 `/oss` 开头，直接使用。
- 若返回路径是完整 HTTP 地址，直接使用。
- 其他相对路径会补为 `/oss/<accessPath>`。

## 5. 错误处理原则

- 配置缺失或 `accessToken` 缺失时，应直接返回明确错误。
- 找不到 `cloudcc-iframe` 时，应在保存 HTML 前阻断发布。
- HTML 保存成功但自定义页面创建失败时，应返回 HTML 组件 ID，方便人工排查和补救。
- 接口失败信息优先取 `returnInfo`，其次取 `errormsg`、`message` 或完整返回体。