API 参考 / attachments

上传附件（multipart）

POST /api/v1/attachments · uploadAttachment

multipart/form-data 上传单个文件并关联到目标对象。表单字段：file（文件本体）、 targetType、targetId。存储 key 由服务端生成，原始文件名仅作展示元数据（防路径穿越）。 强制单文件大小上限与 MIME/扩展白名单，超限或非法类型返回 422/413。 targetType 只接受白名单内的值（requirement / work_item / bug / milestone / document / comment）， 其余返回 422：未知类型既落不到任何读侧列表（永久孤儿附件），鉴权也无从对应到真实对象模块。 targetType 归一（B-00065）：缺陷就是 type=bug 的工作项，故 targetType=work_item 但 targetId 指向缺陷时，服务端落库与响应一律归一成 bug（否则这条附件挂在读侧永远不查的组合上、 永久不可见）；归一后按「缺陷·QA」模块 edit 重新鉴权，只有「子任务」权限不足以往缺陷传附件。 非缺陷工作项（task / dev / qa）的 work_item 不受影响。 评论附件（B-00080）：targetType=comment、targetId=评论 uuid。权限与附件的通例一致 「随目标对象走」——评论的写权限是 view_project（低门槛协作动作，不占 manage_*、也不走五模块闸）， 故评论附件要求 view_project 而不是宿主对象的模块 edit：能在缺陷下发评论的人就该能给自己的 评论贴截图。目标评论必须存在，不存在返回 404（挂在幽灵评论上的附件是永久不可见的孤儿）。 调用顺序：先 POST /comments 拿到评论 id，再用该 id 逐个上传附件（评论创建与附件上传是两次请求， 没有「随评论一起提交附件」的复合端点）。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

Idempotency-Key
string —— 幂等键（建议用 UUID，最长 255 字符）。重复提交同键且请求体一致时返回首次创建的结果（200）而不新建对象；请求体不一致返回 409。有效期 24 小时。

请求体

file（必填）
file
targetType（必填）
enum；取值：requirement / work_item / bug / milestone / document / comment
targetId（必填）
string

响应字段 · 201

id（必填）
string
targetType（必填）
enum；取值：requirement / work_item / bug / milestone / document / comment
targetId（必填）
string
fileName（必填）
string
size（必填）
integer
mimeType（必填）
string
uploaderId（必填）
string
createdAt（必填）
string

响应字段 · 200

id（必填）
string
targetType（必填）
enum；取值：requirement / work_item / bug / milestone / document / comment
targetId（必填）
string
fileName（必填）
string
size（必填）
integer
mimeType（必填）
string
uploaderId（必填）
string
createdAt（必填）
string

错误

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/attachments" \
  -H "Authorization: Bearer wfp_…" \
  -F "file=@截图.png" \
  -F "targetType=requirement" \
  -F "targetId=018f3c2e-0000-7000-8000-000000000000"

响应示例

HTTP/1.1 201
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "targetType": "requirement",
  "targetId": "018f3c2e-0000-7000-8000-000000000000",
  "fileName": "示例标题",
  "size": 1,
  "mimeType": "示例文本",
  "uploaderId": "018f3c2e-0000-7000-8000-000000000000",
  "createdAt": "示例文本"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…