数据库文档编写，开发规范文档，数据库接入
This commit is contained in:
comlibmb
236
docs/sql/01_tables_catalog.md
Normal file
236
docs/sql/01_tables_catalog.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# 01 表清单与职责划分（按业务域）
|
||||
|
||||
本节将 `ml_` 前缀的商城域表按业务域归类，并给出每张表的核心职责、关键字段与主要关联。
|
||||
|
||||
> 说明：用户主表复用 `public.ak_users`，商城域通过外键 `user_id/merchant_id` 关联。
|
||||
|
||||
---
|
||||
|
||||
## 1. 用户域（Account Extension）
|
||||
|
||||
### 1.1 `ml_user_profiles`（用户扩展档案）
|
||||
|
||||
- **职责**：承载商城侧的用户扩展信息（状态、实名、信用分、认证信息、偏好等）。
|
||||
- **关键字段**：
|
||||
- `user_id`：外键到 `ak_users(id)`（且 `UNIQUE`，保证一用户一档案）
|
||||
- `status`：用户状态（正常/冻结/注销/待审核）
|
||||
- `verification_status`、`verification_data`：认证状态及数据（JSONB）
|
||||
- `preferences`：用户偏好（JSONB）
|
||||
- **主要关联**：
|
||||
- `ml_user_profiles.user_id -> ak_users.id`
|
||||
|
||||
### 1.2 `ml_user_addresses`（用户地址）
|
||||
|
||||
- **职责**：用户收货地址（并支持默认地址）。
|
||||
- **关键字段**：
|
||||
- `user_id`：外键到 `ak_users(id)`
|
||||
- `is_default`：是否默认地址（由触发器确保单一默认）
|
||||
- `province/city/district/address_detail`：地址结构化字段
|
||||
- **主要关联**：
|
||||
- `ml_user_addresses.user_id -> ak_users.id`
|
||||
|
||||
---
|
||||
|
||||
## 2. 商品域（Catalog）
|
||||
|
||||
### 2.1 `ml_categories`（商品分类）
|
||||
|
||||
- **职责**：商品分类树，支持 SEO（`cid/slug`）与层级路径。
|
||||
- **关键字段**：
|
||||
- `parent_id`：自关联
|
||||
- `path TEXT[]`：分类路径（便于面包屑、筛选等）
|
||||
- `cid`：对外友好 ID
|
||||
- `slug`：SEO slug
|
||||
- **主要关联**：
|
||||
- `ml_categories.parent_id -> ml_categories.id`
|
||||
|
||||
### 2.2 `ml_brands`（品牌）
|
||||
|
||||
- **职责**：品牌维度，支持 SEO（`cid`）。
|
||||
- **关键字段**：`name/logo_url/is_active/cid`
|
||||
|
||||
### 2.3 `ml_products`（商品 SPU）
|
||||
|
||||
- **职责**：商品主表（SPU），包含：定价、库存汇总、SEO、属性、统计。
|
||||
- **关键字段**：
|
||||
- `merchant_id`：商家（关联 `ak_users`）
|
||||
- `category_id`、`brand_id`
|
||||
- `base_price/market_price/cost_price`
|
||||
- `total_stock/available_stock`（由 SKU 触发器汇总维护）
|
||||
- `status`（上架/下架/草稿/删除）
|
||||
- `image_urls/video_urls/attributes`（JSONB）
|
||||
- `cid/slug/seo_*`
|
||||
- **主要关联**：
|
||||
- `ml_products.merchant_id -> ak_users.id`
|
||||
- `ml_products.category_id -> ml_categories.id`
|
||||
- `ml_products.brand_id -> ml_brands.id`
|
||||
|
||||
### 2.4 `ml_product_skus`（商品 SKU）
|
||||
|
||||
- **职责**：SKU 明细：规格组合、SKU 价格与库存。
|
||||
- **关键字段**：
|
||||
- `product_id`：所属 SPU
|
||||
- `specifications JSONB`：规格组合（例如 `{color:"black", size:"M"}`）
|
||||
- `price/stock/status`
|
||||
- **主要关联**：
|
||||
- `ml_product_skus.product_id -> ml_products.id`
|
||||
|
||||
### 2.5 `ml_product_specs`（商品规格定义）
|
||||
|
||||
- **职责**：描述一个商品有哪些规格项及可选值（用于生成 SKU）。
|
||||
- **关键字段**：
|
||||
- `spec_name`（如 颜色/尺寸）
|
||||
- `spec_values JSONB`（如 `["black","white"]`）
|
||||
|
||||
---
|
||||
|
||||
## 3. 店铺域（Merchant/Shop）
|
||||
|
||||
### `ml_shops`（店铺）
|
||||
|
||||
- **职责**：店铺信息（当前模型约束“一商家一店”）。
|
||||
- **关键字段**：
|
||||
- `merchant_id UNIQUE`：一对一约束
|
||||
- `status`（正常/暂停/关闭）
|
||||
- `address/business_hours`（JSONB）
|
||||
- `rating_avg/rating_count/product_count/order_count`（统计类）
|
||||
|
||||
---
|
||||
|
||||
## 4. 交易域（Order/Trade）
|
||||
|
||||
### 4.1 `ml_orders`（订单主表）
|
||||
|
||||
- **职责**：订单交易核心，含金额、地址快照、状态机、关键时间点。
|
||||
- **关键字段**：
|
||||
- `order_no`：订单号（可由序列+函数生成）
|
||||
- `user_id`：买家
|
||||
- `merchant_id`：商家（当前单商家订单模型）
|
||||
- 金额拆分：`product_amount/discount_amount/shipping_fee/total_amount/paid_amount`
|
||||
- `shipping_address JSONB`：下单快照地址
|
||||
- 状态机：`order_status/payment_status/shipping_status`
|
||||
- 时间点：`paid_at/shipped_at/delivered_at/completed_at`
|
||||
|
||||
### 4.2 `ml_order_items`（订单明细）
|
||||
|
||||
- **职责**：订单行项目，保存下单快照（防止商品信息后改影响历史订单）。
|
||||
- **关键字段**：
|
||||
- `order_id` 外键
|
||||
- `product_id/sku_id`
|
||||
- `product_name/sku_name/specifications/image_url/price`（快照冗余）
|
||||
- `quantity/total_amount`
|
||||
|
||||
---
|
||||
|
||||
## 5. 购物车域
|
||||
|
||||
### `ml_shopping_cart`
|
||||
|
||||
- **职责**：购物车行项目。
|
||||
- **关键字段**：
|
||||
- `user_id/product_id/sku_id`
|
||||
- `quantity`、`selected`
|
||||
- `UNIQUE(user_id, product_id, sku_id)`：避免重复行
|
||||
|
||||
---
|
||||
|
||||
## 6. 营销域（Coupon）
|
||||
|
||||
### 6.1 `ml_coupon_templates`（优惠券模板）
|
||||
|
||||
- **职责**：券模板定义；支持平台券（`merchant_id` 为空）与商家券。
|
||||
- **关键字段**：
|
||||
- `coupon_type`（满减/折扣/免邮）
|
||||
- `discount_type`（固定金额/百分比）
|
||||
- `discount_value/min_order_amount/max_discount_amount`
|
||||
- `applicable_products/applicable_categories`（JSONB）
|
||||
- `start_time/end_time/status`
|
||||
|
||||
### 6.2 `ml_user_coupons`（用户优惠券）
|
||||
|
||||
- **职责**：用户领取的券实例，包含券码与使用归因。
|
||||
- **关键字段**：
|
||||
- `coupon_code`（唯一）
|
||||
- `status`（未用/已用/过期）
|
||||
- `used_at/order_id`
|
||||
|
||||
---
|
||||
|
||||
## 7. 履约域（Delivery）
|
||||
|
||||
### 7.1 `ml_delivery_drivers`（配送员）
|
||||
|
||||
- **职责**：配送员信息与工作状态。
|
||||
- **关键字段**：
|
||||
- `user_id UNIQUE`：一个用户对应一个配送员档案
|
||||
- `work_status/status`、位置信息、统计与评分
|
||||
|
||||
### 7.2 `ml_delivery_tasks`（配送任务）
|
||||
|
||||
- **职责**：配送任务与订单 1:1 绑定。
|
||||
- **关键字段**：
|
||||
- `order_id UNIQUE`：一个订单最多一个配送任务
|
||||
- `driver_id`
|
||||
- `pickup_address/delivery_address`（JSONB 快照）
|
||||
- `status`、`assigned_at/picked_at/delivered_at`
|
||||
|
||||
---
|
||||
|
||||
## 8. 评价域（Review）
|
||||
|
||||
### `ml_product_reviews`
|
||||
|
||||
- **职责**：商品评价；通过 `order_id + order_item_id` 强绑定订单来源。
|
||||
- **关键字段**：
|
||||
- `order_id`、`order_item_id`
|
||||
- `rating/content/images`
|
||||
- `merchant_reply/merchant_replied_at`
|
||||
|
||||
---
|
||||
|
||||
## 9. 用户行为域（Behavior）
|
||||
|
||||
### 9.1 `ml_user_favorites`（收藏）
|
||||
|
||||
- **职责**：收藏（多态目标：商品/店铺）。
|
||||
- **关键字段**：
|
||||
- `target_type`（1 商品 / 2 店铺）
|
||||
- `target_id`
|
||||
- `UNIQUE(user_id, target_type, target_id)`
|
||||
|
||||
### 9.2 `ml_browse_history`（浏览历史）
|
||||
|
||||
- **职责**：浏览记录（当前模型倾向“同商品最后一次浏览覆盖”）。
|
||||
- **关键字段**：`UNIQUE(user_id, product_id)`
|
||||
|
||||
### 9.3 `ml_search_history`（搜索记录）
|
||||
|
||||
- **职责**：搜索日志（可用于热词/推荐/分析）。
|
||||
- **关键字段**：`keyword/result_count/ip_address/user_agent`
|
||||
|
||||
---
|
||||
|
||||
## 10. 配置与地区
|
||||
|
||||
### 10.1 `ml_system_configs`（系统配置）
|
||||
|
||||
- **职责**：配置中心（JSONB），如运费、佣金比例、订单自动确认天数等。
|
||||
- **关键字段**：`config_key` 唯一、`config_value JSONB`
|
||||
|
||||
### 10.2 `ml_regions`（地区）
|
||||
|
||||
- **职责**：地区树（省/市/区/街道）。
|
||||
|
||||
---
|
||||
|
||||
## 11. 订阅模块（Subscription）
|
||||
|
||||
### 11.1 `ml_subscription_plans`（订阅套餐）
|
||||
|
||||
- **职责**：订阅计划定义（计费周期、价格、试用天数、features）。
|
||||
- **关键字段**：`plan_code` 唯一、`billing_period`、`features JSONB`
|
||||
|
||||
### 11.2 `ml_user_subscriptions`（用户订阅）
|
||||
|
||||
- **职责**：用户订阅实例（状态机、自动续费、下次扣费时间等）。
|
||||
- **关键字段**：`status`（trial/active/past_due/canceled/expired）、`auto_renew`、`metadata JSONB`
|
||||
Reference in New Issue
Block a user