# xk-api 定时命令

## 调度基础设施

生产环境需要**每分钟**执行一次调度：
- Linux: `* * * * * php artisan schedule:run`
- 或通过 LaravelS 内置调度

调度定义位于 `routes/console.php`。

## 定时任务

| 命令 | 频率 | 说明 | 类 |
|------|------|------|-----|
| `app:update-prescription-status-in-messages` | 每分钟 | 批量更新聊天消息中的处方状态 | `UpdatePrescriptionStatusInMessagesCommand` |
| `app:accrue-salesperson-commission` | 每小时 | 补算今天已付款但无佣金记录的订单 | `AccrueSalespersonCommissionCommand` |
| `app:sync-store-bank-card-status` | 每 2 小时 | 同步易票联银行卡上报状态 | `SyncStoreBankCardStatusCommand` |

::: warning 跨库注意
`app:accrue-salesperson-commission` 需要同时查询两个库：订单在 `z_o_xk`，佣金记录在 `z_xk`。两步查询，不允许跨库 JOIN。
:::

## 已禁用的定时任务

| 命令 | 原频率 | 说明 | 状态 |
|------|--------|------|------|
| `hy:sync-supervise` | 每天 02:00 | 浙江互联网医院监管数据同步 | 已迁移到 xk-hy-transit-go，已注释 |

## 手动维护命令

以下命令不自动调度，需要手动执行：

| 命令 | 说明 | 参数 |
|------|------|------|
| `app:backfill-reconciliation` | 回填已结算但缺少 `yii_reconciliation` 记录的订单 | `--order-id`, `--limit`, `--dry-run` |
| `app:backfill-settle-audit-logs` | 从 `yii_ledger_log` 回填 `xk_account_able_change_log` | `--order-id`, `--register-id`, `--limit`, `--dry-run` |
| `app:backfill-withdraw-apply-audit-logs` | 回填历史提现申请的审计日志 | `--apply-id`, `--order-no`, `--limit`, `--dry-run` |
| `app:fix-fund-water-timestamps` | 修复 `yii_fund_water` 中 `created_at=0` 的记录 | `--order-id`, `--limit`, `--dry-run` |
| `app:express` | 快递追踪同步（快递100 API） | — |
| `app:update-account-balance-command` | 账户余额更新 | — |
| `hy:sync-supervise` | 监管数据同步（手动触发） | — |

## 命令详情

### app:update-prescription-status-in-messages
每分钟扫描聊天消息表（`message_type=4` 即处方消息），根据处方当前状态批量更新消息中的状态字段，保持前端展示与实际处方状态一致。

### app:accrue-salesperson-commission
补偿逻辑：查询今天已付款的产品订单，检查是否有对应的佣金记录，没有则自动补算。需要跨两个数据库查询。

### app:sync-store-bank-card-status
调用易票联 API 查询银行卡上报状态，更新 `xk_store_bank_card_report` 表中的 `epl_state` 和 `report_status`。

### app:backfill-reconciliation
数据修复命令：找出 `yii_ledger` 中已结算但 `yii_reconciliation` 缺失的记录，补建对账数据。支持 `--dry-run` 模式预览。

### app:backfill-settle-audit-logs
从旧表 `yii_ledger_log` 读取结算记录，在新表 `xk_account_able_change_log` 中补建对应的可提现金额变更日志。

### app:backfill-withdraw-apply-audit-logs
为历史提现申请补建申请阶段的审计日志。

### app:fix-fund-water-timestamps
修复 `yii_fund_water` 表中 `created_at=0` 的异常记录，使用订单的 `pay_time` 作为时间戳。

### app:express
调用快递100 API 同步物流状态，签收后自动触发 `AutoConfirmReceiptOrderJob` 确认收货。