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

xk-api 基类架构

控制器层级

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/>门店推广员微信端]

服务层架构

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	调试接口	开发调试用

模型分层

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	十八反、十九畏、有毒药材