# 文本框任务域 API 参考（Agent）

> 前缀一律 `/api/v1`。成功直接返回业务 JSON；错误为 `{ "code", "message" }`。

## 通用

| 项 | 约定 |
|----|------|
| 成功 | 直接业务 JSON |
| 错误 | `{ "code", "message" }` |
| 认证 | `Authorization: Bearer <jwt>` |
| 分页 | query `page`/`page_size` → `{ items, total, page, page_size }` |
| 任务 id | 路径中为 Sonyflake **字符串** |

### 任务 status（smallint）

| 值 | 含义 |
|----|------|
| 0 | 草稿（如悬赏待托管） |
| 1 | 招募中 / 待接单 |
| 2 | 已选标 |
| 3 | 进行中（已托管） |
| 4 | 待评价（全部验收通过） |
| 5 | 已完成 |
| 6 | 已关闭 |

## 1. 列表查看

### `GET /tasks`（公开）

Query: `page`, `page_size`, `category_id`, `status`, `type_id`（仅 1/2）, `budget_min`, `budget_max`, `keyword`。

行为: 排除 `source=employ`；进行中（status=1）优先，再 `created_at DESC`。

响应 `items[]` 含: `id`(string), `title`, `slug`, `description`, `budget`, `bounty`, `status`, `views`, `delivery_count`, `slot_count`, `category_id`, `created_at`，可选 `bounty_status` / `delivery_deadline` / `source`。

### `GET /tasks/{id}`（可选登录）

详情；带有效 Token 时可能含 `is_favorited`。雇佣任务同样走此路径（`source=employ`）。

### `GET /tasks/my` | `/tasks/my-bids` | `/tasks/my-accepted`（需登录）

我发布的 / 我投标的 / 我中标的。

### `GET /employ`（需登录）

雇佣列表。Query: `role=employer|worker|invited`, `status?`, `page`, `page_size`。

## 2. 创建 / 发布

### `POST /tasks`（需登录，常 201）

```json
{
  "title": "required",
  "category_id": 1,
  "budget": 100,
  "mode": "bid",
  "description": "optional",
  "delivery_deadline": "YYYY-MM-DD",
  "provider_count": 1,
  "skill_ids": [],
  "attachment_uuids": [],
  "pay_type": 1,
  "payment_method": "balance",
  "bounty_mode": "equal",
  "bounty_awards": [{ "winner_count": 1, "amount_per_person": 50 }]
}
```

- `mode`: `bid`（默认，招标）| `bounty`（悬赏）
- 悬赏须 `payment_method`（现仅 `balance`），金额 > 0
- `bounty_mode=custom` 时总金额 = Σ(winner_count × amount_per_person)

### `POST /employ`（需登录，常 201）

```json
{
  "provider_user_uuid": "required",
  "title": "required",
  "description": "required",
  "budget": 100,
  "delivery_deadline": "YYYY-MM-DD",
  "accept_deadline": "YYYY-MM-DD",
  "pay_type": 1
}
```

创建后须先托管，对方方可接单。

## 3. 接单

### `POST /tasks/{id}/bid`（需登录）

```json
{
  "price": 80,
  "description": "方案",
  "delivery_time": 7,
  "writer_intro": "optional",
  "pay_type": 1,
  "attachment_uuids": []
}
```

- 招标: `price` > 0
- 悬赏投稿: `price` 可为 0，`description` 必填
- `delivery_time` 必填 ≥1，最多一位小数

### `POST /employ/{taskId}/accept`（需登录）

仅 `bounty_status=1`（已托管）可接。拒单: `POST /employ/{taskId}/reject`。雇主取消: `POST /employ/{taskId}/cancel`。

## 4. 确认

### 选标 `POST /tasks/{id}/bids/{bidId}/select`（需登录，雇主）

可选 Body: `{ "award_sort_order": 1 }`（悬赏自定义奖项）。

拒标: `POST /tasks/{id}/bids/{bidId}/reject`。

### 交付验收

- 列表/提交: `GET|POST /tasks/{id}/bids/{bidId}/deliveries`
- 通过: `POST /tasks/{id}/bids/{bidId}/deliveries/{deliveryId}/accept`
- 驳回: `POST .../reject` Body `{ "feedback": "required" }`

提交交付 Body 例: `{ "section_index": 1, "content": "...", "attachment_uuids": [] }`。

## 5. 评价

### `POST /tasks/{id}/rate`（需登录）

前置: 任务 `status=4`；仅雇主与中标威客可互评。

```json
{
  "to_uid": 123,
  "comment": "optional",
  "speed_score": 5,
  "quality_score": 5,
  "attitude_score": 5
}
```

分数范围 1–5。双方评完后任务可变为 status=5。

## 相关 Skills

- [/ai/skills/task-list/SKILL.md](/ai/skills/task-list/SKILL.md)
- [/ai/skills/task-publish/SKILL.md](/ai/skills/task-publish/SKILL.md)
- [/ai/skills/task-accept/SKILL.md](/ai/skills/task-accept/SKILL.md)
- [/ai/skills/task-confirm/SKILL.md](/ai/skills/task-confirm/SKILL.md)
- [/ai/skills/task-rate/SKILL.md](/ai/skills/task-rate/SKILL.md)
