> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 源码导出 API

源码导出 API 用于获取项目当前源码的 ZIP 压缩包。接口会在一次请求内完成源码恢复、打包和上传，并返回短期有效的下载链接。

基础地址：`https://meoo.com/open/v1`

## 创建源码导出

```text theme={null}
POST /projects/{project_id}/source-exports
```

所需权限：`source.read`

调用者还必须满足以下条件：

* 对项目具有源码下载权限；当前支持项目 owner 和 admin。
* 当前账号或项目套餐具有源码下载权益。
* 项目处于可操作状态。

无权访问项目时统一返回 `404`，不会通过错误响应暴露项目是否存在。

## 导出内容

* 项目沙箱正在运行时，导出沙箱实际工作目录中的当前源码。
* 项目沙箱未运行时，服务端会启动或恢复沙箱，并从项目最近持久化的源码生成压缩包；客户端不需要预先启动沙箱。
* 导出格式固定为 ZIP。
* 压缩包固定排除 Git 元数据、依赖目录、构建产物、缓存、平台临时文件以及 `.env`、`.env.*` 环境文件。

接口是同步接口。请求会等待恢复、打包和上传完成，因此项目体积较大或需要恢复沙箱时耗时会更长。客户端超时时间建议设置为 240 秒；在未收到明确响应时，不要高频并发重试。

## 请求

### Path 参数

**参数说明**

* `project_id`（string，必填）：项目的 `url_id`

请求不包含请求体。

### 请求示例

```text theme={null}
curl --request POST \
  --url "https://meoo.com/open/v1/projects/event-signup-demo/source-exports" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"
```

## 成功响应

成功时返回 `201 Created`：

```text theme={null}
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: private, no-store
```

### 响应字段

| 字段                        | 类型      | 说明                                 |
| :------------------------ | :------ | :--------------------------------- |
| `export_id`               | string  | 本次导出的唯一标识，格式为 `se_` 加 32 位小写十六进制字符 |
| `project_id`              | string  | 项目的 `url_id`                       |
| `filename`                | string  | 建议保存的 ZIP 文件名                      |
| `content_type`            | string  | 固定为 `application/zip`              |
| `size`                    | integer | ZIP 文件大小，单位为字节                     |
| `sha256`                  | string  | ZIP 文件的 SHA-256，小写十六进制字符串          |
| `download_url`            | string  | 私有对象存储生成的临时签名下载地址                  |
| `download_url_expires_at` | integer | 下载地址过期时间，Unix 毫秒时间戳                |

### 响应示例

```text theme={null}
{
  "export_id": "se_0123456789abcdef0123456789abcdef",
  "project_id": "event-signup-demo",
  "filename": "code-event-signup-demo.zip",
  "content_type": "application/zip",
  "size": 184320,
  "sha256": "c3b68f7d6b5f09a78f22ba15dfee3f0db8b176d79a26b5222d8f9c92e8f4e7ac",
  "download_url": "https://example-bucket.oss-cn-hangzhou.aliyuncs.com/source_exports/...?...",
  "download_url_expires_at": 1787710200000
}
```

`download_url` 默认有效期为 10 分钟。它是可以直接读取项目源码的临时凭证，应按敏感信息处理：不要写入日志、数据库、分析系统或发送给无关人员。建议收到响应后立即下载，不要依赖该地址长期保存文件。

## 下载与完整性校验

下载 ZIP 后，建议同时校验文件大小和 SHA-256：

```text theme={null}
curl --fail --location \
  --output "${FILENAME}" \
  "${DOWNLOAD_URL}"

printf '%s  %s\n' "${SHA256}" "${FILENAME}" | shasum --algorithm 256 --check
```

如果下载地址已经过期，请重新调用创建源码导出接口。不要尝试修改或延长签名参数。

## 限流

| 维度            | 限制                    |
| :------------ | :-------------------- |
| IP            | 20,000 次/分钟（开放平台共享限制） |
| Client        | 600 次/分钟              |
| Client + User | 10 次/分钟               |

成功创建导出会消耗服务端恢复、打包和上传资源。即使未达到限流，也应避免为同一项目并发创建多个导出。

## 常见错误

错误响应使用 `application/problem+json`。

| HTTP 状态 | 常见原因                            | 建议处理                     |
| :------ | :------------------------------ | :----------------------- |
| `400`   | `project_id` 不符合要求              | 检查项目标识                   |
| `401`   | Access Token 或 API Key 缺失、失效或过期 | 更新凭证后重试                  |
| `403`   | 缺少 `source.read`，或当前套餐没有源码下载权益  | 检查授权 Scope 和套餐权益         |
| `404`   | 项目不存在、当前用户无权访问，或项目不可操作          | 检查项目与成员权限；不要持续重试         |
| `429`   | 创建频率超过限制                        | 按 `Retry-After` 等待后重试    |
| `500`   | 恢复、打包或上传失败                      | 保留 `trace_id`，使用退避策略有限重试 |
| `503`   | 源码下载权益校验服务暂不可用                  | 稍后重试                     |

错误示例：

```text theme={null}
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "当前套餐不支持源码下载",
  "code": "forbidden",
  "trace_id": "01JEXAMPLETRACEID"
}
```

反馈问题时请提供请求时间、项目 `url_id`、HTTP 状态码和 `trace_id`，不要提供 Access Token、API Key 或完整 `download_url`。