Posts 接口

Posts 使用三层覆盖模型：基础 caption/media → platform_configurations → account_configurations。状态值为 draft、processing、scheduled、 posted、failed。

接口列表

• GET /api/v1/posts — 按平台/状态筛选列表。
• POST /api/v1/posts — 创建帖子（立即发布、定时或草稿）。
• GET /api/v1/posts/{id} — 获取单条帖子。
• PATCH /api/v1/posts/{id} — 更新任意字段或替换媒体/账号。
• DELETE /api/v1/posts/{id} — 删除帖子及其媒体。

通用字段

• caption (string) — 创建必填，更新可选。
• social_accounts (string[]) — 创建必填；来自 Social Accounts 接口。
• scheduled_at (ISO | null) — null 立即发布；未来时间为定时；PATCH 时不传则保持原值。
• is_draft (boolean | null) — true 保持草稿；false 且 scheduled_at 为 null 时立即发布。
• media (string[] | undefined) — Media 接口返回的 ID；在 PATCH 中提供则替换原附件。
• media_urls (string[] | undefined) — 直接的媒体 URL；创建/更新时会转换为媒体记录，替换现有附件。
• platform_configurations (object | null) — 每个平台的覆盖文案/媒体，自由 JSON。
• account_configurations (object | null) — 按账号覆盖，自由 JSON。
• processing_enabled (boolean | null) — 默认 true，设为 false 可跳过内置视频处理。

GET /api/v1/posts

查询参数：

• offset, limit — 见分页约定。
• platform — 平台 ID 数组（twitter-x、instagram、linkedin、facebook-page、tiktok、youtube、bluesky、threads、pinterest）。
• status — posted | scheduled | processing | draft | failed。

响应：

{
  "data": [
    {
      "id": "post-uuid",
      "caption": "caption text",
      "social_accounts": ["acc-1", "acc-2"],
      "scheduled_at": "2025-12-01T10:00:00.000Z",
      "is_draft": false,
      "status": "scheduled",
      "media": ["media-uuid"],
      "platform_configurations": { /* platform overrides */ },
      "account_configurations": { /* account overrides */ },
      "processing_enabled": true
    }
  ],
  "meta": { "offset": 0, "limit": 10, "total": 12 }
}

示例：

curl "https://<host>/api/v1/posts?status=scheduled&platform=linkedin" \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN"

POST /api/v1/posts

示例请求：

{
  "caption": "Launch post",
  "social_accounts": ["acc-123"],
  "scheduled_at": "2025-12-01T10:00:00Z",
  "is_draft": false,
  "media": ["media-uuid"],
  "platform_configurations": {
    "linkedin": { "caption": "LinkedIn copy" }
  },
  "account_configurations": null,
  "processing_enabled": true
}

响应：{ "data": { ...与列表项相同... } }

错误：400（账号 ID 不合法等业务错误），422（模式校验失败）。

GET /api/v1/posts/{id}

路径参数：id。返回与列表项相同的结构。

PATCH /api/v1/posts/{id}

字段均可选；未提供的保持原值。提供 media 或 media_urls 会整体替换附件。 更新 social_accounts 会重建目标列表（移除不存在的，插入新增的）。

状态调整：

• is_draft=true 可回退草稿。
• scheduled_at=null 且 is_draft=false 将立即发布。
• 提供未来的 scheduled_at 可重新排程。

DELETE /api/v1/posts/{id}

删除帖子、解除媒体关联，并删除媒体记录。返回 { "success": true }。

建议

• 发布前确保附件已经 uploaded，否则无法绑定。
• 响应中的 status 映射：publishing/ready → processing，published → posted。
• 重试时自行实现幂等（例如根据 caption + accounts 生成键），避免重复创建。