#project 前端进度对齐接口调整 (2026-07-07)

#Project 整体流程

1. user 创建 project：通过 POST /api/projects/create 发布企划。projects.status 默认为 open，color_mode 是单选字符串，prod_format 是数组，right_template_id 关联权利模板树。
2. content 端浏览 project：公开列表和详情只展示可公开且 status=open 的企划；close、私密或归档的企划不进入公开发现流。
3. artist 应征 project：通过 artist project request 接口提交报价、币种、工期、修改次数、展示可见性、是否自动接受以及作品快照。应征单初始为 pending，同一 artist 存在 pending 或 user_chosen 应征时不能重复应征同一个 project。
4. user 查看应征列表：requested_list 返回公开、隐藏、已选等筛选数据和数量，并带 artist/user 展示信息。
5. user 选择 artist 应征：POST /api/project_requests/choose 以 project_request_id 为准创建 work task。第一次选择会把应征状态从 pending 改为 user_chosen；之后仍保持 user_chosen。同一个 project 或同一个 project request 可以创建多个 active work task。
6. work task 金额和币种：remuneration 只作为本次新建 work task 的最终成交价；不传时使用 project_requests.budget。work task 币种固定使用 project_requests.currency_id，也就是 artist 应征时选择的收款币种。
7. artist 处理 work task：如果应征 auto_accept=true，选择后 work task 直接进入 wait_pay；否则进入 pending，由 artist 调用 work task accept/reject。artist 拒绝某个 work task 只影响该 work task，不会把 project_requests.status 回退为 pending。
8. 后续履约：project 来源 work task 进入现有支付、制作、交付、评价流程。project 本身不是支付对象，支付和履约状态以 work task 为准。
9. user 关闭 project：project 状态切为 close 后，公开列表不再展示，并阻止新的应征；已有 project request 和 work task 继续保留原有流程状态。

#关键字段速查

#接口变更

#content

• POST /api/content/projects/list
  • 功能：获取公开 project 列表。
  • 变更：确认支持前端最新列表筛选参数：keyword、category_ids、art_style_ids、user_cname、price_currency_id、price_from、price_to、order_by。
  • 变更：补齐 feature/project_add_right_template 的返回结构，列表项会返回 right_template，并在 right_template.right_tree 中展开权益树；内部 pivot 字段 right_pivots、rights 不返回。
  • 变更：仅返回 status=open 的 project，status=close 的 project 不进入公开列表。
• GET /api/content/projects/filters
  • 功能：获取 project 列表筛选元数据。
  • 变更：返回 categories 和 art_styles。
• GET /api/content/projects/info
  • 功能：获取公开 project 详情。
  • 变更：仅允许访问 status=open 的公开 project；status=close 会按不存在处理。
  • 变更：project_requests 不返回 visibility=hidden_all 的应征；新增 hidden_project_requests_count 统计完全隐藏的应征数量。visibility=hidden_offer 的应征仍会返回，由前端隐藏报价和周期。
  • 变更：新增 requested_artist_ids，用于前端判断当前画师是否已经应征。该字段包含公开可见应征画师；如果当前登录画师有 hidden_all 应征，也会包含当前画师自己的 artist_id，但不会泄露其他隐身画师。
  • 变更：发布人 user 新增 commissioned_work_tasks_count，用于展示 user 下单数量；应征画师 project_requests[].artist 新增 completed_work_tasks_count，用于展示画师完稿数量。
  • 变更：应征画师 project_requests[].artist 补充 languages，包含语言基础信息和 pivot.fluency。

#user

• POST /api/projects/list
  • 功能：获取当前用户自己的 project 列表。
  • 变更：列表项补齐 right_template.right_tree，结构与 content/projects/list 一致。
  • 变更：列表项返回 project_requests_count、chosen_project_requests_count、created_commissions_count。
  • 变更：列表项返回 project_requests 应征预览，包含应征画师 artist.avatar，用于用户中心 project 列表展示头像。
  • 变更：列表项返回 chosen_project_requests 和 work_tasks 预览，用于展示选定画师和已达成约稿。
• POST /api/project_requests/choose
  • 功能：project 发布者选择某个 artist 应征并创建 work task。
  • 变更：新增可选参数 remuneration。传入时只作为本次新建 work task 的 price 和阶段金额计算基础，不覆盖 project_requests.budget。
  • 变更：不传 remuneration 时，使用 artist 应征时提交的 project_requests.budget 创建 work task。
  • 变更：work task 的 currency_id 固定使用 project_requests.currency_id，也就是 artist 应征时选择的收款币种。
  • 变更：同一个 project 或同一个 project request 可以创建多个 active work task。
  • 变更：选择时会生成 project_snap，并把 project 快照写入 work_tasks.busable_snap，把 project request 快照写入 work_tasks.reqable_snap。
  • 变更：如果应征记录 auto_accept=true，新建 work task 状态直接为 wait_pay；否则仍为 pending。
• POST /api/project_requests/requested_list
  • 功能：获取当前用户 project 的应征列表。
  • 变更：返回的 artist 补充 languages；应征对象可返回 day_start、day_end、revision、visibility、auto_accept。
  • 变更：返回的 artist 补充 completed_work_tasks_count，用于 user project 详情页展示应征画师完稿数量。
  • 变更：新增 filter 参数，支持 all / public / hidden / selected。
  • 变更：新增 order_by 参数，支持 latest / lower_price / artist_commission。
  • 变更：响应新增 counts，返回 all、public、hidden、selected 四类数量。
• POST /api/project_requests/choosed_list
  • 功能：获取当前用户 project 已选中的应征列表。
  • 变更：返回的 artist 补充 languages；应征对象可返回 day_start、day_end、revision、visibility、auto_accept。
  • 变更：返回的 artist 补充 completed_work_tasks_count，用于 user project 详情页展示已选画师完稿数量。
• POST /api/projects/update_status
  • 功能：project 发布者切换 project 开启/关闭状态。
  • 变更：新增接口，支持把当前用户自己的 project status 切换为 open 或 close。
• POST /api/work_tasks/list
  • 功能：获取当前用户 work task 列表。
  • 变更：project 来源 work task 的 reqable 会加载 project_snap、currency、artworks.uploadImage、artworks.uploadVideo。
• GET /api/work_tasks/info
  • 功能：获取当前用户 work task 详情。
  • 变更：project 来源 work task 的 reqable 会加载 project_snap、currency、artworks.uploadImage、artworks.uploadVideo。

#artist_center

• POST /api/artist_center/project_request/create
  • 功能：artist 对 project 发起应征。
  • 变更：对齐前端最新应征表单，新增 day_start、day_end、revision、visibility、auto_accept；artworks 最多支持 6 个。
  • 兼容：旧字段 is_anonymous 仍可作为入参兼容，但已废弃；新前端应改用 visibility。
  • 兼容：仍支持旧参数 days_need。如果未传 days_need，后端会根据 day_start 与 day_end 计算 days_need。
• POST /api/artist_center/project_request/update
  • 功能：artist 编辑自己的 project 应征。
  • 变更：新增接口。仅允许编辑 status=pending 的应征。
  • 支持字段：currency_id、detail、artworks、budget、days_need、day_start、day_end、revision、visibility、is_anonymous、auto_accept。
• POST /api/artist_center/project_request/cancel
  • 功能：artist 撤回应征。
  • 变更：仅允许撤回 status=pending 的应征；撤回后状态为 artist_canceled。
• POST /api/artist_center/project_request/list
  • 功能：artist 获取自己的 project 应征列表。
  • 变更：应征对象可返回 day_start、day_end、revision、visibility、auto_accept，并加载应征作品的图片/视频信息。
  • 变更：返回 user，字段口径与 content project 详情中的发布人一致，包含 avatar、language、languages、commissioned_work_tasks_count、rating_score、rec_reviews_count。
  • 变更：返回 work_tasks，包含 currency、work_task_stages、paying_order。
• POST /api/artist_center/project_request/list_by_chosen
  • 功能：artist 获取自己已被选中的 project 应征列表。
  • 变更：应征对象可返回 day_start、day_end、revision、visibility、auto_accept，并加载应征作品的图片/视频信息。
  • 变更：返回 user，字段口径与 content project 详情中的发布人一致，包含 avatar、language、languages、commissioned_work_tasks_count、rating_score、rec_reviews_count。
  • 变更：返回 work_tasks，包含 currency、work_task_stages、paying_order。
• POST /api/artist_center/work_tasks/list
  • 功能：artist 获取自己的 work task 列表。
  • 变更：project 来源 work task 的 reqable 会加载 project_snap、currency、artworks.uploadImage、artworks.uploadVideo。
• GET /api/artist_center/work_tasks/info
  • 功能：artist 获取自己的 work task 详情。
  • 变更：project 来源 work task 的 reqable 会加载 project_snap、currency、artworks.uploadImage、artworks.uploadVideo。
• POST /api/artist_center/work_tasks/accept
  • 变更：artist 接受 project 来源 pending work task 后，work task 进入 wait_pay；通知 meta 包含 project_id、project_request_id、work_task_id。
• POST /api/artist_center/work_tasks/reject
  • 变更：artist 拒绝 project 来源 pending work task 时，只把当前 work task 标记为拒绝，不再把 project_requests.status 回退为 pending；通知 meta 包含 project_id、project_request_id、work_task_id。
• POST /api/artist_center/user_rec_reviews/create_work_task_review
  • 功能：artist 对 work task 中的 user 发起评价。
  • 变更：type 仅支持 service、project；project 来源 work task 的评价会关联 project_snap。

#接口示例

#content

#POST /api/content/projects/list

• 功能说明：获取公开 project 列表。
• 变更说明：确认支持前端最新筛选和排序参数。

#请求参数

#请求示例

{
  "keyword": "portrait",
  "category_ids": [12],
  "art_style_ids": [5],
  "price_currency_id": 1,
  "price_from": 10000,
  "price_to": 30000,
  "order_by": "most_applicants",
  "page": 1,
  "size": 15
}

#响应示例

{
  "data": [
    {
      "id": 101,
      "price_start": 10000,
      "price_end": 30000,
      "right_template": {
        "id": 8,
        "name": {
          "en": "Personal"
        },
        "right_tree": [
          {
            "id": 1,
            "name": {
              "en": "Personal Use"
            },
            "state": 1,
            "children": []
          }
        ]
      },
      "project_requests_count": 2
    }
  ],
  "total": 1
}

#错误响应

422：参数校验失败。

#返回字段补充

• right_template：project 绑定的权益模板。
• right_template.right_tree：按权益层级展开的树，每个节点包含该模板中的 state。
• right_template.right_pivots / right_template.rights：内部关系字段，不在响应中返回。

#GET /api/content/projects/filters

• 功能说明：获取 project 列表筛选项。
• 变更说明：返回分类树和画风树。

#请求参数

无。

#响应示例

{
  "data": {
    "categories": [],
    "art_styles": []
  }
}

#错误响应

无新增，沿用原有错误语义。

#GET /api/content/projects/info

• 功能说明：获取公开 project 详情。
• 变更说明：完全隐藏应征不进入 project_requests；公开但隐藏报价的应征仍返回。

#请求参数

#响应示例

{
  "data": {
    "id": 101,
    "project_requests": [
      {
        "id": 201,
        "artist": {
          "id": 301,
          "name": "Artist",
          "completed_work_tasks_count": 12,
          "languages": [
            {
              "id": 1,
              "name": "English",
              "code": "en",
              "is_main": true,
              "pivot": {
                "artist_id": 301,
                "language_id": 1,
                "fluency": "native"
              }
            }
          ]
        },
        "budget": 12000,
        "days_need": 5,
        "day_start": "2026-08-01 00:00:00",
        "day_end": "2026-08-06 00:00:00",
        "revision": "2",
        "visibility": "hidden_offer",
        "auto_accept": true
      }
    ],
    "requested_artist_ids": [301],
    "user": {
      "id": 401,
      "name": "Project Owner",
      "commissioned_work_tasks_count": 8
    },
    "hidden_project_requests_count": 1
  }
}

#错误响应

404：project 不存在或不是公开 project。

{
  "message": "Project not found"
}

status=close 的 project 也会返回 404。

#user

#POST /api/projects/list

• 功能说明：获取当前登录用户自己的 project 列表。
• 变更说明：对齐用户中心 project 列表卡片，补齐权益树、应征头像、选中应征和已创建约稿摘要。

#请求参数

#响应字段补充

#响应片段

{
  "data": [
    {
      "id": 101,
      "project_requests_count": 3,
      "chosen_project_requests_count": 1,
      "created_commissions_count": 1,
      "right_template": {
        "id": 8,
        "right_tree": []
      },
      "project_requests": [
        {
          "id": 201,
          "artist": {
            "id": 301,
            "avatar": {
              "url_sm": "https://example.test/avatar.jpg"
            }
          }
        }
      ],
      "chosen_project_requests": [],
      "work_tasks": []
    }
  ],
  "total": 1
}

#POST /api/project_requests/choose

• 功能说明：project 发布者选择某个应征并创建 work task。
• 变更说明：新增 remuneration；创建 project snap；根据 auto_accept 决定 work task 初始状态。
• 金额说明：remuneration 只影响本次新建 work task 的 price 和阶段金额；不会覆盖 project_requests.budget。不传时使用 project_requests.budget。
• 币种说明：project 来源 work task 的 currency_id 固定使用 project_requests.currency_id，前端不需要也不应该按 user 币种换算。
• 数量说明：同一个 project 或同一个 project request 可以重复创建多个 active work task。

#请求参数

#请求示例

{
  "project_request_id": 201,
  "deadline": "2026-08-20 23:59:59",
  "remuneration": 21000,
  "name": {
    "en": "Chosen project task",
    "_lang": "en"
  }
}

#响应示例

{
  "ok": true
}

#数据写入说明

• 若传入 remuneration，后端会写入：
  • work_tasks.price = remuneration
  • work_task_stages.amount 按 remuneration 分阶段计算
• 若不传 remuneration，后端使用 project_requests.budget 创建 work task。
• 不会更新 project_requests.budget；该字段始终表示 artist 应征时提交的原始报价。
• work_tasks.currency_id 使用 project_requests.currency_id。
• 第一次选择会把 project_requests.status 从 pending 更新为 user_chosen；重复创建 work task 时保持 user_chosen。
• 同一个 project 或同一个 project request 允许存在多个 active work task。
• 创建 project_snaps 记录：
  • snap_type = "project_request"
  • snap_id = project_request_id
  • data 保存 project 快照，并包含应征时的 artworks 快照
• work_tasks.busable_snap 保存 project 快照。
• work_tasks.reqable_snap 保存 project request 快照。
• 如果该应征 auto_accept=true，新 work task 状态为 wait_pay；否则为 pending。

#错误响应

404：应征不存在或不属于当前用户。

{
  "message": "Not found."
}

422：参数校验失败。

#POST /api/project_requests/requested_list

• 功能说明：获取当前用户某个 project 的应征列表。
• 变更说明：支持前端详情页公开/隐藏/选中筛选、数量统计和排序。

#请求参数

#响应字段补充

#排序说明

#响应片段

{
  "data": [
    {
      "id": 201,
      "visibility": "hidden_offer",
      "artist": {
        "id": 301,
        "completed_work_tasks_count": 12,
        "languages": []
      }
    }
  ],
  "total": 1,
  "counts": {
    "all": 3,
    "public": 2,
    "hidden": 1,
    "selected": 1
  }
}

#POST /api/work_tasks/list

• 功能说明：获取当前用户 work task 列表。
• 变更说明：project 来源 work task 的 reqable 会返回 project_snap。

#响应片段

{
  "data": [
    {
      "id": 301,
      "busable_type": "project",
      "reqable": {
        "id": 201,
        "project_snap": {
          "data": {
            "id": 101,
            "name": {
              "en": "Frontend Project"
            },
            "artworks": [
              {
                "id": 501,
                "upload_image": null,
                "upload_video": null
              }
            ]
          }
        },
        "currency": {
          "id": 1,
          "code": "USD"
        },
        "artworks": []
      }
    }
  ],
  "total": 1
}

#错误响应

无新增，沿用原有错误语义。

#POST /api/projects/update_status

• 功能说明：project 发布者切换企划开启/关闭状态。
• 变更说明：新增接口。close 后该 project 不再进入 POST /api/content/projects/list，公开 GET /api/content/projects/info 也会按不存在处理。

#请求参数

#请求示例

{
  "id": 101,
  "status": "close"
}

#响应示例

{
  "ok": true,
  "data": {
    "id": 101,
    "status": "close"
  }
}

#错误响应

403：project 不属于当前用户。

422：status 不是 open / close。

#GET /api/work_tasks/info

• 功能说明：获取当前用户 work task 详情。
• 变更说明：返回字段与 POST /api/work_tasks/list 一致，project 来源 work task 的 reqable 会加载 project_snap。

#错误响应

无新增，沿用原有错误语义。

#artist_center

#POST /api/artist_center/project_request/create

• 功能说明：artist 对 project 发起应征。
• 变更说明：对齐前端最新应征表单。

#请求参数

#其他校验规则

• days_need 和 day_start/day_end 至少提供一组。
• 未传 days_need 时，后端按 day_start 到 day_end 的天数计算并写入 days_need。
• visibility=public 表示公开应征。
• visibility=hidden_offer 表示公开应征卡片，但隐藏报价和周期。
• visibility=hidden_all 表示完全隐藏应征，不出现在公开详情 project_requests 中。

#请求示例

{
  "project_id": 101,
  "currency_id": 1,
  "detail": {
    "en": "I can handle this project.",
    "_lang": "en"
  },
  "artworks": [501, 502, 503],
  "budget": 12000,
  "day_start": "2026-08-01 00:00:00",
  "day_end": "2026-08-06 00:00:00",
  "revision": "2",
  "visibility": "hidden_offer",
  "auto_accept": true
}

#响应示例

{
  "ok": true,
  "data": {
    "id": 201,
    "project_id": 101,
    "budget": 12000,
    "days_need": 5,
    "day_start": "2026-08-01 00:00:00",
    "day_end": "2026-08-06 00:00:00",
    "revision": "2",
    "visibility": "hidden_offer",
    "is_anonymous": "hidden_offer",
    "auto_accept": true,
    "status": "pending"
  }
}

#错误响应

400：不能应征自己的 project，或已存在 active 应征。

{
  "message": "Can not request your own project."
}

422：参数校验失败，或未提供 days_need / day_start + day_end。

{
  "message": "days_need or day_start/day_end is required."
}

#POST /api/artist_center/project_request/update

• 功能说明：artist 编辑自己的 project 应征。
• 变更说明：仅允许编辑 status=pending 的应征。

#请求参数

#响应示例

{
  "ok": true,
  "data": {
    "id": 201,
    "budget": 18000,
    "days_need": 3,
    "visibility": "hidden_all",
    "auto_accept": true
  }
}

#错误响应

400：应征不是 pending，不能编辑。

{
  "message": "Only pending project request can be updated."
}

#POST /api/artist_center/project_request/cancel

• 功能说明：artist 撤回自己的 project 应征。
• 变更说明：仅允许撤回 status=pending 的应征，撤回后状态为 artist_canceled。

#请求参数

#响应示例

{
  "ok": true
}

#错误响应

400：应征不是 pending，不能撤回。

{
  "message": "Only pending project request can be canceled."
}

#POST /api/artist_center/work_tasks/list

• 功能说明：artist 获取自己的 work task 列表。
• 变更说明：project 来源 work task 的 reqable 会返回 project_snap。

#响应字段

与 user 侧 POST /api/work_tasks/list 的 project 来源 work task 返回结构一致。

#错误响应

无新增，沿用原有错误语义。

#GET /api/artist_center/work_tasks/info

• 功能说明：artist 获取自己的 work task 详情。
• 变更说明：project 来源 work task 的 reqable 会返回 project_snap。

#错误响应

无新增，沿用原有错误语义。

#POST /api/artist_center/user_rec_reviews/create_work_task_review

• 功能说明：artist 对 work task 中的 user 发起评价。
• 变更说明：type 只接受真实业务类型 service / project；project 来源 work task 会关联 project_snap。

#请求参数

#错误响应

400：type 与 work task 业务类型不一致。

{
  "message": "Review type mismatch"
}

#数据结构说明

#visibility

is_anonymous 是废弃兼容字段：旧客户端传 hidden_offer / hidden_all 时，后端会写入同名 visibility 值；响应中暂时保留 is_anonymous 作为别名，visibility=public 时该别名为 null。

#remuneration

remuneration 表示本次创建 work task 的最终成交稿酬。它是 work task 级字段，不是 project request 级字段。

写入链路：

remuneration -> work_tasks.price -> work_task_stages.amount

remuneration 不会写回 project_requests.budget。project_requests.budget 始终保持 artist 应征时提交的原始报价。

如果不传 remuneration，后端使用 project_requests.budget 作为新 work task 的 price。

币种固定使用 project_requests.currency_id，即 artist 应征时选择的收款币种。

#ProjectSnap /project_snaps

• project_snaps 是数据库表，用于保存 project 相关业务快照。
• ProjectSnap 是 Laravel Eloquent 模型，对应 project_snaps 表。
• project_snap 是 morphMap 类型名，会写入 bizable_type 等多态字段。

project 应征被选定时会创建或更新一条快照：

注意：project_snap 按 project request 维护；如果需要某个 work task 创建时的独立快照，应读取 work_tasks.busable_snap / work_tasks.reqable_snap。

#前端展示统计字段

#应征画师语言字段

#project status

#兼容性说明

• POST /api/artist_center/project_request/create 仍兼容旧字段 days_need。
• 新前端推荐使用 day_start、day_end、revision、auto_accept、visibility。
• is_anonymous 已废弃，不再作为数据表字段保存；新前端不要继续按 boolean 或主字段使用它。
• hidden_offer 与 hidden_all 的展示语义不同，前端不能再只按 boolean 判断。
• POST /api/project_requests/choose 不传 remuneration 时使用应征原 budget；传入 remuneration 也只影响新建 work task，不覆盖应征原 budget。