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

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