#4.4 文档配置列表与详情【待数据联调】

GET /tieup/api/v1/documents

鉴权：公开接口，不需要 Authorization。

查询参数：

参数	类型	必填	说明
doc_code	string	否	文档代码；传入后返回单个文档详情，不传时返回列表
doc_type	string	否	文档类型筛选：user_agreement、privacy_policy、help、contact、other

请求 Header：

Header	必填	说明
X-App-Version	APP 必填	当前 APP 展示版本号，例如 1.2.0；缺失或格式无效时按最高启用文档版本返回
X-App-Channel	APP 必填	当前渠道代码；服务端自动合并平台默认和渠道覆盖配置

列表请求示例：

GET /tieup/api/v1/documents?doc_type=other
X-App-Version: 1.2.0
X-App-Channel: huawei

详情请求示例：

GET /tieup/api/v1/documents?doc_code=privacy_policy
X-App-Version: 1.2.0
X-App-Channel: huawei

响应字段：

字段	类型	说明
doc_code	string	文档代码，同一作用域允许配置多个版本
doc_type	string	文档类型：user_agreement=用户协议，privacy_policy=隐私政策，help=帮助中心，contact=联系与帮助，other=其他类型
title	string	文档标题
content_format	string	内容格式：markdown=Markdown 原文，url=HTTP/HTTPS 链接
content	string	Markdown 原文或链接地址，客户端必须根据 content_format 处理
version_no	string	当前客户端命中的文档版本号
published_at	string/null	发布时间，格式 YYYY-MM-DD HH:mm:ss；未设置时为 null
updated_at	string	更新时间，格式 YYYY-MM-DD HH:mm:ss

列表响应示例：

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "doc_code": "new_user_guide",
      "doc_type": "other",
      "title": "新用户指南",
      "content_format": "markdown",
      "content": "# 新用户指南\n\n欢迎使用 Tieup。",
      "version_no": "1.2.0",
      "published_at": "2026-07-22 10:00:00",
      "updated_at": "2026-07-22 10:10:00"
    },
    {
      "doc_code": "security_center",
      "doc_type": "other",
      "title": "安全中心",
      "content_format": "url",
      "content": "https://www.example.com/security",
      "version_no": "1.0.0",
      "published_at": null,
      "updated_at": "2026-07-22 09:00:00"
    }
  ]
}

详情响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "doc_code": "privacy_policy",
    "doc_type": "privacy_policy",
    "title": "隐私政策",
    "content_format": "url",
    "content": "https://www.example.com/privacy",
    "version_no": "1.2.0",
    "published_at": "2026-07-22 10:00:00",
    "updated_at": "2026-07-22 10:10:00"
  }
}

说明：

• 未传 doc_code 时始终返回数组；没有匹配文档时返回空数组 []。
• 传入 doc_code 时返回对象；文档不存在，或同时传入的 doc_type 与文档不一致时返回 404 业务错误。
• 服务端先在平台默认和当前渠道中分别选择 version_no 不高于 X-App-Version 的最高启用版本，再由适用的渠道文档覆盖相同 doc_code 的平台文档。渠道不存在适用版本时继续返回平台版本。
• 缺少或无法识别 X-App-Version 时，每个文档代码返回最高启用版本。
• 接口结果按后台 sort 升序排列；内部作用域、渠道和状态字段不对 APP 返回。
• 文档接口按业务配置版本、渠道、APP 版本和查询条件缓存 300 秒，Redis 不可用时直接查询数据库。
• 兼容接口 GET /tieup/api/v1/documents/{doc_type} 继续保留，返回指定类型排序第一条文档；路径类型同时支持 other。