x-server-mobile/docs/modules/user/README.md

用户管理模块 (User Module)

概述

用户管理模块负责用户信息、多租户公司管理、权限控制等功能。

---

核心功能

功能	说明	状态
用户信息	获取、更新用户信息	✅
多租户支持	用户可关联多个公司	✅
公司切换	切换当前公司	⏳ 待实现
权限控制	基于角色的权限管理	⏳ 待实现
密码修改	修改登录密码	✅

---

API 接口

接口	方法	说明
/api/v1/user/info	GET	获取用户信息
/api/v1/user/menu	GET	获取用户菜单
/api/v1/user/companies	GET	获取用户公司列表
/api/v1/user/switch-company	POST	切换公司
/api/v1/user/change-password	POST	修改密码
/api/v1/user/list	GET	获取用户列表（管理员）

---

前端关键文件

frontend/src/
├── pages/
│   ├── profile/          # 个人中心
│   └── change-password/  # 修改密码
├── stores/
│   └── user.ts           # 用户状态管理
└── components/
     └── CompanySelector/ # 公司选择器（待实现）

---

后端关键文件

backend/app/
├── Controller/
│   └── UserController.php    # 用户控制器
├── Model/
│   ├── User.php              # 用户模型
│   └── Company.php           # 公司模型
└── Middleware/
    └── AuthMiddleware.php    # 认证中间件

---

多租户设计

用户-公司关系

user (用户)
  ├── user_company (用户公司关联)
  │     ├── company_id
  │     ├── is_default       -- 是否默认公司
  │     └── role             -- 在该公司的角色
  └── ...

切换公司流程

1. 用户选择公司
  ↓
2. 前端调用 /api/v1/user/switch-company
  ↓
3. 后端验证用户权限
  ↓
4. 更新 token 中的 company_id
  ↓
5. 返回新的 token
  ↓
6. 前端更新本地存储和状态

---

用户状态管理 (Zustand)

interface UserStore {
  user: User | null
  token: string | null
  login: (user: User, token: string) => void
  logout: () => void
  updateUser: (user: User) => void
}

// 使用
const { user, login, logout } = useUserStore()

---

Token 结构

{
  "user_id": 1,
  "company_id": 2,
  "feishu_user_id": "ou_xxx",
  "union_id": "on_xxx",
  "exp": 1234567890
}

---

数据库表结构

user (用户)

id                  -- 主键
username            -- 用户名（登录用）
email               -- 邮箱
phone               -- 手机号
name                -- 姓名
avatar              -- 头像
password            -- 密码（加密）
feishu_user_id      -- 飞书用户ID
feishu_union_id     -- 飞书union_id
created_at
updated_at

company (公司)

id                  -- 主键
name                -- 公司名称
logo                -- 公司logo
status              -- 状态

user_company (用户公司关联)

id                  -- 主键
user_id             -- 用户ID
company_id          -- 公司ID
role                -- 角色
is_default          -- 是否默认公司
created_at

---

权限设计（待实现）

角色类型

角色	代码	说明
超级管理员	super_admin	全部权限
公司管理员	company_admin	公司内全部权限
普通用户	user	基础权限

---

相关文档

• 认证模块
• 数据库分析

---

负责人: 待分配 最后更新: 2026-02-28