初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/role_area_association.md
+++ b/docs/api-reference/role_area_association.md
@@ -0,0 +1,147 @@
+# 角色区域关联 — 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/ 确认字段覆盖完整
+-->