用户分布插件（UserMap）使用说明

根据站点用户填写的地址（居住地 / 户籍地）自动聚合，生成中国地图热力图、省份排行、城市 TOP 10 与用户明细，同时提供后台管理页和前台公开页。

一、前置条件

1. 已安装并启用 用户扩展资料（UserProfile） 插件。
2. 用户在「个人资料」中填写了居住地或户籍地（默认读取字段见下表）。
3. 站点用户表 user 可正常访问。

未安装 UserProfile 时，后台页面会提示「未检测到数据表」，前台仍可访问但只显示空地图。

二、数据来源

插件读取 UserProfile 的扩展资料值表（userprofilevalue），按用户聚合出一个归属地，优先级如下：

• 省份会自动归一化为地图所需的 34 个标准名称（如「四川」→「四川省」、「新疆」→「新疆维吾尔自治区」）。
• 城市名会去掉末尾的「市」，「宜宾」与「宜宾市」合并统计。
• 地址字段可在后台配置中切换，不必写死。

三、后台使用

1. 进入页面

后台左侧菜单 → 插件列表 → 用户分布，地址为 /admin/user_map。

2. 页面内容

• 统计卡片：站点用户总数、已登记地址人数、覆盖省份数、地址覆盖率。
• 地域分布地图：中国地图省份热力图，颜色越深用户越多；支持缩放、拖动。
• 省份排行 / 城市 TOP 10：点击任一条目，下方明细表自动按该地区筛选。
• 用户明细：UID、用户名、昵称、省份、城市、详细地址、手机、注册时间；支持关键字（用户名 / 昵称 / 邮箱 / 手机）搜索、服务端分页。
• 刷新按钮：重新统计并刷新明细。

3. 接口

四、插件配置

后台 → 应用中心 → 用户分布 → 配置。

下拉项来自 UserProfile 已启用的字段；未安装 UserProfile 时使用内置的常见地址字段。

五、前台公开页

1. 访问地址

• 页面：/usermap（带 .html 后缀同样可访问）
• 数据：/usermap/data

页面无需登录，内容包含：

• 4 个统计卡片（注册用户 / 已登记地区 / 覆盖省份 / 覆盖城市）
• 中国地图热力图
• 省份排行、城市 TOP 10
• 顶部「返回首页」按钮

隐私说明：前台接口只返回聚合后的省份 / 城市数量，不返回用户名、手机号、详细地址等任何个人资料。用户明细仅在后台可见。

2. 导航入口

默认已写入主题自定义菜单，显示在顶部导航和移动端抽屉菜单：

• 修改名称：主题设置 → 自定义菜单 → 用户分布 → 名称
• 修改链接：保持 /usermap 即可
• 删除入口：在自定义菜单中删除该项，页面本身仍可通过 /usermap 访问

页面内标题与导航名称相互独立，可分别修改。

3. 样式

前台页面主色取自主题配置 primary_color；后台跟随系统浅色 / 深色模式。

六、静态资源

图表与地图数据为本地文件，不依赖外网 CDN：

public/static/UserMap/echarts.min.js   ECharts 5.5.1
public/static/UserMap/china.json       中国省级 GeoJSON

• 若页面提示「图表脚本加载失败」或「地图数据加载失败」，检查上述两个文件是否存在，可在应用中心重新安装插件以同步资源。
• 如服务器无法访问外网，同样不受影响。

七、卸载说明

在应用中心停用 / 卸载插件时：

• 自动移除后台菜单与权限节点（admin/user_map 等）
• 不删除、不修改 UserProfile 的用户资料数据
• 建议同时手动删除主题自定义菜单中的「用户分布」项

八、常见问题

Q：地图空白 / 没有颜色？

先确认用户是否填写了地址；若所有人都显示「暂无用户数据」，检查 UserProfile 是否启用、配置中的字段名是否存在。同时查看浏览器控制台是否有 china.json 404。

Q：统计人数和站点用户总数不一致？

「已登记地区」只统计能识别出省份或城市的用户；未填写地址的用户计入「未登记」。

Q：城市排行里出现「黔东南」这类名称？

城市按用户填写值清理后统计，自治州 / 地区会保留原名称，不含「自治州」后缀的情况属正常。

Q：修改了「前台页面标题」但前台没变化？

确认已点击保存；如仍未生效，刷新页面或清理站点缓存。

Q：能否只给部分管理组看后台数据？

菜单已注册为权限节点，在「权限管理 → 角色」中按需分配给相应管理组即可。

九、文件结构

plugins/UserMap/
├── plugin.json                    插件信息（名称、图标、版本）
├── UserMapPlugin.php              数据聚合、地址归一化、菜单注册
├── routes.php                     前台 / 后台路由
├── icon.svg                       插件图标
├── controller/
│   ├── Index.php                  前台页面与公开聚合接口
│   └── admin/
│       ├── Base.php               后台基类与模板渲染
│       └── Distribution.php       后台统计 / 明细接口
└── view/
    ├── front/index.html           前台分布图页面
    └── admin/index.html           后台分布图 + 明细页