如何利用文档详情中`module_id`查询该模型下所有可筛选的参数字段？

在安企CMS中，为了更好地组织和展示内容，我们经常会用到文档模型和自定义字段。当您希望为特定模型下的文档提供更灵活的筛选功能时，例如根据某个文档的“城市”或“学历”等属性进行查找，就需要知道如何获取这些可筛选的参数字段。

这通常是一个两步走的过程：首先，我们需要确定目标文档所属的模型ID（module_id），这是连接文档与模型定义的关键；然后，利用这个模型ID来查询该模型下所有可用于筛选的参数字段。

第一步：获取文档所属的模型ID（module_id）

要了解一个具体文档的module_id，我们可以使用“获取文档详情接口”。这个接口能够提供指定文档的所有基本信息，其中就包含了它所关联的模型ID。

您可以通过向 {域名地址}/api/archive/detail 发送一个 GET 请求来调用此接口。在请求时，您需要提供文档的 id（文档ID）或者 filename（文档URL别名）作为参数，两者选其一即可。

例如，如果您想获取 ID 为 1 的文档详情，请求参数会是 id=1。接口返回的数据中，您会发现一个名为 module_id 的字段。这个字段的值（一个整数）就是我们后续查询筛选参数所需的模型ID。它就像是文档的“户口本”，记录着它属于哪个内容类型。

返回数据示例（简化）：

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "欢迎使用AnqiCMS",
    "module_id": 1, // 这就是我们需要的模型ID
    // ... 其他文档详情
  },
  "msg": ""
}

从上面的示例中，我们可以看到 module_id 的值为 1。

第二步：利用module_id查询该模型下所有可筛选的参数字段

一旦我们拿到了 module_id，就可以利用“获取文档参数筛选条件接口”来查询该模型下所有可供筛选的字段及其具体选项。

向 {域名地址}/api/archive/filters 发送一个 GET 请求，并将上一步获取到的 module_id 作为 moduleId 参数传递。

例如，如果您的 module_id 是 1，请求参数会是 moduleId=1。这个接口的响应会非常清晰地列出模型中被设置为可筛选的所有字段。

返回数据示例：

{
  "code": 0,
  "data": [
    {
      "name": "城市",
      "field_name": "city",
      "items": [
        { "label": "全部", "total": 0 },
        { "label": "北京", "total": 0 },
        { "label": "上海", "total": 0 }
      ]
    },
    {
      "name": "学历",
      "field_name": "certificate",
      "items": [
        { "label": "全部", "total": 0 },
        { "label": "硕士", "total": 0 },
        { "label": "本科", "total": 0 }
      ]
    }
  ],
  "msg": ""
}

在这个返回数据中，data 字段是一个数组，数组的每个元素都代表一个可筛选的参数。其中：

• name：是这个筛选参数的中文名称，方便用户理解。
• field_name：是这个筛选参数在接口中实际调用的字段名，这是您在后续进行筛选请求时需要使用的关键标识。
• items：是一个数组，包含了该筛选参数所有可选的值（label），以及当前状态下每个选项对应的文档数量（total）。

通过这种方式，您不仅能知道哪些字段可以筛选，还能了解每个字段提供了哪些具体的筛选选项。

如果您还想进一步了解这些筛选字段的详细配置，比如它们在后台是如何定义的，或者它们是否是系统内置字段，您可以结合“获取模型详情接口” (/api/module/detail) 进行查询。这个接口在返回的模型详情中，会有一个 fields 数组，列出了该模型的所有自定义字段，其中每个字段都有一个 is_filter 属性，明确指示该字段是否被设置为可筛选。这可以帮助您从源头理解筛选参数的设置逻辑。

如何应用这些筛选参数

获取到这些可筛选的 field_name 及其对应的 label 值后，您就可以将其应用到“获取文档列表接口”（/api/archive/list）中，实现更精细的文档列表筛选功能。

例如，如果您从 archive/filters 接口中获得了 field_name 为 city，并且 items 中有 label 为“北京”的选项，那么在请求 /api/archive/list 时，您就可以添加 city=北京 作为查询参数，来获取所有属于“北京”且与该模型相关的文档列表。这为构建动态、用户友好的内容筛选界面提供了强大的基础。

通过这样的两步操作，您可以轻松地实现根据文档模型动态获取并应用筛选条件的需求，为用户提供更加灵活和个性化的内容浏览体验。

常见问题解答 (FAQ)

1. Q: 为什么archive/filters接口返回的items中total字段的值总是0？

   • A: archive/filters 接口的 total 字段设计上是为了表示在当前筛选条件下，每个选项对应的文档数量。如果您仅仅调用 archive/filters 接口而不配合 archive/list 接口进行实际的文档列表查询，这个 total 值通常会是 0。它通常用于与 archive/list 接口结合，当您传入筛选参数后，archive/list 会返回符合条件的文档数量，而这个 total 字段在 archive/filters 的上下文中，更多是展示该筛选选项的存在，而非其实时匹配数量。

2. Q: moduleDetail接口中的is_filter属性和archiveFilters接口返回的数据有什么区别？

   • A: moduleDetail 接口返回的 fields 数组中的 is_filter 属性，表示的是该字段在模型定义层面是否被管理员配置为“可以作为筛选条件”。它是一个布尔值（true 或 false），说明了字段的 能力。而 archiveFilters 接口返回的数据，则是在此能力基础上，列出了该模型下 实际存在 的、可供用户选择进行筛选的具体选项（label），以及它们的调用名称（field_name）。简而言之，is_filter 是“这个字段能否筛选”，archiveFilters 是“这个字段有哪些具体的筛选值”。

3. Q: 如果我的文档模型没有设置任何可筛选字段，调用archive/filters接口会返回什么？

   • A: 如果某个文档模型确实没有设置任何可筛选的自定义字段，或者所有自定义字段的 is_filter 属性都为 false，那么调用 archive/filters 接口时，data 字段会返回一个空数组 []。这表示当前模型下没有可用于筛选的参数。