148 lines
3.9 KiB
Markdown
148 lines
3.9 KiB
Markdown
# 角色区域关联 — 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/ 确认字段覆盖完整
|
||
-->
|