# 角色区域关联 — QueryRoleAreaAssociation

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

---

## 一、接口概述

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

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

---

## 二、请求

### 请求体（JSON）

```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，用于企业集成（预留字段） |

---

## 五、响应样例

```json
{
  "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 下新建配置表。

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/role_area_association.md，按逻辑分组详解递归树形结构字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->