xk-docs/docs/database/overview.md

# 数据库总览

XK 系统使用两个 MySQL 数据库，分别存储新旧系统的数据。

## 数据库概况

| 数据库 | 表数量 | 状态 | 说明 |
|--------|--------|------|------|
| **z_xk** | 67 张 | 活跃使用 | 新库，当前核心业务表 |
| **z_o_xk** | ~100 张 | 部分使用 | 旧库，Yii2 时代遗留 |

## 双库关系

```mermaid
graph TB
    subgraph ZXK["z_xk 新库 67张表"]
        A1[管理后台]
        A2[财务结算]
        A3[销售推广]
        A4[特色处方]
        A5[监管日志]
        A6[系统配置]
        A7[聊天消息]
        A8[中医疾病库]
    end

    subgraph OXK["z_o_xk 旧库 ~100张表"]
        B1[药品目录]
        B2[订单系统]
        B3[处方系统]
        B4[用户系统]
        B5[门店系统]
        B6[医生系统]
        B7[支付系统]
        B8[物流系统]
    end

    API[xk-api] --> A1
    API --> A2
    API --> A3
    API --> B1
    API --> B2
    API --> B3
    API --> B4
    API --> B5
```

::: warning 跨库约束
- 新库和旧库之间**不允许 JOIN 查询**
- 需要跨库关联时使用两步查询
- 定时任务中需要特别注意数据一致性
:::

## 表活跃状态

### z_xk (新库) — 全部活跃

所有 67 张表均在当前系统中使用。

### z_o_xk (旧库) — 部分活跃

| 状态 | 表数量 | 说明 |
|------|--------|------|
| **仍在使用** | ~40 张 | 药品、订单、处方、用户、门店、医生、支付等核心表 |
| **已废弃** | ~60 张 | 旧配置表、旧 IM 表、旧日志表、旧迁移表等 |

### 仍在使用的核心表 (z_o_xk)

| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_drug` | 药品目录 | xk-api, xk-admin |
| `yii_drug_store_relations` | 药品-门店定价 | xk-api, xk-admin |
| `yii_drug_categories` | 药品分类 | xk-api, xk-admin |
| `yii_drug_nature` | 药品配伍 | xk-api |
| `yii_product_order` | 产品订单 | xk-api, xk-admin |
| `yii_product_order_items` | 订单明细 | xk-api, xk-admin |
| `yii_register` | 挂号订单 | xk-api, xk-admin |
| `yii_prescription` | 主处方表 | xk-api, xk-admin, xk-doctor-wx |
| `yii_prescription_chinese` | 中药处方 | xk-api, xk-doctor-wx |
| `yii_prescription_west` | 西药处方 | xk-api, xk-doctor-wx |
| `yii_prescription_granular` | 颗粒处方 | xk-api, xk-doctor-wx |
| `yii_prescription_server` | 服务包处方 | xk-api, xk-doctor-wx |
| `yii_user` | 用户表 | xk-api, xk-client-wx |
| `yii_user_patient` | 就诊人 | xk-api, xk-client-wx |
| `yii_store` | 门店表 | xk-api, xk-admin, xk-doctor-wx |
| `yii_doctor_info` | 医生信息 | xk-api, xk-admin, xk-doctor-wx |
| `yii_doctor_service` | 医生服务设置 | xk-api, xk-doctor-wx |
| `yii_pharmacist_info` | 药师信息 | xk-api, xk-admin, xk-doctor-wx |
| `yii_service_user` | 服务用户 | xk-api |
| `yii_payment_order` | 咨询支付 | xk-api |
| `yii_payment_product_order` | 产品支付 | xk-api |
| `yii_payment_register` | 挂号支付 | xk-api |
| `yii_ledger` | 分账记录 | xk-api, xk-admin |
| `yii_fund_water` | 资金流水 | xk-api, xk-admin |
| `yii_cash_account` | 提现账户 | xk-api, xk-admin |
| `yii_cash_apply` | 提现申请 | xk-api, xk-admin |
| `yii_reconciliation` | 对账记录 | xk-api, xk-admin |
| `yii_order` | 咨询订单 | xk-api |
| `yii_order_refund` | 咨询退款 | xk-api |
| `yii_product_order_refund` | 产品退款 | xk-api |
| `yii_register_refund` | 挂号退款 | xk-api |
| `yii_transfer_prescription` | 转诊处方 | xk-api, xk-admin |
| `yii_chinese_recipe` | 中药处方笺 | xk-api |
| `yii_west_recipe` | 西药处方笺 | xk-api |
| `yii_granular_recipe` | 颗粒处方笺 | xk-api |
| `yii_im_message` | IM 消息 | xk-api |
| `yii_im_message_session` | IM 会话 | xk-api |
| `yii_examine_log` | 药师审核记录 | xk-api |
| `yii_reviewer` | 审方人 | xk-api |
| `yii_region` | 地区 | xk-api, xk-admin |
| `yii_express_nos` | 快递单号 | xk-api |
| `yii_express_companies` | 快递公司 | xk-api, xk-admin |

## 数据库设计规范

### 表命名
- 新表：`xk_` 前缀 + 业务域 + 功能名（如 `xk_salesperson_commission_record`）
- 旧表：`yii_` 前缀（Yii2 框架约定）

### 字段命名
- 主键：`id`（自增 bigint）
- 时间戳：`created_at`, `updated_at`
- 软删除：`deleted_at`
- 外键：`{关联表名}_id`（如 `store_id`, `user_id`）
- 状态字段：`status`（使用枚举值）

### 索引设计
- 主键索引：`id`
- 唯一索引：`uk_` 前缀（如 `uk_order_item_sp_type`）
- 普通索引：`idx_` 前缀（如 `idx_store_id`）
- 联合索引：多字段组合（如 `idx_anchor_step`）

### 数据类型
- 金额：`decimal(10,2)` 或 `decimal(12,2)`
- 大文本：`text` 或 `mediumtext`
- JSON：`json` 或 `text`（存储 JSON 字符串）
- 状态/类型：`tinyint` 或 `int`
- 手机号：`varchar(20)`
- 银行卡：`varchar(30)`

## ER 关系图

### 核心业务关系

```mermaid
erDiagram
    yii_user ||--o{ yii_user_patient : "拥有"
    yii_user ||--o{ yii_product_order : "下单"
    yii_user ||--o{ yii_register : "挂号"
    yii_user ||--o{ yii_order : "问诊"

    yii_store ||--o{ yii_product_order : "归属"
    yii_store ||--o{ yii_register : "归属"
    yii_store ||--o{ yii_drug_store_relations : "定价"

    yii_doctor_info ||--o{ yii_prescription : "开方"
    yii_doctor_info ||--o{ yii_order : "接诊"
    yii_doctor_info ||--o{ yii_register : "接诊"

    yii_prescription ||--o{ yii_prescription_chinese : "中药"
    yii_prescription ||--o{ yii_prescription_west : "西药"
    yii_prescription ||--o{ yii_prescription_granular : "颗粒"

    yii_product_order ||--o{ yii_product_order_items : "明细"
    yii_product_order ||--o{ yii_payment_product_order : "支付"
    yii_product_order ||--o{ yii_product_order_refund : "退款"
    yii_product_order ||--o{ yii_ledger : "分账"

    yii_register ||--o{ yii_payment_register : "支付"
    yii_register ||--o{ yii_register_refund : "退款"

    xk_clinic_salesperson ||--o{ xk_salesperson_commission_record : "佣金"
    xk_salesperson_commission_record ||--o{ xk_salesperson_settlement_record : "结算"
    xk_salesperson_settlement ||--o{ xk_salesperson_settlement_record : "包含"
```