# 创作者投稿接口

文档公开，无需登录。可阅读[网页版](https://financestar.cn/creators/api)，或把 [Markdown 原文链接](https://financestar.cn/creators/api.md)发给 AI。实际上传、投稿和查询本人稿件仍须提供有效的创作者接口令牌。

接口基址为 `https://financestar.cn`，使用标准 HTTPS、JSON 与 multipart 上传，可由 curl、脚本或任何 HTTP 客户端调用，不依赖 Git 或特定模型。下面的编号、文件名和内容都是脱敏示例。

## 入驻与权限

先在网站完成登录，在“创作者后台 → 资料与收款”完成两步入驻。个人第一步填写真实姓名、身份证号并单独授权，腾讯云二要素一致后才进入第二步公开资料与收款资料填写；刷新后重新输入相同资料可幂等匹配已有成功记录。企业选择主体后填写资料，由管理员人工核对，不调用个人接口。个人首次建档必须已有匹配的成功核验，未核验或主体未确认时管理员不能批准。活动期间免收平台服务费，创作者按订单成交金额的 100% 计算分成；非活动期间平台服务费默认 5%，实际以审核批准时的费率为准。付费销售是否开放以工作台和资源详情为准，不能通过接口绕过开放状态。

活动覆盖新订单，以及活动前生成、在活动期间首次成功支付入账的待支付订单。已支付订单、原有账本与结算不因活动切换重算，退款按原订单冻结分成扣回；活动结束不追补已享免服务费订单的服务费。资料接口保留 `creator.commissionBps` 作为非活动期约定费率，以 `capabilities.platformFeeWaived` 表示当前是否免收。

入驻后从网站用户菜单进入“创作者后台”，在侧栏的“接口令牌”中创建或撤销自己的令牌。每位创作者最多保留 5 个有效令牌，有效期 90 天。完整令牌只在创建时显示一次；请存入本地环境变量或密钥管理工具，不要放进源码、公开日志或投稿包。平台管理员负责入驻、投稿审核与风险处置。

请求使用 `Authorization: Bearer <你的令牌>`。以下示例从环境变量 `FSC_TOKEN` 读取令牌；请通过你所用终端的安全输入方式设置该变量，不要把真实令牌写进命令文件。令牌撤销、过期或创作者停用后，请求会被拒绝。

令牌允许已具备投稿资格的创作者上传自己的文件、保存/修改自己的草稿、提交检查、查询自己的投稿和下载自己的原包。个人创作者必须先在网站完成当前姓名和身份证号对应的实名核验，令牌不能代替实名、修改入驻/收款资料、管理令牌、确认结算、访问后台或直接批准发布。姓名或身份证号变更后须重新核验。账户、财务、实名和后台操作必须在网站登录后完成。

## 1. 上传交付文件

`POST /api/creator/assets`，使用 multipart 的 `file` 字段。不要手动设置 multipart 的 Content-Type，客户端应自动携带 boundary。

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FSC_TOKEN" \
  -F "file=@./example-project.zip" \
  https://financestar.cn/api/creator/assets
```

支持 `.zip`、`.md`、`.txt`、`.json`、`.yaml`、`.yml`，单文件最多 50MB。ZIP 仅接受可完整审查的 UTF-8 文本源码，最多 2000 个文件，完整文本总量不超过 2MiB。嵌套归档、二进制/可执行文件、密钥和不能完整审查的内容会被拒绝。请移除 `.git`、`node_modules`、构建产物、环境变量和真实业务数据。

每位创作者当前总容量上限 500MB，最多 1000 个文件；每 24 小时最多上传 200MB、100 个文件。投稿每天最多创建 30 份。被拒绝或失败的上传不应被视为可交付文件。

成功响应为：

```json
{
  "asset": {
    "id": "12345678-1234-4123-8123-123456789abc",
    "name": "example-project.zip",
    "size": 2048,
    "sha256": "示例摘要，实际为64位十六进制",
    "source": { "fileCount": 3, "previewCount": 3 }
  }
}
```

保存 `asset.id`，后续使用 `assetIds` 关联文件。响应不包含存储路径或 COS 凭证。一次投稿最多关联 30 个属于自己的文件。原包可通过 `GET /api/creator/assets/:id/download` 鉴权下载；此接口返回临时下载地址的重定向，不能当作永久公开链接。

## 2. 保存草稿

`POST /api/creator/submissions`，Content-Type 为 `application/json`。将下面内容保存为本地 `submission.json`，把示例 `assetIds` 替换成上传响应中的编号：

```json
{
  "requestKey": "example-project-1.0.0",
  "title": "示例财务分析工具",
  "summary": "用于演示资源交付流程的原创示例项目。",
  "description": "## 项目介绍\n演示财务数据整理与报表输出，适合希望了解分析流程的使用者。\n\n## 使用边界\n演示使用脱敏数据，完整安装与运行步骤随交付文件提供。",
  "category": "PROJECT",
  "coverImage": null,
  "price": 0,
  "version": "1.0.0",
  "releaseNotes": "首次提交。",
  "assetIds": ["12345678-1234-4123-8123-123456789abc"],
  "metadata": {
    "license": "允许购买者内部使用，未经许可不得转售或再分发。",
    "usage": "先阅读 README，配置本地环境后运行演示。",
    "compatibility": "请按实际项目填写操作系统、运行时与依赖要求。",
    "disclosures": "演示无需外部付费服务；正式项目请如实列明额外费用与联网行为。",
    "support": "请按实际情况填写支持渠道、更新范围与期限。"
  }
}
```

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FSC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @submission.json \
  https://financestar.cn/api/creator/submissions
```

响应为 `{ "submission": { ... } }`，其中 `submission.id` 是后续操作使用的稿件编号，状态为 `DRAFT`。

`requestKey` 是 1–80 位字母、数字、点、下划线、冒号或短横线。网络失败后使用相同请求标识与完全相同的内容重试，服务端会返回原草稿；相同标识对应不同内容时返回 409，不会默默覆盖。需要改变已创建的草稿时，应取得稿件编号并使用 PUT。

`category` 支持 `SKILL`、`PROJECT`、`WORKFLOW`、`TEMPLATE`、`OTHER`。价格是元，最多两位小数，`0` 表示免费；付费新购是否可用由服务端配置与创作者审核状态决定。版本号为 1–40 位字母、数字、点、下划线或短横线，并以字母或数字开头。

首版封面 `coverImage` 可留空，或使用平台上传的 `/uploads/` 图片路径；不接受任意外部 HTTPS 图片地址。

元数据字段上限分别为：`license` 1000 字、`usage` 3000 字、`compatibility` 1000 字、`disclosures` 3000 字、`support` 1000 字。草稿可暂时留空，但提交审核及人工批准时五项都必须明确填写授权、使用方法、运行要求、费用披露和支持范围；没有额外费用或不提供支持，也须写明“无”。

标题、简介、项目介绍 `description`、封面及授权、环境、费用和支持范围作为售前信息公开。项目介绍应说明功能、适用人群、场景、效果与限制，便于用户判断是否适合。完整 Skill、提示词和源码应放在交付文件中，请勿粘贴到公开介绍、简介、封面或其他售前信息中。付费资源的安装使用 `metadata.usage`、版本备注和文件正文仅向已购用户及管理员提供；免费资源的使用说明公开，文件仍需登录后访问。

## 3. 修改并提交审核

`PUT /api/creator/submissions/:id` 使用与新建相同的投稿内容字段，但不接受 `requestKey`、`status`、存储路径或审核结果。仅 `DRAFT`、`CHANGES_REQUESTED` 可编辑；请使用保存下来的自己的文件编号。

`POST /api/creator/submissions/:id/submit` 将当前快照排入审核队列：

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FSC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://financestar.cn/api/creator/submissions/$SUBMISSION_ID/submit"
```

提交后稿件被锁定，直接进入 `NEEDS_REVIEW`（待人工审核），不调用 AI 模型。管理员核对原包和交付说明后决定批准、退回修改或拒绝；应用仍会验证文件与提交快照一致。

## 4. 查询审核状态与新版本

- `GET /api/creator/submissions` 返回 `{submissions:[...]}`，当前最多返回最近 100 份投稿。
- `GET /api/creator/submissions/:id` 返回 `{submission:{...}}`，包含安全文件摘要、审核报告和人工意见。
- 按需查询人工审核结果；若轮询，间隔至少 5 秒，状态稳定后停止。无需调用定时任务或自动审核接口。

状态含义：

| 状态 | 含义 | 后续操作 |
| --- | --- | --- |
| `DRAFT` | 草稿 | 可修改、提交 |
| `QUEUED` | 历史待审队列 | 管理员打开审核页后转入人工待审 |
| `SCANNING` | 历史检查中状态 | 管理员打开审核页后转入人工待审 |
| `NEEDS_REVIEW` | 待人工审核 | 等待管理员处理并查看意见 |
| `CHANGES_REQUESTED` | 人工要求修改 | 修改并重新提交 |
| `APPROVED` | 已批准发布 | 创建新版本投稿 |
| `REJECTED` | 此投稿已拒绝 | 查看原因，必要时另建投稿 |

新提交的 `report` 包含 `snapshotHash`、`reviewMode: "MANUAL"`、人工待审摘要和记录时间。批准后的版本快照保留原报告及人工文件校验范围、审核人、意见和时间；历史自动检查记录仅作辅助信息，不再作为 AI 放行门槛。任何报告都不代表运行安全或适用性保证。

提交新版本时，新建稿件并额外传入已发布资源的数字 `resourceId`、新的 `requestKey` 与未使用过的 `version`，关联本次交付文件。不得覆盖已发布版本。新稿待审期间，原批准版本继续交付；风险封禁可能停止相应文件交付。

## 错误与结算边界

失败响应统一为 `{ "error": "中文原因" }`。常见状态：400 输入不合法，401 登录/令牌无效，403 权限或入驻状态不允许，404 记录不存在，409 状态、版本或请求标识冲突，413 内容过大，429 额度限制，503 服务配置不可用。

不要把所有失败当作可重复提交：网络错误可按相同请求标识重试创建；409 应重新查询状态并核对内容；429 应停止上传并等待额度恢复。保留本地原始文件和草稿，避免失败后丢失编辑内容。

结算仅在网站中处理。创作者确认月结单不代表到账；平台须完成人工对账和实际转账后登记唯一付款流水。后台退款登记只记录已在渠道成功完成的退款，不执行渠道退款。API 令牌无法确认月结、变更收款、批准发布或登记付款。