交付出件箱

← 返回出件箱

渠道机构地理分布数据驾驶舱 · 建设调研报告

版本 v2.0（在 v1.0 基础上纳入账号安全处置、分级权限管控、异常提醒三项新增需求）
日期 2026-08-14
面向 内部业务决策
调研范围 doctor-ai-brain（核心系统） + settlement（渠道结算系统）

阅读须知 · 本报告的证据边界

本报告所有技术判断均来自对现有代码的逐项检索，每条结论在附录 A 给出 文件:行号 出处，可逐条复核。

必须先讲清楚哪些能信、哪些不能信：

凡涉及数量、比例、耗时的地方，本报告一律不给编造的数字。需要实测的部分已整理成独立的《数据摸底 SQL》交付件。

一、项目建设背景与建设目的

1.1 建设背景

业务侧现状

公司目前采用"渠道创建 → 机构入驻 → 机构账号独立登录"的三级管理模式：

• 渠道：由平台创建，负责拓展与维护机构，有独立账号与分成比例；
• 机构：由渠道引入，提交入驻资料并签约，归属明确到具体渠道；
• 机构账号：机构下的席位账号独立登录使用系统，按席位售卖。

这套模式在业务扩张期运转正常，但管理侧的观测手段没有跟上，主要体现在三点：

第一，看不到"在哪里"。 系统从建立至今没有采集过机构的地域信息，管理人员无法回答"我们在哪些省有机构""哪个省覆盖薄弱""某个渠道的机构集中在哪些区域"这类基本问题。

第二，看不到"谁在用"。 登录记录虽然完整落库，但只能通过后台表格逐条翻查。管理人员无法一眼判断当前系统的活跃程度，也无法察觉某个区域的机构集体沉默。

第三，发现问题到处置问题之间是断的。 即便通过审计日志发现某个账号异常，处置动作要切换到另外的管理页面去做，中间隔着若干次跳转和查找，异常响应效率低。

技术侧现状（决定本项目难易的关键）

调研中确认了四项事实，两好两坏：

有利事实一：登录行为已经完整落库，且记录的是用户真实公网 IP。
系统的认证审计表记录了每一次登录成功/失败的账号、IP、终端信息和精确时间，且 Nginx 与应用容器的代理配置是配套的，记录的是用户真实公网地址而非机房内部地址。这意味着"登录实时上屏"的数据源已经存在，不需要新增任何埋点。

有利事实二：渠道、机构、签约、登录四类数据在同一个物理数据库中。
结算系统虽然在架构上已拆分为独立服务，但生产部署是与核心系统同库共存（通过独立数据库账号做权限隔离）。这意味着"机构归属哪个渠道"可以用一条 SQL 直接关联出来，不需要跨服务调用接口拼装数据，方案复杂度降低一个量级。

不利事实一：系统没有任何地理维度数据。
全库没有省、市字段，没有行政区划字典。机构地址有两个来源，但一个是门店分享名片时自己在手机上选的位置（业务上从不强制），另一个是入驻资料里的签约地址（表单校验的是营业执照、门头照、视光师资质、设备照四类文件，地址字段允许为空）。

不利事实二：系统没有"在线状态"这个概念。
登录采用无状态令牌机制，登录后不打卡、不心跳、退出也不落库。系统目前能回答"这个账号今天上午十点登录过"，回答不了"这个账号此刻是否在线"。

1.2 建设目的

本项目要达成的目标，按业务价值排序：

1. 把"全国机构分布"从抽象概念变成一屏可见的事实 —— 管理层、渠道管理、市场决策共用一张图；
2. 把"谁在用系统"从事后查表变成实时可感 —— 登录即上屏，活跃度一目了然；
3. 把"发现异常"到"处置异常"的链路缩短到一次点击 —— 在同一个界面完成查看与处置；
4. 让不同层级的管理者看到与其职责匹配的数据 —— 总部看全国，渠道看自己名下，区域看自己辖区；
5. 让异常行为主动找人，而不是等人去找 —— 多地登录、非工作时间登录等风险信号主动提醒。

1.3 本项目的真实难点（提前说明）

必须纠正一个常见预期：这不是一个"前端画张地图"的项目。

地图渲染、点位闪烁、统计卡片这些工作，占总工作量不到三分之一。真正的工程量集中在四处，且都在业务与数据层，不在展示层：

后文对每一项都给出了具体方案和工作量判断。

二、详细业务需求拆解

2.1 地图可视化需求

需求描述

以中国电子地图为核心载体，机构账号登录后，地图上对应地理位置的机构点位自动点亮。

拆解

2.1.1 核心卡点：机构位置从哪来

这是全项目的第一优先级问题。现有两个数据来源都不可靠：

建议的解决路径（三层兜底，按优先级取值）：

1. 有签约地址 → 地址解析成省市与坐标（业务语义最正式）；
2. 无签约地址但有门店名片坐标 → 直接用坐标；
3. 两者都无 → 进入"未定位机构"清单，在大屏上单独计数并明示数量。

关键原则：绝不允许把未定位的机构静默丢弃。 大屏必须显示"全国 X 家机构，其中 Y 家未定位"，否则会造成"我们只有这么多机构"的误判——这比没有大屏更危险。

2.1.2 需要业务确认的一个概念问题

"地图上那个点代表什么"这件事，业务上有两种理解，实现方式完全不同：

建议选 C。理由是"地域分布"和"登录点亮"本来就是两个不同的业务问题，用一个数据源硬扛必然有一边失真。而且两者不一致时（注册在成都、天天从广州登录）本身就是有价值的风控信号，可直接服务于 §2.6 的异常提醒。

2.2 机构详情查询需求

需求描述

点击地图点位，下钻查看该机构的详细信息。

拆解与现状（这部分是全项目现状最好的）

判定：详情弹窗要展示的信息，九成以上是现成数据，只需查询组装，无需新建采集链路。

2.2.1 "在线状态"必须先定义

再次强调技术事实：系统采用无状态令牌，服务端不维护会话，没有心跳，退出不落库。因此"此刻是否在线"在当前架构下无法精确回答。

有两条路：

路线一（建议）：用活跃度分级替代二元在线状态。

优点是零新增埋点，纯查询实现，口径可解释可审计，且能直接支撑"各省份活跃度"的着色。

路线二：新增前端心跳上报。
每隔一段时间由前端上报一次在线信号。精度更高，但需要新建接口、新建表、处理心跳风暴，且对现有的所有客户端（H5、平板、小程序）都要改造。投入产出比不划算，不建议为大屏单独做。

2.3 账号安全处置需求

需求描述

在大屏上可对机构账号执行强制下线、启用/禁用、重置密码等操作，并记录操作日志。

拆解与现状

2.3.1 强制下线的技术真相（重要）

系统当前的"下线"机制有两套，都不能直接满足需求：

机制一：令牌黑名单。 用户主动退出时，把他那一串具体的令牌加入 Redis 黑名单。
局限：管理员要踢某个账号时，服务端手里根本没有那个账号的令牌字符串（无状态令牌不落库）。所以这套机制只能用于"用户自己退出"，无法用于"管理员踢人"。

机制二：席位设备绑定。 席位账号的令牌里带设备标识，每次请求都会与数据库里记录的当前设备做比对，不一致直接拒绝。
这是一个意外的好消息：对机构席位账号而言，只要把数据库里的当前设备标识改掉，该账号的所有请求会立即失效——等于现成的、即时生效的强制下线能力，几乎零成本。

但对管理员账号、机构管理员账号、渠道账号，没有这层校验，强制下线需要新建机制。

建议方案（工程量不大，但必须一次做对）：

1. 在缓存中按账号记录一个"失效时间戳"，管理员执行强制下线时写入当前时间；
2. 令牌校验环节比对令牌的签发时间，早于失效时间戳的一律拒绝；
3. 必须同时处理续期令牌 —— 这一点最容易漏：访问令牌 30 分钟就过期，但续期令牌最长可达一年。如果只废止访问令牌，被踢的用户 30 分钟后会自动续上，等于没踢。

2.3.2 操作日志：可直接复用现有表

结算系统已有一张通用操作审计表，字段结构与本需求完全对口：

操作人、操作人角色、动作类型、操作对象类型、操作对象 ID、操作前快照、操作后快照、操作理由、请求 ID、操作时间。

建议直接复用，不新建表。 其中"操作前后快照"对安全处置场景尤其重要（谁在什么时候把哪个账号从启用改成了禁用，一目了然），"请求 ID"字段还能直接用于 §7.5 的多人操作冲突防护。

2.3.3 一个必须提出的设计风险

大屏是给人看的，通常常驻显示、甚至可能投屏在办公区；而账号处置是高危操作。把两者放在同一个界面，本身是一个需要谨慎对待的设计。

具体风险：大屏常驻意味着登录态长期挂着，若屏幕无人值守，任何路过的人都可以点击禁用某个客户的账号。

建议的防护设计（供业务决策）：

1. 投屏模式与操作模式分离：大屏默认进入只读的"投屏模式"，处置按钮不可见；需要处置时手动切换到"操作模式"；
2. 处置操作二次鉴权：切换到操作模式或执行处置前，要求重新输入密码；
3. 高危操作二次确认 + 填写理由：禁用、重置密码必须填写操作理由（正好落进日志表的 reason 字段）；
4. 闲置自动退回：操作模式闲置若干分钟后自动退回投屏模式。

2.4 配套数据统计需求

需求描述

全国活跃机构数量、各省份机构活跃度、各渠道机构分布统计卡片。

拆解

重要提示：口径必须与现有报表统一。 系统现有的"机构洞察"页面已经有一套活跃度口径。如果大屏另立一套口径，会出现"同一天两个页面两个数字"的情况，管理层会立刻质疑数据可信度。建议大屏的活跃口径直接复用现有实现，而不是重新写一遍聚合逻辑。

2.5 权限管控需求

需求描述

总管理员、渠道管理员、区域管理员按权限查看不同范围数据。

现状：这是本次新增需求里最贵的一项

现有权限体系是"角色 → 菜单开关"的二元结构：一张表记录"某个角色能不能看见某个菜单"。

这套机制只能控制"能不能进这个页面"，完全无法控制"进来后能看到哪些机构的数据"。

本需求要的恰恰是后者——渠道管理员进大屏，只能看到自己名下的机构；区域管理员只能看到自己辖区的机构。这在技术上叫数据行级权限，现有系统一点基础都没有。

逐角色拆解

需要新建的能力

1. 区域体系：区域定义、区域与省份/城市的映射关系、管理员与区域的绑定关系；
2. 数据范围过滤层：所有大屏查询接口统一按"当前登录者能看哪些机构"做过滤，这一层必须做在后端；
3. 角色扩展：新增区域管理员角色，并接入现有的菜单权限体系。

一条安全红线

数据范围过滤必须在后端接口层强制执行，绝不能靠前端隐藏。

前端隐藏只是"看不见"，接口照样能返回全量数据，任何人打开浏览器开发者工具就能看到本不该看的客户信息。渠道之间存在竞争关系，渠道 A 看到渠道 B 的机构名单属于严重的商业信息泄露。这一条在验收时必须专门测试：用渠道管理员的账号直接调用接口，验证返回的数据确实被过滤。

2.6 异常提醒需求

需求描述

多地登录、频繁掉线、非工作时间登录等异常情况提醒。

逐项可行性判定（这一节结论差异很大，需逐条看）

关于"频繁掉线"必须说清楚

系统目前物理上无法统计掉线。 原因是没有心跳机制，也不记录会话终止——系统只知道"什么时候登录的"，不知道"什么时候断的"，因此"掉线"这个事件在数据层根本不存在。

三个选择，请业务方定夺：

建议选 A，并在大屏上把指标名称如实标注为"频繁重连"而非"掉线"——指标名称与实际口径必须一致，这是数据可信度的底线。

告警怎么送达

现状：系统有一个统一错误上报接口，但目前是占位实现，只写日志，既不落表也不推送（代码注释明确写着留待后续升级为"事件表 + 告警规则 + 企业微信机器人"）。

已具备的推送通道：阿里云短信、微信订阅消息。

建议：本期告警先做到"大屏内提醒 + 落库可查"（右侧异常提醒栏 + 异常记录列表），不做外部推送。理由是外部推送涉及告警规则配置、免打扰策略、误报处理，是一个独立的运营监控课题，混进本项目会显著拉长工期。

三、整体功能架构设计

3.1 总体架构

┌──────────────────────────────────────────────────────────────┐
│                      数据驾驶舱大屏（全屏页面）                    │
│  ┌────────────┬──────────────────────────┬────────────────┐  │
│  │  统计卡片区   │        中国地图主区域        │   实时动态区     │  │
│  │  ① 统计模块  │        ② 地图模块          │  登录流水       │  │
│  │            │                          │  ⑥ 异常提醒     │  │
│  └────────────┴──────────────────────────┴────────────────┘  │
│                      ↓ 点击点位                                 │
│            ┌──────────────────────────┐                       │
│            │  ③ 详情弹窗模块              │                       │
│            │  机构信息 / 渠道 / 登录记录    │                       │
│            │  ┌────────────────────┐  │                       │
│            │  │ ④ 账号处置模块（受控） │  │                       │
│            │  └────────────────────┘  │                       │
│            └──────────────────────────┘                       │
└──────────────────────────────────────────────────────────────┘
                              ↕
┌──────────────────────────────────────────────────────────────┐
│                    ⑤ 权限模块（贯穿全部请求）                       │
│         菜单准入（已有） + 数据范围过滤（新建 · 后端强制）             │
└──────────────────────────────────────────────────────────────┘
                              ↕
┌──────────────────────────────────────────────────────────────┐
│                       后端服务层                                │
│  大屏查询服务 │ 处置服务 │ IP归属地服务 │ 异常检测 │ ⑦ 日志审计     │
└──────────────────────────────────────────────────────────────┘
                              ↕
┌──────────────────────────────────────────────────────────────┐
│         数据层（同一数据库 · 现有表为主 · 新增两张小表）              │
│  机构 │ 渠道 │ 签约档案 │ 登录审计 │ 行为流水 │ 操作审计            │
│  ＋ 机构地理表（新）  ＋ 区域体系表（新）                            │
└──────────────────────────────────────────────────────────────┘

3.2 各模块设计要点

① 统计卡片模块

• 卡片：全国活跃机构数、当前在线数、今日登录次数（含环比）、覆盖省份数、未定位机构数、异常事件数；
• 口径复用现有机构洞察实现，避免同一指标两处不同实现导致数字打架；
• 所有卡片受权限模块约束——渠道管理员看到的"全国活跃机构数"实际是"其名下活跃机构数"，卡片标题需随权限动态变化，否则会误导。

② 地图模块

• 中国省级底图 + 机构点位层 + 省份热力着色层；
• 点位状态四色（在线/今日活跃/近期活跃/沉默）；
• 新登录触发点位高亮动效（约 3 秒）；
• 同城多机构自动聚合，点击展开；
• 省份可下钻；
• "未定位机构"以独立卡片计数呈现，不隐藏、不塞进任何省份。

③ 详情弹窗模块

分区展示：机构基础信息 / 归属渠道 / 登录记录（IP + 归属地 + 时间 + 终端）/ 活跃状态 / 席位概况。

登录 IP 按查看者角色脱敏（见 §7.6）。

④ 账号处置模块

• 操作：强制下线、启用、禁用、重置密码、解锁；
• 默认隐藏，仅在"操作模式"下可见（§2.3.3）；
• 每个操作：二次确认 → 填写理由 → 执行 → 写审计 → 刷新状态；
• 所有操作携带请求 ID，防重复提交（§7.5）；
• 处置权限与查看权限分离配置 —— 能看不等于能操作，区域管理员是否有处置权需业务明确。

⑤ 权限模块

两层结构：

1. 菜单准入层（复用现有）：控制角色能否进入大屏页面；
2. 数据范围层（新建）：统一解析当前登录者可见的机构范围，所有查询接口强制经过此层。

实现红线：过滤在后端完成，前端不做任何数据裁剪。

⑥ 异常提醒模块

• 检测项：多地登录、异地登录、非工作时间登录、频繁重连、暴力破解（复用已有信号）；
• 呈现：大屏右侧滚动提醒栏 + 可查询的异常记录列表；
• 每条提醒可一键跳转到对应机构详情，从发现到处置一步到位；
• 本期不做外部推送（§2.6）。

⑦ 日志审计模块

• 复用现有操作审计表，不新建；
• 记录：操作人、角色、动作、对象、前后快照、理由、请求 ID、时间；
• 提供操作日志查询页，支持按操作人、对象、时间、动作筛选；
• 审计记录只增不改不删（现有表已按此设计，权限层面已做限制）。

四、技术选型建议

4.1 前端地图

建议 ECharts 方案。 合规性与可控性优先，内部驾驶舱不需要卫星底图。

需注意：现有前端技术栈的图表库不支持地理投影，必须新增地图库依赖，这是本项目唯一需要新增的前端依赖，需按技术栈管理规则走审批。

4.2 IP 归属地解析（已实测，非推荐而是已验证）

选用离线 IP 归属地库，本机实测结果：

• 精度：省 + 市 + 运营商，满足需求；
• 性能：8 次查询 1.55 毫秒，实时上屏无压力；
• 合规：本地文件查询，登录 IP 不发送给任何第三方；
• 可获取性：可通过公司允许的软件源获取，不依赖受限的外部站点；
• ⚠️ 已知短板：现成库文件为 2022 年版本，近三年新分配的 IP 段可能识别不准。需安排具备外网条件的同事获取最新库文件。不影响开工，属上线前必补项。

附带价值：该库能识别内网地址，可用作部署健康探针——一旦大批登录被解析为内网 IP，说明代理配置被改坏，可第一时间发现。

4.3 后端服务

• 沿用现有技术栈（FastAPI），不引入新框架；
• 大屏接口全部为只读查询，统一前缀独立分组，便于权限与限流管理；
• 处置类接口复用现有已实现的账号管理能力，不重复造轮子；
• 新增：数据范围过滤依赖项（所有大屏接口统一挂载）、IP 归属地服务（解析结果加缓存）、异常检测服务。

4.4 数据库

• 沿用现有 PostgreSQL，不引入新数据库；
• 新增两张小表：机构地理信息表、区域体系相关表；
• 复用现有表：机构、渠道、签约档案、登录审计、行为流水、操作审计；
• 必要的索引优化：登录审计表现有索引是单列的，而大屏所有查询都是"最近 N 分钟的成功登录"这种组合条件，需要增加组合索引，否则大屏每次刷新都会扫描大量数据；
• 是否需要预聚合表：建议先不做。先用实时查询 + 短时缓存，实测有压力再引入，避免过早优化带来的数据一致性问题。

4.5 实时通信

系统内已有两种实时技术的先例：WebSocket（实时语音）与 SSE（流式对话）。但本项目建议都不用，采用定时轮询。

业务侧的"实时"是指十几秒内看到，不是毫秒级。 轮询完全满足，且最稳。若后续确有秒级需求，可单独立项升级。

五、系统部署模式

5.1 现状

系统目前部署在阿里云服务器上，采用容器化编排，数据库、缓存、后端、前端各自独立容器，通过 Nginx 统一对外提供 HTTPS 服务。已经是云端部署。

需要注意的现实约束：当前服务器资源配置偏紧，各容器均设有内存上限，数据库的缓存参数也调得较小。这一点直接关系到 §7.4 的实时刷新压力评估。

5.2 部署模式对比

结论：采用云端部署（方案 A）。 若需要固定的大屏展示位，配一台专用终端常开浏览器即可（方案 C），无需为此改变部署架构。

大屏常驻的一个技术细节必须提前处理：系统的访问令牌 30 分钟过期。大屏挂一晚上，第二天早上会是一片空白或全是错误提示。必须实现静默续期与断线重连提示，这一条容易被漏，须写入实施清单。

六、分阶段落地实施计划

以下工作量为经验估算，非实测，按单人投入计算，不含需求评审与验收往返时间。

阶段划分原则

数据地基必须先行。 先做前端会得到一张漂亮但没有点的空地图，这是本项目最需要避免的返工。

关键说明

1. P0 可以立即启动，不依赖任何业务决策；
2. 地址补录必须与 P0 并行启动，这是唯一一件技术加班也快不了的事——需要业务侧安排人力核对补充。等到 P1 做完才发现没数据，整体会延期 2~4 周；
3. P3 是最贵的一段，因为要动权限底座。如果业务上可以接受"一期只给总管理员用"，P3 可以后置，整体提前约 1.5 周上线；
4. P2 与 P3 的顺序建议不要调换：先有权限隔离再放开处置能力更安全。若 P3 后置，则 P2 阶段的处置能力应仅对总管理员开放。

建议的并行安排

第 1 周   │ P0 数据地基 ──────────┐
         │ （业务侧）地址补录 ─────┼──── 持续进行
第 2-3 周 │ P1 只读大屏 ──────────┘
第 4 周   │ P2 账号处置
第 5-6 周 │ P3 分级权限
第 7 周   │ P4 异常提醒 + 整体验收

七、潜在风险及应对办法

7.1 数据对接风险

7.2 地图定位精度风险

7.3 权限安全风险

7.4 实时刷新压力风险

7.5 多人操作冲突风险

7.6 登录 IP 隐私合规风险

这是本项目合规层面最需要正视的一项。 登录 IP 与地理位置，既涉及机构的经营信息，也在特定场景下可能关联到个人。

八、预期业务价值

8.1 管理效率

8.2 业务决策

• 渠道管理：直观看到各渠道的机构数量、地域集中度与活跃程度，为渠道考核与资源倾斜提供依据；
• 市场拓展：空白省份、薄弱区域一目了然，为拓展计划提供事实基础；
• 客户成功：区域性的活跃度下滑可被及时发现，从被动等客户反馈变为主动干预。

8.3 风险控制

• 多地登录、异地登录等账号共享嫌疑主动暴露，直接服务于按席位售卖的商业模式；
• 非工作时间登录纳入观测，异常使用行为可追溯；
• 所有处置操作留痕，含操作前后快照，责任可追溯。

8.4 数据资产沉淀（容易被低估的长期价值）

本项目最持久的价值可能不是那块大屏，而是它逼着我们把机构的地理数据补齐了。

这份数据一旦建立并纳入常态维护，可以复用于：区域化运营分析、渠道区域保护策略、市场活动的地域投放、客户地域画像。这是一次性投入、长期复用的基础数据资产。

8.5 价值实现的前提（务必正视）

以下三条不满足，上述价值会大打折扣：

1. 地理数据必须补到位 —— 覆盖率决定这块屏的可信度。一张只有三成机构的地图，管理层看两次就不会再看；
2. 指标口径必须与现有报表统一 —— 同一指标两个页面两个数字，数据可信度会瞬间归零；
3. 权限隔离必须真实有效 —— 渠道之间的数据隔离一旦出问题，是商业事故，不是技术 bug。

附录 A · 证据索引

附录 B · 待业务确认事项汇总

附录 C · 立即可执行的下一步

建议在正式立项评审前完成一件事：跑摸底 SQL。

四条只读查询，约 1 分钟执行完，直接决定本项目排期是 6 周还是 10 周。查询脚本与结果解读说明见配套交付件《驾驶舱大屏 · 数据摸底 SQL》。

核心是两个数字：

• 机构地址可定位率 —— 低于 70% 则需先补数据；
• 登录 IP 中私网地址占比 —— 若占比高，说明部署配置需先修复。

本报告为调研结论，不含任何已实施的代码改动。数据层结论待摸底 SQL 执行后回填。本机为隔离开发环境，未连接生产数据库，报告中不提供任何未经实测的数据指标。