116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 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`
|