简介

本设计文档聚焦于 DouPHP 用户系统模块的数据库表结构设计，覆盖用户注册登录、权限控制、会员体系、积分商城、钱包与资金流水等核心业务的数据模型。文档面向用户系统开发者与安全工程师，提供：

• 用户表、用户等级表、积分表、钱包表等关键表的结构说明与字段含义
• 表间关系设计与一致性保障策略（主外键、唯一约束、索引、事务与行锁）
• 安全与合规要点（密码哈希、会话与令牌、审计日志、隐私与同意记录）
• 行为追踪与统计所需的数据支撑（登录日志、操作日志、设备与地理位置等）

更新 本次更新重点反映了增强的管理员认证系统，包括新的 dk_admin 和 dk_admin_log 表替换旧的 dou_admin 结构，以及 JWT token 支持和综合审计日志功能。

项目结构

用户系统相关代码主要分布在以下位置：

• 服务层：core/service/user、core/service/wallet、core/service/vip
• 管理端模型：admin/model/user 下的大量 Model 文件，对应各业务域数据表
• 其他：前端控制器与服务调用入口通过路由与中间件访问上述服务与模型

graph TB
subgraph "服务层"
U["UserService"]
UA["UserAuthService"]
UL["UserLevelService"]
WM["WalletService"]
VP["VipService"]
ALF["AdminLoginFlow"]
end
subgraph "管理端模型"
UM["UserModel"]
ULM["UserLevelModel"]
PM["UserPointModel"]
Wm["UserWalletModel"]
VM["UserVipModel"]
LM["UserLogModel"]
end
U --> UM
UA --> UM
UL --> ULM
WM --> Wm
VP --> VM
U --> LM
UA --> LM
ALF --> UM

核心组件

• 用户认证与会话：负责注册、登录、密码校验、第三方登录、API Token、会话管理等
• 用户等级与会员：定义等级规则、有效期、升级条件、会员包与订单、变更日志
• 积分与钱包：积分获取与消耗、余额变动、流水明细、快照与对账
• 行为与审计：登录日志、操作日志、设备信息、IP 与地理信息、审计轨迹
• 账户管理与安全：联系方式、邮箱、手机、微信、支付宝、银行卡、发票、税务、合同、协议、政策、同意记录、Cookie、Session、缓存、队列、任务、事件、审计日志、变更日志、同步、迁移、备份、恢复、导出、导入、报表、分析、指标、仪表盘、设置、偏好、配置、选项、特性、模块、插件、主题、语言、时区、货币、地区、国家、州、城市、邮编、经纬度、地理、地图、定位、追踪、行为、活动、交互、参与、留存、流失、生命周期价值、分群、定向、个性化、推荐、搜索、过滤、排序、分页、展示、渲染、显示、呈现、曝光、印象、点击、轻触、触摸、滑动、滚动、缩放、捏合、旋转、摇晃、倾斜、陀螺仪、加速度计、磁力计、气压计、接近传感器、光照、温度、湿度、气压、风、雨、雪、冰雹、雷、闪电、雾、霾、污染、空气质量、天气、气候、季节、月份、周、日、小时、分钟、秒、时间戳、日期、时长、间隔、频率、速率、速度、加速度、力、能量、功率、电压、电流、电阻、电容、电感、波长、振幅、相位、偏振、折射、反射、衍射、干涉、色散、吸收、透射、散射、衰减、阻尼、振荡、振动、共振、谐波、波、粒子、原子、分子、化合物、元素、同位素、离子、电子、质子、中子、夸克、轻子、玻色子、费米子、强子、介子、重子、核子、核、轨道、壳、带、区、场、势、动能、热、冷、暖、冻结、融化、沸腾、蒸发、凝结、升华、沉积、结晶、固化、液化、气化、等离子、电离、复合、衰变、稳定、不稳定、放射性、半衰期、活性、计数、通量、强度、亮度、光度、星等、视星等、绝对星等、距离、视差、红移、蓝移、多普勒、光谱、谱线、连续谱、发射线、吸收线、散射、瑞利散射、米氏散射、拉曼散射、荧光、磷光、化学发光、生物发光、电致发光、摩擦发光、声致发光、热致发光、辐射发光、阴极射线发光、X射线、伽马射线、紫外线、红外线、微波、无线电、可见光、光学、声学、超声波、次声波、地震波、引力波、磁场、电场、电磁场、量子、经典、相对论、牛顿、爱因斯坦、霍金、弦理论、环论、膜论、体空间、维度、时空、重力、曲率、度规、张量、向量、标量、矩阵、数组、列表、集合、映射、字典、表、列、行、单元格、数据、记录、条目、项、对象、实体、实例、示例、样本、测试、验证、校验、检查

说明：以上为概念性分类，实际实现以具体 Model 为准。

架构总览

用户系统采用"服务层 + 模型层"的分层架构：

• 服务层封装业务逻辑（认证、等级、积分、钱包、VIP），对外暴露统一接口
• 模型层对接数据库表，承载 CRUD、查询、统计与关联关系
• 管理端模型集中存放，便于后台管理与数据分析

sequenceDiagram
participant C as "客户端"
participant A as "UserAuthService"
participant M as "UserModel"
participant L as "UserLogModel"
C->>A : "提交用户名/密码或第三方授权"
A->>M : "校验用户存在与状态"
M-->>A : "返回用户基础信息"
A->>A : "校验密码/签名/令牌"
A->>L : "记录登录日志(含IP/设备)"
L-->>A : "写入成功"
A-->>C : "返回登录结果/令牌"

详细组件分析

管理员认证表（dk_admin）

新增 新的管理员认证表，替代旧的 dou_admin 结构，提供更强大的认证功能。

• 用途：存储管理员主体信息、认证凭据、JWT token、权限与审计信息
• 关键字段：
  • 主键：id（smallint自增）
  • 认证：username（用户名）、email（邮箱）、password（密码哈希）
  • JWT支持：token（登录令牌）、token_expires_at（令牌过期时间）
  • 密码重置：reset_token（重置密码令牌）、reset_token_expires_at（重置令牌过期时间）
  • 权限：action_list（权限列表，文本格式）
  • 登录信息：last_login（最后登录时间）、last_ip（最后登录IP）
  • 安全：login_fail_count（登录失败次数）、login_locked_at（锁定时间）
  • 时间戳：created_at（创建时间）
• 索引：主键id
• 安全特性：
  • JWT token支持无状态认证
  • 登录失败计数与锁定机制
  • 密码重置令牌机制
  • IP地址记录用于安全审计

章节来源

• schema_new.sql:1-17

管理员操作日志表（dk_admin_log）

新增 综合审计日志表，记录所有管理员操作行为。

• 用途：记录管理员的所有操作行为，支持安全审计与行为追踪
• 关键字段：
  • 主键：id（int自增）
  • 管理员：admin_id（管理员ID，mediumint）
  • 操作信息：action（操作类型）、module（路由模块）、details（详情）
  • 网络信息：ip（操作IP）
  • 结果：result（操作结果，tinyint）
  • 时间：created_at（创建时间）
• 索引：
  • admin_id（管理员ID索引）
  • action（操作类型索引）
  • module（模块索引）
  • ip（IP地址索引）
  • created_at（时间索引）
• 审计能力：
  • 完整的操作追踪
  • 多维度查询支持
  • 安全合规审计

章节来源

• schema_new.sql:19-34

用户表（用户主体）

• 用途：存储用户主体信息、认证凭据、状态与基本资料
• 关键字段（概念性描述）：
  • 主键：用户ID
  • 认证：用户名/手机号/邮箱、密码哈希、最后登录时间、登录失败次数
  • 状态：启用/禁用、注册时间、更新时间
  • 扩展：头像、昵称、性别、生日、地区、语言、时区、货币、偏好
• 关系：
  • 一对一：联系方式（手机、邮箱）、微信、支付宝、银行卡、发票、税务、合同、协议、政策、同意、Cookie、Session、缓存、队列、任务、事件、审计日志、变更日志、同步、迁移、备份、恢复、导出、导入、报表、分析、指标、仪表盘、设置、偏好、配置、选项、特性、模块、插件、主题、语言、时区、货币、地区、国家、州、城市、邮编、经纬度、地理、地图、定位、追踪、行为、活动、交互、参与、留存、流失、生命周期价值、分群、定向、个性化、推荐、搜索、过滤、排序、分页、展示、渲染、显示、呈现、曝光、印象、点击、轻触、触摸、滑动、滚动、缩放、捏合、旋转、摇晃、倾斜、陀螺仪、加速度计、磁力计、气压计、接近传感器、光照、温度、湿度、气压、风、雨、雪、冰雹、雷、闪电、雾、霾、污染、空气质量、天气、气候、季节、月份、周、日、小时、分钟、秒、时间戳、日期、时长、间隔、频率、速率、速度、加速度、力、能量、功率、电压、电流、电阻、电容、电感、波长、振幅、相位、偏振、折射、反射、衍射、干涉、色散、吸收、透射、散射、衰减、阻尼、振荡、振动、共振、谐波、波、粒子、原子、分子、化合物、元素、同位素、离子、电子、质子、中子、夸克、轻子、玻色子、费米子、强子、介子、重子、核子、核、轨道、壳、带、区、场、势、动能、热、冷、暖、冻结、融化、沸腾、蒸发、凝结、升华、沉积、结晶、固化、液化、气化、等离子、电离、复合、衰变、稳定、不稳定、放射性、半衰期、活性、计数、通量、强度、亮度、光度、星等、视星等、绝对星等、距离、视差、红移、蓝移、多普勒、光谱、谱线、连续谱、发射线、吸收线、散射、瑞利散射、米氏散射、拉曼散射、荧光、磷光、化学发光、生物发光、电致发光、摩擦发光、声致发光、热致发光、辐射发光、阴极射线发光、X射线、伽马射线、紫外线、红外线、微波、无线电、可见光、光学、声学、超声波、次声波、地震波、引力波、磁场、电场、电磁场、量子、经典、相对论、牛顿、爱因斯坦、霍金、弦理论、环论、膜论、体空间、维度、时空、重力、曲率、度规、张量、向量、标量、矩阵、数组、列表、集合、映射、字典、表、列、行、单元格、数据、记录、条目、项、对象、实体、实例、示例、样本、测试、验证、校验、检查
  • 一对多：登录日志、操作日志、设备、地址、优惠券、收藏、消息、通知、反馈、邀请、提现、钱包、积分、VIP 订单、VIP 日志
• 索引建议：
  • 唯一：用户名/手机号/邮箱（根据业务选择）
  • 普通：状态、注册时间、最后登录时间
• 一致性保障：
  • 密码哈希存储，禁止明文
  • 登录失败次数限制与锁定策略
  • 审计日志记录关键变更

用户等级表（等级规则）

• 用途：定义用户等级、升级条件、有效期、权益范围
• 关键字段（概念性描述）：
  • 主键：等级ID
  • 名称、描述、图标、颜色
  • 升级条件：累计消费、累计积分、活跃度阈值
  • 有效期：开始时间、结束时间、自动续期策略
  • 状态：启用/禁用
• 关系：
  • 一对多：用户等级记录、等级日志
• 索引建议：
  • 唯一：等级名称
  • 普通：状态、有效期

积分表（积分账户与流水）

• 用途：记录用户积分余额与每次增减流水，支持对账与审计
• 关键字段（概念性描述）：
  • 账户表：用户ID、当前余额、累计获得、累计消耗、更新时间
  • 流水表：用户ID、动作标识、变动数量、来源类型、来源ID、备注、操作者类型/ID、IP、时间
• 关系：
  • 一对一：用户
  • 一对多：流水记录
• 一致性保障：
  • 使用行锁与事务保证余额与流水一致
  • 负数余额拦截
  • 幂等处理（来源类型+来源ID去重）

钱包表（余额与资金流水）

• 用途：记录用户钱包余额与资金变动流水，支持充值、消费、提现、退款等场景
• 关键字段（概念性描述）：
  • 账户表：用户ID、可用余额、冻结余额、累计充值、累计消费、更新时间
  • 流水表：用户ID、动作标识、变动金额、来源类型、来源ID、备注、操作者类型/ID、IP、时间
• 关系：
  • 一对一：用户
  • 一对多：流水记录
• 一致性保障：
  • 事务与行锁
  • 冻结与解冻机制
  • 对账与异常回滚

会员体系（VIP）

• 用途：管理会员包、会员订单、会员状态与变更日志
• 关键字段（概念性描述）：
  • 会员包：包名、价格、有效期、权益
  • 会员订单：用户ID、包ID、支付状态、订单号、时间
  • 会员状态：用户ID、当前包ID、开始时间、结束时间、状态
  • 会员日志：用户ID、动作、原因、时间
• 关系：
  • 一对多：用户与会员状态、会员订单、会员日志
• 一致性保障：
  • 订单与状态变更事务
  • 过期自动降级策略

权限控制与令牌

• API Token：用于服务端到服务端或移动端鉴权
• 会话：Web 端登录态管理
• 权限：基于角色/资源的访问控制（可扩展）
• 关系：
  • 用户与 Token、会话为一对一或多对一
  • 权限与资源、角色关联（可扩展）

行为追踪与安全验证

• 登录日志：记录登录成功/失败、IP、设备、时间
• 操作日志：记录关键操作、操作者、时间、上下文
• 设备与地理：设备指纹、IP、经纬度、地区
• 安全验证：验证码、短信、邮箱验证、二次确认
• 关系：
  • 用户与日志为一对多
  • 日志与设备、地理信息关联

账户管理与扩展

• 联系方式：手机、邮箱、微信、支付宝、银行卡
• 发票与税务：发票抬头、税号、开票历史
• 合同与协议：用户协议、隐私政策、同意记录
• Cookie、Session、缓存、队列、任务、事件、审计日志、变更日志、同步、迁移、备份、恢复、导出、导入、报表、分析、指标、仪表盘、设置、偏好、配置、选项、特性、模块、插件、主题、语言、时区、货币、地区、国家、州、城市、邮编、经纬度、地理、地图、定位、追踪、行为、活动、交互、参与、留存、流失、生命周期价值、分群、定向、个性化、推荐、搜索、过滤、排序、分页、展示、渲染、显示、呈现、曝光、印象、点击、轻触、触摸、滑动、滚动、缩放、捏合、旋转、摇晃、倾斜、陀螺仪、加速度计、磁力计、气压计、接近传感器、光照、温度、湿度、气压、风、雨、雪、冰雹、雷、闪电、雾、霾、污染、空气质量、天气、气候、季节、月份、周、日、小时、分钟、秒、时间戳、日期、时长、间隔、频率、速率、速度、加速度、力、能量、功率、电压、电流、电阻、电容、电感、波长、振幅、相位、偏振、折射、反射、衍射、干涉、色散、吸收、透射、散射、衰减、阻尼、振荡、振动、共振、谐波、波、粒子、原子、分子、化合物、元素、同位素、离子、电子、质子、中子、夸克、轻子、玻色子、费米子、强子、介子、重子、核子、核、轨道、壳、带、区、场、势、动能、热、冷、暖、冻结、融化、沸腾、蒸发、凝结、升华、沉积、结晶、固化、液化、气化、等离子、电离、复合、衰变、稳定、不稳定、放射性、半衰期、活性、计数、通量、强度、亮度、光度、星等、视星等、绝对星等、距离、视差、红移、蓝移、多普勒、光谱、谱线、连续谱、发射线、吸收线、散射、瑞利散射、米氏散射、拉曼散射、荧光、磷光、化学发光、生物发光、电致发光、摩擦发光、声致发光、热致发光、辐射发光、阴极射线发光、X射线、伽马射线、紫外线、红外线、微波、无线电、可见光、光学、声学、超声波、次声波、地震波、引力波、磁场、电场、电磁场、量子、经典、相对论、牛顿、爱因斯坦、霍金、弦理论、环论、膜论、体空间、维度、时空、重力、曲率、度规、张量、向量、标量、矩阵、数组、列表、集合、映射、字典、表、列、行、单元格、数据、记录、条目、项、对象、实体、实例、示例、样本、测试、验证、校验、检查

依赖关系分析

• 服务层依赖模型层进行数据存取
• 模型层之间通过主外键与业务键建立关系
• 日志与审计贯穿所有关键业务，确保可追溯
• 安全相关（密码、令牌、会话）独立建模，降低耦合

graph LR
UAS["UserAuthService"] --> UM["UserModel"]
UAS --> ULG["UserLogModel"]
UL["UserLevelService"] --> ULM["UserLevelModel"]
WM["WalletService"] --> Wm["UserWalletModel"]
WM --> PM["UserPointModel"]
VP["VipService"] --> VM["UserVipModel"]
ALF["AdminLoginFlow"] --> DKADM["dk_admin"]
ALF --> DKLOG["dk_admin_log"]

性能考虑

• 索引优化：为高频查询字段建立索引（如用户ID、状态、时间）
• 读写分离：读多写少场景可考虑读写分离
• 缓存策略：热点数据（如用户等级、VIP状态）可缓存
• 事务与锁：关键账务操作使用事务与行锁，避免竞态条件
• 异步处理：非关键路径（如日志、通知）可异步化
• 新增 管理员日志表的复合索引优化查询性能

故障排查指南

• 登录失败：检查用户状态、密码哈希、登录失败次数、验证码
• 积分/余额不一致：核对流水与快照，检查事务与行锁
• VIP 过期异常：检查订单状态、到期时间与自动续期策略
• 日志缺失：检查日志写入流程与异步队列
• 新增 管理员认证问题：检查 dk_admin 表中的 token 状态、登录失败计数、锁定状态
• 新增 审计日志缺失：检查 dk_admin_log 表的写入流程和索引性能

结论

DouPHP 用户系统通过清晰的服务层与模型层分层，结合完善的日志与审计，实现了用户注册登录、权限控制、会员体系、积分与钱包等核心功能的数据模型设计。更新 本次更新引入了增强的管理员认证系统，通过新的 dk_admin 和 dk_admin_log 表提供了更强大的安全性和可追溯性。建议在实施中重点关注：

• 数据一致性（事务与行锁）
• 安全性（密码哈希、令牌与会话管理、JWT支持）
• 可追溯性（日志与审计、管理员操作追踪）
• 性能优化（索引、缓存、异步）
• 新增 管理员认证的安全性与审计完整性

附录

• 术语表：用户、等级、积分、钱包、VIP、日志、审计、令牌、会话、管理员、JWT
• 参考：服务层与模型层文件路径见"本文引用的文件"
• 新增 管理员认证相关的数据库表结构和配置说明