# 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`