# xk-api 设计思路

## 架构决策

### 双数据库策略

系统同时使用两个 MySQL 数据库（z_xk 和 z_o_xk），这是因为：

1. **历史迁移**：旧系统基于 Yii2，新系统基于 Laravel，数据逐步迁移
2. **业务连续性**：迁移期间需要两套系统并行运行
3. **表规模**：旧库约 100 张表，新库 67 张表，完全迁移风险太大

::: warning 跨库约束
- 不允许跨库 JOIN
- 需要跨库关联时使用两步查询
- 定时任务中需要特别注意数据一致性
:::

### 模型分层

```
Models/
├── old/          # 旧模型（Yii表，z_o_xk库）
│   ├── config/   # 配置类
│   ├── doctor/   # 医生类
│   ├── drug/     # 药品类
│   ├── order/    # 订单类
│   ├── ...
└── new/          # 新模型（xk表，z_xk库）
    ├── admin/    # 管理后台
    ├── finance/  # 财务
    ├── salesperson/ # 销售
    └── ...
```

### 服务层设计

服务层按业务域组织，避免上帝服务：

```
Service/
├── common/           # 公共服务（支付、短信、文件等）
│   ├── http/         # 外部 HTTP 客户端
│   ├── hy/           # 监管平台组件
│   ├── mes/          # MES 对接组件
│   └── sms/          # 短信服务
├── admin/            # 管理后台服务
│   ├── system/       # 系统管理
│   ├── business/     # 业务逻辑
│   ├── finance/      # 财务
│   ├── salesperson/  # 销售
│   └── hy/           # 监管
├── mobile/           # 移动端服务
│   ├── consultation/ # 问诊
│   ├── prescription/ # 处方
│   └── ...
├── DoctorWx/         # 医生微信端
├── ClinicAdminWx/    # 门店管理微信端
└── callback/         # 回调处理
```

### 中间件设计

每种客户端角色有独立的认证中间件：
- 管理后台: `AuthMiddleware` (JWT)
- 患者端: `MobileAuthMiddleware` (Mobile JWT)
- 医生端: `DoctorWxUnifiedAuthMiddleware` (统一角色解析)
- 监管接口: `HyTransitApiMiddleware` (Token 验证)

### 队列设计

使用 RabbitMQ 处理异步任务：
- **支付回调** → 分账结算 Job
- **退款回调** → 佣金冲销 Job
- **定时任务** → 补算、同步 Job
- **超时处理** → 自动取消、自动确认收货

### 多端路由分离

通过独立路由文件区分不同端的接口：
- `admin.php` — 管理后台
- `mobile.php` — 患者小程序
- `doctor.php` — 医生端（含 8 种角色路由组）
- `hy.php` — 监管接口
- `callback.php` — 支付回调

## 技术选型

| 决策 | 选择 | 理由 |
|------|------|------|
| 框架 | Laravel 12 | PHP 生态最成熟，团队熟悉 |
| 认证 | Sanctum + JWT | 多端支持，API 灵活 |
| 队列 | RabbitMQ | 可靠性高，支持延迟队列 |
| 缓存 | Redis | 高性能，支持分布式锁 |
| 文件 | 阿里云 OSS | 国内访问快，成本低 |
| 支付 | 微信 + 易票联 | 双支付通道，覆盖主要场景 |
| Excel | Maatwebsite + PHPSpreadsheet | 复杂报表需求 |

## 扩展性考虑

### 新增 API 端
1. 创建新的路由文件
2. 创建对应的认证中间件
3. 在 `bootstrap/app.php` 中注册

### 新增业务模块
1. 在 `app/Http/Controllers/` 下创建控制器
2. 在 `app/Service/` 下创建服务类
3. 在 `app/Models/` 下创建模型（区分 new/old）
4. 在 `routes/` 对应文件中注册路由

### 新增定时任务
1. 在 `app/Console/Commands/` 下创建命令类
2. 在 `routes/console.php` 中注册调度
3. 更新 `定时任务命令表.md`