# xk-api 基类架构

## 控制器层级

```mermaid
graph TB
    BC[Controller.php<br/>基础控制器] --> AC[AdminController<br/>管理后台控制器]
    BC --> MC[MobileController<br/>移动端控制器]
    BC --> DC[DoctorController<br/>医生端控制器]
    BC --> HC[HyController<br/>监管接口控制器]
    BC --> CC[CallbackController<br/>回调控制器]

    AC --> SYS[admin/system/*<br/>系统管理 22个]
    AC --> BIZ[admin/business/*<br/>业务管理 30+个]
    AC --> FIN[admin/finance/*<br/>财务管理 8个]
    AC --> SAL[admin/salesperson/*<br/>销售管理 3个]

    MC --> MCON[mobile/consultation/*]
    MC --> MPRE[mobile/prescription/*]
    MC --> MORD[mobile/order/*]
    MC --> MGUE[mobile/guest/*]

    DC --> DWX[DoctorWx/*<br/>医生微信端]
    DC --> CAWX[ClinicAdminWx/*<br/>门店管理微信端]
    DC --> PAWX[PlatformAdminWx/*<br/>平台管理微信端]
    DC --> SPWX[SalespersonWx/*<br/>推广员微信端]
    DC --> CSWX[ClinicSalespersonWx/*<br/>门店推广员微信端]
```

## 服务层架构

```mermaid
graph TB
    subgraph 公共服务 common/
        JWT[JWTService] --> AUTH[认证]
        WPAY[WechatPayService] --> PAY[支付]
        EPL[EplPayService] --> EPAY[易票联]
        SMS[SmsService] --> MSG[短信]
        UPLOAD[UploadService] --> FILE[文件上传]
        REDIS[RedisService] --> CACHE[缓存]
        SEC[WeChatContentSecurityService] --> AUDIT[内容审核]
    end

    subgraph HTTP客户端 common/http/
        OLD[OldApiClient] --> LEGACY[旧系统]
        ERP[ErpApiClient] --> ERP_SYS[ERP系统]
        HY[HyApiClient] --> HY_INT[互医平台]
        MES[MesFailoverClient] --> MES_SYS[MES系统]
        WS[WebSocketApiClient] --> IM[即时通讯]
    end

    subgraph 业务服务
        PS[PrescriptionService] --> PRESCRIPTION[处方管理]
        ORD[OrderService] --> ORDER[订单管理]
        REG[RegisterService] --> REGISTER[挂号管理]
        LED[LedgerService] --> SETTLE[结算管理]
        SAL[SalespersonService] --> SALES[销售管理]
    end
```

## 中间件

| 中间件 | 文件 | 用途 |
|--------|------|------|
| `AuthMiddleware` | Admin 认证 | JWT 验证，解析管理员身份 |
| `MobileAuthMiddleware` | 移动端认证 | 患者端 JWT 验证 |
| `DoctorWxUnifiedAuthMiddleware` | 医生统一认证 | 医生端多角色统一认证 |
| `ClinicAdminWxAuthMiddleware` | 门店管理认证 | 门店管理员身份验证 |
| `PlatformAdminWxAuthMiddleware` | 平台管理认证 | 平台管理员身份验证 |
| `SalespersonWxAuthMiddleware` | 推广员认证 | 推广员身份验证 |
| `ClinicSalespersonWxAuthMiddleware` | 门店推广员认证 | 门店推广员身份验证 |
| `HyTransitApiMiddleware` | 监管接口认证 | X-Hy-Transit-Token 验证 |
| `HyTransitEncryptResponseMiddleware` | 监管响应加密 | AES-128-ECB 加密响应体 |
| `EplpayMiddleware` | 易票联回调 | 签名验证 |
| `WechatMiddleware` | 微信回调 | 签名验证 |
| `ErpMiddleware` | ERP 回调 | ERP 系统认证 |
| `ApiMiddleware` | 调试接口 | 开发调试用 |

## 模型分层

```mermaid
graph TB
    subgraph 新模型 Models/new/
        N_ADMIN[admin/*<br/>管理后台 14个]
        N_FIN[finance/*<br/>财务 3个]
        N_SAL[salesperson/*<br/>销售 11个]
        N_SP[special_prescription/*<br/>特色处方 7个]
        N_SYS[system/*<br/>系统 9个]
        N_HY[log/HyTransit*<br/>监管日志 2个]
        N_CHAT[chat/*<br/>聊天 2个]
        N_DISEASE[disease/*<br/>中医疾病 6个]
    end

    subgraph 旧模型 Models/old/
        O_DRUG[drug/*<br/>药品 17个]
        O_ORDER[order/*<br/>订单 15个]
        O_PRESC[prescription/*<br/>处方 8个]
        O_DOCTOR[doctor/*<br/>医生 21个]
        O_USER[user/*<br/>用户 9个]
        O_FIN[finacne/*<br/>财务 7个]
        O_CONFIG[config/*<br/>配置 24个]
        O_STORE[store/*<br/>门店 3个]
    end
```

## 枚举体系

| 域 | 枚举类 | 说明 |
|----|--------|------|
| 角色 | `RoleEnum` | 13 种角色：超管、管理员、省经理、市经理等 |
| 用户类型 | `UserTypeEnum` | 门店、平台、供应商 |
| 订单状态 | `OrderStatusEnum` | 待支付→待发货→待收货→待评价→退款→完成 |
| 退款状态 | `OrderRefundStatusEnum` | 未退、申请中、同意、已退、拒绝、取消 |
| 处方模板 | `PrescriptionTemplateTypeEnum` | 普通方、常用方、特色方 |
| 财务 | `LedgerFeeTypeEnum` | 药品、挂号、快递、处方费、加工费、诊疗费 |
| 财务状态 | `LedgerStatusEnum` | 待结算、已结算、已取消 |
| 银行账户 | `BankAccountTypeEnum` | 对公、对私/法人、存折 |
| 物流 | `ExpressStateEnum` | 收件→运输→签收→退回 |
| 监管步骤 | `HySuperviseStepEnum` | 在线咨询、在线复诊、在线处方、处方核销 |
| 聊天消息 | `MessageTypeEnum` | 文字、图片、语音、视频、处方、视频通话等 15 种 |
| 中药冲突 | `ChineseMedicineConflictEnum` | 十八反、十九畏、有毒药材 |