# xk-api 通用组件

## 支付组件

### 微信支付 (WechatPayService)
- 统一下单、查询、退款
- 回调签名验证 (WechatMiddleware)
- 回调处理 (WechatCallbackService)

### 易票联支付 (EplPayService)
- 统一下单、查询
- 回调签名验证 (EplpayMiddleware)
- 回调处理 (EplpayCallbackService)
- 银行卡上报状态同步

## 认证组件

### JWT (JWTService / MobileJWTService)
- Admin 端和 Mobile 端分别实现
- Token 生成、验证、刷新
- Sanctum 集成

### 角色认证中间件
- `DoctorWxUnifiedAuthMiddleware` — 统一解析医生端多种角色
- `ClinicAdminWxAuthMiddleware` — 门店管理员认证
- `PlatformAdminWxAuthMiddleware` — 平台管理员认证
- `SalespersonWxAuthMiddleware` — 推广员认证

## 文件组件

### 上传 (UploadService)
- 阿里云 OSS 上传
- 支持图片、聊天文件、二维码、注册文件
- 图片压缩处理

### 文件管理 (FileGalleryService)
- 文件分组 (FileGroup)
- 文件类型 (FileType)
- 文件元数据存储

## 短信组件

### 短信服务 (SmsService)
- 阿里云短信 (AliSmsService)
- 统一接口，支持多供应商切换

## 缓存组件

### Redis 服务 (RedisService)
- 通用缓存操作
- 分布式锁
- 会话管理

## HTTP 客户端

| 客户端 | 目标系统 | 用途 |
|--------|----------|------|
| `OldApiClient` | xk-api-yii | 旧系统 API 调用 |
| `OldShopApiClient` | 旧商城 | 旧商城 API |
| `ErpApiClient` | ERP 系统 | ERP 数据同步 |
| `HyApiClient` | 互医平台 | 互医内部 API |
| `MesFailoverClient` | 和利康 MES | 中药智造（自动降级 SOAP→HTTP） |
| `WebSocketApiClient` | IM 服务 | 即时通讯 |
| `WeChatApiClient` | 微信 API | 微信开放平台 |
| `EasyTicketLinkApiClient` | 易票联 | 支付网关 |
| `IpAddressSearchApiClient` | IP 地理位置 | IP 归属地查询 |

## 内容安全

### WeChatContentSecurityService
- 文本内容安全审核
- 图片内容安全审核
- 微信内容安全接口调用

## 监管组件

### HyTransitCryptoService
- AES-128-ECB 加密/解密
- 请求签名 (SignService)
- 文件认证 (FileAuthService)

### HySupervisePayloadValidator
- 监管数据校验
- 字段标签映射 (HySuperviseFieldLabel)

### HyRecipeHtmlRenderer
- 处方打印 HTML 渲染
- 支持中药、西药、颗粒处方

## Excel 组件

### Maatwebsite/Excel
- 数据导出
- 模板导出

### PHPSpreadsheet
- 复杂报表生成
- 大数据量导出

## 工具组件

### AccountOptionService
- 账户选项逻辑（多账户切换）

### DashboardDataService
- 数据大屏数据聚合
- 统计指标计算

### UtilsService
- 通用工具方法
- 错误处理