引言

本设计文档面向数据库设计师与后端开发者，系统化梳理 DouPHP 的核心业务表结构，覆盖用户、商品、订单、文章等关键实体；明确字段定义、数据类型选择、约束条件与索引策略；阐述主外键关系、一对一/一对多/多对多的实现方式；总结命名规范、注释标准与特殊字段（JSON、时间、状态码）的设计考量；并提供表结构变更管理与版本控制建议。

更新 本次更新重点介绍了用户数据表的三表分离架构设计，通过基础用户信息表、扩展属性数据表和高级功能数据表的分离，实现了更清晰的数据层次结构和更好的扩展性。

项目结构

• 数据库脚本集中存放于模块的 storage/backup 目录以及开发手册的系统表结构文件中，便于按模块拆分与维护。
• 核心业务域包括：用户中心、商品与类目、订单与支付、内容（文章/案例）、营销（优惠券/VIP/积分/余额）、基础数据（品牌/区域/属性）。

graph TB
subgraph "用户域"
U["dou_user<br/>基础用户信息"]
UE["dou_user_wallet<br/>用户钱包"]
UT["dou_user_tag<br/>用户标签"]
UC["dou_user_contact<br/>联系人"]
UL["dou_user_level<br/>等级"]
US["dou_user_sns<br/>第三方绑定"]
end
subgraph "商品域"
P["dou_product"]
PC["dou_product_category"]
B["dou_brand"]
A["dou_attribute / dou_attribute_value"]
end
subgraph "订单域"
O["dou_order"]
OI["dou_order_item"]
OA["dou_order_address"]
OP["dou_order_payment"]
OR["dou_order_refund"]
OS["dou_order_status_log"]
end
subgraph "内容域"
AR["dou_article"]
ARC["dou_article_category"]
CM["dou_comment"]
end
subgraph "营销域"
C["dou_coupon"]
VP["dou_vip_package"]
V["dou_vip"]
M["dou_money"]
PT["dou_point"]
end
subgraph "基础数据"
AREA["dou_area"]
end
U --> O
U --> CM
U --> UE
U --> UT
U --> UC
U --> UL
U --> US
P --> OI
PC --> P
B --> P
A --> P
O --> OI
O --> OA
O --> OP
O --> OR
O --> OS
AR --> ARC
CM --> OI
C --> O
VP --> V
U --> V
U --> M
U --> PT
AREA --> U

核心组件

• 用户域：会员主体、联系人、等级、钱包、日志、第三方绑定、标签、API Token。
• 商品域：商品、类目、品牌、属性及属性值。
• 订单域：订单主表、订单项、收货地址、支付流水、退款、状态日志。
• 内容域：文章、文章分类、评论。
• 营销域：优惠券、VIP套餐与购买记录、余额流水、积分流水。
• 基础数据：区域字典。

更新 用户域现在采用三表分离架构：

• 基础用户信息表（dou_user）：存储核心用户身份信息和基本资料
• 扩展属性数据表（dou_user_wallet、dou_user_tag等）：存储用户的扩展属性和功能数据
• 高级功能数据表（dou_user_level、dou_user_sns等）：存储用户的高级功能和关联数据

架构总览

• 统一前缀：所有业务表以 dou_ 前缀命名，避免与其他系统冲突。
• 主键策略：普遍使用自增整型主键 id，部分表使用业务编号作为唯一键（如 order_sn、payment_sn、refund_sn、user_sn）。
• 时间字段：统一采用 datetime 类型存储创建/更新时间，便于查询与展示；历史快照类字段（如 add_time）在部分旧表中仍保留为时间戳，新表优先使用 datetime。
• 金额字段：统一使用 decimal(10,2) 或更高精度，避免浮点误差。
• 状态字段：广泛使用 tinyint/tinyint(1) 表示开关或枚举状态；复杂状态机使用 varchar 字符串（如订单状态、支付状态），配合索引优化查询。
• JSON 字段：用于灵活扩展配置与元数据（如 attributes、config、metadata），兼顾可读性与扩展性。
• 索引策略：针对高频查询维度建立复合索引（如 user_id+status、status+created_at、pay_id+status+paid_at 等）。

更新 三表分离架构的优势：

• 基础表保持精简，提高核心查询性能
• 扩展表支持灵活的属性扩展，无需频繁修改表结构
• 功能表独立管理特定业务功能，便于维护和升级

详细组件分析

用户域 - 三表分离架构

基础用户信息表（dou_user）

更新 这是用户数据的核心表，采用精简设计原则

• 关键字段：id、user_sn（唯一）、email/mobile（唯一）、password、token、reset_token、sex、nickname、avatar、status、created_at。
• 设计要点：账号唯一标识采用 user_sn；登录安全包含 token、重置令牌与失败锁定；社交绑定通过独立表关联。
• 新增字段：level_id（会员等级ID）、direct_user_id（直接推荐人ID）、indirect_user_id（间接推荐人ID）、distribution_level_id（分销等级ID）。

用户扩展属性表（dou_user_wallet）

更新 新增的用户钱包表，专门处理用户的财务相关数据

• 关键字段：id（用户ID）、money_balance（余额）、money_freeze（冻结额）、point_balance（积分余额）、point_freeze（积分冻结）、total_consumption（累计消费）、total_promote（累计推广）。
• 设计目的：将用户的财务数据从基础用户表中分离，提高查询性能和数据安全性。

用户标签表（dou_user_tag）

更新 新增的用户标签系统，支持多维度用户分类

• 关键字段：id、user_id、tag、created_at。
• 设计特点：支持多对多标签体系，便于按标签检索和用户分群。

用户联系人表（dou_user_contact）

• 支持多地址管理，默认地址标记 is_default。
• 更新字段：phone（手机号）、id_card（身份证号）、is_default（是否默认）。

用户等级系统（dou_user_level / dou_user_level_log）

• 支持按消费金额自动升级，并记录升级轨迹。
• 更新字段：upgrade_type（升级类型）、good_discount（商品折扣）、icon（等级图标）。

第三方绑定（dou_user_sns）

• 支持多平台 OpenID/UnionID 映射。
• 更新字段：unionid（微信UnionID）、apptype（应用类型）。

API Token（dou_user_token）

• 会话级 Token 哈希存储，支持过期与活跃时间追踪。

erDiagram
DOU_USER ||--o{ DOU_USER_WALLET : "拥有钱包"
DOU_USER ||--o{ DOU_USER_TAG : "拥有多个标签"
DOU_USER ||--o{ DOU_USER_CONTACT : "拥有多个联系人"
DOU_USER ||--o{ DOU_USER_LOG : "操作日志"
DOU_USER ||--o{ DOU_USER_SNS : "第三方绑定"
DOU_USER ||--|| DOU_USER_LEVEL : "属于某个等级"
DOU_USER ||--o{ DOU_ORDER : "下单"
DOU_USER ||--o{ DOU_COMMENT : "评论"
DOU_USER ||--o{ DOU_VIP : "购买VIP"
DOU_USER ||--o{ DOU_MONEY : "余额流水"
DOU_USER ||--o{ DOU_POINT : "积分流水"

商品域

• 商品表（dou_product）
  • 关键字段：category_id、brand_id、title、slug、price、promote_price、stock、content、image、model、point、sales、keywords、description、sort、status、created_at。
  • 设计要点：支持促销价与有效期；SEO 字段完善；销量与库存跟踪；operator_type/operator_id 记录创建者。
• 商品类目（dou_product_category）
  • 支持层级分类与导航同步。
• 品牌（dou_brand）
  • 品牌分组、介绍、图片与 SEO。
• 属性与属性值（dou_attribute / dou_attribute_value）
  • 模块化属性体系，支持文本/图片/价格变动等多类型属性值。

classDiagram
class Product {
+id
+category_id
+brand_id
+title
+slug
+price
+promote_price
+stock
+content
+image
+model
+point
+sales
+status
+created_at
}
class ProductCategory {
+id
+parent_id
+name
+sync_to_nav
+sort
}
class Brand {
+id
+name
+class
+content
+image
+status
}
class Attribute {
+id
+module
+category_id
+name
+type
+sort
}
class AttributeValue {
+id
+module
+item_id
+att_id
+value
+type
+image
+price_change
}
ProductCategory <|-- Product : "归属"
Brand <|-- Product : "品牌"
Attribute <|-- AttributeValue : "定义"
AttributeValue <|-- Product : "属性值"

订单域

• 订单主表（dou_order）
  • 关键字段：order_sn（唯一）、user_id、mode、module、contact_id、pay_id、shipping_id、tracking_no、item_amount、order_amount、wallet_paid、gateway_paid、allow_aftersale、aftersale_status、allow_comment、parent_order_id、cancel_reason、refund_status、source、status、created_at。
  • 设计要点：订单号唯一且可追溯；金额分拆"商品总额""订单总额""钱包支付""网关支付"；状态机使用字符串，便于扩展；支持售后与评价控制。
• 订单项（dou_order_item）
  • 记录每个商品的名称、原价、实付价、数量、属性、是否锁定库存、是否售后/评价、自定义字段等。
• 收货地址（dou_order_address）
  • 与订单一对一绑定，保证历史快照一致性。
• 支付流水（dou_order_payment）
  • 支付单号唯一，记录第三方支付流水号、凭证、回调报文、过期时间等。
• 退款（dou_order_refund）
  • 退款单号唯一，关联订单与支付流水，记录渠道与回调。
• 状态日志（dou_order_status_log）
  • 记录状态变迁原因、操作者与 IP，便于审计。

sequenceDiagram
participant U as "用户"
participant O as "订单服务"
participant DB as "数据库"
U->>O : "提交订单"
O->>DB : "插入 dou_order"
O->>DB : "插入 dou_order_item"
O->>DB : "插入 dou_order_address"
U->>O : "发起支付"
O->>DB : "插入 dou_order_payment"
DB-->>O : "返回支付单号"
O-->>U : "跳转支付"
Note over O,DB : "支付成功后更新订单与支付状态"

内容域

• 文章（dou_article）
  • 标题、slug、正文、缩略图、附件、点击数、SEO 字段、排序、状态、创建时间。
• 文章分类（dou_article_category）
  • 层级分类、图标、SEO、导航同步。
• 评论（dou_comment）
  • 支持回复、匿名、评分、显示控制、已读标记、IP 记录。

erDiagram
DOU_ARTICLE_CATEGORY ||--o{ DOU_ARTICLE : "分类下文章"
DOU_ORDER_ITEM ||--o{ DOU_COMMENT : "基于订单项评论"

营销域

• 优惠券（dou_coupon / dou_coupon_log）
  • 面值、上限、领取/使用限制、适用范围、有效期、状态；日志记录领取与使用。
• VIP（dou_vip_package / dou_vip）
  • 套餐定义与用户购买记录，支持原价/等级价/促销价。
• 余额流水（dou_money）
  • 记录余额变动、来源、IP、关联对象。
• 积分流水（dou_point）
  • 记录积分变动、来源、关联对象。

flowchart TD
Start(["营销活动"]) --> Coupon["发放/领取优惠券"]
Coupon --> Use["下单使用优惠券"]
Use --> Order["生成订单并计算优惠"]
Order --> Pay["支付完成"]
Pay --> Log["记录优惠券使用日志"]
Start --> VIP["购买VIP套餐"]
VIP --> VipBuy["记录VIP购买流水"]
Start --> Money["充值/扣款"]
Money --> MoneyLog["记录余额流水"]
Start --> Point["获取/消耗积分"]
Point --> PointLog["记录积分流水"]

基础数据

• 区域（dou_area）
  • 支持国家/地区层级与 ISO 代码，用于地址与配送范围。

依赖关系分析

• 用户与订单：用户是订单的发起者，订单通过 user_id 关联用户。
• 订单与商品：订单通过订单项关联具体商品，同时记录商品快照（名称、价格、属性）。
• 订单与支付/退款：支付流水与退款记录均关联订单，形成完整的资金流闭环。
• 内容与评论：评论可基于订单项进行，确保真实交易后评价。
• 营销与订单：优惠券在订单中生效，记录使用明细；VIP/余额/积分与用户账户联动。

更新 三表分离架构下的依赖关系：

• 基础用户表只承担核心身份验证和基本信息查询
• 扩展功能表通过 user_id 关联，提供按需加载的功能数据
• 高级功能表独立管理复杂的业务逻辑和数据关系

graph LR
User["用户(基础表)"] --> Order["订单"]
User --> Wallet["用户钱包(扩展表)"]
User --> Tags["用户标签(扩展表)"]
Order --> Item["订单项"]
Item --> Product["商品"]
Order --> Payment["支付流水"]
Order --> Refund["退款"]
Order --> Address["收货地址"]
Order --> StatusLog["状态日志"]
Article["文章"] --> Category["文章分类"]
Comment["评论"] --> OrderItem["订单项"]
Coupon["优惠券"] --> Order
VIP["VIP"] --> User
Money["余额流水"] --> User
Point["积分流水"] --> User

性能考虑

• 索引设计
  • 订单表：user_id+status、status+created_at、pay_id+status+paid_at 等复合索引，加速按用户与状态查询。
  • 支付流水：status+expired_at、status+gateway+created_at，提升超时清理与对账效率。
  • 商品/文章：slug 唯一索引，提高 URL 路由性能。
• 时间字段
  • 新表统一使用 datetime，便于范围查询与格式化；历史快照字段保持原样以避免迁移成本。
• 金额字段
  • 使用 decimal 避免精度丢失；区分原价与实付价，利于报表统计。
• JSON 字段
  • 用于非结构化扩展（attributes/config/metadata），减少频繁改表；注意查询时合理使用函数与索引。
• 读写分离与归档
  • 日志类表（订单状态日志、AI 使用日志、聊天消息）建议定期归档，降低热表体积。

更新 三表分离架构的性能优势：

• 基础表查询优化：核心用户信息查询更快，减少不必要的数据传输
• 扩展表按需加载：根据业务场景动态加载扩展数据，减少内存占用
• 功能表独立优化：针对不同功能的访问模式进行专门的索引和缓存优化

故障排查指南

• 订单状态异常
  • 检查 dou_order_status_log 中的 from_status/to_status/reason，定位状态流转问题。
• 支付未到账
  • 核对 dou_order_payment 的 status/gateway/transaction_id/raw_callback，结合 gateway 回调排查。
• 退款失败
  • 查看 dou_order_refund 的 channel/status/raw_callback，确认渠道侧响应。
• 评论权限校验
  • 根据 comment.order_item_id 关联订单，检查 allow_comment 与用户权限。
• 用户登录锁定
  • 检查 dou_user.login_fail_count/login_locked_at，必要时解锁。
• 用户数据异常
  • 检查基础用户表与扩展表的数据一致性
  • 验证用户钱包余额与流水记录的匹配性
  • 确认用户标签与用户身份的关联正确性

结论

DouPHP 的表结构围绕用户、商品、订单、内容、营销与基础数据六大域构建，采用统一前缀、合理的主键与唯一键策略、完善的索引设计与清晰的字段语义。通过 JSON 字段与状态字符串化，提升了扩展性与可维护性。最新的三表分离架构设计进一步提升了系统的可扩展性和性能表现，通过将用户数据分为基础信息、扩展属性和高级功能三个层次，实现了更清晰的数据组织结构和更好的查询性能。建议在后续演进中持续遵循命名规范、注释标准与变更流程，保障数据一致性与系统稳定性。

附录

命名规范与约定

• 表名：统一以 dou_ 前缀开头，模块内表名尽量体现业务含义（如 order、product、article）。
• 字段名：小写下划线分隔，语义清晰（如 created_at、updated_at、status、order_sn）。
• 主键：优先使用自增 id；对外唯一标识使用业务编号（如 order_sn、payment_sn、user_sn）。
• 时间：datetime 类型为主，历史兼容字段保留时间戳。
• 金额：decimal(10,2) 及以上，禁止使用浮点。
• 状态：简单开关用 tinyint(1)，复杂状态机使用 varchar 字符串，配合索引。
• JSON：用于灵活扩展（attributes/config/metadata），避免过度使用导致查询困难。

三表分离架构设计规范

更新 新增的用户数据三表分离架构设计规范

• 基础用户信息表（dou_user）

  • 职责：存储用户核心身份信息和基本资料
  • 字段特征：精简、稳定、高频访问
  • 示例字段：user_sn、email、mobile、password、nickname、avatar、status

• 扩展属性数据表（dou_user_wallet、dou_user_tag等）

  • 职责：存储用户的扩展属性和功能数据
  • 字段特征：灵活、可选、按需加载
  • 示例字段：money_balance、point_balance、tag等

• 高级功能数据表（dou_user_level、dou_user_sns等）

  • 职责：存储用户的高级功能和关联数据
  • 字段特征：复杂、低频、业务特定
  • 示例字段：level_id、openid、unionid等

特殊字段设计说明

• JSON 字段
  • 场景：商品属性、应用配置、消息元数据等。
  • 注意事项：避免在 JSON 中进行复杂过滤；必要时对常用键建立虚拟列或冗余字段。
• 时间字段
  • 格式：datetime 存储本地时间；如需跨时区，可在应用层转换。
• 状态字段
  • 定义：订单/支付/退款等使用字符串状态，便于扩展；售后/开关类使用 tinyint。

表结构变更管理与版本控制策略

• 变更流程
  • 需求评审 → 设计评审（含影响面评估） → 编写 SQL 脚本（增量升级） → 测试验证 → 灰度发布 → 全量上线。
• 版本控制
  • 所有 DDL/DML 变更纳入版本库，按版本号组织脚本（如 v1.x.upgrade.sql）。
  • 提供回滚脚本与数据修复脚本，确保可逆性。
• 兼容性
  • 新增字段设置默认值；删除字段先软停用再下线。
  • 大表变更采用分批执行与在线工具，避免锁表。
• 监控与审计
  • 变更记录与执行日志留存；上线后观察慢查询与错误率。

用户数据迁移策略

更新 三表分离架构的数据迁移指导

• 迁移原则

  • 保持数据完整性：确保基础表、扩展表、功能表之间的数据一致性
  • 渐进式迁移：分阶段进行数据迁移，降低风险
  • 回滚机制：提供完整的数据回滚方案

• 迁移步骤

  1. 创建新的扩展表和功能表结构
  2. 从基础用户表提取相关数据到新表
  3. 建立表间关联关系和外键约束
  4. 验证数据完整性和一致性
  5. 切换应用访问路径
  6. 清理历史冗余数据