初始化

2026-07-08 15:04:42 +08:00
commit 70264153e5
129 changed files with 13797 additions and 0 deletions
--- a/docs/projects/xk-api/architecture.md
+++ b/docs/projects/xk-api/architecture.md
@@ -0,0 +1,121 @@
+# xk-api 基类架构
+
+## 控制器层级
+
+```mermaid
+graph TB
+    BC[Controller.php<br/>基础控制器] --> AC[AdminController<br/>管理后台控制器]
+    BC --> MC[MobileController<br/>移动端控制器]
+    BC --> DC[DoctorController<br/>医生端控制器]
+    BC --> HC[HyController<br/>监管接口控制器]
+    BC --> CC[CallbackController<br/>回调控制器]
+
+    AC --> SYS[admin/system/*<br/>系统管理 22个]
+    AC --> BIZ[admin/business/*<br/>业务管理 30+个]
+    AC --> FIN[admin/finance/*<br/>财务管理 8个]
+    AC --> SAL[admin/salesperson/*<br/>销售管理 3个]
+
+    MC --> MCON[mobile/consultation/*]
+    MC --> MPRE[mobile/prescription/*]
+    MC --> MORD[mobile/order/*]
+    MC --> MGUE[mobile/guest/*]
+
+    DC --> DWX[DoctorWx/*<br/>医生微信端]
+    DC --> CAWX[ClinicAdminWx/*<br/>门店管理微信端]
+    DC --> PAWX[PlatformAdminWx/*<br/>平台管理微信端]
+    DC --> SPWX[SalespersonWx/*<br/>推广员微信端]
+    DC --> CSWX[ClinicSalespersonWx/*<br/>门店推广员微信端]
+```
+
+## 服务层架构
+
+```mermaid
+graph TB
+    subgraph 公共服务 common/
+        JWT[JWTService] --> AUTH[认证]
+        WPAY[WechatPayService] --> PAY[支付]
+        EPL[EplPayService] --> EPAY[易票联]
+        SMS[SmsService] --> MSG[短信]
+        UPLOAD[UploadService] --> FILE[文件上传]
+        REDIS[RedisService] --> CACHE[缓存]
+        SEC[WeChatContentSecurityService] --> AUDIT[内容审核]
+    end
+
+    subgraph HTTP客户端 common/http/
+        OLD[OldApiClient] --> LEGACY[旧系统]
+        ERP[ErpApiClient] --> ERP_SYS[ERP系统]
+        HY[HyApiClient] --> HY_INT[互医平台]
+        MES[MesFailoverClient] --> MES_SYS[MES系统]
+        WS[WebSocketApiClient] --> IM[即时通讯]
+    end
+
+    subgraph 业务服务
+        PS[PrescriptionService] --> PRESCRIPTION[处方管理]
+        ORD[OrderService] --> ORDER[订单管理]
+        REG[RegisterService] --> REGISTER[挂号管理]
+        LED[LedgerService] --> SETTLE[结算管理]
+        SAL[SalespersonService] --> SALES[销售管理]
+    end
+```
+
+## 中间件
+
+| 中间件 | 文件 | 用途 |
+|--------|------|------|
+| `AuthMiddleware` | Admin 认证 | JWT 验证，解析管理员身份 |
+| `MobileAuthMiddleware` | 移动端认证 | 患者端 JWT 验证 |
+| `DoctorWxUnifiedAuthMiddleware` | 医生统一认证 | 医生端多角色统一认证 |
+| `ClinicAdminWxAuthMiddleware` | 门店管理认证 | 门店管理员身份验证 |
+| `PlatformAdminWxAuthMiddleware` | 平台管理认证 | 平台管理员身份验证 |
+| `SalespersonWxAuthMiddleware` | 推广员认证 | 推广员身份验证 |
+| `ClinicSalespersonWxAuthMiddleware` | 门店推广员认证 | 门店推广员身份验证 |
+| `HyTransitApiMiddleware` | 监管接口认证 | X-Hy-Transit-Token 验证 |
+| `HyTransitEncryptResponseMiddleware` | 监管响应加密 | AES-128-ECB 加密响应体 |
+| `EplpayMiddleware` | 易票联回调 | 签名验证 |
+| `WechatMiddleware` | 微信回调 | 签名验证 |
+| `ErpMiddleware` | ERP 回调 | ERP 系统认证 |
+| `ApiMiddleware` | 调试接口 | 开发调试用 |
+
+## 模型分层
+
+```mermaid
+graph TB
+    subgraph 新模型 Models/new/
+        N_ADMIN[admin/*<br/>管理后台 14个]
+        N_FIN[finance/*<br/>财务 3个]
+        N_SAL[salesperson/*<br/>销售 11个]
+        N_SP[special_prescription/*<br/>特色处方 7个]
+        N_SYS[system/*<br/>系统 9个]
+        N_HY[log/HyTransit*<br/>监管日志 2个]
+        N_CHAT[chat/*<br/>聊天 2个]
+        N_DISEASE[disease/*<br/>中医疾病 6个]
+    end
+
+    subgraph 旧模型 Models/old/
+        O_DRUG[drug/*<br/>药品 17个]
+        O_ORDER[order/*<br/>订单 15个]
+        O_PRESC[prescription/*<br/>处方 8个]
+        O_DOCTOR[doctor/*<br/>医生 21个]
+        O_USER[user/*<br/>用户 9个]
+        O_FIN[finacne/*<br/>财务 7个]
+        O_CONFIG[config/*<br/>配置 24个]
+        O_STORE[store/*<br/>门店 3个]
+    end
+```
+
+## 枚举体系
+
+| 域 | 枚举类 | 说明 |
+|----|--------|------|
+| 角色 | `RoleEnum` | 13 种角色：超管、管理员、省经理、市经理等 |
+| 用户类型 | `UserTypeEnum` | 门店、平台、供应商 |
+| 订单状态 | `OrderStatusEnum` | 待支付→待发货→待收货→待评价→退款→完成 |
+| 退款状态 | `OrderRefundStatusEnum` | 未退、申请中、同意、已退、拒绝、取消 |
+| 处方模板 | `PrescriptionTemplateTypeEnum` | 普通方、常用方、特色方 |
+| 财务 | `LedgerFeeTypeEnum` | 药品、挂号、快递、处方费、加工费、诊疗费 |
+| 财务状态 | `LedgerStatusEnum` | 待结算、已结算、已取消 |
+| 银行账户 | `BankAccountTypeEnum` | 对公、对私/法人、存折 |
+| 物流 | `ExpressStateEnum` | 收件→运输→签收→退回 |
+| 监管步骤 | `HySuperviseStepEnum` | 在线咨询、在线复诊、在线处方、处方核销 |
+| 聊天消息 | `MessageTypeEnum` | 文字、图片、语音、视频、处方、视频通话等 15 种 |
+| 中药冲突 | `ChineseMedicineConflictEnum` | 十八反、十九畏、有毒药材 |
--- a/docs/projects/xk-api/commands.md
+++ b/docs/projects/xk-api/commands.md
@@ -0,0 +1,67 @@
+# 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` 确认收货。
--- a/docs/projects/xk-api/components.md
+++ b/docs/projects/xk-api/components.md
@@ -0,0 +1,111 @@
+# 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
+- 通用工具方法
+- 错误处理
--- a/docs/projects/xk-api/design.md
+++ b/docs/projects/xk-api/design.md
@@ -0,0 +1,115 @@
+# 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`
--- a/docs/projects/xk-api/features.md
+++ b/docs/projects/xk-api/features.md
@@ -0,0 +1,236 @@
+# xk-api 重点功能
+
+## 处方流转体系
+
+```mermaid
+graph TB
+    subgraph 开方
+        D1[医生接诊] --> D2[选择患者]
+        D2 --> D3{处方类型}
+        D3 -->|中药| D4[中医处方]
+        D3 -->|西药| D5[西药处方]
+        D3 -->|颗粒| D6[颗粒处方]
+        D3 -->|中成药| D7[中成药处方]
+        D3 -->|服务包| D8[服务包处方]
+    end
+
+    subgraph 审方
+        D4 --> R1[医生初审]
+        D5 --> R1
+        D6 --> R1
+        D7 --> R1
+        R1 -->|通过| R2[药师复审]
+        R1 -->|拒绝| R3[退回修改]
+        R2 -->|通过| R4[处方生效]
+        R2 -->|拒绝| R3
+    end
+
+    subgraph 履约
+        R4 --> P1[患者购药]
+        P1 --> P2{配送方式}
+        P2 -->|快递| P3[仓库发货]
+        P2 -->|自提| P4[门店自提]
+        P2 -->|代煎| P5[MES 下单]
+    end
+```
+
+### 处方状态机
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 待审核 | 0 | 医生已开方，等待审核 |
+| 通过 | 1 | 审核通过 |
+| 未通过 | 2 | 审核拒绝 |
+| 无需审核 | 3 | 免审处方 |
+
+### 处方类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 中药 | 1 | 中药饮片处方 |
+| 西药 | 2 | 西药处方 |
+| 颗粒 | 3 | 配方颗粒处方 |
+| 中成药 | 4 | 中成药处方 |
+| 产品服务包 | 5 | 服务包处方 |
+
+### 转诊处方
+
+转诊处方是跨门店的处方流转机制：
+- **转诊方**（发起方）获得 100% 利润
+- **接收方**（被转方）负责履约
+- 处方来源自动设为接收方门店（`store_id = delegate_store_id`）
+- 支持线上转诊和线下转诊两种模式
+
+## 分账结算体系
+
+```mermaid
+graph TB
+    subgraph 收入
+        PAY1[产品订单付款] --> LED[分账记录]
+        PAY2[挂号订单付款] --> LED
+    end
+
+    subgraph 分账规则
+        LED --> S1[门店分账]
+        LED --> S2[平台分账]
+        LED --> S3[供应商分账]
+    end
+
+    subgraph 结算
+        S1 --> SET[结算单]
+        S2 --> SET
+        S3 --> SET
+        SET --> WITH[提现申请]
+        WITH --> AUDIT[审核]
+        AUDIT -->|通过| PAY3[打款]
+        AUDIT -->|拒绝| REJECT[退回]
+    end
+```
+
+### 分账记录 (yii_ledger)
+
+| 字段 | 说明 |
+|------|------|
+| `fee_type` | 费用类型：药品/挂号/快递/处方费/加工费/诊疗费 |
+| `status` | 0=待结算, 1=已结算, 2=已取消 |
+| `user_type` | 0=用户, 1=诊所, 2=平台 |
+
+### 可提现金额变更
+
+每次分账、退款、提现都会在 `xk_account_able_change_log` 中记录：
+- **来源类型**: settle（分账）、withdraw（提现）、refund（退款）
+- **变更前后金额**: before_amount → after_amount
+- **关联订单**: order_id, order_type, order_no
+
+## 佣金体系
+
+```mermaid
+graph TB
+    subgraph 佣金来源
+        O1[产品订单] --> C1[佣金记录]
+        O2[挂号订单] --> C1
+    end
+
+    subgraph 佣金计算
+        C1 --> CAL{计算方式}
+        CAL -->|固定佣金| F1[按模板/药品配置]
+        CAL -->|百分比佣金| F2[按比例计算]
+    end
+
+    subgraph 佣金结算
+        F1 --> SET[推广员结算单]
+        F2 --> SET
+        SET --> PAY[打款]
+    end
+
+    subgraph 退款冲销
+        REF[订单退款] --> REV[佣金冲销记录]
+        REV --> SET2[结算调整]
+    end
+```
+
+### 佣金模板
+- 按门店配置佣金模板
+- 模板下按药品配置单品佣金
+- 支持固定金额和百分比两种模式
+
+### 佣金结算
+- 支持按时段和按订单两种结算方式
+- 结算时生成凭证图片
+- 退款时自动冲销已结算佣金
+
+## MES 对接（中药智造）
+
+与和利康 MES 系统对接，实现处方自动下发到中药煎煮中心：
+
+```mermaid
+sequenceDiagram
+    participant API as xk-api
+    participant MES as 和利康 MES
+    participant DRUG as 煎煮中心
+
+    API->>MES: H001 提交处方 (HTTP+JSON)
+    MES-->>API: 返回处理结果
+    Note over MES: 失败时自动降级
+    API->>MES: W001 提交处方 (SOAP+XML)
+    MES-->>API: 返回处理结果
+    API->>API: 记录同步状态
+```
+
+### 处方字段映射
+- 煎煮方式: 28 种（先煎、煎煮、后下、烊化等）
+- 服法: 内服/外用
+- 剂量数、包装数、煎煮容量(ml)
+
+## 互联网医院监管上报
+
+```mermaid
+graph TB
+    subgraph 数据类型
+        T1[在线咨询]
+        T2[在线复诊]
+        T3[在线处方]
+        T4[处方核销]
+    end
+
+    subgraph 流程
+        T1 --> P[拉取打包]
+        T2 --> P
+        T3 --> P
+        T4 --> P
+        P --> ENC[加密]
+        ENC --> FWD[xk-hy-forward-go 转发]
+        FWD --> GOV[浙江省政务云]
+        GOV --> CB[回调结果]
+        CB --> UPD[更新状态]
+    end
+```
+
+### 监管数据接口
+
+| 接口 | 说明 |
+|------|------|
+| `uploadConsultIndicators` | 咨询信息上报 |
+| `uploadReferralIndicators` | 转诊/复诊信息上报 |
+| `uploadRecipeIndicators` | 处方信息上报（含中药扩展） |
+| `uploadRecipeVerificationIndicators` | 处方核销信息上报 |
+
+### 加密规则
+- 算法: AES-128-ECB + PKCS7 + Base64
+- 密钥: `substr(sha256(HY_TRANSIT_API_TOKEN), 0, 16)`
+
+### 签名规则
+- `sign = HmacSHA256(requestBody + secret + header params sorted alphabetically)`
+
+## 药品价格同步
+
+```mermaid
+graph LR
+    WH[仓库药品] -->|价格变更| PUB[xk_api 公共接口]
+    PUB --> SUB1[订阅门店1]
+    PUB --> SUB2[订阅门店2]
+    PUB --> SUB3[订阅门店N]
+
+    subgraph 同步方式
+        A[全量同步<br/>SyncDrugPriceBySubscribeJob]
+        B[单品同步<br/>SyncSingleDrugPriceBySubscribeJob]
+        C[批量同步<br/>BatchSyncDrugPriceJob]
+    end
+```
+
+### 价格计算规则
+- 门店采购价 = 仓库价 × 采购比例 (`z_buy_percent`)
+- 门店销售价 = 仓库价 × 销售比例 (`z_sale_percent`)
+- 支持门店独立调价
+
+## 特色处方体系
+
+特色处方是标准化的处方产品，具有独立的 SKU 和定价体系：
+
+| 概念 | 说明 |
+|------|------|
+| 特色处方 | 标准化的处方产品，如"感冒方"、"养生方" |
+| SKU | 剂量规格，如 7 剂、14 剂、21 剂 |
+| 价格方案 | 固定价 / 门店浮动价 |
+| 药品分摊 | 每个 SKU 下各药品的分摊价格 |
+| 患者记录 | 患者选择特色处方的记录（待应用→已应用→完成） |
--- a/docs/projects/xk-api/models.md
+++ b/docs/projects/xk-api/models.md
@@ -0,0 +1,142 @@
+# xk-api 模型分析
+
+模型分为两大类：**旧模型**（`Models/old/`，对应 `z_o_xk` 库的 `yii_*` 表）和**新模型**（`Models/new/`，对应 `z_xk` 库的 `xk_*` 表）。
+
+## 新模型 (z_xk 库)
+
+### 管理后台 (admin/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `AdminModel` | `xk_admin` | 管理员用户 |
+| `AdminNoticeModel` | `xk_admin_notice` | 管理员消息通知 |
+| `AdminNoticeRelationsModel` | `xk_admin_notice_relations` | 用户通知关联 |
+| `AdminSalespersonModel` | `xk_admin_salesperson` | 管理员-推广员关联 |
+| `AccountModel` | `xk_account_balance` | 账户余额 |
+| `AccountBalanceChangeRecordModel` | `xk_account_balance_change_record` | 余额变更记录 |
+| `CardModel` | `xk_card` | 用户银行卡 |
+| `MenuModel` | `xk_menu` | 菜单定义 |
+| `NoticeModel` | `xk_notice` | 公告 |
+| `PlatformModel` | `xk_platform` | 平台信息 |
+| `QueueJobModel` | `xk_queue_job` | 业务队列任务 |
+| `RoleModel` | `xk_role` | 角色定义 |
+| `RoleMenuRelationsModel` | `xk_role_menu_relations` | 角色-菜单绑定 |
+| `RoleQuickNavModel` | `xk_role_quick_nav` | 角色快捷导航 |
+| `SupplierModel` | `xk_supplier` | 供应商 |
+
+### 财务 (finance/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `AccountAbleChangeLogModel` | `xk_account_able_change_log` | 可提现金额变更日志 |
+| `MonthlyPaymentModel` | `xk_monthly_payment` | 月结账单 |
+| `MonthlyPaymentSettlementModel` | `xk_monthly_payment_settlement` | 月结结算记录 |
+
+### 销售 (salesperson/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ClinicSalespersonModel` | `xk_clinic_salesperson` | 门店推广员 |
+| `SalespersonCommissionRecordModel` | `xk_salesperson_commission_record` | 佣金记录 |
+| `SalespersonCommissionTemplateModel` | `xk_salesperson_commission_template` | 佣金模板 |
+| `SalespersonCommissionTemplateItemModel` | `xk_salesperson_commission_template_item` | 佣金模板明细 |
+| `SalespersonDrugCommissionModel` | `xk_salesperson_drug_commission` | 药品佣金配置 |
+| `SalespersonQrCodeModel` | `xk_salesperson_qr_code` | 推广员二维码 |
+| `SalespersonSettlementModel` | `xk_salesperson_settlement` | 推广员结算单 |
+| `SalespersonSettlementRecordModel` | `xk_salesperson_settlement_record` | 结算-佣金关联 |
+| `SalespersonStoreConfigModel` | `xk_salesperson_store_config` | 推广员门店配置 |
+| `UserSalespersonModel` | `xk_user_salesperson` | 用户-推广员绑定 |
+
+### 特色处方 (special_prescription/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionModel` | `xk_special_prescription` | 特色处方主表 |
+| `SpecialPrescriptionCategoryModel` | `xk_special_prescription_category` | 处方分类 |
+| `SpecialPrescriptionSkuModel` | `xk_special_prescription_sku` | SKU 剂量规格 |
+| `SpecialPrescriptionDrugPriceModel` | `xk_special_prescription_drug_price` | 药品分摊价格 |
+| `SpecialPrescriptionOrderModel` | `xk_special_prescription_order` | 处方订单快照 |
+| `SpecialPrescriptionPatientRecordModel` | `xk_special_prescription_patient_record` | 患者处方记录 |
+| `SpecialPrescriptionIntroductionImageModel` | `xk_special_prescription_introduction_images` | 介绍图片 |
+
+### 系统 (system/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `StoreInputModel` | `xk_store_input` | 门店预填表单 |
+| `StoreInputContractModel` | `xk_store_input_contract` | 门店合同文件 |
+| `StoreInputNavModel` | `xk_store_input_nav` | 门店轮播图 |
+| `DoctorInputModel` | `xk_doctor_input` | 医生预填表单 |
+| `DoctorInputStoreModel` | `xk_doctor_input_store` | 医生-门店绑定 |
+| `StoreBankCardReportModel` | `xk_store_bank_card_report` | 门店银行卡上报 |
+| `SpreadsheetTableConfigModel` | `xk_spreadsheet_table_config` | 画布表格配置 |
+| `SpreadsheetEditHistoryModel` | `xk_spreadsheet_edit_history` | 画布编辑历史 |
+| `SpreadsheetFormulaModel` | `xk_spreadsheet_formula` | 画布公式库 |
+
+### 监管日志 (log/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `HyTransitBatchModel` | `xk_hy_transit_batch` | 监管同步批次 |
+| `HyTransitRecordModel` | `xk_hy_transit_record` | 监管拉取/回调记录 |
+| `ApiOpLogModel` | `xk_api_op_log` | 新 API 操作日志 |
+| `ErrorLogModel` | `xk_error_log` | 错误日志 |
+| `ProductOrderPriceAdjustLogModel` | `xk_product_order_price_adjust_log` | 订单改价日志 |
+| `StoreDrugUpdateLogModel` | `xk_store_drug_update_log` | 药品价格变更日志 |
+| `SyncChinaOrderLogModel` | `xk_sync_china_order_log` | ERP 同步日志 |
+
+### 其他
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ChatMessageModel` | `xk_chat_messages` | 聊天消息 |
+| `ChatRoomModel` | `xk_chat_room` | 聊天房间 |
+| `SystemConfigModel` | `xk_system_config` | 系统配置 |
+| `FileModel` | `xk_file` | 文件管理 |
+| `FileGroupModel` | `xk_file_group` | 文件分组 |
+| `FileGroupRelModel` | `xk_file_group_rel` | 文件-分组关联 |
+| `FileTypeModel` | `xk_file_type` | 文件类型 |
+| `HomeZoneModel` | `xk_home_zones` | 首页分区 |
+| `PlatformQualificationsModel` | `xk_platform_qualifications` | 平台资质 |
+| `TransferAssistantConfigModel` | `xk_transfer_assistant_config` | 转诊助手配置 |
+| `TransferQuestionModel` | `xk_transfer_question` | 转诊问题模板 |
+| `TransferPrescriptionQuestionModel` | `xk_transfer_prescription_question` | 转诊处方问答 |
+| `RegisterInfoModel` | `xk_register_info` | 挂号就诊信息 |
+| `RegisterInfoDrugModel` | `xk_register_info_drug` | 挂号关联药品 |
+| `UserPatientGuardianModel` | `xk_user_patient_guardian` | 患者监护人信息 |
+| `SubjectsModel` | `xk_subjects` | 医学学科 |
+| `DoctorOrderModel` | `xk_doctor_order` | 医嘱 |
+| `DoctorQuickReplyModel` | `xk_doctor_quick_reply` | 医生快捷回复 |
+| `DoctorWxPhoneOpenidModel` | `xk_doctor_wx_phone_openid` | 医生手机-微信绑定 |
+| `DrugIntroductionImageModel` | `xk_drug_introduction_images` | 药品介绍图片 |
+| `StoreSubscribeModel` | `xk_store_subscribe` | 门店价格订阅 |
+| `TraditionalChineseMedicineDiseasesModel` | `xk_traditional_chinese_medicine_diseases` | 中医疾病库 |
+| `TraditionalChineseMedicineMethodModel` | `xk_traditional_chinese_medicine_method` | 中医治法库 |
+| `TraditionalChineseMedicineSyndromeModel` | `xk_traditional_chinese_medicine_syndrome` | 中医证候库 |
+| `PrescriptionDiseaseModel` | `xk_prescription_disease` | 处方-疾病关联 |
+| `PrescriptionMethodModel` | `xk_prescription_method` | 处方-治法关联 |
+| `PrescriptionSyndromeModel` | `xk_prescription_syndrome` | 处方-证候关联 |
+| `ProductOrderExportSchemeModel` | `xk_product_order_export_scheme` | 订单导出方案 |
+
+## 旧模型 (z_o_xk 库)
+
+旧模型按业务域组织在 `Models/old/` 下：
+
+| 目录 | 模型数 | 主要表 |
+|------|--------|--------|
+| `drug/` | 17 | `yii_drug`, `yii_drug_store_relations`, `yii_drug_categories` 等 |
+| `order/` | 15 | `yii_product_order`, `yii_product_order_items`, `yii_register` 等 |
+| `prescription/` | 8 | `yii_prescription`, `yii_prescription_chinese/west/granular` 等 |
+| `doctor/` | 21 | `yii_doctor_info`, `yii_doctor_service`, `yii_store_doctor` 等 |
+| `user/` | 9 | `yii_user`, `yii_user_patient`, `yii_service_user` 等 |
+| `finacne/` | 7 | `yii_ledger`, `yii_cash_account`, `yii_fund_water` 等 |
+| `config/` | 24 | `yii_admin`, `yii_role`, `yii_config`, `yii_menu` 等 |
+| `store/` | 3 | `yii_store`, `yii_store_doctor`, `yii_store_user` |
+| `recipe/` | 6 | `yii_chinese_recipe`, `yii_west_recipe`, `yii_granular_recipe` 等 |
+| `hospital/` | 5 | `yii_hospital`, `yii_hospital_yard`, `yii_department` 等 |
+| `im/` | 4 | `yii_im_message`, `yii_im_message_session` 等 |
+| `log/` | 8 | `yii_op_log`, `yii_order_log`, `yii_prescription_log` 等 |
+| `patient/` | 5 | `yii_user_patient_case`, `yii_patient_visit_record` 等 |
+| `physical/` | 3 | `yii_physical_package`, `yii_physical_reserve` 等 |
+| `queue/` | 3 | `yii_queue`, `yii_queue4`, `yii_failed_jobs` |
+| `other/` | 12 | `yii_disease`, `yii_department`, `yii_region` 等 |
--- a/docs/projects/xk-api/modules/chat.md
+++ b/docs/projects/xk-api/modules/chat.md
@@ -0,0 +1,62 @@
+# 聊天通讯模块
+
+## 概述
+
+聊天通讯模块负责好友管理和即时通讯功能。
+
+---
+
+## 好友管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `chat-friends/list` | 好友列表 |
+| POST | `chat-friends/add` | 添加好友 |
+| POST | `chat-friends/delete` | 删除好友 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ChatFriendsController` | `app/Http/Controllers/admin/chat/ChatFriendsController.php` | 控制器 |
+| `ChatFriendsService` | `app/Service/admin/chat/ChatFriendsService.php` | 业务服务 |
+
+---
+
+## 即时通讯
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `WebSocketApiClient` | `app/Service/common/http/WebSocketApiClient.php` | WebSocket 客户端 |
+| `ReadMessagesJob` | `app/Jobs/chat/ReadMessagesJob.php` | 消息已读 Job |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ChatMessageModel` | `xk_chat_messages` | 聊天消息 |
+| `ChatRoomModel` | `xk_chat_room` | 聊天房间 |
+
+### 消息类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 文字 | 0 | 文本消息 |
+| 图片 | 1 | 图片消息 |
+| 语音 | 2 | 语音消息 |
+| 视频 | 3 | 视频消息 |
+| 处方 | 4 | 处方消息 |
+| 病历 | 5 | 病历文件 |
+| 视频通话 | 6 | 视频通话 |
+| 语音通话 | 7 | 语音通话 |
+| 文件 | 8 | 文件消息 |
+| 系统 | 9 | 系统消息 |
+| 挂号 | 10 | 挂号消息 |
+| 患者体验 | 11 | 患者体验 |
+| 产品卡片 | 12 | 产品卡片 |
+| 结束问诊 | 13 | 结束问诊 |
+| 转诊处方 | 14 | 转诊处方 |
--- a/docs/projects/xk-api/modules/doctor.md
+++ b/docs/projects/xk-api/modules/doctor.md
@@ -0,0 +1,213 @@
+# 医生管理模块
+
+## 概述
+
+医生管理模块负责医生、药师的信息管理、接诊、在线问诊、患者管理等。
+
+---
+
+## 医生管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `doctor/list` | 医生列表 |
+| GET | `doctor/detail` | 医生详情 |
+| POST | `doctor/update` | 更新医生信息 |
+| GET | `doctor/option` | 医生选项 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `DoctorController` | `app/Http/Controllers/admin/business/doctor/DoctorController.php` | 控制器 |
+| `DoctorService` | `app/Service/admin/business/doctor/DoctorService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DoctorInfoModel` | `yii_doctor_info` | 医生信息 |
+| `DoctorServiceModel` | `yii_doctor_service` | 医生服务设置 |
+| `DoctorStoreModel` | `yii_store_doctor` | 门店-医生关联 |
+| `DoctorIdentityModel` | `yii_doctor_identity` | 身份验证 |
+| `DoctorPracticingModel` | `yii_doctor_practicing` | 执业证书 |
+| `DoctorTitleModel` | `yii_doctor_title` | 职称 |
+| `DoctorRegisterModel` | `yii_doctor_register` | 挂号设置 |
+| `DoctorRosteringModel` | `yii_doctor_rostering` | 排班 |
+| `DoctorNoticeModel` | `yii_doctor_notice` | 停诊通知 |
+
+---
+
+## 药师管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `pharmacist/list` | 药师列表 |
+| GET | `pharmacist/detail` | 药师详情 |
+| POST | `pharmacist/update` | 更新药师信息 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `PharmacistController` | `app/Http/Controllers/admin/business/doctor/PharmacistController.php` | 控制器 |
+| `PharmacistService` | `app/Service/admin/business/doctor/PharmacistService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `PharmacistInfoModel` | `yii_pharmacist_info` | 药师信息 |
+| `PharmacistIdentityModel` | `yii_pharmacist_identity` | 身份验证 |
+| `PharmacistPracticingModel` | `yii_pharmacist_practicing` | 执业证书 |
+
+---
+
+## 医生接诊
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `doctor-reception/list` | 接诊列表 |
+| GET | `doctor-reception/detail` | 接诊详情 |
+| POST | `doctor-reception/accept` | 接诊 |
+| POST | `doctor-reception/refuse` | 拒绝 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `DoctorReceptionController` | `app/Http/Controllers/admin/business/doctor/DoctorReceptionController.php` | 控制器 |
+| `DoctorReceptionService` | `app/Service/admin/business/doctor/DoctorReceptionService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `OrderModel` | `yii_order` | 咨询订单 |
+
+---
+
+## 在线问诊
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `online-consultation/list` | 问诊列表 |
+| POST | `online-consultation/config` | 问诊配置 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `OnlineConsultationController` | `app/Http/Controllers/admin/business/doctor/OnlineConsultationController.php` | 控制器 |
+| `OnlineConsultationService` | `app/Service/admin/business/doctor/OnlineConsultationService.php` | 业务服务 |
+| `OnlineConsultationClinicController` | `app/Http/Controllers/admin/business/doctor/OnlineConsultationClinicController.php` | 门店问诊控制器 |
+| `OnlineConsultationClinicService` | `app/Service/admin/business/doctor/OnlineConsultationClinicService.php` | 门店问诊服务 |
+
+---
+
+## 患者管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `patient-management/list` | 患者列表 |
+| GET | `patient-management/detail` | 患者详情 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `PatientManagementController` | `app/Http/Controllers/admin/business/doctor/PatientManagementController.php` | 控制器 |
+| `PatientManagementService` | `app/Service/admin/business/doctor/PatientManagementService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DoctorPatientModel` | `yii_doctor_patient` | 医生患者列表 |
+| `DoctorPatientRemarkModel` | `yii_doctor_patient_remark` | 患者备注 |
+| `PatientVisitRecordModel` | `yii_patient_visit_record` | 就诊记录 |
+| `UserPatientCaseModel` | `yii_user_patient_case` | 患者病历 |
+
+---
+
+## 医生文章
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `doctor-article/list` | 文章列表 |
+| GET | `doctor-article/detail` | 文章详情 |
+| POST | `doctor-article/create` | 创建文章 |
+| POST | `doctor-article/update` | 更新文章 |
+| POST | `doctor-article/delete` | 删除文章 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `DoctorArticleController` | `app/Http/Controllers/admin/business/doctor/DoctorArticleController.php` | 控制器 |
+| `DoctorArticleService` | `app/Service/admin/business/doctor/DoctorArticleService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DoctorArticleModel` | `yii_doctor_article` | 医生文章 |
+
+---
+
+## 文章分类
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `article-categories/list` | 分类列表 |
+| POST | `article-categories/create` | 创建分类 |
+| POST | `article-categories/update` | 更新分类 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ArticleCategoriesController` | `app/Http/Controllers/admin/business/doctor/ArticleCategoriesController.php` | 控制器 |
+| `ArticleCategoriesService` | `app/Service/admin/business/doctor/ArticleCategoriesService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ArticleCategoriesModel` | `yii_categories` | 文章分类 |
+
+---
+
+## 医生改价
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `doctor-reception/adjust-price` | 医生改价 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `OrderPriceAdjustService` | `app/Service/admin/business/doctor/OrderPriceAdjustService.php` | 改价服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ProductOrderPriceAdjustLogModel` | `xk_product_order_price_adjust_log` | 改价日志 |
--- a/docs/projects/xk-api/modules/drug.md
+++ b/docs/projects/xk-api/modules/drug.md
@@ -0,0 +1,217 @@
+# 药品管理模块
+
+## 概述
+
+药品管理模块负责药品目录、分类、定价、仓库管理、价格同步等。
+
+---
+
+## 西药/中成药
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `western-medicine/list` | 药品列表 |
+| GET | `western-medicine/detail` | 药品详情 |
+| POST | `western-medicine/create` | 创建药品 |
+| POST | `western-medicine/update` | 更新药品 |
+| POST | `western-medicine/status` | 上下架 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `WesternMedicineController` | `app/Http/Controllers/admin/business/product/WesternMedicineController.php` | 控制器 |
+| `WesternMedicineService` | `app/Service/admin/business/product/WesternMedicineService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DrugModel` | `yii_drug` | 药品主表 |
+| `DrugStoreRelationsModel` | `yii_drug_store_relations` | 药品-门店定价 |
+
+---
+
+## 中药
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `china-medicine/list` | 中药列表 |
+| GET | `china-medicine/detail` | 中药详情 |
+| POST | `china-medicine/create` | 创建中药 |
+| POST | `china-medicine/update` | 更新中药 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ChinaMedicineController` | `app/Http/Controllers/admin/business/product/ChinaMedicineController.php` | 控制器 |
+| `ChinaMedicineService` | `app/Service/admin/business/product/ChinaMedicineService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DrugModel` | `yii_drug` | 药品主表 |
+| `DrugNatureModel` | `yii_drug_nature` | 药品配伍（十八反十九畏） |
+
+### 中药配伍禁忌
+
+| 类型 | 常量 | 说明 |
+|------|------|------|
+| 十八反 | `OPPOSITION` | 相反药物不能同用 |
+| 十九畏 | `CONFLICT` | 相畏药物需谨慎 |
+| 有毒药材 | `POISONOUS` | 有毒性药材 |
+
+---
+
+## 保健食品
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `health-food/list` | 保健食品列表 |
+| POST | `health-food/create` | 创建 |
+| POST | `health-food/update` | 更新 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `HealthFoodController` | `app/Http/Controllers/admin/business/product/HealthFoodController.php` | 控制器 |
+| `HealthFoodService` | `app/Service/admin/business/product/HealthFoodService.php` | 业务服务 |
+
+---
+
+## 非药品/医疗器械
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `non-drug/list` | 非药品列表 |
+| POST | `non-drug/create` | 创建 |
+| GET | `medical-device/list` | 医疗器械列表 |
+| POST | `medical-device/create` | 创建 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `NonDrugController` | `app/Http/Controllers/admin/business/product/NonDrugController.php` | 非药品控制器 |
+| `MedicalDeviceController` | `app/Http/Controllers/admin/business/product/MedicalDeviceController.php` | 医疗器械控制器 |
+| `NonDrugService` | `app/Service/admin/business/product/NonDrugService.php` | 非药品服务 |
+| `MedicalDeviceService` | `app/Service/admin/business/product/MedicalDeviceService.php` | 医疗器械服务 |
+
+---
+
+## 药品分类
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `drug-categories/list` | 分类列表 |
+| POST | `drug-categories/create` | 创建分类 |
+| POST | `drug-categories/update` | 更新分类 |
+| POST | `drug-categories/delete` | 删除分类 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `DrugCategoriesController` | `app/Http/Controllers/admin/business/product/DrugCategoriesController.php` | 控制器 |
+| `DrugCategoriesService` | `app/Service/admin/business/product/DrugCategoriesService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DrugCategoriesModel` | `yii_drug_categories` | 药品分类 |
+
+---
+
+## 仓库管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `warehouse-drug-management/list` | 仓库药品列表 |
+| POST | `warehouse-drug-management/update-price` | 更新价格 |
+| POST | `warehouse-drug-management/update-status` | 更新状态 |
+| GET | `warehouse-drug-management-store/list` | 门店药品列表 |
+| POST | `warehouse-drug-management-store/sync` | 同步到门店 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `WarehouseDrugManagementController` | `app/Http/Controllers/admin/business/warehouseDrugManagement/WarehouseDrugManagementController.php` | 仓库控制器 |
+| `WarehouseDrugManagementStoreController` | `app/Http/Controllers/admin/business/warehouseDrugManagement/WarehouseDrugManagementStoreController.php` | 门店控制器 |
+| `WarehouseDrugManagementService` | `app/Service/admin/business/warehouseDrugManagement/WarehouseDrugManagementService.php` | 仓库服务 |
+| `WarehouseDrugManagementStoreService` | `app/Service/admin/business/warehouseDrugManagement/WarehouseDrugManagementStoreService.php` | 门店服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DrugStoreModel` | `yii_drugstore` | 药品仓库 |
+| `DrugStoreDrugModel` | `yii_drugstore_drug` | 仓库药品 |
+| `DrugStoreRelationsModel` | `yii_drug_store_relations` | 药品-门店定价 |
+
+### 价格同步流程
+
+```mermaid
+sequenceDiagram
+    participant WH as 仓库
+    participant API as xk-api
+    participant STORE as 门店
+
+    WH->>API: 价格变更
+    API->>API: BatchSyncDrugPriceJob
+    API->>STORE: 同步采购价(warehouse * z_buy_percent)
+    API->>STORE: 同步销售价(warehouse * z_sale_percent)
+    STORE->>STORE: 更新 yii_drug_store_relations
+```
+
+### 关联 Job
+
+| Job | 文件 | 说明 |
+|-----|------|------|
+| `BatchSyncDrugPriceJob` | `app/Jobs/admin/store/BatchSyncDrugPriceJob.php` | 批量同步价格 |
+| `SyncDrugPriceBySubscribeJob` | `app/Jobs/admin/store/SyncDrugPriceBySubscribeJob.php` | 订阅同步 |
+| `SyncSingleDrugPriceBySubscribeJob` | `app/Jobs/admin/store/SyncSingleDrugPriceBySubscribeJob.php` | 单品同步 |
+| `UpdateStoreChinesePriceByRatioJob` | `app/Jobs/admin/products/UpdateStoreChinesePriceByRatioJob.php` | 按比例更新中药价格 |
+| `UpdateStoreChineseSalePriceJob` | `app/Jobs/admin/products/UpdateStoreChineseSalePriceJob.php` | 更新中药销售价百分比 |
+
+---
+
+## 加工费管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `process/list` | 加工费列表 |
+| POST | `process/create` | 创建加工费 |
+| POST | `process/update` | 更新加工费 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ProsessController` | `app/Http/Controllers/admin/system/ProsessController.php` | 控制器 |
+| `ProcessService` | `app/Service/admin/system/ProcessService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ProcessRuleModel` | `yii_process_rule` | 加工规则 |
+| `ProcessRuleNoteModel` | `yii_process_rule_note` | 加工规则说明 |
--- a/docs/projects/xk-api/modules/finance.md
+++ b/docs/projects/xk-api/modules/finance.md
@@ -0,0 +1,219 @@
+# 财务结算模块
+
+## 概述
+
+财务结算模块负责分账、提现、对账、资金流水、月结等财务管理功能。
+
+---
+
+## 分账结算
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `settlement/list` | 结算列表 |
+| GET | `settlement/detail` | 结算详情 |
+| POST | `settlement/settle` | 执行结算 |
+| GET | `settlement/export` | 导出结算单 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SettlementController` | `app/Http/Controllers/admin/finance/SettlementController.php` | 控制器 |
+| `SettlementService` | `app/Service/admin/finance/SettlementService.php` | 业务服务 |
+| `LedgerService` | `app/Service/finance/LedgerService.php` | 分账服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `LedgerModel` | `yii_ledger` | 分账记录 |
+| `LedgerLogModel` | `yii_ledger_log` | 分账变更日志 |
+| `AccountAbleChangeLogModel` | `xk_account_able_change_log` | 可提现金额变更 |
+
+### 分账规则
+
+| 费用类型 | 值 | 说明 |
+|----------|-----|------|
+| 药品费用 | 1 | 产品订单药品费用 |
+| 挂号费用 | 2 | 挂号订单费用 |
+| 快递费用 | 3 | 快递费用 |
+| 处方费 | 4 | 处方费用 |
+| 加工费 | 5 | 代煎/加工费用 |
+| 诊疗费 | 6 | 诊疗费用 |
+
+### 分账流程
+
+```mermaid
+sequenceDiagram
+    participant P as 支付回调
+    participant J as ProductOrderPaidJob
+    participant L as LedgerService
+    participant DB as 数据库
+
+    P->>J: 支付成功
+    J->>L: createLedger(order)
+    L->>L: calculateSplit(order)
+    L->>DB: INSERT INTO yii_ledger (门店)
+    L->>DB: INSERT INTO yii_ledger (平台)
+    L->>DB: INSERT INTO xk_account_able_change_log
+```
+
+---
+
+## 提现管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `withdrawal-application/list` | 提现申请列表 |
+| GET | `withdrawal-application/detail` | 申请详情 |
+| POST | `withdrawal-application/audit` | 审核申请 |
+| POST | `withdrawal-application/pay` | 打款 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `WithdrawalApplicationController` | `app/Http/Controllers/admin/finance/WithdrawalApplicationController.php` | 控制器 |
+| `WithdrawalApplicationService` | `app/Service/admin/finance/WithdrawalApplicationService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `CashApplyModel` | `yii_cash_apply` | 提现申请 |
+| `CashAccountModel` | `yii_cash_account` | 提现账户 |
+
+### 提现审核流程
+
+```mermaid
+stateDiagram-v2
+    [*] --> 审核中: 提交申请
+    审核中 --> 已通过: 审核通过
+    审核中 --> 已拒绝: 审核拒绝
+    已通过 --> 打款中: 发起打款
+    打款中 --> 已打款: 打款成功
+    打款中 --> 打款失败: 打款失败
+    已拒绝 --> 审核中: 重新申请
+```
+
+---
+
+## 对账管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `reconciliation/list` | 对账列表 |
+| GET | `reconciliation/detail` | 对账详情 |
+| GET | `reconciliation/export` | 导出对账单 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ReconciliationController` | `app/Http/Controllers/admin/finance/ReconciliationController.php` | 控制器 |
+| `ReconciliationService` | `app/Service/admin/finance/ReconciliationService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ReconciliationModel` | `yii_reconciliation` | 对账记录 |
+
+---
+
+## 资金流水
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `fund-water/list` | 流水列表 |
+| GET | `fund-water/detail` | 流水详情 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `FundWaterController` | `app/Http/Controllers/admin/finance/FundWaterController.php` | 控制器 |
+| `FundWaterService` | `app/Service/admin/finance/FundWaterService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `FundWaterModel` | `yii_fund_water` | 资金流水 |
+
+---
+
+## 月结管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `monthly-payment/list` | 月结列表 |
+| GET | `monthly-payment/detail` | 月结详情 |
+| POST | `monthly-payment/settle` | 结算 |
+| POST | `monthly-payment/cancel` | 取消 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `MonthlyPaymentController` | `app/Http/Controllers/admin/finance/MonthlyPaymentController.php` | 控制器 |
+| `MonthlyPaymentService` | `app/Service/admin/finance/MonthlyPaymentService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `MonthlyPaymentModel` | `xk_monthly_payment` | 月结账单 |
+| `MonthlyPaymentSettlementModel` | `xk_monthly_payment_settlement` | 月结结算记录 |
+
+---
+
+## 代理付款
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `charge-cash-pay-record/list` | 付款记录列表 |
+| POST | `charge-cash-pay-record/create` | 创建付款记录 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ChargeCashPayRecordController` | `app/Http/Controllers/admin/finance/ChargeCashPayRecordController.php` | 控制器 |
+| `ChargeCashPayRecordService` | `app/Service/admin/finance/ChargeCashPayRecordService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ChargeCashPayRecordModel` | `yii_charge_cash_pay_record` | 代理付款记录 |
+
+---
+
+## 财务可视化
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `visualization-chart/data` | 图表数据 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `VisualizationChartController` | `app/Http/Controllers/admin/finance/VisualizationChartController.php` | 控制器 |
+| `VisualizationChartService` | `app/Service/admin/finance/VisualizationChartService.php` | 业务服务 |
--- a/docs/projects/xk-api/modules/hy-supervise.md
+++ b/docs/projects/xk-api/modules/hy-supervise.md
@@ -0,0 +1,180 @@
+# 监管上报模块
+
+## 概述
+
+监管上报模块负责与浙江省互联网医院监管平台对接，实现咨询、转诊、处方、核销等数据的上报和回调。
+
+---
+
+## 监管批次管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `transit/batch/create` | 创建批次 |
+| POST | `transit/batch/callback` | 批次回调 |
+| POST | `transit/batch/finish` | 完成批次 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `HyTransitBatchController` | `app/Http/Controllers/hy/HyTransitBatchController.php` | 控制器 |
+| `HyTransitRecordService` | `app/Service/admin/hy/HyTransitRecordService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `HyTransitBatchModel` | `xk_hy_transit_batch` | 监管同步批次 |
+| `HyTransitRecordModel` | `xk_hy_transit_record` | 监管拉取/回调记录 |
+
+### 批次状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 拉取中 | pulling | 正在拉取数据 |
+| 拉取完成 | done | 数据拉取完成 |
+| 拉取失败 | failed | 数据拉取失败 |
+
+### 回调状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 待回调 | pending | 等待回调 |
+| 回调完成 | done | 回调完成 |
+
+---
+
+## 监管数据拉取
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `supervise/consult` | 拉取咨询数据 |
+| GET | `supervise/referral` | 拉取转诊数据 |
+| GET | `supervise/recipe` | 拉取处方数据 |
+| GET | `supervise/verification` | 拉取核销数据 |
+| GET | `supervise/config` | 获取机构配置 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `HySupervisePullController` | `app/Http/Controllers/hy/HySupervisePullController.php` | 控制器 |
+| `HyApiService` | `app/Service/admin/hy/HyApiService.php` | API 服务 |
+| `HySupervisePayloadValidator` | `app/Service/admin/hy/HySupervisePayloadValidator.php` | 数据校验 |
+
+### 监管步骤
+
+| 步骤 | 值 | 说明 |
+|------|-----|------|
+| 在线咨询 | consult | 咨询信息上报 |
+| 在线复诊 | referral | 转诊/复诊信息上报 |
+| 在线处方 | recipe | 处方信息上报 |
+| 处方核销 | verification | 处方核销信息上报 |
+
+### 监管数据类型
+
+| 接口 | 说明 |
+|------|------|
+| `uploadConsultIndicators` | 咨询信息上报 |
+| `uploadReferralIndicators` | 转诊/复诊信息上报 |
+| `uploadRecipeIndicators` | 处方信息上报（含中药扩展） |
+| `uploadRecipeVerificationIndicators` | 处方核销信息上报 |
+
+### 监管数据流程
+
+```mermaid
+sequenceDiagram
+    participant API as xk-api
+    participant GO as xk-hy-forward-go
+    participant GOV as 浙江省政务云
+
+    Note over API: 定时触发 / 手动拉取
+    API->>API: 1. 创建批次 (batch/create)
+    API->>API: 2. 拉取数据 (supervise/consult, /recipe, ...)
+    API->>API: 3. 加密打包数据
+    API->>GO: 4. 转发加密数据
+    GO->>GOV: 5. 透传至政务云
+    GOV-->>GO: 6. 返回处理结果
+    GO-->>API: 7. 回调结果
+    API->>API: 8. 更新批次状态
+```
+
+---
+
+## 处方打印
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `PrescriptionPrintService` | `app/Service/admin/hy/PrescriptionPrintService.php` | 打印服务 |
+| `HyRecipeHtmlRenderer` | `app/Service/admin/hy/HyRecipeHtmlRenderer.php` | HTML 渲染 |
+
+### 处方详情
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET/POST | `transit/prescription/detail` | 处方详情 + 打印 HTML |
+| POST | `transit/prescription/recipe-file` | 保存处方文件 ID |
+
+---
+
+## 监管查询（管理后台）
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `log/hy-transit-batch-list` | 批次列表 |
+| GET | `log/hy-transit-record-list` | 记录列表 |
+| GET | `log/hy-transit-record-detail` | 记录详情 |
+
+---
+
+## 加密规则
+
+::: warning 安全信息
+- 算法: AES-128-ECB + PKCS7 + Base64
+- 密钥: `substr(sha256(HY_TRANSIT_API_TOKEN), 0, 16)`
+- 默认启用加密（`HY_TRANSIT_PAYLOAD_ENCRYPT=true`）
+:::
+
+### 签名规则
+
+```
+sign = HmacSHA256(requestBody + secret + header params sorted alphabetically)
+```
+
+---
+
+## 政务云接口规范
+
+### HTTP 层返回码
+
+| 代码 | 说明 |
+|------|------|
+| 200 | 成功 |
+| -1 | 系统繁忙 |
+| 40001 | 参数错误 |
+| 40002 | appKey 未找到 |
+| 40003 | appKey 已冻结 |
+| 40004 | appKey/appSecret 不匹配 |
+| 40006 | 无权限 |
+| 40007 | IP 未在白名单 |
+| 40010 | 签名无效 |
+| 40011 | 请求已过期 |
+| 40012 | 其他服务错误 |
+
+### 业务层 msgCode
+
+| 代码 | 说明 |
+|------|------|
+| 200 | 成功 |
+| -99 | 参数字段为空 |
+| -98 | 数据为空 |
+| -1 | 具体失败原因 |
--- a/docs/projects/xk-api/modules/index.md
+++ b/docs/projects/xk-api/modules/index.md
@@ -0,0 +1,64 @@
+# xk-api 功能模块
+
+## 模块总览
+
+```mermaid
+graph TB
+    subgraph 系统管理
+        S1[管理员管理]
+        S2[角色权限]
+        S3[菜单管理]
+        S4[系统配置]
+        S5[操作日志]
+        S6[公告通知]
+    end
+
+    subgraph 业务核心
+        B1[处方管理]
+        B2[订单管理]
+        B3[挂号管理]
+        B4[药品管理]
+        B5[门店管理]
+        B6[医生管理]
+        B7[药师管理]
+    end
+
+    subgraph 财务结算
+        F1[分账结算]
+        F2[提现管理]
+        F3[对账管理]
+        F4[资金流水]
+        F5[月结管理]
+    end
+
+    subgraph 销售推广
+        SP1[推广员管理]
+        SP2[佣金计算]
+        SP3[佣金结算]
+        SP4[转诊管理]
+    end
+
+    subgraph 特色功能
+        TF1[特色处方]
+        TF2[画布表格]
+        TF3[监管上报]
+        TF4[MES 对接]
+    end
+```
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 系统管理 | 管理员、角色、菜单、配置 | [系统管理](./system.md) |
+| 处方管理 | 处方开具、审核、转诊 | [处方管理](./prescription.md) |
+| 订单管理 | 产品订单、挂号、快递 | [订单管理](./order.md) |
+| 药品管理 | 药品目录、仓库、价格同步 | [药品管理](./drug.md) |
+| 医生管理 | 医生、药师、接诊、问诊 | [医生管理](./doctor.md) |
+| 门店管理 | 门店、入驻、银行卡上报 | [门店管理](./store.md) |
+| 财务结算 | 分账、提现、对账、月结 | [财务结算](./finance.md) |
+| 销售推广 | 推广员、佣金、结算 | [销售推广](./salesperson.md) |
+| 特色处方 | 特色处方、SKU、定价 | [特色处方](./special-prescription.md) |
+| 监管上报 | 互联网医院监管数据上报 | [监管上报](./hy-supervise.md) |
+| 聊天通讯 | 好友、即时通讯 | [聊天通讯](./chat.md) |
+| 画布表格 | 表格配置、编辑历史、公式 | [画布表格](./spreadsheet.md) |
--- a/docs/projects/xk-api/modules/order.md
+++ b/docs/projects/xk-api/modules/order.md
@@ -0,0 +1,173 @@
+# 订单管理模块
+
+## 概述
+
+订单管理模块负责产品订单、挂号订单的全流程管理，包括创建、支付、发货、退款等。
+
+---
+
+## 产品订单
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `order/list` | 订单列表 |
+| GET | `order/detail` | 订单详情 |
+| POST | `order/ship` | 发货 |
+| POST | `order/adjust-price` | 改价 |
+| POST | `order/export` | 导出 |
+| POST | `order/refund` | 退款 |
+| POST | `order/simulate-pay` | 模拟支付 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `OrderController` | `app/Http/Controllers/admin/business/order/OrderController.php` | 控制器 |
+| `OrderService` | `app/Service/admin/business/order/OrderService.php` | 业务服务 |
+| `OrderTraceService` | `app/Service/admin/business/order/OrderTraceService.php` | 状态追踪 |
+| `OrderSimulatePayService` | `app/Service/admin/business/order/OrderSimulatePayService.php` | 模拟支付 |
+| `DrugStockRollbackService` | `app/Service/admin/business/order/DrugStockRollbackService.php` | 库存回滚 |
+| `ProductOrderExportSchemeService` | `app/Service/admin/business/order/ProductOrderExportSchemeService.php` | 导出方案 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ProductOrderModel` | `yii_product_order` | 产品订单 |
+| `ProductOrderItemsModel` | `yii_product_order_items` | 订单明细 |
+| `ProductOrderRefundModel` | `yii_product_order_refund` | 产品退款 |
+| `PaymentProductOrderModel` | `yii_payment_product_order` | 产品支付 |
+| `ProductOrderPriceAdjustLogModel` | `xk_product_order_price_adjust_log` | 改价日志 |
+| `ProductOrderExportSchemeModel` | `xk_product_order_export_scheme` | 导出方案 |
+
+### 订单状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 待支付 | 0 | 订单已创建 |
+| 待发货 | 1 | 已支付，等待发货 |
+| 待收货 | 2 | 已发货，等待收货 |
+| 待评价 | 3 | 已收货，等待评价 |
+| 退款 | 4 | 已退款 |
+| 退款中 | 5 | 退款处理中 |
+| 已收货 | 6 | 已确认收货 |
+| 确认收货 | 7 | 已确认收货 |
+| 拒绝退款 | 8 | 退款被拒绝 |
+| 已取消 | 9 | 订单已取消 |
+
+### 订单流程
+
+```mermaid
+stateDiagram-v2
+    [*] --> 待支付: 创建订单
+    待支付 --> 待发货: 支付成功
+    待支付 --> 已取消: 超时未支付
+    待发货 --> 待收货: 发货
+    待收货 --> 已收货: 确认收货
+    待收货 --> 已收货: 自动确认
+    已收货 --> 已完成: 评价/超时
+    待支付 --> 退款中: 申请退款
+    退款中 --> 已退款: 退款成功
+    退款中 --> 待支付: 退款拒绝
+```
+
+### 关联 Job
+
+| Job | 文件 | 触发时机 |
+|-----|------|----------|
+| `ProductOrderPaidJob` | `app/Jobs/ProductOrderPaidJob.php` | 支付成功后创建分账 |
+| `ProductOrderRefundJob` | `app/Jobs/ProductOrderRefundJob.php` | 退款后更新分账 |
+| `ProductOrderSendJob` | `app/Jobs/ProductOrderSendJob.php` | 发货后延迟结算 |
+| `ProductOrderSyncPlatformJob` | `app/Jobs/ProductOrderSyncPlatformJob.php` | 同步订单状态 |
+| `AutoConfirmReceiptOrderJob` | `app/Jobs/admin/order/AutoConfirmReceiptOrderJob.php` | 自动确认收货 |
+| `AutomaticallyCancelTheOrderJob` | `app/Jobs/admin/order/AutomaticallyCancelTheOrderJob.php` | 自动取消订单 |
+
+---
+
+## 挂号管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `register/list` | 挂号列表 |
+| GET | `register/detail` | 挂号详情 |
+| POST | `register/refund` | 退款 |
+| POST | `register/accept` | 接诊 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `RegisterController` | `app/Http/Controllers/admin/business/registers/RegisterController.php` | 控制器 |
+| `RegisterService` | `app/Service/admin/business/register/RegisterService.php` | 业务服务 |
+| `RegisterRefundService` | `app/Service/admin/business/register/RegisterRefundService.php` | 退款服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `RegisterOrderModel` | `yii_register` | 挂号订单 |
+| `RegisterRefundModel` | `yii_register_refund` | 挂号退款 |
+| `PaymentRegisterModel` | `yii_payment_register` | 挂号支付 |
+
+### 关联 Job
+
+| Job | 文件 | 触发时机 |
+|-----|------|----------|
+| `RegisterPaidJob` | `app/Jobs/RegisterPaidJob.php` | 支付成功后创建分账 |
+| `RegisterAcceptJob` | `app/Jobs/RegisterAcceptJob.php` | 接诊后结算 |
+| `RegisterSmsJob` | `app/Jobs/RegisterSmsJob.php` | 支付后短信通知医生 |
+
+---
+
+## 快递管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `express-companies/list` | 快递公司列表 |
+| GET | `express-detail/list` | 物流详情列表 |
+| GET | `express-detail/detail` | 物流详情 |
+| POST | `express-detail/detail-by-order` | 按订单查物流 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ExpressCompaniesController` | `app/Http/Controllers/admin/business/express/ExpressCompaniesController.php` | 快递公司控制器 |
+| `ExpressDetailController` | `app/Http/Controllers/admin/business/express/ExpressDetailController.php` | 物流详情控制器 |
+| `ExpressCompaniesService` | `app/Service/admin/business/express/ExpressCompaniesService.php` | 快递公司服务 |
+| `ExpressDetailService` | `app/Service/admin/business/express/ExpressDetailService.php` | 物流详情服务 |
+| `ExpressCommand` | `app/Console/Commands/ExpressCommand.php` | 快递同步命令 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ExpressCompaniesModel` | `yii_express_companies` | 快递公司 |
+| `ExpressNosModel` | `yii_express_nos` | 快递单号 |
+| `ExpressDetailModel` | `yii_express_details` | 物流详情 |
+
+---
+
+## 服务包管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `service-pack/list` | 服务包列表 |
+| POST | `service-pack/create` | 创建服务包 |
+| POST | `service-pack/update` | 更新服务包 |
+| POST | `service-pack/delete` | 删除服务包 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ServicePackController` | `app/Http/Controllers/admin/business/product/ServicePackController.php` | 控制器 |
+| `ServicePackService` | `app/Service/admin/business/product/ServicePackService.php` | 业务服务 |
--- a/docs/projects/xk-api/modules/prescription.md
+++ b/docs/projects/xk-api/modules/prescription.md
@@ -0,0 +1,270 @@
+# 处方管理模块
+
+## 概述
+
+处方管理模块是 XK 系统的核心业务模块，负责处方的开具、审核、转诊、打印等全流程管理。
+
+---
+
+## 处方开具
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `prescription/list` | 处方列表 |
+| GET | `prescription/detail` | 处方详情 |
+| POST | `prescription/add-chinese` | 创建中药处方 |
+| POST | `prescription/add-west` | 创建西药处方 |
+| POST | `prescription/add-granular` | 创建颗粒处方 |
+| POST | `prescription/add-simple` | 创建简单处方（中成药/服务包/非药品/医疗器械） |
+| POST | `prescription/update` | 更新处方 |
+| POST | `prescription/delete` | 删除处方 |
+| GET | `prescription/print` | 处方打印 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `PrescriptionController` | `app/Http/Controllers/admin/business/prescription/PrescriptionController.php` | 控制器 |
+| `PrescriptionService` | `app/Service/admin/business/prescription/PrescriptionService.php` | 业务服务 |
+| `PrescriptionModel` | `app/Models/old/prescription/PrescriptionModel.php` | 主处方模型 |
+| `PrescriptionChineseModel` | `app/Models/old/prescription/PrescriptionChineseModel.php` | 中药处方模型 |
+| `PrescriptionWestModel` | `app/Models/old/prescription/PrescriptionWestModel.php` | 西药处方模型 |
+| `PrescriptionGranularModel` | `app/Models/old/prescription/PrescriptionGranularModel.php` | 颗粒处方模型 |
+| `PrescriptionServerModel` | `app/Models/old/prescription/PrescriptionServerModel.php` | 服务包处方模型 |
+| `PrescriptionPrintService` | `app/Service/admin/hy/PrescriptionPrintService.php` | 打印服务 |
+| `HyRecipeHtmlRenderer` | `app/Service/admin/hy/HyRecipeHtmlRenderer.php` | HTML 渲染 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `PrescriptionModel` | `yii_prescription` | 主处方表 |
+| `PrescriptionChineseModel` | `yii_prescription_chinese` | 中药处方 |
+| `PrescriptionWestModel` | `yii_prescription_west` | 西药处方 |
+| `PrescriptionGranularModel` | `yii_prescription_granular` | 颗粒处方 |
+| `PrescriptionServerModel` | `yii_prescription_server` | 服务包处方 |
+
+### 处方状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> 待审核: 医生开方
+    待审核 --> 通过: 医生初审通过
+    待审核 --> 未通过: 审核拒绝
+    通过 --> 药师复审: 药师审核
+    药师复审 --> 生效: 复审通过
+    药师复审 --> 未通过: 复审拒绝
+    生效 --> 已使用: 患者购药
+    生效 --> 已过期: 超时未用
+```
+
+### 处方类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 中药 | 1 | 中药饮片处方 |
+| 西药 | 2 | 西药处方 |
+| 颗粒 | 3 | 配方颗粒处方 |
+| 中成药 | 4 | 中成药处方 |
+| 产品服务包 | 5 | 服务包处方 |
+
+### 处方状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 待审核 | 0 | 医生已开方，等待审核 |
+| 通过 | 1 | 审核通过 |
+| 未通过 | 2 | 审核拒绝 |
+| 无需审核 | 3 | 免审处方 |
+
+### 处方开具流程
+
+```mermaid
+sequenceDiagram
+    participant D as 医生
+    participant C as PrescriptionController
+    participant S as PrescriptionService
+    participant M as PrescriptionModel
+    participant DB as 数据库
+
+    D->>C: POST prescription/add-chinese
+    C->>S: addChinesePrescription(data)
+    S->>S: validateData(data)
+    S->>M: create(prescription)
+    M->>DB: INSERT INTO yii_prescription
+    S->>M: createChinese(items)
+    M->>DB: INSERT INTO yii_prescription_chinese
+    S-->>C: prescription_id
+    C-->>D: 处方创建成功
+```
+
+---
+
+## 处方审核
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `audit-prescription/list` | 待审处方列表 |
+| GET | `audit-prescription/detail` | 处方详情 |
+| POST | `audit-prescription/audit` | 审核操作 |
+| POST | `audit-prescription/reject` | 拒绝操作 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `AuditPrescriptionController` | `app/Http/Controllers/admin/business/prescription/AuditPrescriptionController.php` | 控制器 |
+| `AuditPrescriptionService` | `app/Service/admin/business/prescription/AuditPrescriptionService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `PrescriptionModel` | `yii_prescription` | 主处方表 |
+
+### 审核流程
+
+```mermaid
+sequenceDiagram
+    participant A as 审核员
+    participant C as AuditPrescriptionController
+    participant S as AuditPrescriptionService
+    participant M as PrescriptionModel
+
+    A->>C: POST audit-prescription/audit
+    C->>S: audit(prescription_id, action)
+    S->>M: findById(prescription_id)
+    S->>S: checkPermission(audit_user)
+    
+    alt 医生初审
+        S->>M: update(status=1, first_view, first_sign)
+    else 药师复审
+        S->>M: update(status=1, again_view, again_sign)
+    end
+    
+    S-->>C: audit_result
+    C-->>A: 审核成功
+```
+
+---
+
+## 转诊处方
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `transfer-prescription/list` | 转诊处方列表 |
+| GET | `transfer-prescription/detail` | 转诊详情 |
+| POST | `transfer-prescription/create` | 创建转诊 |
+| POST | `transfer-prescription/confirm` | 确认转诊 |
+| POST | `transfer-prescription/import` | 导入转诊 |
+| POST | `transfer-prescription/cancel` | 取消转诊 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `TransferPrescriptionController` | `app/Http/Controllers/admin/business/prescription/TransferPrescriptionController.php` | 控制器 |
+| `TransferPrescriptionService` | `app/Service/admin/business/prescription/TransferPrescriptionService.php` | 业务服务 |
+| `TransferPrescriptionModel` | `app/Models/old/prescription/TransferPrescriptionModel.php` | 模型 |
+| `TransferQuestionService` | `app/Service/admin/business/prescription/TransferQuestionService.php` | 问题配置 |
+| `TransferAssistantConfigService` | `app/Service/admin/business/prescription/TransferAssistantConfigService.php` | 助手配置 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `TransferPrescriptionModel` | `yii_transfer_prescription` | 转诊处方 |
+| `TransferQuestionModel` | `xk_transfer_question` | 转诊问题 |
+| `TransferPrescriptionQuestionModel` | `xk_transfer_prescription_question` | 转诊问答 |
+| `TransferAssistantConfigModel` | `xk_transfer_assistant_config` | 转诊助手配置 |
+
+### 转诊流程
+
+```mermaid
+sequenceDiagram
+    participant O as 转诊方(发起)
+    participant R as 接收方(接收)
+    participant DB as 数据库
+
+    O->>DB: 创建转诊处方(transfer_prescription)
+    O->>O: 设置 is_from_transfer=1
+    
+    Note over O,R: 转诊方获得 100% 利润
+    
+    R->>DB: 确认接收
+    R->>DB: 导入为注册订单(register)
+    R->>DB: 创建处方(prescription)
+    R->>DB: 设置 store_id = delegate_store_id
+```
+
+### 转诊分账规则
+
+::: warning 关键逻辑
+- 转诊方（发起方）获得 **100%** 利润
+- 接收方（被转方）获得 **0%** 利润
+- 处方来源自动设为接收方门店（`store_id = delegate_store_id`）
+:::
+
+---
+
+## 常用处方
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `common-prescription/list` | 常用处方列表 |
+| POST | `common-prescription/create` | 创建常用处方 |
+| POST | `common-prescription/update` | 更新常用处方 |
+| POST | `common-prescription/delete` | 删除常用处方 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `CommonPrescriptionController` | `app/Http/Controllers/admin/business/doctor/CommonPrescriptionController.php` | 控制器 |
+| `CommonPrescriptionService` | `app/Service/admin/business/doctor/CommonPrescriptionService.php` | 业务服务 |
+
+---
+
+## 转诊问题配置
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `transfer-question/list` | 问题列表 |
+| POST | `transfer-question/create` | 创建问题 |
+| POST | `transfer-question/update` | 更新问题 |
+| POST | `transfer-question/delete` | 删除问题 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `TransferQuestionController` | `app/Http/Controllers/admin/business/prescription/TransferQuestionController.php` | 控制器 |
+| `TransferQuestionService` | `app/Service/admin/business/prescription/TransferQuestionService.php` | 业务服务 |
+
+---
+
+## 转诊助手配置
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `transfer-assistant-config/detail` | 助手配置详情 |
+| POST | `transfer-assistant-config/update` | 更新助手配置 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `TransferAssistantConfigController` | `app/Http/Controllers/admin/business/prescription/TransferAssistantConfigController.php` | 控制器 |
+| `TransferAssistantConfigService` | `app/Service/admin/business/prescription/TransferAssistantConfigService.php` | 业务服务 |
--- a/docs/projects/xk-api/modules/salesperson.md
+++ b/docs/projects/xk-api/modules/salesperson.md
@@ -0,0 +1,228 @@
+# 销售推广模块
+
+## 概述
+
+销售推广模块负责推广员管理、佣金计算、佣金结算等。
+
+---
+
+## 推广员管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `salesperson/list` | 推广员列表 |
+| GET | `salesperson/detail` | 推广员详情 |
+| POST | `salesperson/create` | 创建推广员 |
+| POST | `salesperson/update` | 更新推广员 |
+| POST | `salesperson/delete` | 删除推广员 |
+| GET | `salesperson/option` | 推广员选项 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SalespersonController` | `app/Http/Controllers/admin/salesperson/SalespersonController.php` | 控制器 |
+| `SalespersonService` | `app/Service/admin/salesperson/SalespersonService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ClinicSalespersonModel` | `xk_clinic_salesperson` | 门店推广员 |
+| `AdminSalespersonModel` | `xk_admin_salesperson` | 管理员-推广员关联 |
+| `UserSalespersonModel` | `xk_user_salesperson` | 用户-推广员绑定 |
+| `SalespersonQrCodeModel` | `xk_salesperson_qr_code` | 推广员二维码 |
+| `SalespersonStoreConfigModel` | `xk_salesperson_store_config` | 推广员门店配置 |
+
+---
+
+## 佣金计算
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SalespersonCommissionAccrualService` | `app/Service/admin/salesperson/SalespersonCommissionAccrualService.php` | 佣金计提 |
+| `SalespersonCommissionCalculator` | `app/Service/admin/salesperson/SalespersonCommissionCalculator.php` | 佣金计算 |
+| `SalespersonCommissionRecordFormatter` | `app/Service/admin/salesperson/SalespersonCommissionRecordFormatter.php` | 记录格式化 |
+| `SalespersonOrderBindService` | `app/Service/admin/salesperson/SalespersonOrderBindService.php` | 订单绑定 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SalespersonCommissionRecordModel` | `xk_salesperson_commission_record` | 佣金记录 |
+| `SalespersonCommissionTemplateModel` | `xk_salesperson_commission_template` | 佣金模板 |
+| `SalespersonCommissionTemplateItemModel` | `xk_salesperson_commission_template_item` | 佣金模板明细 |
+| `SalespersonDrugCommissionModel` | `xk_salesperson_drug_commission` | 药品佣金配置 |
+
+### 佣金计算方式
+
+| 方式 | 说明 |
+|------|------|
+| 固定金额 | 按模板/药品配置固定佣金 |
+| 百分比 | 按订单金额百分比计算 |
+
+### 佣金来源
+
+| 来源 | 说明 |
+|------|------|
+| 直接 | 推广员直接推广的订单 |
+| 邀请 | 推广员邀请的用户产生的订单 |
+
+### 佣金计提流程
+
+```mermaid
+sequenceDiagram
+    participant C as 定时任务
+    participant SVC as SalespersonCommissionAccrualService
+    participant DB as 数据库
+
+    C->>SVC: app:accrue-salesperson-commission
+    SVC->>DB: 查询今天已付款但无佣金的订单
+    loop 每个订单
+        SVC->>SVC: calculateCommission(order)
+        SVC->>DB: INSERT INTO xk_salesperson_commission_record
+    end
+```
+
+---
+
+## 佣金结算
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `settlement/list` | 结算单列表 |
+| GET | `settlement/detail` | 结算单详情 |
+| POST | `settlement/create` | 创建结算单 |
+| POST | `settlement/settle` | 执行结算 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SalespersonSettlementService` | `app/Service/admin/salesperson/SalespersonSettlementService.php` | 结算服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SalespersonSettlementModel` | `xk_salesperson_settlement` | 推广员结算单 |
+| `SalespersonSettlementRecordModel` | `xk_salesperson_settlement_record` | 结算-佣金关联 |
+
+### 结算方式
+
+| 方式 | 值 | 说明 |
+|------|-----|------|
+| 按时段 | 1 | 按时间段结算 |
+| 按订单 | 2 | 按订单逐笔结算 |
+
+---
+
+## 佣金冲销
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SalespersonCommissionReversalService` | `app/Service/admin/salesperson/SalespersonCommissionReversalService.php` | 冲销服务 |
+
+### 关联 Job
+
+| Job | 文件 | 说明 |
+|-----|------|------|
+| `SalespersonCommissionRefundJob` | `app/Jobs/SalespersonCommissionRefundJob.php` | 退款后佣金冲销 |
+
+### 冲销流程
+
+```mermaid
+sequenceDiagram
+    participant R as 退款回调
+    participant J as SalespersonCommissionRefundJob
+    participant SVC as SalespersonCommissionReversalService
+    participant DB as 数据库
+
+    R->>J: 退款成功
+    J->>SVC: reverseCommission(order_id)
+    SVC->>DB: 查询原佣金记录
+    SVC->>DB: INSERT INTO xk_salesperson_commission_record (record_type=退款冲销)
+```
+
+---
+
+## 佣金模板
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `commission-template/list` | 模板列表 |
+| POST | `commission-template/create` | 创建模板 |
+| POST | `commission-template/update` | 更新模板 |
+| POST | `commission-template/delete` | 删除模板 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SalespersonCommissionTemplateService` | `app/Service/admin/salesperson/SalespersonCommissionTemplateService.php` | 模板服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SalespersonCommissionTemplateModel` | `xk_salesperson_commission_template` | 佣金模板 |
+| `SalespersonCommissionTemplateItemModel` | `xk_salesperson_commission_template_item` | 佣金模板明细 |
+
+---
+
+## 门店推广员
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `clinic-salesperson-self/info` | 门店推广员信息 |
+| POST | `clinic-salesperson-self/update` | 更新信息 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `ClinicSalespersonSelfController` | `app/Http/Controllers/admin/salesperson/ClinicSalespersonSelfController.php` | 控制器 |
+| `SalespersonAdminAccountService` | `app/Service/admin/salesperson/SalespersonAdminAccountService.php` | 账户服务 |
+
+---
+
+## 推广员门店配置
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `salesperson-store-config/list` | 配置列表 |
+| POST | `salesperson-store-config/update` | 更新配置 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SalespersonStoreConfigController` | `app/Http/Controllers/admin/salesperson/SalespersonStoreConfigController.php` | 控制器 |
+| `SalespersonStoreConfigService` | `app/Service/admin/salesperson/SalespersonStoreConfigService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SalespersonStoreConfigModel` | `xk_salesperson_store_config` | 推广员门店配置 |
+
+### 配置说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `store_id` | int | 门店 ID（唯一） |
+| `see_price` | tinyint | 是否可见价格：0=否, 1=是 |
--- a/docs/projects/xk-api/modules/special-prescription.md
+++ b/docs/projects/xk-api/modules/special-prescription.md
@@ -0,0 +1,201 @@
+# 特色处方模块
+
+## 概述
+
+特色处方模块是 XK 系统的特色功能，提供标准化的处方产品，具有独立的 SKU 和定价体系。
+
+---
+
+## 特色处方管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `special-prescription/list` | 处方列表 |
+| GET | `special-prescription/detail` | 处方详情 |
+| POST | `special-prescription/create` | 创建处方 |
+| POST | `special-prescription/update` | 更新处方 |
+| POST | `special-prescription/status` | 上下架 |
+| GET | `special-prescription/sku-list` | SKU 列表 |
+| POST | `special-prescription/sku/create` | 创建 SKU |
+| POST | `special-prescription/sku/update` | 更新 SKU |
+| POST | `special-prescription/sku/delete` | 删除 SKU |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpecialPrescriptionController` | `app/Http/Controllers/admin/business/special_prescription/SpecialPrescriptionController.php` | 控制器 |
+| `SpecialPrescriptionService` | `app/Service/admin/business/special_prescription/SpecialPrescriptionService.php` | 业务服务 |
+| `SpecialPrescriptionPriceConfigService` | `app/Service/admin/business/special_prescription/SpecialPrescriptionPriceConfigService.php` | 价格配置 |
+| `SpecialPrescriptionPriceResolver` | `app/Service/admin/business/special_prescription/SpecialPrescriptionPriceResolver.php` | 价格解析 |
+| `SpecialPrescriptionPriceDistributor` | `app/Service/admin/business/special_prescription/SpecialPrescriptionPriceDistributor.php` | 价格分发 |
+| `SpecialPrescriptionShippingResolver` | `app/Service/admin/business/special_prescription/SpecialPrescriptionShippingResolver.php` | 运费解析 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionModel` | `xk_special_prescription` | 特色处方主表 |
+| `SpecialPrescriptionSkuModel` | `xk_special_prescription_sku` | SKU 剂量规格 |
+| `SpecialPrescriptionDrugPriceModel` | `xk_special_prescription_drug_price` | 药品分摊价格 |
+| `SpecialPrescriptionIntroductionImageModel` | `xk_special_prescription_introduction_images` | 介绍图片 |
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `prescription_sub_type` | tinyint | 1=中药, 2=西药, 3=颗粒 |
+| `name` | varchar | 处方名称 |
+| `category_id` | int | 分类 ID |
+| `cover_image` | varchar | 封面图 |
+| `intro_text` | mediumtext | 介绍文本 |
+| `tags` | json | 标签 |
+| `price_per_dose` | decimal | 每剂价格 |
+| `price_calc_scheme` | tinyint | 1=固定价, 3=门店浮动价 |
+| `buy_price_per_dose` | decimal | 每剂采购价 |
+| `sale_price_per_dose` | decimal | 每剂销售价 |
+| `sales_count` | int | 销量 |
+| `status` | tinyint | 状态 |
+| `is_free_shipping` | tinyint | 是否包邮 |
+| `free_shipping_min_doses` | int | 包邮最小剂量数 |
+| `store_id` | int | 门店 ID |
+
+---
+
+## 特色处方分类
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `special-prescription-category/list` | 分类列表 |
+| POST | `special-prescription-category/create` | 创建分类 |
+| POST | `special-prescription-category/update` | 更新分类 |
+| POST | `special-prescription-category/delete` | 删除分类 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpecialPrescriptionCategoryController` | `app/Http/Controllers/admin/business/special_prescription/SpecialPrescriptionCategoryController.php` | 控制器 |
+| `SpecialPrescriptionCategoryService` | `app/Service/admin/business/special_prescription/SpecialPrescriptionCategoryService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionCategoryModel` | `xk_special_prescription_category` | 处方分类 |
+
+---
+
+## SKU 管理
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionSkuModel` | `xk_special_prescription_sku` | SKU 剂量规格 |
+
+### SKU 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `special_prescription_id` | int | 特色处方 ID |
+| `store_id` | int | 门店 ID |
+| `sku_name` | varchar | SKU 名称（如"7剂"） |
+| `dose_count` | int | 剂量数 |
+| `status` | tinyint | 状态 |
+| `is_free_shipping` | tinyint | 是否包邮 |
+| `is_default` | tinyint | 是否默认 SKU |
+| `buy_price` | decimal | 采购价 |
+| `sale_price` | decimal | 销售价 |
+| `sort` | int | 排序 |
+
+---
+
+## 药品分摊价格
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionDrugPriceModel` | `xk_special_prescription_drug_price` | 药品分摊价格 |
+
+### 分摊逻辑
+
+```mermaid
+graph TB
+    subgraph 特色处方
+        SP[特色处方总价]
+    end
+
+    subgraph SKU
+        SKU1[SKU1: 7剂 ¥70]
+        SKU2[SKU2: 14剂 ¥130]
+        SKU3[SKU3: 21剂 ¥189]
+    end
+
+    subgraph 药品分摊
+        DRUG1[药品A: ¥10/剂]
+        DRUG2[药品B: ¥8/剂]
+        DRUG3[药品C: ¥5/剂]
+        DRUG4[药品D: ¥7/剂]
+    end
+
+    SP --> SKU1
+    SP --> SKU2
+    SP --> SKU3
+    SKU1 --> DRUG1
+    SKU1 --> DRUG2
+    SKU1 --> DRUG3
+    SKU1 --> DRUG4
+```
+
+---
+
+## 特色处方订单
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionOrderModel` | `xk_special_prescription_order` | 处方订单快照 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpecialPrescriptionOrderPricingService` | `app/Service/admin/business/special_prescription/SpecialPrescriptionOrderPricingService.php` | 订单定价 |
+| `SpecialPrescriptionPackageOrderItemBuilder` | `app/Service/admin/business/special_prescription/SpecialPrescriptionPackageOrderItemBuilder.php` | 订单项构建 |
+
+---
+
+## 患者处方记录
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpecialPrescriptionPatientRecordModel` | `xk_special_prescription_patient_record` | 患者处方记录 |
+
+### 状态流转
+
+```mermaid
+stateDiagram-v2
+    [*] --> 待应用: 患者选择
+    待应用 --> 已应用: 应用到处方
+    已应用 --> 完成: 购药完成
+    待应用 --> 取消: 患者取消
+```
+
+---
+
+## 特色处方模板
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpecialPrescriptionTemplateService` | `app/Service/admin/business/special_prescription/SpecialPrescriptionTemplateService.php` | 模板服务 |
--- a/docs/projects/xk-api/modules/spreadsheet.md
+++ b/docs/projects/xk-api/modules/spreadsheet.md
@@ -0,0 +1,130 @@
+# 画布表格模块
+
+## 概述
+
+画布表格模块提供类似 Excel 的在线表格编辑功能，支持表格配置、编辑历史、公式库等。
+
+---
+
+## 表格配置
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `spreadsheet-table-config/list` | 配置列表 |
+| GET | `spreadsheet-table-config/detail` | 配置详情 |
+| POST | `spreadsheet-table-config/create` | 创建配置 |
+| POST | `spreadsheet-table-config/update` | 更新配置 |
+| POST | `spreadsheet-table-config/delete` | 删除配置 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpreadsheetTableConfigController` | `app/Http/Controllers/admin/system/SpreadsheetTableConfigController.php` | 控制器 |
+| `SpreadsheetTableConfigService` | `app/Service/admin/system/SpreadsheetTableConfigService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpreadsheetTableConfigModel` | `xk_spreadsheet_table_config` | 画布表格配置 |
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `admin_id` | bigint | 管理员 ID |
+| `table_name` | varchar | 表名 |
+| `sheet_key` | varchar | 工作表标识 |
+| `name` | varchar | 配置名称 |
+| `is_default` | tinyint | 是否默认配置 |
+| `config` | json | 表格配置 |
+
+---
+
+## 编辑历史
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `spreadsheet-history/list` | 历史列表 |
+| POST | `spreadsheet-history/rollback` | 回滚操作 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpreadsheetHistoryController` | `app/Http/Controllers/admin/system/SpreadsheetHistoryController.php` | 控制器 |
+| `SpreadsheetHistoryService` | `app/Service/admin/system/SpreadsheetHistoryService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpreadsheetEditHistoryModel` | `xk_spreadsheet_edit_history` | 画布编辑历史 |
+
+### 操作类型
+
+| 类型 | 说明 |
+|------|------|
+| edit | 编辑单元格 |
+| fill | 填充 |
+| paste | 粘贴 |
+| rollback | 回滚 |
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `table_name` | varchar | 表名 |
+| `sheet_key` | varchar | 工作表标识 |
+| `admin_user_id` | bigint | 操作管理员 |
+| `admin_user_name` | varchar | 管理员名称 |
+| `row_key` | varchar | 行标识 |
+| `field_id` | varchar | 字段 ID |
+| `action` | varchar | 操作类型 |
+| `before_snapshot` | json | 操作前快照 |
+| `after_snapshot` | json | 操作后快照 |
+| `client_entry_id` | varchar | 客户端条目 ID |
+
+---
+
+## 公式库
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `spreadsheet-formula/list` | 公式列表 |
+| GET | `spreadsheet-formula/detail` | 公式详情 |
+| POST | `spreadsheet-formula/create` | 创建公式 |
+| POST | `spreadsheet-formula/update` | 更新公式 |
+| POST | `spreadsheet-formula/delete` | 删除公式 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SpreadsheetFormulaController` | `app/Http/Controllers/admin/system/SpreadsheetFormulaController.php` | 控制器 |
+| `SpreadsheetFormulaService` | `app/Service/admin/system/SpreadsheetFormulaService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SpreadsheetFormulaModel` | `xk_spreadsheet_formula` | 画布公式库 |
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | varchar | 公式编码（唯一） |
+| `name` | varchar | 公式名称 |
+| `description` | varchar | 公式描述 |
+| `expression_template` | text | 表达式模板 |
+| `ref_slots` | json | 引用槽位 |
+| `sort` | int | 排序 |
+| `status` | tinyint | 状态 |
--- a/docs/projects/xk-api/modules/store.md
+++ b/docs/projects/xk-api/modules/store.md
@@ -0,0 +1,176 @@
+# 门店管理模块
+
+## 概述
+
+门店管理模块负责门店信息管理、入驻审核、银行卡上报等。
+
+---
+
+## 门店管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `store/list` | 门店列表 |
+| GET | `store/detail` | 门店详情 |
+| POST | `store/create` | 创建门店 |
+| POST | `store/update` | 更新门店 |
+| POST | `store/audit` | 审核门店 |
+| GET | `store/option` | 门店选项 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `StoreController` | `app/Http/Controllers/admin/system/StoreController.php` | 控制器 |
+| `StoreService` | `app/Service/admin/system/StoreService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `StoreInputModel` | `xk_store_input` | 门店预填表单 |
+| `StoreModel` | `yii_store` | 门店表 |
+
+### 门店类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 诊所 | 0 | 中医/西医诊所 |
+| 药店 | 1 | 药品零售店 |
+
+### 诊所类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 西医 | 1 | 西医诊所 |
+| 中医 | 2 | 中医诊所 |
+
+---
+
+## 门店预填
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `store-input/list` | 预填列表 |
+| GET | `store-input/detail` | 预填详情 |
+| POST | `store-input/create` | 创建预填 |
+| POST | `store-input/update` | 更新预填 |
+| POST | `store-input/audit` | 审核预填 |
+| POST | `store-input/upload-contract` | 上传合同 |
+| POST | `store-input/add-nav` | 添加轮播图 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `StoreInputController` | `app/Http/Controllers/admin/system/StoreInputController.php` | 控制器 |
+| `StoreInputService` | `app/Service/admin/system/StoreInputService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `StoreInputModel` | `xk_store_input` | 门店预填表单 |
+| `StoreInputContractModel` | `xk_store_input_contract` | 门店合同文件 |
+| `StoreInputNavModel` | `xk_store_input_nav` | 门店轮播图 |
+
+### 门店审核流程
+
+```mermaid
+sequenceDiagram
+    participant S as 门店
+    participant A as 管理员
+    participant C as StoreInputController
+    participant SVC as StoreInputService
+    participant M as StoreInputModel
+
+    S->>C: POST store-input/create
+    C->>SVC: create(data)
+    SVC->>M: create(data)
+    M-->>C: store_input_id
+    C-->>S: 提交成功，等待审核
+
+    A->>C: POST store-input/audit
+    C->>SVC: audit(id, status, remark)
+    SVC->>M: update(status, audit_time)
+    
+    alt 审核通过
+        SVC->>SVC: syncToStore(store_input)
+        SVC-->>C: 门店创建成功
+    else 审核拒绝
+        SVC-->>C: 已拒绝
+    end
+```
+
+---
+
+## 医生预填
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `doctor-input/list` | 预填列表 |
+| GET | `doctor-input/detail` | 预填详情 |
+| POST | `doctor-input/create` | 创建预填 |
+| POST | `doctor-input/update` | 更新预填 |
+| POST | `doctor-input/audit` | 审核预填 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `DoctorInputController` | `app/Http/Controllers/admin/system/DoctorInputController.php` | 控制器 |
+| `DoctorInputService` | `app/Service/admin/system/DoctorInputService.php` | 业务服务 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DoctorInputModel` | `xk_doctor_input` | 医生预填表单 |
+| `DoctorInputStoreModel` | `xk_doctor_input_store` | 医生-门店绑定 |
+
+---
+
+## 银行卡上报
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `store-bank-card-report/list` | 上报列表 |
+| GET | `store-bank-card-report/detail` | 上报详情 |
+| POST | `store-bank-card-report/create` | 创建上报 |
+| POST | `store-bank-card-report/update` | 更新上报 |
+| GET | `store-bank-card-report/sync-status` | 同步状态 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `StoreBankCardReportController` | `app/Http/Controllers/admin/system/StoreBankCardReportController.php` | 控制器 |
+| `StoreBankCardReportService` | `app/Service/admin/system/StoreBankCardReportService.php` | 业务服务 |
+| `SyncStoreBankCardStatusCommand` | `app/Console/Commands/SyncStoreBankCardStatusCommand.php` | 状态同步命令 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `StoreBankCardReportModel` | `xk_store_bank_card_report` | 门店银行卡上报 |
+
+### 上报状态流程
+
+```mermaid
+stateDiagram-v2
+    [*] --> 待上报: 创建上报
+    待上报 --> 上报中: 提交易票联
+    上报中 --> 已通过: 审核通过
+    上报中 --> 已拒绝: 审核拒绝
+    已拒绝 --> 待上报: 重新上报
+    已通过 --> 已修改: 信息变更
+    已修改 --> 上报中: 重新上报
+```
--- a/docs/projects/xk-api/modules/system.md
+++ b/docs/projects/xk-api/modules/system.md
@@ -0,0 +1,259 @@
+# 系统管理模块
+
+## 概述
+
+系统管理模块负责管理后台的基础配置，包括管理员、角色权限、菜单、系统配置、操作日志、公告通知等。
+
+---
+
+## 管理员管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `admin/login` | 登录 |
+| POST | `admin/send-verification-code` | 发送验证码 |
+| POST | `admin/logout` | 退出 |
+| GET | `admin/my-info` | 当前用户信息 |
+| GET | `admin/codes` | 权限码列表 |
+| GET | `admin/menu` | 菜单列表 |
+| GET | `admin/my-belong-id` | 当前归属 ID |
+| GET | `admin/sibling-accounts` | 同级账户列表 |
+| POST | `admin/switch-account` | 切换账户 |
+| GET | `admin/my-balance` | 我的余额 |
+| GET | `admin/my-card` | 我的银行卡 |
+| GET | `admin/get-quick-menu` | 快捷菜单 |
+| GET | `admin/list` | 管理员列表 |
+| GET | `admin/option` | 管理员选项 |
+| GET | `admin/detail` | 管理员详情 |
+| GET | `admin/creatable-roles` | 可创建角色 |
+| POST | `admin/create` | 创建管理员 |
+| POST | `admin/update` | 更新管理员 |
+| POST | `admin/delete` | 删除管理员 |
+| POST | `admin/reset-password` | 重置密码 |
+| POST | `admin/update-password` | 修改密码 |
+| POST | `admin/save-card` | 保存银行卡 |
+| POST | `admin/generate-login-account` | 生成登录账号 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `AdminController` | `app/Http/Controllers/admin/system/AdminController.php` | 控制器 |
+| `AdminService` | `app/Service/admin/system/AdminService.php` | 业务服务 |
+| `AdminModel` | `app/Models/new/admin/AdminModel.php` | 模型 |
+| `AdminNoticeModel` | `app/Models/new/admin/AdminNoticeModel.php` | 通知模型 |
+| `AdminNoticeRelationsModel` | `app/Models/new/admin/AdminNoticeRelationsModel.php` | 通知关联 |
+| `JWTService` | `app/Service/common/JWTService.php` | JWT 认证 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `AdminModel` | `xk_admin` | 管理员用户 |
+| `AdminNoticeModel` | `xk_admin_notice` | 管理员消息 |
+| `AdminNoticeRelationsModel` | `xk_admin_notice_relations` | 用户通知关联 |
+
+### 流程图
+
+```mermaid
+sequenceDiagram
+    participant C as 客户端
+    participant A as AdminController
+    participant S as AdminService
+    participant M as AdminModel
+    participant JWT as JWTService
+
+    C->>A: POST admin/login
+    A->>S: login(account, password)
+    S->>M: findByAccount(account)
+    M-->>S: admin
+    S->>S: verifyPassword(password, hash)
+    S->>JWT: generateToken(admin)
+    JWT-->>C: token
+```
+
+---
+
+## 角色权限
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `role/list` | 角色列表 |
+| GET | `role/detail` | 角色详情 |
+| POST | `role/create` | 创建角色 |
+| POST | `role/update` | 更新角色 |
+| POST | `role/delete` | 删除角色 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `RoleController` | `app/Http/Controllers/admin/system/RoleController.php` | 控制器 |
+| `RoleService` | `app/Service/admin/system/RoleService.php` | 业务服务 |
+| `RoleModel` | `app/Models/new/admin/RoleModel.php` | 模型 |
+| `RoleMenuRelationsModel` | `app/Models/new/admin/RoleMenuRelationsModel.php` | 角色-菜单关联 |
+| `RoleQuickNavModel` | `app/Models/new/admin/RoleQuickNavModel.php` | 快捷导航 |
+| `RoleEnum` | `app/Enum/RoleEnum.php` | 角色枚举 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `RoleModel` | `xk_role` | 角色定义 |
+| `RoleMenuRelationsModel` | `xk_role_menu_relations` | 角色-菜单绑定 |
+| `RoleQuickNavModel` | `xk_role_quick_nav` | 角色快捷导航 |
+
+### 角色枚举 (RoleEnum)
+
+| 值 | 常量 | 说明 |
+|----|------|------|
+| 1 | `SUPPER_ADMIN` | 超级管理员 |
+| 2 | `ADMIN` | 管理员 |
+| 3 | `PROVINCE_MANAGER` | 省经理 |
+| 4 | `CITY_MANAGER` | 市经理 |
+| 5 | `DISTRICT_MANAGER` | 区经理 |
+| 6 | `SALESPERSON` | 推广员 |
+| 7 | `SUPPLIER` | 供应商 |
+| 8 | `CLINIC_ADMINISTRATOR` | 门店管理员 |
+| 9 | `CLINIC_STAFF` | 门店员工 |
+| 10 | `DOCTOR` | 医生 |
+| 11 | `PHARMACIST` | 药师 |
+| 12 | `HEADQUARTERS_FINANCE` | 总部财务 |
+| 14 | `CLINIC_SALESPERSON` | 门店推广员 |
+
+---
+
+## 菜单管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `menu/list` | 菜单列表 |
+| POST | `menu/create` | 创建菜单 |
+| POST | `menu/update` | 更新菜单 |
+| POST | `menu/delete` | 删除菜单 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `MenuController` | `app/Http/Controllers/admin/system/MenuController.php` | 控制器 |
+| `MenuService` | `app/Service/admin/system/MenuService.php` | 业务服务 |
+| `MenuModel` | `app/Models/new/admin/MenuModel.php` | 模型 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `MenuModel` | `xk_menu` | 菜单定义 |
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `title` | varchar | 菜单名称 |
+| `icon` | varchar | 图标 |
+| `name` | varchar | 路由名称 |
+| `path` | varchar | 路由路径 |
+| `component` | varchar | 组件路径 |
+| `redirect` | varchar | 重定向 |
+| `pid` | int | 父级 ID |
+| `sort` | int | 排序 |
+| `hide_in_menu` | tinyint | 是否隐藏 |
+| `affix_tab` | tinyint | 是否固定标签 |
+
+---
+
+## 系统配置
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `system-config/list` | 配置列表 |
+| POST | `system-config/update` | 更新配置 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `SystemConfigController` | `app/Http/Controllers/admin/system/SystemConfigController.php` | 控制器 |
+| `SystemConfigService` | `app/Service/admin/system/SystemConfigService.php` | 业务服务 |
+| `SystemConfigModel` | `app/Models/new/config/SystemConfigModel.php` | 模型 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `SystemConfigModel` | `xk_system_config` | 系统配置 |
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `config_key` | varchar | 配置键（唯一） |
+| `config_value` | text | 配置值 |
+| `value_type` | varchar | 值类型：string/int/float/bool/json |
+| `config_group` | varchar | 配置分组 |
+| `description` | varchar | 描述 |
+| `is_system` | tinyint | 是否系统配置 |
+
+---
+
+## 操作日志
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `log/list` | 日志列表 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `OldController` | `app/Http/Controllers/admin/log/OldController.php` | 控制器 |
+| `OldLogService` | `app/Service/admin/log/OldLogService.php` | 业务服务 |
+| `ApiOpLogModel` | `app/Models/new/log/ApiOpLogModel.php` | 模型 |
+| `ErrorLogModel` | `app/Models/new/log/ErrorLogModel.php` | 错误日志模型 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `ApiOpLogModel` | `xk_api_op_log` | API 操作日志 |
+| `ErrorLogModel` | `xk_error_log` | 错误日志 |
+
+---
+
+## 公告通知
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `notice/list` | 通知列表 |
+| POST | `notice/create` | 创建通知 |
+| POST | `notice/update` | 更新通知 |
+| POST | `notice/delete` | 删除通知 |
+
+### 关联类
+
+| 类 | 文件 | 说明 |
+|----|------|------|
+| `NoticeController` | `app/Http/Controllers/admin/system/NoticeController.php` | 控制器 |
+| `NoticeService` | `app/Service/admin/system/NoticeService.php` | 业务服务 |
+| `NoticeModel` | `app/Models/new/admin/NoticeModel.php` | 模型 |
+| `AdminNoticeModel` | `app/Models/new/admin/AdminNoticeModel.php` | 管理员通知模型 |
+
+### 关联模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `NoticeModel` | `xk_notice` | 公告 |
+| `AdminNoticeModel` | `xk_admin_notice` | 管理员消息 |
--- a/docs/projects/xk-api/overview.md
+++ b/docs/projects/xk-api/overview.md
@@ -0,0 +1,79 @@
+# xk-api 概览
+
+xk-api 是 XK 系统的核心 API 服务，基于 Laravel 12 构建，承载所有业务逻辑。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 框架 | Laravel 12.x |
+| PHP 版本 | >= 8.4 |
+| 包管理 | Composer |
+| 认证 | Laravel Sanctum + 自定义 JWT |
+| 队列 | RabbitMQ (vladimir-yuldashev/laravel-queue-rabbitmq) |
+| 性能 | LaravelS (hhxsv5/laravel-s) |
+| 文件存储 | 阿里云 OSS |
+| 支付 | 微信支付 + 易票联 (EPL) |
+| 短信 | EasySms (阿里云短信) |
+| Excel | Maatwebsite/Excel + PHPSpreadsheet |
+
+## 目录结构
+
+```
+xk-api/
+├── app/
+│   ├── BaseApp/          # 基础应用类
+│   ├── Console/Commands/ # Artisan 命令 (10个)
+│   ├── Constants/        # 常量定义
+│   ├── Core/             # 核心逻辑
+│   ├── Enum/             # 枚举类 (30+)
+│   ├── Excel/            # Excel 导出
+│   ├── Http/
+│   │   ├── Controllers/  # 控制器 (116个)
+│   │   └── Middleware/    # 中间件
+│   ├── Jobs/             # 队列任务 (24个)
+│   ├── Mail/             # 邮件
+│   ├── Models/
+│   │   ├── old/          # 旧模型 (Yii表, ~130个)
+│   │   └── new/          # 新模型 (xk表, ~100个)
+│   ├── Providers/        # 服务提供者
+│   ├── Service/          # 业务服务 (~160个)
+│   └── Support/          # 支撑类
+├── config/               # 配置文件 (17个)
+├── database/             # 迁移、种子
+├── docs/                 # 项目文档
+├── routes/               # 路由定义 (9个文件)
+├── scripts/              # 脚本工具
+└── tests/                # 测试
+```
+
+## 路由入口
+
+| 路由文件 | 前缀 | 端 | 说明 |
+|----------|------|-----|------|
+| `admin.php` | `/api/admin` | 管理后台 | 50+ 路由组，覆盖系统管理、业务、财务 |
+| `mobile.php` | `/api/mobile` | 患者小程序 | 问诊、购药、挂号、处方、转诊 |
+| `doctor.php` | `/api/doctor` | 医生端小程序 | 8 种角色独立路由组 |
+| `hy.php` | `/api/hy` | 监管中转 | 批次管理、数据拉取、回调 |
+| `callback.php` | `/api/callback` | 支付回调 | 易票联、微信支付 |
+| `open-api.php` | `/api/open` | 开放 API | 上传、同步、数据大屏 |
+
+## 关键配置文件
+
+| 文件 | 说明 |
+|------|------|
+| `config/xk.php` | XK 项目专属配置 |
+| `config/ase.php` | 加密配置 |
+| `config/laravels.php` | LaravelS 性能优化配置 |
+| `config/queue.php` | 队列配置 (RabbitMQ) |
+| `config/filesystems.php` | 文件系统 (OSS) |
+
+## 现有文档
+
+| 文档 | 说明 |
+|------|------|
+| `docs/hy-transit-api.md` | 互联网医院监管中转 API 接口文档 |
+| `定时任务命令表.md` | 定时任务命令索引 |
+| `新互联网医院监管平台文档.md` | 浙江省互联网医院监管平台接口规范 v2.0 |
+| `转接方分账和处方来源修改_影响分析.md` | 转诊分账逻辑影响分析 |
+| `《和利康源中药智能制造 MES 系统接口说明 V1.2》.md` | MES 系统接口规范 |