用户扩展资料插件（UserProfile）

作者：kuakeba.cn

版本：1.0.0

适用：Zsens Admin 轻量级后台管理系统 PHP 8.2+

为用户增加丰富的扩展资料字段，支持管理员动态增删字段，默认内置 21 个常用字段（性别、生日、公司、学历、职业、QQ、备用电话、省/市/区三级地址、祖籍、字派、身份标签、个人简介等）。

一、安装

1. 进入后台 → 应用中心
2. 找到「用户扩展资料」→ 点击 安装
3. 安装完成后左侧菜单自动出现「用户扩展资料」入口
4. 插件自动执行：

  - 建表（userprofilefield + userprofilevalue）

  - 写入 21 个默认字段

  - 注册后台菜单和权限

💡 如果表不存在，运行时也会自动建表，装完即用。

二、后台使用

2.1 字段定义（上半部分）

进入后台 → 用户扩展资料，页面上半部分是「字段定义」卡片：

字段类型：

分组：任意字符串，同分组字段在表单里会归到一起显示。默认分组有：基本档案、联系方式、户籍所在地、现居住地、祖籍/字派、个人简介。

2.2 用户资料管理（下半部分）

页面下半部分是「用户扩展资料」列表：

💡 字段定义改动后（新增/删除/启停），列表列会自动刷新，无需手动同步。

三、前台使用

3.1 自助编辑（登录用户）

GET  /userprofile/edit
POST /userprofile/save

• 未登录自动跳登录页
• 页面是完全独立的自包含 HTML，不依赖任何主题 layout
• 按分组动态渲染所有启用的字段
• 保存走 AJAX，返回 {"code":1,"msg":"保存成功"}

3.2 查看他人资料

GET /userprofile/view?uid=1

• 只渲染有值的字段和分组，没填的不显示
• 未填写任何扩展资料时显示"暂无资料"占位

3.3 任意页面取用户资料

use plugins\UserProfile\UserProfilePlugin;

// 拿某个用户的所有扩展资料（name => value 数组）
$profile = UserProfilePlugin::forUser($uid);

// 保存
UserProfilePlugin::saveForUser($uid, [
    'company' => 'XX 科技',
    'zp'      => '善朝德应福...',
]);

四、数据库

两张表，key-value 模式，新增字段不用改表结构：

-- 字段定义
user_profile_field (id, name, label, type, options, group_name, placeholder, required, sort, status, ...)

-- 用户字段值
user_profile_value (uid, field_id, field_name, value, update_time, PRIMARY KEY(uid, field_id))

userprofilevalue.field_name 是冗余字段，方便直接按名查值、做搜索。

五、文件结构

plugins/UserProfile/
├── plugin.json              # 插件元信息
├── icon.svg                 # 图标
├── install.sql              # 建表 SQL
├── UserProfilePlugin.php    # 主类 + API（fields / forUser / saveForUser / saveField / deleteField / seedDefaultFields）
├── routes.php               # 前台 + 后台路由注册
├── model/UserProfile.php
├── controller/
│   ├── Index.php            # 前台控制器（edit / save / view）
│   └── admin/
│       ├── Base.php         # 后台基类（重置 view_path + fetchPlugin）
│       ├── Field.php        # 字段定义管理（list / save / delete）
│       └── Profile.php      # 用户资料管理（index / list / edit / save / delete）
└── view/
    ├── admin/
    │   ├── index.html       # 后台主页面（上：字段定义卡片 + 下：资料列表，合并页）
    │   └── form.html        # 编辑某人资料（按分组动态渲染字段）
    └── index/
        ├── edit.html        # 前台自助编辑（独立自包含 HTML，动态字段）
        └── view.html        # 前台查看（只显示有值的分组）

六、常见问题

Q: 我新增了一个字段，前台怎么没显示？  

A: 检查字段是否「启用」状态（status=1），前台只渲染启用的字段。

Q: 前台页面样式和我主题不搭？  

A: 前台是自包含 HTML（用 Bootstrap 5 CDN），可以在主题的 /public/static/ 里加覆盖样式，或者直接改 view/index/edit.html。

Q: 怎么只让管理员看到某些字段？  

A: 目前前后台渲染相同。如果需要前台隐藏某些字段（如身份证号），可在 UserProfilePlugin::fields() 里加过滤，或用 {if $cfg.xxx} 做条件输出。

Q: 卸载插件会清数据吗？  

A: 会。卸载时 DROP 两张表。如果要保留数据，请先备份。