用户身份管理体系

# 用户身份管理体系设计文档

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-21
> **最后更新**: 2026-02-21
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

## 一、概述

### 1.1 设计目标

构建统一的用户身份管理体系，实现：
- 统一身份识别：跨端（PC、H5、小程序、APP）用户身份打通
- 多层级归属：用户 → 合作伙伴 → 企业 → 应用 → 角色
- 身份标签体系：管理身份 + 业务身份的标签化管理
- 花名册联动：通过企业花名册自动打标业务身份

### 1.2 核心概念

| 概念 | 说明 |
|------|------|
| **用户** | 在任意客户端进行过授权的用户（头像/昵称/手机号任一） |
| **潜在用户** | 仅有OpenID，未授权头像/昵称/手机号的用户 |
| **访客** | 未授权的访问者 |
| **身份标签** | 标识用户身份角色的标签（如管理员、HR、员工等） |
| **归属关系** | 用户与合作伙伴/企业/应用的关联关系 |

---

## 二、用户身份分级模型

### 2.1 身份等级定义

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        用户身份分级模型                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   访客 ────────→ 潜在用户 ────────→ 正式用户 ────────→ 活跃用户               │
│   (未授权)       (仅OpenID)        (头像/昵称/手机号)   (有活跃行为)          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 2.2 身份判定规则

| 等级 | 定义 | 授权条件 | 是否纳入用户池 | 能力范围 |
|------|------|----------|----------------|----------|
| **访客** | 未授权用户 | 无授权 | ❌ 不纳入 | 仅浏览公开内容 |
| **潜在用户** | 仅OpenID | 有OpenID，无头像/昵称/手机号 | ⚠️ 独立统计 | 基础访问，引导授权 |
| **正式用户** | 已授权 | 有头像 **或** 昵称 **或** 手机号 | ✅ 纳入 | 完整功能访问 |
| **活跃用户** | 正式+活跃 | 正式用户 + 近30天有登录 | ✅ 纳入 | 同正式用户 |
| **价值用户** | 正式+归属 | 正式用户 + 有企业归属 | ✅ 纳入 | 企业相关功能 |

### 2.3 授权行为与身份关系

| 授权行为 | 授权内容 | 身份判定 | 说明 |
|----------|----------|----------|------|
| 小程序静默登录 | 仅OpenID | 潜在用户 | 最小授权，仅识别身份 |
| 小程序getUserInfo | 头像+昵称 | 正式用户 | 满足任一即正式用户 |
| 小程序手机号授权 | 手机号 | 正式用户 | 高级授权，跨端识别 |
| 公众号扫码关注 | 仅OpenID | 潜在用户 | 未授权网页则为潜在 |
| 公众号网页授权 | 头像+昵称 | 正式用户 | snsapi_userinfo |
| H5手机号登录 | 手机号 | 正式用户 | 完整身份 |
| PC手机号注册 | 手机号 | 正式用户 | 完整身份 |

---

## 三、身份标签体系

### 3.1 标签分类

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                          用户身份标签体系                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   一、管理身份标签（系统角色，有管理权限）                                      │
│   ├── 平台级：super_admin / platform_admin                                  │
│   ├── 合作伙伴级：partner_owner / partner_admin / partner_operator          │
│   └── 企业级：company_owner / company_admin / company_hr                    │
│                                                                             │
│   二、业务身份标签（花名册角色，无管理权限）                                    │
│   ├── 员工：boss / hr / finance / manager / employee                        │
│   └── 外部：customer / supplier / partner                                   │
│                                                                             │
│   三、属性标签（用户属性特征）                                                 │
│   ├── 基础属性：vip / new_user / verified                                   │
│   ├── 行为属性：active_user / dormant_user / churned_user                   │
│   └── 渠道属性：miniapp_user / official_follower / qywx_user                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 3.2 管理身份标签定义

| 标签编码 | 标签名称 | 分类 | 权限级别 | 说明 |
|----------|----------|------|----------|------|
| `super_admin` | 超级管理员 | 平台 | 100 | 系统最高权限管理员 |
| `platform_admin` | 平台管理员 | 平台 | 90 | 平台运营管理员 |
| `partner_owner` | 合作伙伴所有者 | 合作伙伴 | 80 | 合作伙伴创建者 |
| `partner_admin` | 合作伙伴管理员 | 合作伙伴 | 70 | 合作伙伴管理权限 |
| `partner_operator` | 合作伙伴运营 | 合作伙伴 | 60 | 合作伙伴运营权限 |
| `company_owner` | 企业所有者 | 企业 | 50 | 企业老板 |
| `company_admin` | 企业管理员 | 企业 | 40 | 企业管理权限 |
| `company_hr` | 企业HR | 企业 | 30 | 企业人事权限 |

### 3.3 业务身份标签定义

| 标签编码 | 标签名称 | 分类 | 需花名册 | 说明 |
|----------|----------|------|----------|------|
| `boss` | 老板 | 员工 | ✅ | 企业老板/企业主 |
| `hr` | 人事专员 | 员工 | ✅ | 负责薪酬/招聘 |
| `finance` | 财务人员 | 员工 | ✅ | 负责薪酬发放 |
| `manager` | 部门经理 | 员工 | ✅ | 部门管理人员 |
| `employee` | 普通员工 | 员工 | ✅ | 普通员工 |
| `customer` | 客户 | 外部 | ❌ | 企业客户 |
| `supplier` | 供应商 | 外部 | ❌ | 供应商 |
| `partner` | 合作方 | 外部 | ❌ | 合作方 |

### 3.4 权限级别对照

```
权限级别越高，管理范围越大：

super_admin (100) ─── 全系统管理
    │
platform_admin (90) ─ 平台运营管理
    │
partner_owner (80) ── 合作伙伴全部权限
    │
partner_admin (70) ── 合作伙伴管理权限
    │
partner_operator (60)─ 合作伙伴运营权限
    │
company_owner (50) ── 企业全部权限
    │
company_admin (40) ── 企业管理权限
    │
company_hr (30) ───── 企业人事权限
    │
业务身份 (0) ───────── 无管理权限
```

---

## 四、数据模型

### 4.1 核心数据表

#### 4.1.1 用户表 (users)

```sql
CREATE TABLE users (
  id                VARCHAR(32) PRIMARY KEY,
  
  -- 核心标识（至少有一个）
  phone             VARCHAR(20) UNIQUE,
  phone_country     VARCHAR(10) DEFAULT '86',
  phone_bound_at    TIMESTAMP,
  
  -- 基础信息（至少有一个才算正式用户）
  nickname          VARCHAR(100),
  avatar            TEXT,
  name              VARCHAR(50),
  
  -- 其他信息
  gender            VARCHAR(10),
  birthday          DATE,
  id_card           VARCHAR(100),
  email             VARCHAR(100),
  
  -- 用户等级
  user_level        VARCHAR(20) DEFAULT 'formal',
  
  -- 身份标识（冗余字段）
  is_verified       BOOLEAN DEFAULT FALSE,
  has_company       BOOLEAN DEFAULT FALSE,
  is_admin          BOOLEAN DEFAULT FALSE,
  
  -- 状态
  status            VARCHAR(20) DEFAULT 'active',
  
  -- 注册信息
  register_channel  VARCHAR(20),
  register_scene    VARCHAR(50),
  register_type     VARCHAR(20),
  register_ip       VARCHAR(50),
  register_at       TIMESTAMP DEFAULT NOW(),
  
  -- 来源信息
  inviter_id        VARCHAR(32),
  utm_source        VARCHAR(100),
  utm_medium        VARCHAR(100),
  utm_campaign      VARCHAR(100),
  
  -- 活跃信息
  last_login_at     TIMESTAMP,
  last_login_channel VARCHAR(20),
  total_logins      INT DEFAULT 0,
  active_days       INT DEFAULT 0,
  
  -- 生命周期
  lifecycle_stage   VARCHAR(20) DEFAULT 'new',
  
  -- 时间戳
  created_at        TIMESTAMP DEFAULT NOW(),
  updated_at        TIMESTAMP DEFAULT NOW(),
  deleted_at        TIMESTAMP,
  
  CONSTRAINT valid_user CHECK (
    phone IS NOT NULL OR 
    nickname IS NOT NULL OR 
    avatar IS NOT NULL
  )
);
```

#### 4.1.2 潜在用户表 (potential_users)

```sql
CREATE TABLE potential_users (
  id                VARCHAR(32) PRIMARY KEY,
  
  unionid           VARCHAR(100),
  openid_miniapp    VARCHAR(100),
  openid_official   VARCHAR(100),
  qywx_userid       VARCHAR(100),
  
  nickname          VARCHAR(100),
  avatar            TEXT,
  
  source_channel    VARCHAR(20),
  first_visit_at    TIMESTAMP,
  last_visit_at     TIMESTAMP,
  visit_count       INT DEFAULT 1,
  
  upgrade_status    VARCHAR(20) DEFAULT 'pending',
  upgraded_at       TIMESTAMP,
  upgraded_to       VARCHAR(32),
  
  created_at        TIMESTAMP DEFAULT NOW()
);
```

#### 4.1.3 用户身份标签表 (user_identity_tags)

```sql
CREATE TABLE user_identity_tags (
  id                SERIAL PRIMARY KEY,
  user_id           VARCHAR(32) NOT NULL,
  
  -- 标签信息
  tag_code          VARCHAR(50) NOT NULL,
  tag_name          VARCHAR(100),
  tag_category      VARCHAR(20) NOT NULL,  -- admin/business
  
  -- 来源信息
  source            VARCHAR(20) NOT NULL,  -- system/roster/manual
  source_id         VARCHAR(32),
  
  -- 关联信息
  partner_id        VARCHAR(32),
  company_id        VARCHAR(32),
  app_id            VARCHAR(32),
  
  -- 扩展信息
  department        VARCHAR(100),
  position          VARCHAR(100),
  employee_no       VARCHAR(50),
  
  -- 花名册关联
  roster_id         VARCHAR(32),
  roster_sync_at    TIMESTAMP,
  
  -- 状态
  status            VARCHAR(20) DEFAULT 'active',
  is_primary        BOOLEAN DEFAULT FALSE,
  has_admin_perm    BOOLEAN DEFAULT FALSE,
  
  created_at        TIMESTAMP DEFAULT NOW(),
  updated_at        TIMESTAMP DEFAULT NOW(),
  expired_at        TIMESTAMP,
  
  UNIQUE(user_id, tag_code, company_id)
);
```

#### 4.1.4 身份标签定义表 (identity_tag_definitions)

```sql
CREATE TABLE identity_tag_definitions (
  id                SERIAL PRIMARY KEY,
  tag_code          VARCHAR(50) UNIQUE NOT NULL,
  tag_name          VARCHAR(100) NOT NULL,
  tag_category      VARCHAR(20) NOT NULL,
  
  sub_category      VARCHAR(50),
  is_admin_tag      BOOLEAN DEFAULT FALSE,
  permission_level  INT DEFAULT 0,
  
  description       TEXT,
  icon              VARCHAR(50),
  color             VARCHAR(20),
  
  is_system         BOOLEAN DEFAULT TRUE,
  is_multiple       BOOLEAN DEFAULT TRUE,
  need_roster       BOOLEAN DEFAULT FALSE,
  
  status            VARCHAR(20) DEFAULT 'active',
  sort_order        INT DEFAULT 0,
  
  created_at        TIMESTAMP DEFAULT NOW()
);
```

#### 4.1.5 企业花名册表 (company_roster)

```sql
CREATE TABLE company_roster (
  id                VARCHAR(32) PRIMARY KEY,
  company_id        VARCHAR(32) NOT NULL,
  
  employee_no       VARCHAR(50),
  name              VARCHAR(50) NOT NULL,
  phone             VARCHAR(20),
  email             VARCHAR(100),
  id_card           VARCHAR(100),
  
  department_id     VARCHAR(32),
  department_name   VARCHAR(100),
  position          VARCHAR(100),
  
  identity_role     VARCHAR(20),
  is_manager        BOOLEAN DEFAULT FALSE,
  
  hire_date         DATE,
  probation_end     DATE,
  regular_date      DATE,
  leave_date        DATE,
  
  status            VARCHAR(20) DEFAULT 'active',
  
  user_id           VARCHAR(32),
  user_bound_at     TIMESTAMP,
  
  source            VARCHAR(20),
  sync_at           TIMESTAMP,
  
  created_at        TIMESTAMP DEFAULT NOW(),
  updated_at        TIMESTAMP DEFAULT NOW()
);
```

#### 4.1.6 用户渠道绑定表 (user_channel_bindings)

```sql
CREATE TABLE user_channel_bindings (
  id                SERIAL PRIMARY KEY,
  user_id           VARCHAR(32) NOT NULL,
  
  channel_type      VARCHAR(20) NOT NULL,  -- official/miniapp/qywx/app
  channel_openid    VARCHAR(100),
  channel_unionid   VARCHAR(100),
  
  is_bound          BOOLEAN DEFAULT TRUE,
  bound_at          TIMESTAMP,
  unbound_at        TIMESTAMP,
  
  is_following      BOOLEAN,
  follow_at         TIMESTAMP,
  unfollow_at       TIMESTAMP,
  
  nickname          VARCHAR(100),
  avatar            TEXT,
  
  last_interaction_at TIMESTAMP,
  channel_data      JSONB,
  
  created_at        TIMESTAMP DEFAULT NOW(),
  updated_at        TIMESTAMP DEFAULT NOW(),
  
  UNIQUE(user_id, channel_type)
);
```

#### 4.1.7 用户归属关系表 (user_belongings)

```sql
CREATE TABLE user_belongings (
  id                SERIAL PRIMARY KEY,
  user_id           VARCHAR(32) NOT NULL,
  
  partner_id        VARCHAR(32),
  company_id        VARCHAR(32),
  app_id            VARCHAR(32),
  
  role              VARCHAR(20) NOT NULL,
  role_data         JSONB,
  
  terminals         VARCHAR[] DEFAULT '{}',
  
  status            VARCHAR(20) DEFAULT 'active',
  created_by        VARCHAR(32),
  
  expired_at        TIMESTAMP,
  last_active_at    TIMESTAMP,
  
  created_at        TIMESTAMP DEFAULT NOW(),
  
  UNIQUE(user_id, partner_id, company_id, app_id)
);
```

### 4.2 数据表关系图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              数据实体关系                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────┐       ┌─────────────┐       ┌─────────────┐             │
│   │  partners   │       │ companies   │       │   apps      │             │
│   │  合作伙伴    │←─────│   企业      │←─────│   应用      │             │
│   └─────────────┘       └─────────────┘       └─────────────┘             │
│         │                     │                     │                     │
│         └─────────────────────┼─────────────────────┘                     │
│                               │                                             │
│                               ▼                                             │
│                      ┌─────────────────┐                                   │
│                      │ user_belongings │                                   │
│                      │   用户归属       │                                   │
│                      └─────────────────┘                                   │
│                               │                                             │
│                               ▼                                             │
│   ┌─────────────────────────────────────────────────────────────────────┐ │
│   │                           用户体系                                   │ │
│   │                                                                     │ │
│   │   ┌───────────┐    ┌───────────┐    ┌───────────┐                  │ │
│   │   │  users    │    │ potential │    │  visitor  │                  │ │
│   │   │ 正式用户   │    │  _users   │    │   _logs   │                  │ │
│   │   └───────────┘    └───────────┘    └───────────┘                  │ │
│   │         │                                                         │ │
│   │         ├──────────────────────────────────────┐                  │ │
│   │         ▼                                      ▼                  │ │
│   │   ┌───────────┐                        ┌───────────┐              │ │
│   │   │ user_     │                        │ identity_ │              │ │
│   │   │ channels  │                        │ tags      │              │ │
│   │   │ 渠道绑定   │                        │ 身份标签   │              │ │
│   │   └───────────┘                        └───────────┘              │ │
│   │                                                                     │ │
│   └─────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 五、身份标签获取流程

### 5.1 管理身份标签获取

```
场景1：合作伙伴注册
用户注册合作伙伴 → 创建合作伙伴记录 → 自动获得 partner_owner 身份标签

场景2：邀请管理员
合作伙伴邀请成员 → 输入手机号/邮箱 → 查找/创建用户 → 分配身份标签
                                                    │
                                                    ▼
                                          user_identity_tags
                                          - tag_code: partner_admin
                                          - source: system
                                          - has_admin_perm: TRUE

场景3：企业管理员分配
企业管理员邀请 → 添加管理员信息 → 查找/创建用户 → 分配身份标签
                                                    │
                                                    ▼
                                          user_identity_tags
                                          - tag_code: company_hr
                                          - source: system
                                          - has_admin_perm: TRUE
```

### 5.2 业务身份标签自动打标（花名册同步）

```
步骤1：导入花名册
HR上传Excel或通过API同步
┌─────────────────────────────────────────────────────────────┐
│ 姓名    │ 手机号      │ 部门     │ 职位      │ 身份角色      │
├─────────────────────────────────────────────────────────────┤
│ 张三    │ 13812345678 │ 总经办   │ CEO       │ boss         │
│ 李四    │ 13823456789 │ 人事部   │ HR主管    │ hr           │
│ 王五    │ 13834567890 │ 财务部   │ 财务经理  │ finance      │
└─────────────────────────────────────────────────────────────┘

步骤2：匹配用户
花名册记录 → 手机号匹配 → users表查询 → 找到用户？
                                    │
                    ┌───────────────┴───────────────┐
                    │                               │
                 找到                            未找到
                    │                               │
                    ▼                               ▼
              关联用户                      创建待激活账号
              user_id                       等待用户注册后自动绑定

步骤3：创建身份标签
INSERT INTO user_identity_tags (
  user_id,           -- 用户ID
  tag_code,          -- 'hr' / 'boss' / 'employee'
  tag_name,          -- '人事专员' / '老板' / '普通员工'
  tag_category,      -- 'business'
  source,            -- 'roster'
  company_id,        -- 企业ID
  department,        -- 部门名称
  position,          -- 职位
  roster_id,         -- 花名册记录ID
  roster_sync_at     -- 同步时间
)
```

---

## 六、API接口设计

### 6.1 用户身份API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/user/identity-tags` | 获取当前用户身份标签 |
| GET | `/api/v1/user/profile` | 获取用户信息 |
| PUT | `/api/v1/user/profile` | 更新用户信息 |

### 6.2 管理后台API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/admin/users` | 用户列表 |
| GET | `/api/admin/users/:id` | 用户详情 |
| PUT | `/api/admin/users/:id` | 更新用户 |
| PUT | `/api/admin/users/:id/status` | 更新状态 |
| GET | `/api/admin/users/stats` | 用户统计 |
| GET | `/api/admin/potential-users` | 潜在用户列表 |
| GET | `/api/admin/users/:id/identity-tags` | 获取用户身份标签 |
| POST | `/api/admin/users/:id/identity-tags` | 添加身份标签 |
| DELETE | `/api/admin/users/:id/identity-tags/:tagId` | 删除身份标签 |

### 6.3 身份标签管理API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/identity-tags` | 获取身份标签列表 |
| GET | `/api/v1/identity-tags/:code` | 获取标签详情 |
| POST | `/api/admin/identity-tags` | 创建身份标签 |

### 6.4 花名册同步API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/admin/companies/:id/roster/import` | 导入花名册 |
| GET | `/api/admin/companies/:id/roster` | 获取花名册列表 |
| POST | `/api/admin/companies/:id/roster/sync` | 触发身份标签同步 |
| GET | `/api/admin/companies/:id/roster/sync-status` | 同步状态 |

---

## 七、前端页面设计

### 7.1 管理后台菜单结构

```
平台管理
├── 基础设置
│   ├── 基础设置
│   ├── 品牌设置
│   ├── 安全设置
│   └── SEO设置
├── 数据设置
│   ├── 图片管理
│   ├── 数据管理
│   ├── 数据备份
│   └── 程序备份
├── 通知服务
│   ├── 邮件功能
│   └── 短信功能
├── 集成配置
│   └── ...
├── 渠道管理
│   └── ...
├── 用户管理 (新增)
│   ├── 用户列表
│   ├── 潜在用户
│   ├── 身份标签
│   └── 归属管理
├── 员工权限
└── 项目记忆
```

### 7.2 用户列表页

**功能要点**：
- 筛选：用户类型、身份标签、企业、状态
- 搜索：姓名、手机号、昵称
- 列表展示：基本信息、身份标签、归属企业、渠道绑定状态
- 操作：查看详情、编辑、禁用、分配归属

### 7.3 用户详情页

**信息区域**：
- 基本信息：用户ID、手机号、昵称、真实姓名、用户等级
- 绑定状态：手机号、公众号、小程序、企业微信
- 身份标签：管理身份、业务身份
- 归属关系：合作伙伴、企业、应用、角色
- 花名册信息：部门、职位、工号
- 登录记录：最近登录历史

### 7.4 身份标签管理页

**功能要点**：
- 标签分类展示：管理身份、业务身份、属性标签
- 标签定义：编码、名称、分类、权限级别
- 用户统计：每个标签关联的用户数
- 操作：新增、编辑、删除（系统标签不可删除）

---

## 八、实施路线图

### 阶段一：基础建设 (P0)

| 任务 | 说明 |
|------|------|
| 数据库表创建 | users, potential_users, user_identity_tags 等 |
| 核心API开发 | 用户注册登录、身份标签查询 |
| 基础管理后台 | 用户列表、用户详情、潜在用户列表 |
| 微信生态对接 | 小程序授权、公众号网页授权、回调处理 |

### 阶段二：身份标签 (P1)

| 任务 | 说明 |
|------|------|
| 身份标签表创建 | identity_tag_definitions, user_identity_tags |
| 花名册表创建 | company_roster |
| 花名册导入功能 | Excel导入、API同步 |
| 自动打标逻辑 | 花名册同步自动创建身份标签 |

### 阶段三：完善优化 (P2)

| 任务 | 说明 |
|------|------|
| 权限控制 | 基于身份标签的权限验证 |
| 数据统计 | 用户统计面板、转化漏斗 |
| 性能优化 | 缓存策略、分表分区 |

---

## 九、附录

### 9.1 相关文档

- [系统架构](./系统架构.md)
- [数据库字典](../05-数据库/数据库字典.md)
- [API接口文档](../04-API文档/API接口文档.md)

### 9.2 更新日志

| 日期 | 版本 | 更新内容 |
|------|------|----------|
| 2026-02-21 | v1.0.0 | 初始版本，完成用户身份管理体系设计 |

---

**文档维护**: 未来鸟FutureBird码巢企业服务引擎开发组
**最后更新**: 2026-02-21