ZQYY.FQ-ETL/docs/api-reference/role_area_association.md

角色区域关联 — QueryRoleAreaAssociation

模块：User · ODS 表：无（新发现 API，尚未建表） · 配置查询

---

一、接口概述

查询指定角色 ID 关联的区域树形结构，返回省/市/门店的层级关系。用于权限管理场景，确定某个角色可以访问哪些区域和门店。该接口为新发现的 API，当前尚未建立 ODS 表。

属性	值
完整路径	POST /User/QueryRoleAreaAssociation
Base URL	https://pc.ficoo.vip/apiprod/admin/v1/
鉴权	Authorization: Bearer <token>
分页	无分页
时间范围	不需要

---

二、请求

请求体（JSON）

{
  "roleId": 12
}

参数说明

参数	类型	必填	说明
roleId	int	是	角色 ID，查询该角色关联的区域树

---

三、响应结构

{
  "code": 200,
  "data": {
    "roleAreaRelations": [
      {
        "id": ...,
        "name": "广东",
        "children": [
          {
            "id": ...,
            "name": "广州",
            "children": [],
            "siteList": []
          }
        ],
        "siteList": []
      }
    ]
  }
}

data.roleAreaRelations 为树形数组，每个节点代表一个区域层级（省 → 市 → 门店），通过 children 递归嵌套。

---

四、响应字段详解

4.1 区域节点字段（递归结构，每层相同）

字段	类型	示例	说明
id	int	2790684101675845	区域节点 ID
pid	int	0	父节点 ID。0 = 顶层节点（省级）
name	string	"广东"	区域名称（省/市/区等）
deptCode	string	""	部门编码，当前为空
level	int	3	层级标识：3 = 省级，2 = 市级（数值越小层级越深）
sort	int	1	排序权重
selected	bool	false	是否被当前角色选中
isMarketing	int	0	是否为营销区域：0 = 否
siteList	array	[]	该节点下直属的门店列表（当前为空数组）
children	array	[...]	子区域节点列表，递归嵌套同一结构
shopStatus	int	0	门店状态标识（预留字段）
dingDeptId	int	0	钉钉部门 ID，用于企业集成（预留字段）

---

五、响应样例

{
  "roleAreaRelations": [
    {
      "id": 2790684101675845,
      "pid": 0,
      "name": "广东",
      "deptCode": "",
      "level": 3,
      "sort": 1,
      "selected": false,
      "isMarketing": 0,
      "siteList": [],
      "children": [
        {
          "id": 2790684179467077,
          "pid": 2790684101675845,
          "name": "广州",
          "deptCode": "",
          "level": 2,
          "sort": 1,
          "selected": false,
          "isMarketing": 0,
          "siteList": [],
          "children": [],
          "shopStatus": 0,
          "dingDeptId": 0
        }
      ],
      "shopStatus": 0,
      "dingDeptId": 0
    }
  ]
}

---

六、跨表关联

该接口为权限配置查询，与业务数据表无直接关联。

潜在关联	说明
id（区域节点）	可能与门店维度中的区域层级 ID 对应
siteList 中的门店	预期包含 site_id，可与各业务表的 site_id 关联

当前该接口尚未建立 ODS 表，暂无 ETL 入库流程。如后续需要持久化角色-区域映射关系，建议在 billiards schema 下新建配置表。