fin

docs/api_v2_mission_my_api_2026-07-03.md

@@ -0,0 +1,214 @@
+# GET /api/v2/missions/my/
+
+获取当前登录用户相关的任务列表。
+
+## Authentication
+
+需要 JWT 登录。
+
+Authorization: Bearer <access_token>
+
+当前用户必须绑定 Employee：
+
+request.user.employee 必须存在
+
+## Query Params
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---:|---|---|
+| `limit` | number | 否 | 800 | 分页条数，最大 1000 |
+| `offset` | number | 否 | 0 | 分页偏移 |
+| `created_by_me` | boolean | 否 | false | 是否只返回我创建的任务。`false` 表示不限定创建者，仍返回“我创建或我参与”的任务 |
+| `is_completed` | boolean | 否 | 不限制 | 是否完成 |
+| `is_cancelled` | boolean | 否 | 不限制 | 是否取消 |
+| `is_urgent` | boolean | 否 | 不限制 | 是否紧急 |
+| `created_at_from` | string | 否 | 不限制 | 创建时间开始，支持 `YYYY-MM-DD` 或日期时间 |
+| `created_at_to` | string | 否 | 不限制 | 创建时间结束，支持 `YYYY-MM-DD` 或日期时间；传纯日期时包含整天 |
+
+boolean 参数支持：
+
+true 值：`true` / `1` / `yes` / `y` / `on`
+
+false 值：`false` / `0` / `no` / `n` / `off`
+
+## Filter Logic
+
+接口会根据当前 JWT 用户找到：
+
+current_employee = request.user.employee
+current_merchant = current_employee.merchant
+
+基础范围：
+
+mission.merchant == current_merchant
+
+默认返回“与我相关”的任务，即满足以下任一条件：
+
+mission.creator == current_employee
+或
+mission.participants 包含 current_employee
+
+当 `created_by_me=true` 时，只返回：
+
+mission.creator == current_employee
+
+状态筛选只有在显式传参时才生效：
+
+is_completed=false
+=> 只返回未完成任务
+
+is_cancelled=false
+=> 只返回未取消任务
+
+is_urgent=true
+=> 只返回紧急任务
+
+## Date Filter
+
+created_at_from=2026-07-03
+=> created_at >= 2026-07-03 00:00:00
+
+created_at_to=2026-07-03
+=> created_at < 2026-07-04 00:00:00
+
+如果传日期时间，则按传入的具体时间筛选：
+
+created_at_from=2026-07-03T08:30:00+08:00
+=> created_at >= 2026-07-03 08:30:00+08:00
+
+created_at_to=2026-07-03T18:00:00+08:00
+=> created_at <= 2026-07-03 18:00:00+08:00
+
+## Common Examples
+
+获取我相关的所有任务：
+
+GET /api/v2/missions/my/
+
+获取我相关的未完成、未取消任务：
+
+GET /api/v2/missions/my/?is_completed=false&is_cancelled=false
+
+获取我创建的未完成、未取消任务：
+
+GET /api/v2/missions/my/?created_by_me=true&is_completed=false&is_cancelled=false
+
+获取我相关的紧急任务：
+
+GET /api/v2/missions/my/?is_urgent=true
+
+获取我相关的某天创建的任务：
+
+GET /api/v2/missions/my/?created_at_from=2026-07-03&created_at_to=2026-07-03
+
+分页：
+
+GET /api/v2/missions/my/?limit=20&offset=0
+
+## Response
+
+{
+  "count": 1,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 1,
+      "merchant": 1,
+      "description": "跟进客户问题",
+      "category": 1,
+      "category_name": "通用",
+      "is_urgent": false,
+      "is_completed": false,
+      "is_cancelled": false,
+      "notify_if_unreplied": false,
+      "unreplied_notify_interval_minutes": null,
+      "unreplied_notify_max_count": 5,
+      "unreplied_notify_sent_count": 0,
+      "unreplied_last_notified_at": null,
+      "cancelled_at": null,
+      "creator": {
+        "id": 10,
+        "name": "张三",
+        "merchant_id": 1
+      },
+      "cancelled_by": null,
+      "participants": [
+        {
+          "id": 11,
+          "name": "李四",
+          "merchant_id": 1
+        }
+      ],
+      "content_type": 23,
+      "content_type_label": "printing.printingorder",
+      "content_id": 1001,
+      "extra": {
+        "source": "printing-order"
+      },
+      "has_ending_reply": false,
+      "can_reply": true,
+      "created_at": "2026-07-03T15:40:00+08:00",
+      "updated_at": "2026-07-03T15:40:00+08:00"
+    }
+  ]
+}
+
+## Empty Response
+
+{
+  "count": 0,
+  "next": null,
+  "previous": null,
+  "results": []
+}
+
+## Error Responses
+
+### 未登录
+
+401 Unauthorized
+
+### 当前用户未绑定 Employee
+
+{
+  "non_field_errors": [
+    "当前用户未关联员工"
+  ]
+}
+
+### boolean 参数格式错误
+
+{
+  "is_completed": "必须是布尔值"
+}
+
+或：
+
+{
+  "is_cancelled": "必须是布尔值"
+}
+
+或：
+
+{
+  "is_urgent": "必须是布尔值"
+}
+
+或：
+
+{
+  "created_by_me": "必须是布尔值"
+}
+
+### created_at_from 格式错误
+
+{
+  "created_at_from": "必须是日期或日期时间"
+}
+
+### created_at_to 格式错误
+
+{
+  "created_at_to": "必须是日期或日期时间"
+}