xk-docs/docs/projects/xk-api/features.md

# xk-api 重点功能

## 处方流转体系

```mermaid
graph TB
    subgraph 开方
        D1[医生接诊] --> D2[选择患者]
        D2 --> D3{处方类型}
        D3 -->|中药| D4[中医处方]
        D3 -->|西药| D5[西药处方]
        D3 -->|颗粒| D6[颗粒处方]
        D3 -->|中成药| D7[中成药处方]
        D3 -->|服务包| D8[服务包处方]
    end

    subgraph 审方
        D4 --> R1[医生初审]
        D5 --> R1
        D6 --> R1
        D7 --> R1
        R1 -->|通过| R2[药师复审]
        R1 -->|拒绝| R3[退回修改]
        R2 -->|通过| R4[处方生效]
        R2 -->|拒绝| R3
    end

    subgraph 履约
        R4 --> P1[患者购药]
        P1 --> P2{配送方式}
        P2 -->|快递| P3[仓库发货]
        P2 -->|自提| P4[门店自提]
        P2 -->|代煎| P5[MES 下单]
    end
```

### 处方状态机

| 状态 | 值 | 说明 |
|------|-----|------|
| 待审核 | 0 | 医生已开方，等待审核 |
| 通过 | 1 | 审核通过 |
| 未通过 | 2 | 审核拒绝 |
| 无需审核 | 3 | 免审处方 |

### 处方类型

| 类型 | 值 | 说明 |
|------|-----|------|
| 中药 | 1 | 中药饮片处方 |
| 西药 | 2 | 西药处方 |
| 颗粒 | 3 | 配方颗粒处方 |
| 中成药 | 4 | 中成药处方 |
| 产品服务包 | 5 | 服务包处方 |

### 转诊处方

转诊处方是跨门店的处方流转机制：
- **转诊方**（发起方）获得 100% 利润
- **接收方**（被转方）负责履约
- 处方来源自动设为接收方门店（`store_id = delegate_store_id`）
- 支持线上转诊和线下转诊两种模式

## 分账结算体系

```mermaid
graph TB
    subgraph 收入
        PAY1[产品订单付款] --> LED[分账记录]
        PAY2[挂号订单付款] --> LED
    end

    subgraph 分账规则
        LED --> S1[门店分账]
        LED --> S2[平台分账]
        LED --> S3[供应商分账]
    end

    subgraph 结算
        S1 --> SET[结算单]
        S2 --> SET
        S3 --> SET
        SET --> WITH[提现申请]
        WITH --> AUDIT[审核]
        AUDIT -->|通过| PAY3[打款]
        AUDIT -->|拒绝| REJECT[退回]
    end
```

### 分账记录 (yii_ledger)

| 字段 | 说明 |
|------|------|
| `fee_type` | 费用类型：药品/挂号/快递/处方费/加工费/诊疗费 |
| `status` | 0=待结算, 1=已结算, 2=已取消 |
| `user_type` | 0=用户, 1=诊所, 2=平台 |

### 可提现金额变更

每次分账、退款、提现都会在 `xk_account_able_change_log` 中记录：
- **来源类型**: settle（分账）、withdraw（提现）、refund（退款）
- **变更前后金额**: before_amount → after_amount
- **关联订单**: order_id, order_type, order_no

## 佣金体系

```mermaid
graph TB
    subgraph 佣金来源
        O1[产品订单] --> C1[佣金记录]
        O2[挂号订单] --> C1
    end

    subgraph 佣金计算
        C1 --> CAL{计算方式}
        CAL -->|固定佣金| F1[按模板/药品配置]
        CAL -->|百分比佣金| F2[按比例计算]
    end

    subgraph 佣金结算
        F1 --> SET[推广员结算单]
        F2 --> SET
        SET --> PAY[打款]
    end

    subgraph 退款冲销
        REF[订单退款] --> REV[佣金冲销记录]
        REV --> SET2[结算调整]
    end
```

### 佣金模板
- 按门店配置佣金模板
- 模板下按药品配置单品佣金
- 支持固定金额和百分比两种模式

### 佣金结算
- 支持按时段和按订单两种结算方式
- 结算时生成凭证图片
- 退款时自动冲销已结算佣金

## MES 对接（中药智造）

与和利康 MES 系统对接，实现处方自动下发到中药煎煮中心：

```mermaid
sequenceDiagram
    participant API as xk-api
    participant MES as 和利康 MES
    participant DRUG as 煎煮中心

    API->>MES: H001 提交处方 (HTTP+JSON)
    MES-->>API: 返回处理结果
    Note over MES: 失败时自动降级
    API->>MES: W001 提交处方 (SOAP+XML)
    MES-->>API: 返回处理结果
    API->>API: 记录同步状态
```

### 处方字段映射
- 煎煮方式: 28 种（先煎、煎煮、后下、烊化等）
- 服法: 内服/外用
- 剂量数、包装数、煎煮容量(ml)

## 互联网医院监管上报

```mermaid
graph TB
    subgraph 数据类型
        T1[在线咨询]
        T2[在线复诊]
        T3[在线处方]
        T4[处方核销]
    end

    subgraph 流程
        T1 --> P[拉取打包]
        T2 --> P
        T3 --> P
        T4 --> P
        P --> ENC[加密]
        ENC --> FWD[xk-hy-forward-go 转发]
        FWD --> GOV[浙江省政务云]
        GOV --> CB[回调结果]
        CB --> UPD[更新状态]
    end
```

### 监管数据接口

| 接口 | 说明 |
|------|------|
| `uploadConsultIndicators` | 咨询信息上报 |
| `uploadReferralIndicators` | 转诊/复诊信息上报 |
| `uploadRecipeIndicators` | 处方信息上报（含中药扩展） |
| `uploadRecipeVerificationIndicators` | 处方核销信息上报 |

### 加密规则
- 算法: AES-128-ECB + PKCS7 + Base64
- 密钥: `substr(sha256(HY_TRANSIT_API_TOKEN), 0, 16)`

### 签名规则
- `sign = HmacSHA256(requestBody + secret + header params sorted alphabetically)`

## 药品价格同步

```mermaid
graph LR
    WH[仓库药品] -->|价格变更| PUB[xk_api 公共接口]
    PUB --> SUB1[订阅门店1]
    PUB --> SUB2[订阅门店2]
    PUB --> SUB3[订阅门店N]

    subgraph 同步方式
        A[全量同步<br/>SyncDrugPriceBySubscribeJob]
        B[单品同步<br/>SyncSingleDrugPriceBySubscribeJob]
        C[批量同步<br/>BatchSyncDrugPriceJob]
    end
```

### 价格计算规则
- 门店采购价 = 仓库价 × 采购比例 (`z_buy_percent`)
- 门店销售价 = 仓库价 × 销售比例 (`z_sale_percent`)
- 支持门店独立调价

## 特色处方体系

特色处方是标准化的处方产品，具有独立的 SKU 和定价体系：

| 概念 | 说明 |
|------|------|
| 特色处方 | 标准化的处方产品，如"感冒方"、"养生方" |
| SKU | 剂量规格，如 7 剂、14 剂、21 剂 |
| 价格方案 | 固定价 / 门店浮动价 |
| 药品分摊 | 每个 SKU 下各药品的分摊价格 |
| 患者记录 | 患者选择特色处方的记录（待应用→已应用→完成） |