xk-docs/docs/guide/architecture.md

系统架构

整体架构

graph TB
    subgraph 客户端
        U[患者小程序<br/>xk-client-wx]
        D[医生小程序<br/>xk-doctor-wx]
        A[管理后台<br/>xk-admin]
        S[数据大屏<br/>xk-data]
    end

    subgraph API层
        API[xk-api<br/>Laravel 12]
        YII[xk-api-yii<br/>Yii2 遗留]
    end

    subgraph 数据层
        DB1[(z_xk<br/>新库)]
        DB2[(z_o_xk<br/>旧库)]
        RD[(Redis)]
        MQ[(RabbitMQ)]
        OSS[(阿里云 OSS)]
    end

    subgraph 外部集成
        PAY1[微信支付]
        PAY2[易票联支付]
        SMS[短信服务]
        HY[xk-hy-forward-go<br/>Go 转发]
        GOV[浙江省政务云<br/>监管平台]
        MES[和利康 MES<br/>中药智造]
        ERP[ERP 系统]
        KUAI100[快递100]
    end

    U --> API
    D --> API
    A --> API
    S --> API
    API --> DB1
    API --> DB2
    API --> RD
    API --> MQ
    API --> OSS
    API --> PAY1
    API --> PAY2
    API --> SMS
    API --> HY
    API --> MES
    API --> ERP
    API --> KUAI100
    HY --> GOV

双数据库策略

系统同时连接两个 MySQL 数据库：

graph LR
    subgraph z_xk 新库 67张表
        A1[管理后台 xk_admin]
        A2[财务 xk_account_*]
        A3[销售 xk_salesperson_*]
        A4[处方 xk_special_prescription*]
        A5[监管 xk_hy_transit_*]
        A6[系统配置 xk_system_config]
    end

    subgraph z_o_xk 旧库 约100张表
        B1[药品 yii_drug]
        B2[订单 yii_product_order]
        B3[处方 yii_prescription]
        B4[用户 yii_user]
        B5[门店 yii_store]
        B6[医生 yii_doctor_info]
        B7[挂号 yii_register]
    end

    API[xk-api] -->|读写| A1
    API -->|读写| A2
    API -->|读写| A3
    API -->|读写| B1
    API -->|读写| B2
    API -->|读写| B3

::: warning 跨库注意事项

• 新库和旧库之间不允许 JOIN 查询
• 跨库关联需要在应用层做两步查询
• 定时任务 app:accrue-salesperson-commission 需要同时查两个库 :::

API 路由架构

xk-api 通过路由文件划分不同端的接口：

路由文件	前缀	用途	认证方式
admin.php	/api/admin	管理后台 API	JWT (AdminAuthMiddleware)
mobile.php	/api/mobile	患者小程序 API	JWT (MobileAuthMiddleware)
doctor.php	/api/doctor	医生端小程序 API	多种角色中间件
hy.php	/api/hy	互联网医院监管 API	HyTransitApiMiddleware
callback.php	/api/callback	支付回调	签名验证
open-api.php	/api/open	开放 API	无/简单认证

中间件链

graph LR
    REQ[请求] --> CORS[CORS]
    CORS --> THROTTLE[限流]
    THROTTLE --> AUTH{认证中间件}
    AUTH -->|Admin| JWT[JWT验证]
    AUTH -->|Mobile| MJWT[Mobile JWT]
    AUTH -->|Doctor| DROLE[角色验证]
    AUTH -->|Hy| HTOKEN[Hy Transit Token]
    JWT --> LOG[操作日志]
    MJWT --> LOG
    DROLE --> LOG
    HTOKEN --> LOG
    LOG --> CTRL[Controller]

消息队列架构

graph TB
    subgraph 生产者
        P1[订单支付回调]
        P2[挂号支付回调]
        P3[退款回调]
        P4[定时任务]
    end

    subgraph RabbitMQ
        Q1[default 队列]
        Q2[failed_jobs]
    end

    subgraph 消费者 Job
        J1[ProductOrderPaidJob<br/>分账结算]
        J2[RegisterPaidJob<br/>挂号分账]
        J3[ProductOrderRefundJob<br/>退款处理]
        J4[SalespersonCommissionRefundJob<br/>佣金冲销]
        J5[AutoConfirmReceiptOrderJob<br/>自动确认收货]
        J6[AutomaticallyCancelTheOrderJob<br/>自动取消订单]
        J7[AutoExpirePrescriptionHandlerJob<br/>处方过期处理]
        J8[SyncDrugPriceBySubscribeJob<br/>药品价格同步]
    end

    P1 --> Q1
    P2 --> Q1
    P3 --> Q1
    P4 --> Q1
    Q1 --> J1
    Q1 --> J2
    Q1 --> J3
    Q1 --> J4
    Q1 --> J5
    Q1 --> J6
    Q1 --> J7
    Q1 --> J8

监管数据流转

sequenceDiagram
    participant API as xk-api
    participant GO as xk-hy-forward-go
    participant GOV as 浙江省政务云

    Note over API: 定时触发 / 手动拉取
    API->>API: 1. 创建批次 (batch/create)
    API->>API: 2. 拉取数据 (supervise/consult, /recipe, ...)
    API->>API: 3. 加密打包数据
    API->>GO: 4. 转发加密数据
    GO->>GOV: 5. 透传至政务云
    GOV-->>GO: 6. 返回处理结果
    GO-->>API: 7. 回调结果
    API->>API: 8. 更新批次状态

部署架构

服务	部署方式	说明
xk-api	服务器 + LaravelS	PHP-FPM + LaravelS 常驻进程
xk-admin	CDN / Nginx	静态资源部署
xk-client-wx	微信小程序平台	HBuilderX 上传
xk-doctor-wx	微信小程序平台	HBuilderX 上传
xk-data	服务器 / CDN	静态页面
xk-hy-forward-go	内网服务器	Windows 部署，run.bat 启动
MySQL	服务器	双库部署
Redis	服务器	缓存 / 队列
RabbitMQ	服务器	消息队列