> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acturehub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 服务商管理

> 维护服务商档案、成员、服务、评价、资料文件与上架状态。

服务商页面路径为 `/ecosystem/providers`；平台管理员使用 `/admin/ecosystem/providers`。服务商与生态对接共用租户边界，生态需求可继续通过兼容的 `partner_id` 关联服务商主档。

## 页面能力

* 查询区默认展示服务商名称、服务商类型和入驻时间区间；展开后补充联系人和联系人手机号，并按三列栅格对齐。
* 查询条件内的输入框支持按回车提交，与点击“查询”按钮使用同一组条件。
* 服务商列表支持导出当前筛选范围内的全部记录，导出不受当前分页限制。
* 新增企业基本信息、联系人、核心成员、荣誉证书和资质文件。
* 从列表或详情进入编辑，修改企业资料、联系人、核心成员，并继续补充荣誉与资质文件。
* 在固定尺寸详情弹窗中查看企业资料、成员、服务、客户评价和文件；荣誉证书与资质文件分组展示并分别计数。
* 联系人手机默认脱敏，用户主动点击后显示完整号码。
* 上架或下架前进行二次确认，状态保存到数据库。

服务商编号由后端生成，格式类似 `SP-202610-A1B2C3D4`；来源默认取当前租户名称，入驻时间默认取创建日期。

## 接口合同

| 方法 | 路径 | 用途 |
| - | - | - |
| `GET` | `/api/ecosystem/providers` | 分页筛选服务商 |
| `GET` | `/api/ecosystem/providers/export` | 按租户与筛选条件导出服务商 CSV |
| `POST` | `/api/ecosystem/providers` | 新增服务商 |
| `GET` | `/api/ecosystem/providers/{provider_id}` | 查看完整服务商档案 |
| `PATCH` | `/api/ecosystem/providers/{provider_id}` | 修改企业与联系人资料 |
| `PATCH` | `/api/ecosystem/providers/{provider_id}/listing-status` | 上架或下架 |
| `PUT` | `/api/ecosystem/providers/{provider_id}/members` | 整体更新核心成员 |
| `PUT` | `/api/ecosystem/providers/{provider_id}/service-offerings` | 整体更新服务项目 |
| `PUT` | `/api/ecosystem/providers/{provider_id}/reviews` | 整体更新客户评价 |
| `POST` | `/api/ecosystem/providers/{provider_id}/documents` | 上传荣誉或资质文件 |
| `GET` | `/api/ecosystem/providers/{provider_id}/documents/{document_id}/content` | 下载或预览文件 |

页面查询使用 `name`、`provider_type`、`joined_from`、`joined_to`、`contact`、`phone`、`page` 和 `page_size`。接口仍支持 `listing_status`，供其他调用方按上架状态筛选；平台管理员可额外传 `tenant_id`。

导出接口复用相同筛选参数和租户权限，返回带 UTF-8 BOM 的 CSV，可直接用 Excel 打开。文件包含企业资料、上下架状态以及荣誉、资质、成员、服务和评价数量；用户输入文本会进行电子表格公式注入防护。

## 新增服务商

```bash theme={null}
curl -X POST 'http://127.0.0.1:8000/api/ecosystem/providers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "示例知识产权服务商",
    "provider_type": "intellectual",
    "contact_person": "李经理",
    "phone": "13800000000",
    "office_address": "上海市浦东新区",
    "members": [
      {"name": "陈顾问", "description": "负责专利布局"}
    ]
  }'
```

## 上架状态

```bash theme={null}
curl -X PATCH 'http://127.0.0.1:8000/api/ecosystem/providers/<PROVIDER_ID>/listing-status' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"listing_status": "listed"}'
```

状态只接受 `listed` 或 `unlisted`。普通租户成员只能读取；租户管理员和平台管理员可以写入。

## 文件上传

文件上传使用 `multipart/form-data`。`category` 为 `honor` 或 `qualification`，单文件最大 10 MB，支持 PDF、PNG、JPG、JPEG 和 WebP。下载接口会重新校验 JWT 和租户范围，不返回可跨租户复用的公开文件地址。

详情中的文件预览同时展示资料类别、资料编号、来源单位和上传时间。核心成员、已上架服务与 C 端用户评价页签均显示对应小节标题和记录数量。

前端在选择文件时先校验扩展名和大小，并支持在一次选择中加入多个文件。新增服务商后如果个别文件上传失败，服务商主档仍保留，页面会明确提示失败数量；用户可从“编辑 / 上传资料”重新选择失败文件。编辑时上传失败的文件会保留在表单中，可直接重试。

页面会逐个提交同一批文件；接口同时使用服务商记录行锁串行追加文档元数据。因此多个浏览器或调用方并发上传时，后提交的文件不会覆盖先提交的文件。每个文件仍使用一次独立的 `POST` 请求，调用方可以按文件记录成功或失败并只重试失败项。

```bash theme={null}
curl -X POST 'http://127.0.0.1:8000/api/ecosystem/providers/<PROVIDER_ID>/documents?category=qualification' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -F 'file=@./qualification.pdf'
```

服务项目价格按“分”存储。固定价使用 `price_type=fixed`；区间价使用 `price_type=range`，并保证 `price_max` 不小于 `price_min`。客户评价等级为 `excellent`、`good` 或 `poor`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.