03 — 任务中心开放 API（OAuth2）

第三方在门户「任务中心」创建异步任务、汇报进度、完成 / 失败 / 取消确认。
代码锚点：OpenTaskController、OpenTaskAccessSupport、OpenTask*Request。

基路径：/api/open/tasks
鉴权：Authorization: Bearer {access_token}（OAuth2 opaque Token，非 JWT）。

---

1. 如何拿到 Token

1. 门户管理员为你注册 CONFIDENTIAL Client，绑定 system_code，scopes 至少含：
   • 写：api:write（创建 / 进度 / 完成 / 失败 / 取消确认）
   • 仅查：api:read（详情 / 分页）
2. 走 授权码 流程让门户用户授权（见 04-SSO接入-IdP.md）：
   • GET /oauth2/authorize?...&scope=api:write（或含 api:read）
   • POST /oauth2/token（grant_type=authorization_code）
3. 后续可用 POST /oauth2/refresh 刷新。

未开通 client_credentials。无用户授权则无法调用本开放面。

规则	说明
api:write 蕴含读	持有写 scope 时可调详情 / 分页
system_code	取自 Token 对应 Client 绑定，不信任请求体
归属校验	写操作前按 TaskAccessContext.forApp(systemCode) 校验任务属本应用
禁止混用	本 Token 不能调 /api/system/** 等管理端 API

---

2. 接口清单

方法	路径	scope	说明
POST	/api/open/tasks	api:write	创建任务，立刻出现在 ownerUsername 的任务中心
PATCH	/api/open/tasks/{taskCode}/progress	api:write	汇报进度
POST	/api/open/tasks/{taskCode}/complete	api:write	完成（SUCCESS / PARTIAL）
POST	/api/open/tasks/{taskCode}/fail	api:write	标记失败
POST	/api/open/tasks/{taskCode}/cancelled	api:write	执行方确认已停止（用户请求取消后）
GET	/api/open/tasks/{taskCode}	api:read	详情（含 cancelRequested，供轮询停止意图）
GET	/api/open/tasks	api:read	本应用任务分页（联调/对账）

成功时响应为统一 ApiResult，data 为任务快照（见 §4）或分页结果。

---

3. 请求字段

3.1 创建 — POST /api/open/tasks

字段	必填	说明
title	是	任务标题
bizType	是	业务类型，如 REPORT_EXPORT
category	是	EXPORT / IMPORT / CONVERT / EXECUTE / QUERY / OTHER
ownerUsername	是	归属门户用户登录名（任务出现在其任务中心）
externalRef	否	第三方幂等键
cancellable	否	是否可被用户请求中断
payload	否	入参对象（服务端序列化为 JSON）
payloadJson	否	入参 JSON 字符串；与 payload 二选一，优先 payloadJson
contextJson	否	上下文 JSON
expireAt	否	结果过期时间

createdBy 由服务端写入为 client_id；systemCode 取自 Client 绑定。

3.2 进度 — PATCH /api/open/tasks/{taskCode}/progress

Body（AsyncTaskProgressCommand）：

字段	说明
progressPercent	0–100
totalCount / processedCount / successCount / failCount	计数
message	进度文案

3.3 完成 — POST /api/open/tasks/{taskCode}/complete

字段	必填	说明
status	是	SUCCESS 或 PARTIAL
message	否	摘要
resultJson	否	结果摘要 JSON
actions	否	完成动作列表（见下）
totalCount 等计数 / progressPercent	否	终态计数

actions[]（完成动作）

字段	说明
type	DOWNLOAD / ROUTE / LINK / COPY
label	按钮文案
primary	是否主按钮
fileKey	DOWNLOAD：DFS fileKey（入库）
url	DOWNLOAD/LINK：可访问 URL（出参常由门户填充）
path / name / query	ROUTE
target	LINK 打开方式
text	COPY 文本

3.4 失败 / 取消确认

POST .../fail、POST .../cancelled，可选 body：

字段	说明
message	说明文案；缺省分别为「任务失败」「用户已停止」

协作式取消：cancellable=true 时用户可请求停止；RUNNING 仅置 cancelRequested，执行方安全点调用 cancelled 确认。详见 doc/10-规范定义.md §7.5。

3.5 分页 Query — GET /api/open/tasks

参数	说明
pageNum	从 1，默认 1
pageSize	默认 20，上限 100
category / status / bizType / keyword	筛选
systemCode	查询字段存在；实际列表按 Token Client 绑定应用隔离

---

4. 任务快照（响应 data 要点）

字段	说明
taskCode	任务业务编码（路径参数）
externalRef	第三方幂等键
title / bizType / category	创建时字段
systemCode	来源应用
ownerUsername	归属用户
status	PENDING → RUNNING → SUCCESS / PARTIAL / FAILED / CANCELLED
cancellable / cancelRequested / canCancel	中断协作
progressPercent 与计数、message	进度
payloadJson / contextJson / resultJson / actions	入参与结果
createdBy / createdAt / updatedAt / finishedAt / expireAt	审计与时效

---

5. curl 示例

# 假设已通过授权码换得 ACCESS_TOKEN
curl -sS -X POST "https://portal.example.com/api/open/tasks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "报表导出",
    "bizType": "REPORT_EXPORT",
    "category": "EXPORT",
    "ownerUsername": "admin",
    "externalRef": "job-20260716-001",
    "cancellable": true,
    "payload": {"reportId": "R1"}
  }'

curl -sS -X PATCH "https://portal.example.com/api/open/tasks/{taskCode}/progress" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"progressPercent":40,"message":"处理中"}'

curl -sS "https://portal.example.com/api/open/tasks/{taskCode}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

---

6. 常见错误

code / 现象	含义
缺少 / 无效 access_token	未带 Bearer 或 Token 失效
403 Token 缺少 scope	未申请 api:write / api:read
400 Client 未绑定 system_code	管理端补绑
任务不属于本应用	taskCode 非本 Client 创建 / 归属不对

更多规范见 doc/10 §7.5、doc/07 §4.6。

---

7. 下载 Demo

• Java：/downloads/oauth2-tasks-java.zip
• 说明：sdk/oauth2-tasks-java/README.md