初始化

2026-07-08 15:04:42 +08:00
commit 70264153e5
129 changed files with 13797 additions and 0 deletions
--- a/docs/projects/xk-admin/architecture.md
+++ b/docs/projects/xk-admin/architecture.md
@@ -0,0 +1,55 @@
+# xk-admin 基类架构
+
+## 技术架构
+
+```mermaid
+graph TB
+    subgraph Monorepo
+        APP[apps/web-antd<br/>主应用]
+        INT[internal/<br/>内部共享包]
+        PKG[packages/<br/>共享工作区包]
+        PLAY[playground/<br/>开发调试]
+    end
+
+    subgraph 主应用 web-antd
+        MAIN[main.ts] --> VUE[Vue 3 App]
+        VUE --> ROUTER[Vue Router]
+        VUE --> PINIA[Pinia Store]
+        VUE --> UI[Ant Design Vue]
+        ROUTER --> VIEWS[views/*]
+        VIEWS --> API[api/*]
+        API --> HTTP[axios]
+    end
+
+    HTTP --> BACKEND[xk-api<br/>后端 API]
+```
+
+## 目录结构
+
+| 目录 | 说明 |
+|------|------|
+| `adapter/` | API 适配器，统一请求格式 |
+| `api/` | API 接口定义，按模块组织 |
+| `components/` | 共享 Vue 组件 |
+| `composables/` | Vue Composition API 复用逻辑 |
+| `layouts/` | 页面布局（侧边栏、顶栏、内容区） |
+| `locales/` | 国际化资源文件 |
+| `router/` | 路由配置和守卫 |
+| `store/` | Pinia 状态管理 |
+| `views/` | 页面视图，按模块组织 |
+| `utils/` | 工具函数 |
+
+## 构建工具
+
+- **Vite**: 开发服务器和构建
+- **Turborepo**: Monorepo 任务编排和缓存
+- **pnpm**: 包管理（workspace 协议）
+- **TypeScript**: 类型检查
+
+## 开发命令
+
+```bash
+pnpm dev          # 启动开发服务器
+pnpm build        # 生产构建
+pnpm lint         # 代码检查
+```
--- a/docs/projects/xk-admin/components.md
+++ b/docs/projects/xk-admin/components.md
@@ -0,0 +1,30 @@
+# xk-admin 通用组件
+
+## 布局组件
+
+| 组件 | 说明 |
+|------|------|
+| `layouts/` | 页面整体布局（侧边栏 + 顶栏 + 内容区） |
+| 侧边栏 | 菜单导航，支持多级折叠 |
+| 顶栏 | 面包屑、搜索、通知、用户信息 |
+| 标签页 | 多标签页切换 |
+
+## 业务组件
+
+| 组件 | 说明 |
+|------|------|
+| 权限指令 | `v-access:code` 按钮级权限控制 |
+| API 适配器 | 统一请求格式和错误处理 |
+| 数据表格 | Ant Design Vue Table 封装 |
+| 表单组件 | 搜索表单、编辑表单 |
+| 文件上传 | 图片、文件上传组件 |
+| 富文本编辑 | Markdown / 富文本编辑器 |
+| 图表 | ECharts 集成（数据大屏） |
+
+## 工具函数
+
+| 工具 | 说明 |
+|------|------|
+| `utils/` | 通用工具函数 |
+| `composables/` | Vue Composition API 复用逻辑 |
+| `locales/` | 国际化资源 |
--- a/docs/projects/xk-admin/design.md
+++ b/docs/projects/xk-admin/design.md
@@ -0,0 +1,45 @@
+# xk-admin 设计思路
+
+## 架构决策
+
+### Monorepo 结构
+
+采用 pnpm workspace + Turborepo 的 Monorepo 架构：
+- **apps/web-antd**: 主应用，包含所有业务页面
+- **internal/**: 内部共享包（构建配置、工具）
+- **packages/**: 共享工作区包（可复用的组件库）
+- **playground/**: 开发调试环境
+
+### Vben Admin Pro
+
+选择 Vben Admin Pro 作为基础框架：
+- 开箱即用的管理后台模板
+- 完善的权限体系（菜单权限 + 按钮权限）
+- 丰富的布局和主题配置
+- TypeScript 支持
+
+### 多角色菜单
+
+通过后端动态菜单接口 (`auth/menu`) 加载菜单，不同角色看到不同菜单：
+- 前端不硬编码菜单结构
+- 菜单数据由后端 `xk_menu` 表管理
+- 支持菜单层级、图标、排序、隐藏
+
+### 按钮权限
+
+使用 `v-access:code` 自定义指令控制按钮级权限：
+- 权限码从后端 `auth/codes` 接口获取
+- 指令在元素级别控制显示/隐藏
+- 避免前端硬编码权限判断
+
+## 技术选型
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 框架 | Vue 3 + Vben Admin Pro | 成熟的管理后台方案 |
+| UI 库 | Ant Design Vue | 企业级 UI 组件库 |
+| 状态管理 | Pinia | Vue 3 官方推荐 |
+| 路由 | Vue Router | Vue 生态标准 |
+| 构建 | Vite + Turborepo | 快速开发和构建 |
+| 包管理 | pnpm | 高效的依赖管理 |
+| 语言 | TypeScript | 类型安全 |
--- a/docs/projects/xk-admin/modules/business.md
+++ b/docs/projects/xk-admin/modules/business.md
@@ -0,0 +1,43 @@
+# 业务管理模块
+
+## 处方管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 处方管理 | `prescription/*` | 处方列表、详情、打印 |
+| 处方审核 | `audit-prescription/*` | 处方审核流程 |
+| 转诊管理 | `transfer-prescription/*` | 转诊处方管理 |
+| 转诊问题 | `transfer-question/*` | 转诊问题模板 |
+| 常用处方 | `common-prescription/*` | 处方模板管理 |
+
+## 订单管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 产品订单 | `order/*` | 订单列表、发货、退款 |
+| 挂号管理 | `register/*` | 挂号订单管理 |
+| 服务包 | `service-pack/*` | 服务包管理 |
+| 快递管理 | `express-companies/*`, `express-detail/*` | 快递公司、物流详情 |
+
+## 转诊流程
+
+```mermaid
+graph LR
+    A[转诊方开方] --> B[转诊处方]
+    B --> C[接收方确认]
+    C --> D[导入为挂号]
+    D --> E[接收方开方]
+    E --> F[患者购药]
+```
+
+## 处方审核流程
+
+```mermaid
+graph TB
+    A[医生开方] --> B{医生初审}
+    B -->|通过| C{药师复审}
+    B -->|拒绝| D[退回修改]
+    C -->|通过| E[处方生效]
+    C -->|拒绝| D
+    E --> F[患者购药]
+```
--- a/docs/projects/xk-admin/modules/dashboard.md
+++ b/docs/projects/xk-admin/modules/dashboard.md
@@ -0,0 +1,52 @@
+# 仪表盘模块
+
+## 功能概述
+
+管理后台首页仪表盘，展示系统核心指标和营业趋势。
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 数据分析 | `/analytics` | 核心指标卡片 + 营业额趋势图 |
+| 工作台 | `/workspace` | 工作台快捷入口 |
+
+## 数据分析页
+
+### 指标卡片
+
+| 指标 | 数据来源 | 说明 |
+|------|----------|------|
+| 用户数 | `yii_user` | 系统注册用户总数 |
+| API 日志数 | `xk_api_op_log` | API 调用总次数 |
+| 订单数 | `yii_product_order` | 产品订单总数 |
+| 门店数 | `yii_store` | 系统门店总数 |
+
+### 营业额趋势
+
+| 参数 | 说明 |
+|------|------|
+| `type=1` | 最近 24 小时（按小时统计） |
+| `type=2` | 最近 12 个月（按月统计） |
+
+```mermaid
+graph LR
+    A[AnalyticsService] --> B[UserModel<br/>用户总数]
+    A --> C[ApiOpLogModel<br/>API日志数]
+    A --> D[ProductOrderModel<br/>订单数 + 营业额]
+    A --> E[StoreModel<br/>门店数]
+```
+
+## 对应 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `api/admin/home/analytics` | 指标卡片统计数据 |
+| GET | `api/admin/home/turnover` | 营业额趋势数据 |
+
+## 关联类
+
+| 类 | 路径 | 说明 |
+|----|------|------|
+| `AnalyticsController` | `app/Service/admin/home/AnalyticsController.php` | 控制器 |
+| `AnalyticsService` | `app/Service/admin/home/AnalyticsService.php` | 服务层 |
--- a/docs/projects/xk-admin/modules/doctor.md
+++ b/docs/projects/xk-admin/modules/doctor.md
@@ -0,0 +1,51 @@
+# 医生管理模块
+
+## 医生管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 医生管理 | `doctor/*` | 医生信息管理 |
+| 药师管理 | `pharmacist/*` | 药师信息管理 |
+| 医生接诊 | `doctor-reception/*` | 接诊工作台 |
+| 在线问诊 | `online-consultation/*` | 在线问诊管理 |
+| 患者管理 | `patient-management/*` | 患者列表 |
+| 医生文章 | `doctor-article/*` | 科普文章管理 |
+| 文章分类 | `article-categories/*` | 文章分类管理 |
+
+## 医生状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 停用 | -1 | 已停用 |
+| 待激活 | 0 | 未激活 |
+| 待审核 | 1 | 等待审核 |
+| 已认证 | 2 | 已通过认证 |
+| 拒绝 | 3 | 审核拒绝 |
+
+## 医生类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 中医 | 1 | 中医医生 |
+| 西医 | 2 | 西医医生 |
+
+## 接诊流程
+
+```mermaid
+sequenceDiagram
+    participant P as 患者
+    participant A as 管理员
+    participant D as 医生
+
+    P->>A: 提交问诊
+    A->>D: 分配医生
+    D->>D: 接诊/拒绝
+    alt 接诊
+        D->>P: 开始问诊
+        D->>D: 开具处方
+        D->>P: 处方生效
+    else 拒绝
+        D->>A: 说明原因
+        A->>P: 重新分配
+    end
+```
--- a/docs/projects/xk-admin/modules/drug.md
+++ b/docs/projects/xk-admin/modules/drug.md
@@ -0,0 +1,44 @@
+# 药品管理模块
+
+## 药品目录
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 西药/中成药 | `western-medicine/*` | 西药和中成药管理 |
+| 中药 | `china-medicine/*` | 中药饮片管理 |
+| 保健食品 | `health-food/*` | 保健食品管理 |
+| 非药品 | `non-drug/*` | 非药品管理 |
+| 医疗器械 | `medical-device/*` | 医疗器械管理 |
+| 药品分类 | `drug-categories/*` | 分类树管理 |
+
+## 仓库管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 仓库管理 | `warehouse-drug-management/*` | 仓库药品价格和库存 |
+| 门店仓库 | `warehouse-drug-management-store/*` | 门店药品同步 |
+
+## 价格管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 加工费 | `process/*` | 代煎/加工费用 |
+| 区域价格 | `region/*` | 区域价格管理 |
+
+## 药品价格同步
+
+```mermaid
+graph LR
+    WH[仓库药品] -->|价格变更| PUB[公共接口]
+    PUB --> SUB1[订阅门店1]
+    PUB --> SUB2[订阅门店2]
+    PUB --> SUB3[订阅门店N]
+```
+
+## 药品状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 草稿 | 1 | 未上架 |
+| 下架 | 2 | 已下架 |
+| 上架 | 3 | 正常销售 |
--- a/docs/projects/xk-admin/modules/finance.md
+++ b/docs/projects/xk-admin/modules/finance.md
@@ -0,0 +1,48 @@
+# 财务管理模块
+
+## 财务模块
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 分账结算 | `settlement/*` | 分账记录、结算操作 |
+| 提现管理 | `withdrawal-application/*` | 提现申请审核 |
+| 对账管理 | `reconciliation/*` | 对账单查询 |
+| 资金流水 | `fund-water/*` | 资金流水查询 |
+| 月结管理 | `monthly-payment/*` | 医保月结 |
+| 代理付款 | `charge-cash-pay-record/*` | 费用记录 |
+| 财务图表 | `visualization-chart/*` | 可视化展示 |
+
+## 分账规则
+
+```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[打款]
+    end
+```
+
+## 提现审核流程
+
+```mermaid
+graph LR
+    A[提交申请] --> B[管理员审核]
+    B -->|通过| C[发起打款]
+    B -->|拒绝| D[退回]
+    C --> E[打款成功]
+```
--- a/docs/projects/xk-admin/modules/hy-audit.md
+++ b/docs/projects/xk-admin/modules/hy-audit.md
@@ -0,0 +1,38 @@
+# 监管审计模块
+
+## 监管拉取记录
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 监管拉取记录 | `log/hy-transit-batch-list` | 批次查询 |
+| 监管回调结果 | `log/hy-transit-record-list` | 回调记录 |
+| 监管记录详情 | `log/hy-transit-record-detail` | 失败详情 |
+
+## 监管批次状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 拉取中 | pulling | 正在拉取数据 |
+| 拉取完成 | done | 数据拉取完成 |
+| 拉取失败 | failed | 数据拉取失败 |
+
+## 监管记录状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 已拉取 | pulled | 数据已拉取 |
+| 校验跳过 | skipped_validate | 校验跳过 |
+| 待上报 | pending | 等待上报 |
+| 上报成功 | success | 上报成功 |
+| 上报失败 | failed | 上报失败 |
+| 已跳过 | skipped | 已跳过 |
+
+## 监管数据流程
+
+```mermaid
+graph LR
+    A[数据拉取] --> B[打包加密]
+    B --> C[转发至政务云]
+    C --> D[回调结果]
+    D --> E[更新状态]
+```
--- a/docs/projects/xk-admin/modules/index.md
+++ b/docs/projects/xk-admin/modules/index.md
@@ -0,0 +1,22 @@
+# xk-admin 功能模块
+
+## 模块总览
+
+管理后台按业务域组织视图页面，对应后端 API 的路由分组。
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 系统管理 | 管理员、角色、菜单、配置 | [系统管理](./system.md) |
+| 业务管理 | 处方、订单、挂号、服务包 | [业务管理](./business.md) |
+| 药品管理 | 药品目录、仓库、分类 | [药品管理](./drug.md) |
+| 医生管理 | 医生、药师、接诊、问诊 | [医生管理](./doctor.md) |
+| 门店管理 | 门店、入驻、银行卡上报 | [门店管理](./store.md) |
+| 财务管理 | 分账、提现、对账、月结 | [财务管理](./finance.md) |
+| 销售推广 | 推广员、佣金、转诊 | [销售推广](./salesperson.md) |
+| 特色处方 | 特色处方管理 | [特色处方](./special-prescription.md) |
+| 监管审计 | 监管拉取记录、回调结果 | [监管审计](./hy-audit.md) |
+| 仪表盘 | 首页数据分析、营业额趋势 | [仪表盘](./dashboard.md) |
+| 日志管理 | 操作日志、API 日志、监管拉取记录 | [日志管理](./log.md) |
+| 通知公告 | 系统通知发布与已读管理 | [通知公告](./notice.md) |
--- a/docs/projects/xk-admin/modules/log.md
+++ b/docs/projects/xk-admin/modules/log.md
@@ -0,0 +1,95 @@
+# 日志管理模块
+
+## 功能概述
+
+统一管理系统操作日志、订单日志、处方日志、分账日志、API 访问日志以及互联网医院监管拉取记录。
+
+## 日志类型
+
+| 日志类型 | 数据模型 | 说明 |
+|----------|----------|------|
+| 操作日志 | `LogModel` (旧) | 审核/订单/财务/同步互医操作记录 |
+| 订单日志 | `ProductOrderLogModel` | 产品订单变更日志 |
+| 处方日志 | `PrescriptionLogModel` | 处方状态变更日志 |
+| 分账日志 | `LedgerLogModel` | 分账/扣费/退款明细 |
+| 旧 API 日志 | `OldOpLogModel` | 旧系统 API 调用记录 |
+| API 访问日志 | `ApiOpLogModel` | 新系统 API 访问记录（后台/患者/医生） |
+| 监管拉取批次 | `HyTransitBatchModel` | 互联网医院监管数据拉取批次 |
+| 监管回调记录 | `HyTransitRecordModel` | 监管数据回调结果明细 |
+
+## 操作日志
+
+### 日志分类 (mold)
+
+| 值 | 分类 | 说明 |
+|----|------|------|
+| 1 | 审核操作 | 处方审核、药师审方等 |
+| 2 | 订单操作 | 订单状态变更 |
+| 3 | 财务操作 | 分账、提现等 |
+| 4 | 同步互医 | 互联网医院数据同步 |
+
+## API 访问日志
+
+### 平台类型 (platform_type)
+
+| 值 | 平台 | 说明 |
+|----|------|------|
+| `Admin` | 管理后台 | admin 端操作 |
+| `Mobile` | 患者端 | 小程序端操作 |
+| `Doctor` | 医生端 | 医生/药师端操作 |
+
+### 用户搜索
+
+支持按三种用户类型搜索 API 日志操作人：
+
+| 用户类型 | 搜索来源 | 搜索字段 |
+|----------|----------|----------|
+| admin | `xk_admin` | 昵称、手机号 |
+| patient | `yii_user` | 昵称 |
+| doctor | `yii_service_user` | 昵称、手机号、医生姓名 |
+
+## 监管拉取记录
+
+### 批次查询
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/log/hy-transit-batch-list` | 监管拉取批次分页列表 |
+| GET | `/log/hy-transit-record-list` | 监管回调结果明细分页（支持 `callback_status` 过滤） |
+| GET | `/log/hy-transit-record-detail` | 回调详情（payload + response + error） |
+
+```mermaid
+graph TB
+    subgraph 日志查询
+        A[操作日志] --> D[日志列表]
+        B[订单日志] --> D
+        C[处方日志] --> D
+        E[分账日志] --> D
+        F[API 日志] --> D
+    end
+
+    subgraph 监管记录
+        G[拉取批次] --> H[回调明细]
+        H --> I[回调详情]
+    end
+```
+
+## 对应 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `api/admin/log/op-list` | 操作日志列表 |
+| GET | `api/admin/log/order-list` | 订单日志列表 |
+| GET | `api/admin/log/prescription-list` | 处方日志列表 |
+| GET | `api/admin/log/ledger-list` | 分账日志列表 |
+| GET | `api/admin/log/old-api-list` | 旧 API 日志列表 |
+| GET | `api/admin/log/api-list` | 新 API 访问日志列表 |
+| GET | `api/admin/log/user-search` | API 日志操作用户搜索 |
+
+## 关联类
+
+| 类 | 路径 | 说明 |
+|----|------|------|
+| `OldController` | `app/Service/admin/log/OldController.php` | 控制器 |
+| `OldLogService` | `app/Service/admin/log/OldLogService.php` | 服务层 |
+| `HyTransitRecordService` | `app/Service/admin/hy/HyTransitRecordService.php` | 监管记录服务 |
--- a/docs/projects/xk-admin/modules/notice.md
+++ b/docs/projects/xk-admin/modules/notice.md
@@ -0,0 +1,64 @@
+# 通知公告模块
+
+## 功能概述
+
+管理系统内部通知公告的发布、已读/未读状态管理。支持全员公告和指定用户通知。
+
+## 通知类型
+
+| 类型 | 说明 |
+|------|------|
+| `type=0` | 全员公告（仅平台管理员可发） |
+| `type>0` | 指定用户通知 |
+
+## 核心流程
+
+```mermaid
+graph TB
+    A[管理员发送通知] --> B{type=0?}
+    B -->|是| C[全员公告<br/>所有管理员可见]
+    B -->|否| D[指定用户通知<br/>仅选中用户可见]
+    C --> E[用户查看已读]
+    D --> E
+    E --> F{全部已读?}
+    F -->|是| G[通知状态标记为已读]
+    F -->|否| H[保持未读状态]
+```
+
+## 数据模型
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `AdminNoticeModel` | `xk_admin_notice` | 通知主体（标题、内容、类型、发布人） |
+| `AdminNoticeRelationsModel` | `xk_admin_notice_relations` | 通知-用户关联（已读状态） |
+
+### 通知字段
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 通知标题 |
+| `detail` | 摘要 |
+| `content` | 详细内容 |
+| `type` | 通知类型（0=全员） |
+| `edit_type` | 编辑类型 |
+| `user_id` | 发布人 ID |
+| `status` | 全局已读状态（0=未全读, 1=全部已读） |
+
+## 对应 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `api/admin/notice/list` | 通知列表（当前用户） |
+| GET | `api/admin/notice/detail` | 通知详情（自动标记已读） |
+| POST | `api/admin/notice/read` | 标记单条已读 |
+| POST | `api/admin/notice/read-all` | 全部已读 |
+| POST | `api/admin/notice/send` | 发送通知 |
+| GET | `api/admin/notice/user-option` | 接收人下拉列表 |
+
+## 关联类
+
+| 类 | 路径 | 说明 |
+|----|------|------|
+| `NoticeController` | `app/Service/admin/notice/NoticeController.php` | 控制器 |
+| `NoticeService` | `app/Service/admin/notice/NoticeService.php` | 服务层 |
+| `SendToUserNoticeJob` | `app/Jobs/admin/notices/SendToUserNoticeJob.php` | 异步发送 Job |
--- a/docs/projects/xk-admin/modules/salesperson.md
+++ b/docs/projects/xk-admin/modules/salesperson.md
@@ -0,0 +1,43 @@
+# 销售推广模块
+
+## 推广员管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 推广员管理 | `salesperson/*` | 推广员 CRUD |
+| 门店推广员 | `clinic-salesperson-self/*` | 门店推广员自助 |
+| 推广员配置 | `salesperson-store-config/*` | 门店推广配置 |
+
+## 佣金模板
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 佣金模板 | `commission-template/*` | 佣金模板管理 |
+| 药品佣金 | `salesperson-drug-commission/*` | 药品佣金配置 |
+
+## 佣金计算流程
+
+```mermaid
+graph TB
+    A[订单支付] --> B{是否有推广员}
+    B -->|是| C[计算佣金]
+    B -->|否| D[无佣金]
+    C --> E{佣金方式}
+    E -->|固定| F[按模板/药品配置]
+    E -->|百分比| G[按比例计算]
+    F --> H[生成佣金记录]
+    G --> H
+```
+
+## 转诊管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 转诊管理 | `transfer-prescription/*` | 转诊处方管理 |
+
+## 转诊分账规则
+
+::: warning 关键逻辑
+- 转诊方（发起方）获得 **100%** 利润
+- 接收方（被转方）获得 **0%** 利润
+:::
--- a/docs/projects/xk-admin/modules/special-prescription.md
+++ b/docs/projects/xk-admin/modules/special-prescription.md
@@ -0,0 +1,35 @@
+# 特色处方模块
+
+## 特色处方管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 特色处方 | `special-prescription/*` | 特色处方管理 |
+| 特色处方分类 | `special-prescription-category/*` | 分类管理 |
+
+## 特色处方结构
+
+```mermaid
+graph TB
+    SP[特色处方] --> CAT[分类]
+    SP --> SKU1[SKU: 7剂]
+    SP --> SKU2[SKU: 14剂]
+    SP --> SKU3[SKU: 21剂]
+    SKU1 --> DP1[药品A: ¥10/剂]
+    SKU1 --> DP2[药品B: ¥8/剂]
+    SKU1 --> DP3[药品C: ¥5/剂]
+```
+
+## 价格方案
+
+| 方案 | 值 | 说明 |
+|------|-----|------|
+| 固定价 | 1 | 统一价格 |
+| 门店浮动价 | 3 | 门店可调整价格 |
+
+## 处方状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 下架 | 0 | 不可见 |
+| 上架 | 1 | 正常销售 |
--- a/docs/projects/xk-admin/modules/store.md
+++ b/docs/projects/xk-admin/modules/store.md
@@ -0,0 +1,34 @@
+# 门店管理模块
+
+## 门店管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 门店管理 | `store/*` | 门店 CRUD、审核 |
+| 门店预填 | `store-input/*` | 门店信息预填 |
+| 医生预填 | `doctor-input/*` | 医生入驻信息预填 |
+| 银行卡上报 | `store-bank-card-report/*` | 易票联银行卡上报 |
+
+## 门店审核流程
+
+```mermaid
+graph TB
+    A[门店提交入驻] --> B[管理员审核]
+    B -->|通过| C[创建门店]
+    B -->|拒绝| D[退回修改]
+    C --> E[门店生效]
+```
+
+## 门店类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 诊所 | 0 | 中医/西医诊所 |
+| 药店 | 1 | 药品零售店 |
+
+## 诊所类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 西医 | 1 | 西医诊所 |
+| 中医 | 2 | 中医诊所 |
--- a/docs/projects/xk-admin/modules/system.md
+++ b/docs/projects/xk-admin/modules/system.md
@@ -0,0 +1,36 @@
+# 系统管理模块
+
+## 管理员管理
+
+| 模块 | 对应 API | 说明 |
+|------|----------|------|
+| 管理员管理 | `admin/list` | 管理员 CRUD、密码重置、角色分配 |
+| 角色管理 | `role/*` | 角色 CRUD、菜单绑定 |
+| 菜单管理 | `menu/*` | 菜单树配置 |
+| 系统配置 | `system-config/*` | 键值对配置 |
+| 操作日志 | `log/*` | 操作日志查询 |
+| 公告管理 | `announcement/*` | 公告发布 |
+| 平台信息 | `platform/*` | 平台资质、信息管理 |
+
+## 权限控制
+
+使用 `v-access:code` 指令控制按钮级权限：
+
+```vue
+<template>
+  <a-button v-access:code="'admin:create'">创建管理员</a-button>
+</template>
+```
+
+## 角色列表
+
+| 角色 | 说明 | 主要功能 |
+|------|------|----------|
+| 超级管理员 | 全局管理 | 所有功能 |
+| 管理员 | 普通管理 | 日常管理操作 |
+| 省经理 | 省级管理 | 区域门店管理 |
+| 市经理 | 市级管理 | 区域门店管理 |
+| 区经理 | 区级管理 | 区域门店管理 |
+| 供应商 | 药品供应 | 药品管理 |
+| 门店管理员 | 门店运营 | 门店端功能 |
+| 总部财务 | 财务管理 | 财务功能 |
--- a/docs/projects/xk-admin/overview.md
+++ b/docs/projects/xk-admin/overview.md
@@ -0,0 +1,64 @@
+# xk-admin 概览
+
+xk-admin 是 XK 系统的管理后台前端，基于 Vben Admin Pro v5.5.1 构建。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 框架 | Vue 3 + Vben Admin Pro v5.5.1 |
+| UI 库 | Ant Design Vue |
+| 包管理 | pnpm 10.2.0 (Monorepo) |
+| 构建 | Vite + Turborepo |
+| 语言 | TypeScript |
+| Node | >= 20.10.0 |
+
+## 目录结构
+
+```
+xk-admin/
+├── apps/
+│   └── web-antd/          # 主应用
+│       └── src/
+│           ├── adapter/       # API 适配器
+│           ├── api/           # API 调用定义
+│           ├── components/    # 共享组件
+│           ├── composables/   # Vue Composables
+│           ├── layouts/       # 布局组件
+│           ├── locales/       # 国际化
+│           ├── router/        # 路由配置
+│           ├── store/         # Pinia Store
+│           ├── views/         # 页面视图
+│           └── utils/         # 工具函数
+├── internal/              # 内部共享包
+├── packages/              # 共享工作区包
+├── playground/            # 开发调试
+├── scripts/               # 构建脚本
+├── turbo.json             # Turborepo 配置
+└── pnpm-workspace.yaml    # 工作区配置
+```
+
+## 多角色支持
+
+管理后台支持多种角色登录，不同角色看到不同的菜单和功能：
+
+| 角色 | 说明 | 主要功能 |
+|------|------|----------|
+| 超级管理员 | 全局管理 | 所有功能 |
+| 管理员 | 普通管理 | 日常管理操作 |
+| 省经理 | 省级管理 | 区域门店管理 |
+| 市经理 | 市级管理 | 区域门店管理 |
+| 区经理 | 区级管理 | 区域门店管理 |
+| 供应商 | 药品供应 | 药品管理 |
+| 门店管理员 | 门店运营 | 门店端功能 |
+| 总部财务 | 财务管理 | 财务功能 |
+
+## 权限控制
+
+使用 `v-access:code` 指令控制按钮级权限：
+
+```vue
+<template>
+  <a-button v-access:code="'admin:create'">创建管理员</a-button>
+</template>
+```
--- a/docs/projects/xk-api-yii/architecture.md
+++ b/docs/projects/xk-api-yii/architecture.md
@@ -0,0 +1,56 @@
+# xk-api-yii 基类架构
+
+## 多应用结构
+
+```mermaid
+graph TB
+    subgraph 应用层
+        ADMIN[admin/<br/>管理后台]
+        MEMBER[member/<br/>会员端]
+        PLATFORM[platform/<br/>平台端]
+        SERVICE[service/<br/>服务端]
+        CONSOLE[console/<br/>控制台]
+    end
+
+    subgraph 共享层 common/
+        MODELS[models/<br/>共享模型]
+        SERVICES[services/<br/>业务服务]
+        COMPONENTS[components/<br/>共享组件]
+        JOBS[jobs/<br/>队列任务]
+        EVENTS[events/<br/>事件]
+        HANDLERS[handlers/<br/>事件处理器]
+    end
+
+    ADMIN --> MODELS
+    MEMBER --> MODELS
+    PLATFORM --> MODELS
+    SERVICE --> MODELS
+    CONSOLE --> MODELS
+```
+
+## 目录说明
+
+| 目录 | 说明 |
+|------|------|
+| `common/models/` | 共享数据模型（对应 z_o_xk 库表） |
+| `common/modelsgii/` | Gii 自动生成的模型 |
+| `common/services/` | 业务服务层 |
+| `common/components/` | 共享组件（支付、短信等） |
+| `common/jobs/` | 队列任务 |
+| `common/events/` | 事件定义 |
+| `common/handlers/` | 事件处理器 |
+| `common/validators/` | 自定义验证器 |
+| `common/enums/` | 枚举定义 |
+| `common/foundation/` | 基础类 |
+| `console/` | 定时任务、控制台命令 |
+
+## 数据库
+
+使用 `z_o_xk` 库，Yii2 风格表名（`yii_*` 前缀）。
+
+## 与 xk-api 的关系
+
+xk-api-yii 是旧系统，xk-api 是新系统。两套系统通过以下方式共存：
+- 共享同一个 `z_o_xk` 数据库
+- xk-api 通过 `OldApiClient` 调用 xk-api-yii 的接口
+- 新功能在 xk-api 中开发，旧功能逐步迁移
--- a/docs/projects/xk-api-yii/design.md
+++ b/docs/projects/xk-api-yii/design.md
@@ -0,0 +1,35 @@
+# xk-api-yii 设计思路
+
+## 架构决策
+
+### Yii2 Advanced
+
+选择 Yii2 Advanced 作为旧系统框架：
+- 成熟的 PHP 框架，适合企业级应用
+- 多应用模式（admin/member/platform/service）
+- 内置 RBAC 权限体系
+- Gii 代码生成器
+
+### 多应用分离
+
+每个应用独立部署，共享 common 代码：
+- 减少单应用复杂度
+- 各应用可独立扩展
+- 共享模型和服务层
+
+### 迁移策略
+
+旧系统向新系统迁移的策略：
+1. **共享数据库**：两套系统操作同一个 `z_o_xk` 库
+2. **接口桥接**：xk-api 通过 `OldApiClient` 调用旧接口
+3. **渐进迁移**：新功能在 xk-api 开发，旧功能逐步迁移
+4. **数据同步**：通过 Open API 同步关键数据
+
+## 与 xk-api 的关系
+
+| 维度 | xk-api-yii | xk-api |
+|------|------------|--------|
+| 框架 | Yii2 | Laravel 12 |
+| 数据库 | z_o_xk | z_xk + z_o_xk |
+| 状态 | 维护模式 | 活跃开发 |
+| 功能 | 旧功能 | 新功能 + 迁移功能 |
--- a/docs/projects/xk-api-yii/models.md
+++ b/docs/projects/xk-api-yii/models.md
@@ -0,0 +1,140 @@
+# xk-api-yii 模型分析
+
+所有模型对应 `z_o_xk` 库的 `yii_*` 表。
+
+## 配置/系统 (config/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `AdminModel` | `yii_admin` | 管理员 |
+| `AdminAccessTokenModel` | `yii_admin_access_token` | 管理员令牌 |
+| `AdminRoleModel` | `yii_admin_role` | 管理员角色关联 |
+| `AttachmentModel` | `yii_attachment` | 文件附件 |
+| `AttachmentGroupModel` | `yii_attachment_group` | 附件分组 |
+| `AuthAssignmentModel` | `yii_auth_assignment` | RBAC 分配 |
+| `AuthItemModel` | `yii_auth_item` | RBAC 项 |
+| `AuthItemChildModel` | `yii_auth_item_child` | RBAC 层级 |
+| `AuthRoleModel` | `yii_auth_role` | 认证角色 |
+| `AuthRuleModel` | `yii_auth_rule` | 认证规则（菜单/权限） |
+| `BaseConfigModel` | `yii_base_config` | 基础配置（协议） |
+| `BillsModel` | `yii_bills` | 账单 |
+| `CallbackModel` | `yii_callback` | 回调记录 |
+| `CategoriesModel` | `yii_categories` | 分类 |
+| `ConfigModel` | `yii_config` | 系统配置 |
+| `MenuModel` | `yii_menu` | 菜单 |
+| `NavModel` | `yii_nav` | 轮播图 |
+| `PayConfigModel` | `yii_pay_config` | 支付配置 |
+| `PlatformModel` | `yii_platform` | 平台配置 |
+| `PlateModel` | `yii_plate` | 平台（旧） |
+| `RegionModel` | `yii_region` | 地区 |
+| `RoleModel` | `yii_role` | 角色 |
+| `RoleMenuModel` | `yii_role_menu` | 角色-菜单 |
+| `SystemConfigModel` | `yii_system_config` | 系统配置 |
+| `SystemNoticeModel` | `yii_system_notice` | 系统通知 |
+
+## 医生 (doctor/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DoctorInfoModel` | `yii_doctor_info` | 医生基本信息 |
+| `DoctorServiceModel` | `yii_doctor_service` | 医生服务设置 |
+| `DoctorIdentityModel` | `yii_doctor_identity` | 医生身份验证 |
+| `DoctorPracticingModel` | `yii_doctor_practicing` | 医生执业证书 |
+| `DoctorRegisterModel` | `yii_doctor_register` | 医生挂号 |
+| `DoctorRosteringModel` | `yii_doctor_rostering` | 医生排班 |
+| `DoctorNoticeModel` | `yii_doctor_notice` | 医生停诊通知 |
+| `DoctorPatientModel` | `yii_doctor_patient` | 医生患者列表 |
+| `DoctorPatientRemarkModel` | `yii_doctor_patient_remark` | 患者备注 |
+| `DoctorArticleModel` | `yii_doctor_article` | 医生文章 |
+| `DoctorApplyModel` | `yii_doctor_apply` | 医生升级申请 |
+| `DoctorCommonModel` | `yii_doctor_common` | 医生常用药品 |
+| `DoctorTagIllModel` | `yii_doctor_tag_ill` | 医生疾病标签 |
+| `DoctorTagWordModel` | `yii_doctor_tag_word` | 医生常用语 |
+| `DoctorTitleModel` | `yii_doctor_title` | 医生职称 |
+| `DoctorStoreModel` | `yii_store_doctor` | 门店-医生关联 |
+| `DepartmentModel` | `yii_department` | 科室 |
+| `DiagnoseCommonModel` | `yii_diagnose_common` | 常用医嘱 |
+| `DiseaseModel` | `yii_disease` | 疾病库 |
+| `DiseaseCommonModel` | `yii_disease_common` | 常用疾病 |
+| `PharmacistIdentityModel` | `yii_pharmacist_identity` | 药师身份验证 |
+
+## 药品 (drug/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `DrugModel` | `yii_drug` | 药品主表 |
+| `DrugCategoriesModel` | `yii_drug_categories` | 药品分类 |
+| `DrugStoreRelationsModel` | `yii_drug_store_relations` | 药品-门店定价 |
+| `DrugNatureModel` | `yii_drug_nature` | 药品配伍（十八反十九畏） |
+| `DrugDosageModel` | `yii_drug_dosage` | 中药剂量 |
+| `DrugUseFrequencyModel` | `yii_drug_use_frequency` | 用药频率 |
+| `DrugUseNumModel` | `yii_drug_use_num` | 用药数量 |
+| `DrugUseTimeModel` | `yii_drug_use_time` | 用药时间 |
+| `DrugUseTypeModel` | `yii_drug_use_type` | 用药方式 |
+| `DrugUseWayModel` | `yii_drug_use_way` | 煎煮方式 |
+| `DrugStoreModel` | `yii_drugstore` | 药品仓库 |
+| `DrugStoreDrugModel` | `yii_drugstore_drug` | 仓库药品 |
+| `CartModel` | `yii_carts` | 购物车 |
+| `PackageMethodModel` | `package_method` | 包装方式 |
+| `ProcessRuleModel` | `yii_process_rule` | 加工规则 |
+| `ProcessRuleNoteModel` | `yii_process_rule_note` | 加工规则说明 |
+| `WestUnitModel` | `yii_west_unit` | 西药单位 |
+
+## 订单 (order/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `OrderModel` | `yii_order` | 咨询订单 |
+| `ProductOrderModel` | `yii_product_order` | 产品订单 |
+| `ProductOrderItemsModel` | `yii_product_order_items` | 订单明细 |
+| `RegisterOrderModel` | `yii_register` | 挂号订单 |
+| `OrderRefundModel` | `yii_order_refund` | 咨询退款 |
+| `RegisterRefundModel` | `yii_register_refund` | 挂号退款 |
+| `ProductOrderRefundModel` | `yii_product_order_refund` | 产品退款 |
+| `OrderNumberChangeModel` | `yii_order_number_change` | 回复次数变更 |
+| `OrderVideoInfoModel` | `yii_order_video_info` | 视频通话信息 |
+| `PaymentOrderModel` | `yii_payment_order` | 咨询支付记录 |
+| `PaymentProductOrderModel` | `yii_payment_product_order` | 产品支付记录 |
+| `PaymentRegisterModel` | `yii_payment_register` | 挂号支付记录 |
+| `PaymentRefundModel` | `yii_payment_refund` | 咨询退款记录 |
+| `PaymentProductRefundModel` | `yii_payment_product_refund` | 产品退款记录 |
+| `PaymentRegisterRefundModel` | `yii_payment_register_refund` | 挂号退款记录 |
+| `RefundReasonModel` | `yii_refund_reason` | 退款原因 |
+
+## 处方 (prescription/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `PrescriptionModel` | `yii_prescription` | 主处方表 |
+| `PrescriptionChineseModel` | `yii_prescription_chinese` | 中药处方 |
+| `PrescriptionWestModel` | `yii_prescription_west` | 西药处方 |
+| `PrescriptionGranularModel` | `yii_prescription_granular` | 颗粒处方 |
+| `PrescriptionServerModel` | `yii_prescription_server` | 服务包处方 |
+| `TransferPrescriptionModel` | `yii_transfer_prescription` | 转诊处方 |
+| `PrescripOrderLogModel` | `yii_prescrip_order_log` | 处方订单日志 |
+| `PrescripOrderRefundModel` | `yii_prescrip_order_refund` | 处方订单退款 |
+
+## 财务 (finacne/)
+
+| 模型 | 表名 | 说明 |
+|------|------|------|
+| `LedgerModel` | `yii_ledger` | 分账记录 |
+| `LedgerLogModel` | `yii_ledger_log` | 分账变更日志 |
+| `CashAccountModel` | `yii_cash_account` | 提现账户 |
+| `CashApplyModel` | `yii_cash_apply` | 提现申请 |
+| `ChargeCashPayRecordModel` | `yii_charge_cash_pay_record` | 代理付款记录 |
+| `FundWaterModel` | `yii_fund_water` | 资金流水 |
+| `ReconciliationModel` | `yii_reconciliation` | 对账记录 |
+| `RefundBillsModel` | `yii_refund_bills` | 退款账单 |
+
+## 其他
+
+| 目录 | 主要模型 | 说明 |
+|------|----------|------|
+| `user/` | `UserModel`, `ServiceUserModel`, `UserPatientModel` | 用户、服务用户、患者 |
+| `recipe/` | `ChineseRecipeModel`, `WestRecipeModel`, `GranularRecipeModel` | 处方笺 |
+| `hospital/` | `HospitalModel`, `HospitalYardModel` | 医院、院区 |
+| `im/` | `ImMessageModel`, `ImMessageSessionModel` | 即时通讯 |
+| `log/` | `LogModel`, `OldOpLogModel` | 日志 |
+| `physical/` | `PhysicalPackageModel`, `PhysicalReserveModel` | 体检 |
+| `express/` | `ExpressFeesModel` | 快递费用 |
--- a/docs/projects/xk-api-yii/modules/admin.md
+++ b/docs/projects/xk-api-yii/modules/admin.md
@@ -0,0 +1,29 @@
+# 管理后台模块
+
+## 模块说明
+
+| 模块 | 说明 |
+|------|------|
+| 管理员管理 | 管理员 CRUD、角色分配 |
+| RBAC 权限 | 基于 Yii2 RBAC 的权限体系 |
+| 系统配置 | 键值对配置管理 |
+| 菜单管理 | 动态菜单配置 |
+
+## 目录结构
+
+```
+admin/
+├── controllers/    # 控制器
+├── models/         # 模型
+├── views/          # 视图
+└── config/         # 配置
+```
+
+## RBAC 权限体系
+
+Yii2 内置 RBAC：
+- `yii_auth_item` — 权限项
+- `yii_auth_item_child` — 权限层级
+- `yii_auth_assignment` — 权限分配
+- `yii_role` — 角色定义
+- `yii_role_menu` — 角色-菜单绑定
--- a/docs/projects/xk-api-yii/modules/index.md
+++ b/docs/projects/xk-api-yii/modules/index.md
@@ -0,0 +1,14 @@
+# xk-api-yii 功能模块
+
+::: warning 状态说明
+xk-api-yii 是旧系统，核心功能已逐步迁移到 xk-api (Laravel)。以下模块仍可能在旧系统中运行。
+:::
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 管理后台 | 管理员、RBAC、配置 | [管理后台](./admin.md) |
+| 会员端 | 用户、患者、购物车、订单 | [会员端](./member.md) |
+| 平台端 | 门店、医生、药品、财务 | [平台端](./platform.md) |
+| 服务端 | 医生工作台、药师审方、IM | [服务端](./service.md) |
--- a/docs/projects/xk-api-yii/modules/member.md
+++ b/docs/projects/xk-api-yii/modules/member.md
@@ -0,0 +1,33 @@
+# 会员端模块
+
+## 模块说明
+
+| 模块 | 说明 |
+|------|------|
+| 用户管理 | 用户注册、登录、信息管理 |
+| 患者管理 | 就诊人管理、病历 |
+| 购物车 | 药品购物车 |
+| 产品订单 | 产品订单管理 |
+| 挂号订单 | 挂号预约管理 |
+| 处方查看 | 处方记录查看 |
+| 健康资讯 | 健康文章浏览 |
+
+## 目录结构
+
+```
+member/
+├── controllers/    # 控制器
+├── models/         # 模型
+├── views/          # 视图
+└── config/         # 配置
+```
+
+## 主要功能
+
+- 用户注册/登录
+- 就诊人管理
+- 药品浏览/购物车
+- 订单管理
+- 挂号预约
+- 处方查看
+- 健康资讯
--- a/docs/projects/xk-api-yii/modules/platform.md
+++ b/docs/projects/xk-api-yii/modules/platform.md
@@ -0,0 +1,33 @@
+# 平台端模块
+
+## 模块说明
+
+| 模块 | 说明 |
+|------|------|
+| 门店管理 | 门店审核、配置 |
+| 医生管理 | 医生审核、信息管理 |
+| 药师管理 | 药师审核 |
+| 药品管理 | 药品上架、下架、定价 |
+| 订单管理 | 订单处理、发货 |
+| 财务管理 | 分账、结算、提现 |
+| 数据统计 | 业务数据统计 |
+
+## 目录结构
+
+```
+platform/
+├── controllers/    # 控制器
+├── models/         # 模型
+├── views/          # 视图
+└── config/         # 配置
+```
+
+## 主要功能
+
+- 门店审核/管理
+- 医生审核/管理
+- 药师审核/管理
+- 药品管理
+- 订单处理
+- 财务结算
+- 数据统计
--- a/docs/projects/xk-api-yii/modules/service.md
+++ b/docs/projects/xk-api-yii/modules/service.md
@@ -0,0 +1,27 @@
+# 服务端模块
+
+## 模块说明
+
+| 模块 | 说明 |
+|------|------|
+| 医生工作台 | 接诊、开方、患者管理 |
+| 药师审方 | 处方审核 |
+| 即时通讯 | 医患聊天 |
+| 常用处方 | 处方模板管理 |
+
+## 目录结构
+
+```
+service/
+├── controllers/    # 控制器
+├── models/         # 模型
+├── views/          # 视图
+└── config/         # 配置
+```
+
+## 主要功能
+
+- 医生接诊/开方
+- 药师审方
+- 医患聊天
+- 处方模板
--- a/docs/projects/xk-api-yii/overview.md
+++ b/docs/projects/xk-api-yii/overview.md
@@ -0,0 +1,60 @@
+# xk-api-yii 概览
+
+xk-api-yii 是 XK 系统的旧 API 服务，基于 Yii2 Advanced 构建。目前处于维护状态，核心业务逻辑已逐步迁移到 xk-api (Laravel)。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 框架 | Yii2 Advanced |
+| PHP 版本 | >= 7.4 \| 8.0.2 |
+| 包管理 | Composer |
+| 队列 | yii2-queue |
+| 微信 | overtrue/wechat 5.x |
+| 支付 | 易票联 |
+| 短信 | overtrue/easy-sms |
+| Redis | yii2-redis |
+| Excel | phpoffice/phpexcel |
+
+## 目录结构
+
+```
+xk-api-yii/
+├── admin/              # 管理后台应用
+├── common/             # 共享代码
+│   ├── components/     # 共享组件
+│   ├── config/         # 共享配置
+│   ├── core/           # 核心逻辑
+│   ├── enums/          # 枚举
+│   ├── events/         # 事件
+│   ├── forms/          # 表单模型
+│   ├── foundation/     # 基础类
+│   ├── handlers/       # 事件处理器
+│   ├── helpers/        # 辅助函数
+│   ├── jobs/           # 队列任务
+│   ├── mail/           # 邮件
+│   ├── models/         # 共享模型
+│   ├── modelsgii/      # Gii 生成的模型
+│   ├── services/       # 业务服务
+│   ├── validators/     # 自定义验证器
+│   └── tests/          # 测试
+├── console/            # 控制台应用
+├── environments/       # 环境配置
+├── member/             # 会员应用
+├── platform/           # 平台应用
+├── service/            # 服务应用
+├── web/                # Web 入口
+│   ├── admin/          # 管理后台入口
+│   ├── member/         # 会员入口
+│   ├── platform/       # 平台入口
+│   └── service/        # 服务入口
+└── yii                 # CLI 入口
+```
+
+## 多应用架构
+
+Yii2 Advanced 采用多应用模式：
+- **admin**: 管理后台
+- **member**: 会员端
+- **platform**: 平台端
+- **service**: 服务端（医生/药师）
--- 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 系统接口规范 |
--- a/docs/projects/xk-client-wx/architecture.md
+++ b/docs/projects/xk-client-wx/architecture.md
@@ -0,0 +1,50 @@
+# xk-client-wx 基类架构
+
+## 页面结构
+
+```mermaid
+graph TB
+    subgraph 主包 pages/
+        HOME[首页<br/>pages/home]
+        CATE[健康资讯<br/>pages/cate]
+        MSG[消息<br/>pages/index]
+        MINE[我的<br/>pages/mine]
+        LOGIN[登录<br/>pages/login]
+    end
+
+    subgraph 分包 subPackages/
+        DOC[doctor/<br/>医生详情/问诊]
+        PROD[product/<br/>商品浏览]
+        FU[follow-up/<br/>复诊续方]
+        SP[special-prescription/<br/>特色处方]
+        MY[my/<br/>我的记录/订单]
+        REG[register/<br/>挂号预约]
+        SHOP[shop/<br/>商城订单]
+        SET[setup/<br/>设置/协议]
+        CHAT[chat/<br/>在线问诊]
+        TRANS[transfer/<br/>转诊咨询]
+    end
+
+    HOME --> DOC
+    HOME --> PROD
+    HOME --> SP
+    MINE --> MY
+    MINE --> SET
+    DOC --> CHAT
+    DOC --> REG
+    PROD --> SHOP
+```
+
+## 请求模块
+
+`request/` 目录封装了 HTTP 请求：
+- 统一请求拦截器
+- Token 注入
+- 错误处理
+- 基础 URL 配置
+
+## 状态管理
+
+使用 Vuex + Pinia 双状态管理：
+- Vuex: 旧模块状态
+- Pinia: 新模块状态
--- a/docs/projects/xk-client-wx/components.md
+++ b/docs/projects/xk-client-wx/components.md
@@ -0,0 +1,29 @@
+# xk-client-wx 通用组件
+
+## 页面组件
+
+| 组件 | 说明 |
+|------|------|
+| 医生卡片 | 医生信息展示（头像、姓名、职称、擅长） |
+| 药品卡片 | 药品信息展示（图片、名称、规格、价格） |
+| 处方卡片 | 处方信息展示（处方内容、状态） |
+| 订单卡片 | 订单信息展示（商品、金额、状态） |
+| 地址选择 | 收货地址选择组件 |
+
+## 功能组件
+
+| 组件 | 说明 |
+|------|------|
+| 登录弹窗 | 微信授权登录 |
+| 加载更多 | 列表分页加载 |
+| 空状态 | 空数据提示 |
+| 价格显示 | 价格格式化显示 |
+| 状态标签 | 订单/处方状态标签 |
+
+## 工具函数
+
+| 工具 | 说明 |
+|------|------|
+| `request/` | HTTP 请求封装 |
+| `utils/` | 工具函数 |
+| `common/` | 公共方法 |
--- a/docs/projects/xk-client-wx/design.md
+++ b/docs/projects/xk-client-wx/design.md
@@ -0,0 +1,44 @@
+# xk-client-wx 设计思路
+
+## 架构决策
+
+### uni-app 跨平台
+
+选择 uni-app 作为小程序框架：
+- 一套代码多端运行（微信小程序、H5、App）
+- Vue 3 Composition API 支持
+- 丰富的插件生态
+
+### 分包加载
+
+使用分包（subPackages）优化首屏加载：
+- 主包：核心页面（首页、消息、我的）
+- 分包：业务页面（问诊、购药、挂号等）
+- 按需加载，减少初始包体积
+
+### 状态管理
+
+Vuex + Pinia 双状态管理：
+- Vuex: 旧模块状态（兼容性）
+- Pinia: 新模块状态（推荐）
+- 逐步迁移到 Pinia
+
+## 用户体验
+
+### 首页设计
+- 顶部：门店信息、搜索
+- 中部：医生推荐、药品推荐
+- 底部：特色处方、健康资讯
+
+### 问诊流程
+1. 选择医生 → 查看详情
+2. 发起问诊 → 选择就诊人
+3. 发送症状描述 → 等待医生回复
+4. 医生开具处方 → 查看处方
+5. 确认购药 → 下单支付
+
+### 购药流程
+1. 浏览药品 → 加入购物车
+2. 选择收货地址
+3. 确认订单 → 支付
+4. 等待发货 → 查看物流
--- a/docs/projects/xk-client-wx/modules/consultation.md
+++ b/docs/projects/xk-client-wx/modules/consultation.md
@@ -0,0 +1,41 @@
+# 问诊模块
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 医生列表 | `pages/Inquiries/` | 按科室、擅长筛选医生 |
+| 医生详情 | `subPackages/doctor/` | 医生信息、评价、开诊时间 |
+| 图文问诊 | `subPackages/doctor/` | 发起图文问诊 |
+| 在线问诊聊天 | `subPackages/chat/` | 实时聊天界面 |
+
+## 问诊流程
+
+```mermaid
+graph TB
+    A[选择医生] --> B[查看医生详情]
+    B --> C[发起问诊]
+    C --> D[选择就诊人]
+    D --> E[发送症状描述]
+    E --> F[等待医生回复]
+    F --> G[医生回复]
+    G --> H{是否需要开方}
+    H -->|是| I[医生开具处方]
+    H -->|否| J[继续问诊]
+    I --> K[查看处方]
+    K --> L{是否购药}
+    L -->|是| M[确认购药]
+    L -->|否| N[结束问诊]
+```
+
+## 聊天消息类型
+
+| 类型 | 说明 |
+|------|------|
+| 文字 | 文本消息 |
+| 图片 | 图片消息 |
+| 语音 | 语音消息 |
+| 处方 | 处方卡片 |
+| 病历 | 病历文件 |
+| 视频通话 | 视频通话 |
+| 结束问诊 | 结束问诊 |
--- a/docs/projects/xk-client-wx/modules/home.md
+++ b/docs/projects/xk-client-wx/modules/home.md
@@ -0,0 +1,26 @@
+# 首页模块
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 首页 | `pages/home/` | 门店信息、医生列表、药品推荐、特色处方入口 |
+
+## 功能
+
+- 门店信息展示
+- 医生推荐列表
+- 药品推荐列表
+- 特色处方入口
+- 健康资讯入口
+
+## 页面结构
+
+```mermaid
+graph TB
+    HOME[首页] --> STORE[门店信息]
+    HOME --> DOC[医生推荐]
+    HOME --> DRUG[药品推荐]
+    HOME --> SP[特色处方]
+    HOME --> NEWS[健康资讯]
+```
--- a/docs/projects/xk-client-wx/modules/index.md
+++ b/docs/projects/xk-client-wx/modules/index.md
@@ -0,0 +1,13 @@
+# xk-client-wx 功能模块
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 首页模块 | 门店信息、医生推荐、药品推荐 | [首页模块](./home.md) |
+| 问诊模块 | 医生浏览、图文问诊、在线聊天 | [问诊模块](./consultation.md) |
+| 购药模块 | 商品浏览、购物车、下单支付 | [购药模块](./product.md) |
+| 挂号模块 | 挂号预约、挂号记录 | [挂号模块](./register.md) |
+| 处方模块 | 处方查看、特色处方、复诊续方 | [处方模块](./prescription.md) |
+| 转诊模块 | 转诊咨询 | [转诊模块](./transfer.md) |
+| 个人中心 | 我的、就诊人、设置 | [个人中心](./mine.md) |
--- a/docs/projects/xk-client-wx/modules/mine.md
+++ b/docs/projects/xk-client-wx/modules/mine.md
@@ -0,0 +1,38 @@
+# 个人中心
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 我的 | `pages/mine/` | 个人信息、快捷入口 |
+| 就诊人管理 | `subPackages/my/` | 就诊人添加、编辑 |
+| 健康档案 | `subPackages/my/` | 健康信息 |
+| 设置 | `subPackages/setup/` | 个人设置 |
+| 协议 | `subPackages/setup/` | 服务协议、隐私政策 |
+
+## 功能
+
+- 个人信息查看/编辑
+- 就诊人管理（添加/编辑/删除）
+- 健康档案查看
+- 我的订单
+- 我的挂号
+- 我的处方
+- 设置
+- 协议查看
+- 客服联系
+
+## 页面结构
+
+```mermaid
+graph TB
+    MINE[我的] --> INFO[个人信息]
+    MINE --> PATIENT[就诊人管理]
+    MINE --> HEALTH[健康档案]
+    MINE --> ORDER[我的订单]
+    MINE --> REG[我的挂号]
+    MINE --> PRESC[我的处方]
+    MINE --> SET[设置]
+    MINE --> AGREEMENT[协议]
+    MINE --> SERVICE[客服]
+```
--- a/docs/projects/xk-client-wx/modules/prescription.md
+++ b/docs/projects/xk-client-wx/modules/prescription.md
@@ -0,0 +1,38 @@
+# 处方模块
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 处方查看 | `subPackages/doctor/` | 查看处方详情 |
+| 特色处方 | `subPackages/special-prescription/` | 特色药方浏览、购买 |
+| 复诊续方 | `subPackages/follow-up/` | 复诊续方 |
+
+## 处方类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 中药 | 1 | 中药饮片处方 |
+| 西药 | 2 | 西药处方 |
+| 颗粒 | 3 | 配方颗粒处方 |
+| 中成药 | 4 | 中成药处方 |
+| 服务包 | 5 | 服务包处方 |
+
+## 处方状态
+
+| 状态 | 值 | 说明 |
+|------|-----|------|
+| 待审核 | 0 | 医生已开方 |
+| 通过 | 1 | 审核通过 |
+| 未通过 | 2 | 审核拒绝 |
+| 无需审核 | 3 | 免审处方 |
+
+## 特色处方购买流程
+
+```mermaid
+graph TB
+    A[浏览特色处方] --> B[选择剂量]
+    B --> C[确认购买]
+    C --> D[支付]
+    D --> E[处方生效]
+```
--- a/docs/projects/xk-client-wx/modules/product.md
+++ b/docs/projects/xk-client-wx/modules/product.md
@@ -0,0 +1,37 @@
+# 购药模块
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 商品浏览 | `subPackages/product/` | 药品列表、搜索、分类 |
+| 商品详情 | `subPackages/product/` | 药品详情、价格、库存 |
+| 购物车 | `subPackages/shop/` | 购物车管理 |
+| 下单 | `subPackages/shop/` | 确认订单、选择地址 |
+| 订单列表 | `subPackages/my/` | 我的订单 |
+| 订单详情 | `subPackages/my/` | 订单状态、物流 |
+
+## 购药流程
+
+```mermaid
+graph TB
+    A[浏览药品] --> B[加入购物车]
+    B --> C[选择收货地址]
+    C --> D[确认订单]
+    D --> E[支付]
+    E --> F[等待发货]
+    F --> G[查看物流]
+    G --> H[确认收货]
+```
+
+## 订单状态
+
+| 状态 | 说明 |
+|------|------|
+| 待支付 | 订单已创建 |
+| 待发货 | 已支付，等待发货 |
+| 待收货 | 已发货，等待收货 |
+| 已收货 | 已确认收货 |
+| 已取消 | 订单已取消 |
+| 退款中 | 退款处理中 |
+| 已退款 | 退款完成 |
--- a/docs/projects/xk-client-wx/modules/register.md
+++ b/docs/projects/xk-client-wx/modules/register.md
@@ -0,0 +1,28 @@
+# 挂号模块
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 挂号预约 | `subPackages/register/` | 选择科室、医生、时间 |
+| 挂号记录 | `subPackages/my/` | 我的挂号记录 |
+
+## 挂号流程
+
+```mermaid
+graph TB
+    A[选择科室] --> B[选择医生]
+    B --> C[选择时间]
+    C --> D[选择就诊人]
+    D --> E[确认挂号]
+    E --> F[支付]
+    F --> G[挂号成功]
+```
+
+## 挂号类型
+
+| 类型 | 值 | 说明 |
+|------|-----|------|
+| 线下 | 0 | 线下挂号 |
+| 线上 | 1 | 线上挂号 |
+| 线上复诊 | 2 | 线上复诊挂号 |
--- a/docs/projects/xk-client-wx/modules/transfer.md
+++ b/docs/projects/xk-client-wx/modules/transfer.md
@@ -0,0 +1,37 @@
+# 转诊模块
+
+## 页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 转诊咨询 | `subPackages/transfer/` | 转诊咨询流程 |
+
+## 转诊流程
+
+```mermaid
+graph TB
+    A[发起转诊] --> B[选择转诊门店]
+    B --> C[填写患者信息]
+    C --> D[提交转诊]
+    D --> E[等待接收方确认]
+    E --> F{是否确认}
+    F -->|是| G[导入为挂号]
+    F -->|否| H[转诊取消]
+    G --> I[接收方接诊]
+    I --> J[开具处方]
+    J --> K[患者购药]
+```
+
+## 转诊类型
+
+| 类型 | 说明 |
+|------|------|
+| 转诊方 | 发起转诊的门店 |
+| 接收方 | 接收转诊的门店 |
+
+## 转诊分账
+
+::: warning 关键逻辑
+- 转诊方（发起方）获得 **100%** 利润
+- 接收方（被转方）获得 **0%** 利润
+:::
--- a/docs/projects/xk-client-wx/overview.md
+++ b/docs/projects/xk-client-wx/overview.md
@@ -0,0 +1,68 @@
+# xk-client-wx 概览
+
+xk-client-wx 是 XK 系统的患者端微信小程序，基于 uni-app 构建。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 框架 | uni-app (Vue 3 Composition API) |
+| UI 库 | uview-ui 1.8.8 |
+| 状态管理 | Vuex 3.6.2 + Pinia 2.0.14 |
+| 构建工具 | HBuilderX |
+| 其他 | js-base64, vue-demi |
+
+## 目录结构
+
+```
+xk-client-wx/
+├── App.vue             # 应用入口
+├── main.js             # 主入口
+├── manifest.json       # uni-app 配置
+├── pages.json          # 页面路由
+├── common/             # 公共工具
+├── components/         # 共享组件
+├── pages/              # 主包页面
+│   ├── home/           # 首页
+│   ├── cate/           # 健康资讯
+│   ├── index/          # 消息
+│   ├── login/          # 登录
+│   ├── mine/           # 我的
+│   └── Inquiries/      # 医生列表
+├── subPackages/        # 分包（懒加载）
+│   ├── doctor/         # 医生详情、问诊
+│   ├── product/        # 商品浏览
+│   ├── follow-up/      # 复诊续方
+│   ├── special-prescription/ # 特色处方
+│   ├── my/             # 我的记录、订单、就诊人
+│   ├── register/       # 挂号预约
+│   ├── shop/           # 商城订单
+│   ├── setup/          # 设置、协议
+│   ├── chat/           # 在线问诊聊天
+│   └── transfer/       # 转诊咨询
+├── request/            # HTTP 请求模块
+├── static/             # 静态资源
+├── store/              # Vuex/Pinia Store
+└── utils/              # 工具函数
+```
+
+## Tab Bar 页面
+
+| Tab | 页面 | 说明 |
+|-----|------|------|
+| 首页 | `pages/home` | 首页展示 |
+| 健康资讯 | `pages/cate` | 健康文章浏览 |
+| 消息 | `pages/index` | 消息通知 |
+| 我的 | `pages/mine` | 个人中心 |
+
+## 主要功能
+
+- 医生浏览和问诊（图文问诊）
+- 商品浏览和购药
+- 挂号预约
+- 处方查看
+- 特色药方
+- 在线问诊聊天
+- 转诊咨询
+- 商城订单、购物车、物流
+- 设置、协议、客服
--- a/docs/projects/xk-data/design.md
+++ b/docs/projects/xk-data/design.md
@@ -0,0 +1,25 @@
+# xk-data 设计思路
+
+## 架构决策
+
+### 独立部署
+
+数据大屏作为独立的前端应用部署：
+- 不依赖管理后台框架
+- 简化的技术栈（Vue CLI + ECharts）
+- 可独立部署为静态页面
+
+### 数据聚合
+
+通过后端 Open API 获取聚合数据：
+- 前端只负责展示，不做数据计算
+- 后端 `DashboardDataController` 负责数据聚合
+- 支持缓存，减少数据库查询
+
+### 大屏适配
+
+针对大屏显示优化：
+- 全屏布局
+- 高对比度配色
+- 自适应分辨率
+- 数字动画效果
--- a/docs/projects/xk-data/modules/charts.md
+++ b/docs/projects/xk-data/modules/charts.md
@@ -0,0 +1,32 @@
+# 数据展示模块
+
+## 图表类型
+
+基于 ECharts 实现：
+
+| 图表 | 说明 |
+|------|------|
+| 折线图 | 趋势分析（订单/用户/收入趋势） |
+| 柱状图 | 对比分析 |
+| 饼图 | 占比分析 |
+| 地图 | 区域分布 |
+| 数字动画 | countup.js 实现数字滚动效果 |
+
+## 数据接口
+
+| 接口 | 说明 |
+|------|------|
+| `GET /api/open/data/count` | 统计总数 |
+| `GET /api/open/data/top-drugs` | 热门药品 |
+| `GET /api/open/data/store-number` | 门店数量 |
+| `GET /api/open/data/trend` | 趋势数据 |
+
+## 页面结构
+
+```mermaid
+graph TB
+    APP[数据大屏] --> COUNT[统计总览]
+    APP --> TOP[热门药品]
+    APP --> STORE[门店统计]
+    APP --> TREND[趋势图表]
+```
--- a/docs/projects/xk-data/modules/index.md
+++ b/docs/projects/xk-data/modules/index.md
@@ -0,0 +1,24 @@
+# xk-data 功能模块
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 数据展示 | 统计总览、趋势图表 | [数据展示](./charts.md) |
+
+## 数据展示
+
+| 模块 | 说明 |
+|------|------|
+| 统计总览 | 订单数、用户数、门店数等核心指标 |
+| 热门药品 | 热销药品排行 |
+| 门店统计 | 门店数量、分布 |
+| 趋势图表 | 订单/用户/收入趋势折线图 |
+
+## 数据来源
+
+通过 `open-api.php` 的 `/api/open/data/*` 接口获取数据：
+- `data/count` — 统计总数
+- `data/top-drugs` — 热门药品
+- `data/store-number` — 门店数量
+- `data/trend` — 趋势数据
--- a/docs/projects/xk-data/overview.md
+++ b/docs/projects/xk-data/overview.md
@@ -0,0 +1,38 @@
+# xk-data 概览
+
+xk-data 是 XK 系统的数据大屏，基于 Vue 3 和 ECharts 构建，用于业务数据可视化展示。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 框架 | Vue 3 (Vue CLI) |
+| 构建工具 | @vue/cli-service 5.0 |
+| 图表库 | ECharts 5.5.1 |
+| HTTP | Axios |
+| 计数动画 | countup.js |
+| 其他 | jQuery |
+
+## 目录结构
+
+```
+xk-data/
+├── public/             # 静态文件
+├── src/
+│   ├── api/            # API 调用
+│   ├── App.vue         # 根组件
+│   ├── App1.vue        # 备用根组件
+│   ├── assets/         # 资源文件
+│   ├── components/     # 组件
+│   └── main.js         # 入口
+├── vue.config.js       # Vue CLI 配置
+└── babel.config.js     # Babel 配置
+```
+
+## 数据来源
+
+通过 `open-api.php` 的 `/api/open/data/*` 接口获取数据：
+- `data/count` — 统计总数
+- `data/top-drugs` — 热门药品
+- `data/store-number` — 门店数量
+- `data/trend` — 趋势数据
--- a/docs/projects/xk-doctor-wx/architecture.md
+++ b/docs/projects/xk-doctor-wx/architecture.md
@@ -0,0 +1,66 @@
+# xk-doctor-wx 基类架构
+
+## 角色路由架构
+
+```mermaid
+graph TB
+    subgraph 主包 pages/
+        LOGIN[登录<br/>pages/login]
+        WB[工作台<br/>pages/workbench]
+        PAT[患者<br/>pages/patient]
+        MY[我的<br/>pages/my]
+        PHARM[审方<br/>pages/pharmacist]
+    end
+
+    subgraph 医生分包
+        SW[sub_workbench/<br/>工作台功能]
+        SP[sub_patient/<br/>患者管理]
+        SM[sub_my/<br/>我的功能]
+        SOR[sub_online_reception/<br/>在线接诊]
+    end
+
+    subgraph 药师分包
+        SPH[sub_pharmacist/<br/>药师功能]
+    end
+
+    subgraph 门店管理分包
+        SCA[sub_clinic_admin/<br/>门店管理]
+    end
+
+    subgraph 平台管理分包
+        SPA[sub_platform_admin/<br/>平台管理]
+    end
+
+    subgraph 推广员分包
+        SSM[sub_salesperson_manage/<br/>推广员管理]
+        SS[sub_salesperson/<br/>推广员自助]
+        SCS[sub_clinic_salesperson/<br/>门店推广员]
+    end
+
+    WB --> SW
+    PAT --> SP
+    MY --> SM
+    WB --> SOR
+    PHARM --> SPH
+    WB --> SCA
+    WB --> SPA
+    WB --> SSM
+    WB --> SS
+    WB --> SCS
+```
+
+## 多角色认证
+
+```mermaid
+graph LR
+    REQ[请求] --> AUTH{角色中间件}
+    AUTH -->|医生| DAUTH[DoctorWxUnifiedAuth]
+    AUTH -->|门店管理| CAUTH[ClinicAdminWxAuth]
+    AUTH -->|平台管理| PAUTH[PlatformAdminWxAuth]
+    AUTH -->|推广员| SAUTH[SalespersonWxAuth]
+    AUTH -->|门店推广员| CSAUTH[ClinicSalespersonWxAuth]
+```
+
+## API 层
+
+`api/` 目录定义了所有 API 接口调用，按角色和功能组织。
--- a/docs/projects/xk-doctor-wx/components.md
+++ b/docs/projects/xk-doctor-wx/components.md
@@ -0,0 +1,21 @@
+# xk-doctor-wx 通用组件
+
+## 页面组件
+
+| 组件 | 说明 |
+|------|------|
+| 工作台卡片 | 数据统计卡片（待办、收入、患者数） |
+| 患者卡片 | 患者信息展示（头像、姓名、最近就诊） |
+| 处方卡片 | 处方信息展示（类型、状态、金额） |
+| 订单卡片 | 订单信息展示（商品、金额、状态） |
+| 审方卡片 | 待审处方展示（处方内容、患者信息） |
+
+## 功能组件
+
+| 组件 | 说明 |
+|------|------|
+| 角色切换 | 多角色身份切换 |
+| 状态标签 | 订单/处方/审核状态标签 |
+| 加载更多 | 列表分页加载 |
+| 空状态 | 空数据提示 |
+| 操作确认 | 危险操作确认弹窗 |
--- a/docs/projects/xk-doctor-wx/design.md
+++ b/docs/projects/xk-doctor-wx/design.md
@@ -0,0 +1,44 @@
+# xk-doctor-wx 设计思路
+
+## 架构决策
+
+### 多角色单应用
+
+一个小程序支持 6 种角色，通过角色中间件和动态菜单控制功能访问：
+- 医生、药师、门店管理员、平台管理员、推广员、门店推广员
+- 每种角色有独立的路由组和页面分包
+- 共享登录和基础页面
+
+### 分包策略
+
+按角色和功能域分包：
+- 主包：登录、工作台、患者、我的、审方（核心入口）
+- 医生分包：接诊、开方、患者管理
+- 药师分包：审方、追溯
+- 管理分包：门店管理、平台管理
+- 推广员分包：推广管理、自助服务
+
+### 页面配置
+
+`pages.json` 有 613 行，包含所有页面路由和 tabBar 配置。另有 `pages1.json` 作为备用配置。
+
+## 用户体验
+
+### 医生工作流
+1. 登录 → 工作台查看待办
+2. 接诊患者 → 查看病历
+3. 问诊聊天 → 开具处方
+4. 患者购药 → 跟踪订单
+
+### 药师工作流
+1. 登录 → 审方列表
+2. 查看处方详情 → 审核通过/拒绝
+3. 处方追溯 → 查看流转记录
+4. IM 聊天 → 与医生沟通
+
+### 门店管理员工作流
+1. 登录 → 门店工作台
+2. 查看订单 → 处理发货
+3. 仓库管理 → 库存查看
+4. 结算管理 → 分账查看
+5. 提现管理 → 申请提现
--- a/docs/projects/xk-doctor-wx/modules/clinic-admin.md
+++ b/docs/projects/xk-doctor-wx/modules/clinic-admin.md
@@ -0,0 +1,38 @@
+# 门店管理模块
+
+## 门店工作台
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 门店工作台 | `sub_clinic_admin/` | 门店数据概览 |
+| 提现管理 | `sub_clinic_admin/` | 提现申请、记录 |
+| 对账管理 | `sub_clinic_admin/` | 对账单查看 |
+| 订单管理 | `sub_clinic_admin/` | 门店订单处理 |
+| 仓库管理 | `sub_clinic_admin/` | 药品库存 |
+| 结算管理 | `sub_clinic_admin/` | 分账结算 |
+
+## 门店管理员工作流程
+
+```mermaid
+graph TB
+    A[登录] --> B[门店工作台]
+    B --> C[查看订单]
+    C --> D[处理发货]
+    D --> E[仓库管理]
+    E --> F[库存查看]
+    F --> G[结算管理]
+    G --> H[分账查看]
+    H --> I[提现管理]
+    I --> J[申请提现]
+```
+
+## 功能说明
+
+| 功能 | 说明 |
+|------|------|
+| 工作台 | 门店数据概览、待办事项 |
+| 提现管理 | 提现申请、提现记录 |
+| 对账管理 | 对账单查看、导出 |
+| 订单管理 | 订单列表、发货操作 |
+| 仓库管理 | 药品库存、价格查看 |
+| 结算管理 | 分账记录、结算操作 |
--- a/docs/projects/xk-doctor-wx/modules/doctor.md
+++ b/docs/projects/xk-doctor-wx/modules/doctor.md
@@ -0,0 +1,51 @@
+# 医生模块
+
+## 工作台
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 工作台首页 | `pages/workbench/` | 待办事项、数据统计 |
+| 接诊管理 | `sub_workbench/` | 接诊列表、接诊操作 |
+| 在线接诊 | `sub_online_reception/` | 在线问诊聊天 |
+| 开方 | `sub_workbench/` | 处方开具（中药/西药/颗粒） |
+| 常用处方 | `sub_workbench/` | 处方模板管理 |
+| 医生评价 | `sub_workbench/` | 患者评价查看 |
+| 医生二维码 | `sub_workbench/` | 推广二维码 |
+| 排班管理 | `sub_workbench/` | 出诊时间设置 |
+
+## 患者管理
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 患者列表 | `pages/patient/` | 我的患者 |
+| 患者详情 | `sub_patient/` | 患者信息、病历 |
+| 患者备注 | `sub_patient/` | 患者备注管理 |
+
+## 医生工作流程
+
+```mermaid
+graph TB
+    A[登录] --> B[工作台查看待办]
+    B --> C[接诊患者]
+    C --> D[查看病历]
+    D --> E[问诊聊天]
+    E --> F[开具处方]
+    F --> G[患者购药]
+    G --> H[跟踪订单]
+```
+
+## 处方开具流程
+
+```mermaid
+graph TB
+    A[选择患者] --> B{处方类型}
+    B -->|中药| C[中医处方]
+    B -->|西药| D[西药处方]
+    B -->|颗粒| E[颗粒处方]
+    C --> F[添加药品]
+    D --> F
+    E --> F
+    F --> G[设置用法用量]
+    G --> H[确认开方]
+    H --> I[处方生效]
+```
--- a/docs/projects/xk-doctor-wx/modules/index.md
+++ b/docs/projects/xk-doctor-wx/modules/index.md
@@ -0,0 +1,11 @@
+# xk-doctor-wx 功能模块
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 医生模块 | 工作台、接诊、开方、患者管理 | [医生模块](./doctor.md) |
+| 药师模块 | 审方、处方追溯、IM 聊天 | [药师模块](./pharmacist.md) |
+| 门店管理模块 | 门店工作台、提现、对账、结算 | [门店管理](./clinic-admin.md) |
+| 平台管理模块 | 平台工作台、审核、门店管理 | [平台管理](./platform-admin.md) |
+| 推广员模块 | 推广员管理、佣金、结算 | [推广员模块](./salesperson.md) |
--- a/docs/projects/xk-doctor-wx/modules/pharmacist.md
+++ b/docs/projects/xk-doctor-wx/modules/pharmacist.md
@@ -0,0 +1,45 @@
+# 药师模块
+
+## 审方
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 审方列表 | `pages/pharmacist/` | 待审处方列表 |
+| 处方审核 | `sub_pharmacist/` | 处方详情、审核操作 |
+| 处方追溯 | `sub_pharmacist/` | 处方流转记录 |
+| IM 聊天 | `sub_pharmacist/` | 与医生/患者沟通 |
+| 分诊 | `sub_pharmacist/` | 处方分诊 |
+
+## 药师工作流程
+
+```mermaid
+graph TB
+    A[登录] --> B[审方列表]
+    B --> C[查看处方详情]
+    C --> D{审核结果}
+    D -->|通过| E[处方生效]
+    D -->|拒绝| F[退回修改]
+    E --> G[患者购药]
+    F --> H[通知医生修改]
+```
+
+## 处方审核流程
+
+```mermaid
+graph TB
+    A[医生开方] --> B[医生初审]
+    B -->|通过| C[药师复审]
+    B -->|拒绝| D[退回修改]
+    C -->|通过| E[处方生效]
+    C -->|拒绝| D
+    E --> F[患者购药]
+```
+
+## 处方状态
+
+| 状态 | 说明 |
+|------|------|
+| 待审核 | 医生已开方，等待审核 |
+| 通过 | 审核通过 |
+| 未通过 | 审核拒绝 |
+| 无需审核 | 免审处方 |
--- a/docs/projects/xk-doctor-wx/modules/platform-admin.md
+++ b/docs/projects/xk-doctor-wx/modules/platform-admin.md
@@ -0,0 +1,36 @@
+# 平台管理模块
+
+## 平台工作台
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 平台工作台 | `sub_platform_admin/` | 平台数据概览 |
+| 提现审核 | `sub_platform_admin/` | 提现申请审核 |
+| 门店管理 | `sub_platform_admin/` | 门店列表、审核 |
+| 门店入驻审核 | `sub_platform_admin/` | 新门店审核 |
+| 医生入驻审核 | `sub_platform_admin/` | 新医生审核 |
+| 医生管理 | `sub_platform_admin/` | 医生列表 |
+| 药师管理 | `sub_platform_admin/` | 药师列表 |
+
+## 平台管理员工作流程
+
+```mermaid
+graph TB
+    A[登录] --> B[平台工作台]
+    B --> C[查看门店]
+    C --> D[审核入驻]
+    D --> E[审核医生]
+    E --> F[审核提现]
+    F --> G[管理药品]
+    G --> H[查看财务]
+```
+
+## 审核流程
+
+```mermaid
+graph TB
+    A[提交申请] --> B[管理员审核]
+    B -->|通过| C[创建成功]
+    B -->|拒绝| D[退回修改]
+    C --> E[生效]
+```
--- a/docs/projects/xk-doctor-wx/modules/salesperson.md
+++ b/docs/projects/xk-doctor-wx/modules/salesperson.md
@@ -0,0 +1,54 @@
+# 推广员模块
+
+## 推广员管理
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 推广员工作台 | `sub_salesperson_manage/` | 推广数据概览 |
+| 门店入驻 | `sub_salesperson_manage/` | 新门店录入 |
+| 医生入驻 | `sub_salesperson_manage/` | 新医生录入 |
+| 银行卡上报 | `sub_salesperson_manage/` | 易票联银行卡上报 |
+
+## 推广员自助
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 推广员工作台 | `sub_salesperson/` | 个人数据概览 |
+| 收益查看 | `sub_salesperson/` | 佣金收益 |
+| 线索管理 | `sub_salesperson/` | 推广线索 |
+| 佣金明细 | `sub_salesperson/` | 佣金记录 |
+| 邀请记录 | `sub_salesperson/` | 邀请的用户 |
+| 结算记录 | `sub_salesperson/` | 结算单 |
+
+## 门店推广员
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 门店推广员工作台 | `sub_clinic_salesperson/` | 门店推广数据 |
+| 转诊处方 | `sub_clinic_salesperson/` | 转诊处方管理 |
+
+## 推广员工作流程
+
+```mermaid
+graph TB
+    A[登录] --> B[工作台]
+    B --> C[查看收益]
+    C --> D[管理线索]
+    D --> E[查看佣金]
+    E --> F[查看结算]
+    F --> G[申请提现]
+```
+
+## 佣金计算
+
+```mermaid
+graph TB
+    A[订单支付] --> B{是否有推广员}
+    B -->|是| C[计算佣金]
+    B -->|否| D[无佣金]
+    C --> E{佣金方式}
+    E -->|固定| F[按模板配置]
+    E -->|百分比| G[按比例计算]
+    F --> H[生成佣金记录]
+    G --> H
+```
--- a/docs/projects/xk-doctor-wx/overview.md
+++ b/docs/projects/xk-doctor-wx/overview.md
@@ -0,0 +1,69 @@
+# xk-doctor-wx 概览
+
+xk-doctor-wx 是 XK 系统的医生端微信小程序，支持医生、药师、门店管理员、平台管理员、推广员等多种角色。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 框架 | uni-app (Vue) |
+| UI 库 | uview-ui 1.8.8 |
+| 构建工具 | HBuilderX |
+| 其他 | js-base64 |
+
+## 目录结构
+
+```
+xk-doctor-wx/
+├── App.vue             # 应用入口
+├── main.js             # 主入口
+├── manifest.json       # uni-app 配置
+├── pages.json          # 页面路由 (613行)
+├── pages1.json         # 备用页面配置
+├── api/                # API 定义
+├── common/             # 公共代码
+├── components/         # 共享组件
+├── config/             # 配置
+├── pages/              # 主包页面
+│   ├── login/          # 登录/注册
+│   ├── workbench/      # 工作台 (主Tab)
+│   ├── patient/        # 患者列表 (主Tab)
+│   ├── my/             # 我的 (主Tab)
+│   └── pharmacist/     # 药师审方 (主Tab)
+├── subPackages/        # 分包
+│   ├── sub_workbench/  # 工作台功能
+│   ├── sub_patient/    # 患者管理
+│   ├── sub_my/         # 我的功能
+│   ├── sub_pharmacist/ # 药师功能
+│   ├── sub_clinic_admin/ # 门店管理
+│   ├── sub_platform_admin/ # 平台管理
+│   ├── sub_salesperson_manage/ # 推广员管理
+│   ├── sub_salesperson/ # 推广员自助
+│   ├── sub_clinic_salesperson/ # 门店推广员
+│   ├── sub_agreement/  # 协议页面
+│   ├── sub_online_reception/ # 在线接诊
+│   └── sub_business_shared/ # 共享业务页面
+├── static/             # 静态资源
+├── store/              # Vuex Store
+└── utils/              # 工具函数
+```
+
+## Tab Bar 页面
+
+| Tab | 页面 | 说明 |
+|-----|------|------|
+| 工作台 | `pages/workbench/` | 医生/管理员工作台 |
+| 患者 | `pages/patient/` | 患者列表 |
+| 我的 | `pages/my/` | 个人中心 |
+| 审方 | `pages/pharmacist/` | 药师审方 |
+
+## 多角色支持
+
+| 角色 | 入口 | 主要功能 |
+|------|------|----------|
+| 医生 | workbench + sub_workbench | 接诊、开方、患者管理、评价、在线接诊 |
+| 药师 | pharmacist + sub_pharmacist | 处方审核、处方追溯、IM 聊天、分诊 |
+| 门店管理员 | sub_clinic_admin | 工作台、提现、对账、订单、仓库、结算 |
+| 平台管理员 | sub_platform_admin | 工作台、提现审核、门店管理、入驻审核 |
+| 推广员 | sub_salesperson_manage | 工作台、门店/医生入驻、银行卡上报 |
+| 门店推广员 | sub_clinic_salesperson | 工作台、收益、线索、佣金、邀请、结算 |
--- a/docs/projects/xk-hy-forward-go/architecture.md
+++ b/docs/projects/xk-hy-forward-go/architecture.md
@@ -0,0 +1,47 @@
+# xk-hy-forward-go 基类架构
+
+## 代码结构
+
+```
+xk-hy-forward-go/
+├── main.go                 # 入口，调用 forward.Run()
+├── go.mod                  # Go 模块定义
+├── go.sum                  # 依赖校验
+├── run.bat                 # Windows 启动脚本
+├── .env.example            # 环境变量模板
+└── internal/
+    └── forward/
+        ├── run.go          # HTTP 服务器启动
+        ├── proxy.go        # 反向代理逻辑
+        ├── config.go       # 配置加载
+        ├── env.go          # 环境变量解析
+        ├── headers.go      # 请求头白名单过滤
+        ├── apilog.go       # API 请求日志
+        ├── applog.go       # 应用日志
+        ├── *_test.go       # 测试
+        └── testweb/        # 测试 Web 资源
+```
+
+## 核心模块
+
+| 文件 | 职责 |
+|------|------|
+| `run.go` | HTTP 服务器启动，路由注册 |
+| `proxy.go` | 反向代理核心逻辑，请求转发和响应处理 |
+| `config.go` | 配置加载和验证 |
+| `headers.go` | 请求头白名单，只转发允许的头 |
+| `apilog.go` | API 请求日志记录 |
+| `applog.go` | 应用级日志 |
+
+## 反向代理流程
+
+```mermaid
+graph LR
+    REQ[收到请求] --> CHECK{IP 白名单}
+    CHECK -->|通过| LOG[记录日志]
+    CHECK -->|拒绝| REJECT[返回 403]
+    LOG --> FILTER[过滤请求头]
+    FILTER --> FORWARD[转发至目标]
+    FORWARD --> RESP[接收响应]
+    RESP --> RET[返回给调用方]
+```
--- a/docs/projects/xk-hy-forward-go/design.md
+++ b/docs/projects/xk-hy-forward-go/design.md
@@ -0,0 +1,42 @@
+# xk-hy-forward-go 设计思路
+
+## 架构决策
+
+### 内网转发
+
+采用内网双通道转发架构：
+- 外部网络 `xk-hy-transit-go` 只能访问本服务
+- 本服务负责转发至浙江省政务云
+- 内外网隔离，确保政务云安全
+
+### Go 实现
+
+选择 Go 语言：
+- 高性能、低资源消耗
+- 原生支持并发
+- 适合做透明代理
+- 部署简单（单二进制文件）
+
+### 透明转发
+
+服务本身不做业务逻辑处理：
+- 只做请求转发和响应返回
+- 请求头白名单过滤
+- IP 白名单控制
+- 日志记录
+
+### Echo 模式
+
+支持 Echo 模式用于调试：
+- 不实际转发请求
+- 返回请求详情
+- 方便开发和测试
+
+## 安全考虑
+
+| 措施 | 说明 |
+|------|------|
+| IP 白名单 | `ALLOW_IPS` 配置允许访问的 IP |
+| 共享密钥 | `FORWARD_SHARED_SECRET` 验证调用方 |
+| 请求头过滤 | 只转发白名单中的请求头 |
+| 内网部署 | 部署在内网服务器，外部无法直接访问 |
--- a/docs/projects/xk-hy-forward-go/modules/forward.md
+++ b/docs/projects/xk-hy-forward-go/modules/forward.md
@@ -0,0 +1,49 @@
+# 监管数据转发模块
+
+## 监管业务数据
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/province/supervise/data` | 转发加密的监管业务 JSON 数据至政务云 |
+
+**目标**: `SUPERVISE_TARGET_URL` (端口 28212)
+
+## 文件上传
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/mng/file/auth/upload` | 转发处方 PDF 多部分上传至政务云 |
+
+**目标**: `FILE_TARGET_URL` (端口 28211)
+
+## 转发流程
+
+```mermaid
+sequenceDiagram
+    participant TRANSIT as xk-hy-transit-go
+    participant FORWARD as xk-hy-forward-go
+    participant GOV as 浙江省政务云
+
+    TRANSIT->>FORWARD: POST /province/supervise/data
+    FORWARD->>FORWARD: 验证 IP 白名单
+    FORWARD->>FORWARD: 过滤请求头
+    FORWARD->>GOV: 转发请求
+    GOV-->>FORWARD: 返回响应
+    FORWARD-->>TRANSIT: 返回结果
+```
+
+## 安全措施
+
+| 措施 | 说明 |
+|------|------|
+| IP 白名单 | `ALLOW_IPS` 配置允许访问的 IP |
+| 共享密钥 | `FORWARD_SHARED_SECRET` 验证调用方 |
+| 请求头过滤 | 只转发白名单中的请求头 |
+| 内网部署 | 部署在内网服务器，外部无法直接访问 |
+
+## Echo 模式
+
+当 `ENABLE_FORWARD=false` 时，服务进入 Echo 模式：
+- 不实际转发请求
+- 返回请求的详细信息（用于调试）
+- 适合开发和测试环境
--- a/docs/projects/xk-hy-forward-go/modules/health.md
+++ b/docs/projects/xk-hy-forward-go/modules/health.md
@@ -0,0 +1,30 @@
+# 健康检查模块
+
+## 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 服务健康状态检查 |
+| GET | `/t` | 政务云连通性测试页面 |
+
+## 健康检查
+
+- **路径**: `GET /health`
+- **说明**: 服务健康状态检查
+- **返回**: 200 OK
+
+## 测试页面
+
+- **路径**: `GET /t`
+- **说明**: 政务云连通性测试页面
+- **用途**: 验证服务能否正常转发至政务云
+
+## 日志系统
+
+### API 日志
+- 记录每个请求的方法、路径、状态码、耗时
+- 格式化输出，便于排查问题
+
+### 应用日志
+- 记录服务启动、配置加载、错误信息
+- 输出到控制台和日志文件
--- a/docs/projects/xk-hy-forward-go/modules/index.md
+++ b/docs/projects/xk-hy-forward-go/modules/index.md
@@ -0,0 +1,32 @@
+# xk-hy-forward-go 功能模块
+
+## 模块清单
+
+| 模块 | 说明 | 页面 |
+|------|------|------|
+| 监管数据转发 | 监管业务数据、文件上传转发 | [监管数据转发](./forward.md) |
+| 健康检查 | 服务健康状态检查 | [健康检查](./health.md) |
+
+## 架构角色
+
+```mermaid
+graph LR
+    subgraph 外部网络
+        TRANSIT[xk-hy-transit-go<br/>外部网络]
+    end
+
+    subgraph 内部网络
+        API[xk-api<br/>监管数据打包]
+        FORWARD[xk-hy-forward-go<br/>透明转发]
+    end
+
+    subgraph 政务云
+        GOV[浙江省政务云<br/>59.202.52.129]
+    end
+
+    API -->|加密数据| TRANSIT
+    TRANSIT -->|转发| FORWARD
+    FORWARD -->|透传| GOV
+    GOV -->|结果| FORWARD
+    FORWARD -->|回调| API
+```
--- a/docs/projects/xk-hy-forward-go/overview.md
+++ b/docs/projects/xk-hy-forward-go/overview.md
@@ -0,0 +1,73 @@
+# xk-hy-forward-go 概览
+
+xk-hy-forward-go 是 XK 系统的互联网医院监管数据转发服务，基于 Go 构建，负责将内部网络的监管数据透明转发至浙江省政务云。
+
+## 基本信息
+
+| 项 | 值 |
+|----|-----|
+| 语言 | Go 1.22 |
+| 模块 | `xk-hy-forward-go` |
+| 依赖 | github.com/joho/godotenv (环境变量加载) |
+| 部署 | 内网服务器 Windows |
+
+## 架构角色
+
+```mermaid
+graph LR
+    subgraph 外部网络
+        TRANSIT[xk-hy-transit-go<br/>外部网络]
+    end
+
+    subgraph 内部网络
+        API[xk-api<br/>监管数据打包]
+        FORWARD[xk-hy-forward-go<br/>透明转发]
+    end
+
+    subgraph 政务云
+        GOV[浙江省政务云<br/>59.202.52.129]
+    end
+
+    API -->|加密数据| TRANSIT
+    TRANSIT -->|转发| FORWARD
+    FORWARD -->|透传| GOV
+    GOV -->|结果| FORWARD
+    FORWARD -->|回调| API
+```
+
+::: warning 双通道设计
+- 外部网络 `xk-hy-transit-go` 只能访问本服务
+- 本服务负责转发至浙江省政务云
+- 内外网隔离，确保安全
+:::
+
+## 端点
+
+| 监听路径 | 转发目标 | 说明 |
+|----------|----------|------|
+| `POST /province/supervise/data` | `SUPERVISE_TARGET_URL` (端口 28212) | 加密监管业务 JSON |
+| `POST /mng/file/auth/upload` | `FILE_TARGET_URL` (端口 28211) | 处方 PDF 多部分上传 |
+| `GET /health` | 本地 | 健康检查 |
+| `GET /t` | 本地 | 政务云测试页面 |
+
+## 配置 (.env)
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `LISTEN_ADDR` | `:16001` | 监听地址 |
+| `SUPERVISE_TARGET_URL` | — | 监管数据转发目标 |
+| `FILE_TARGET_URL` | — | 文件上传转发目标 |
+| `ALLOW_IPS` | — | 允许的 IP 白名单 |
+| `FORWARD_SHARED_SECRET` | — | 转发共享密钥 |
+| `ENABLE_FORWARD` | `true` | 启用转发（false 为 echo 模式） |
+| `LOG_DIR` | — | 日志目录 |
+
+## 启动方式
+
+```bash
+# Windows
+run.bat
+
+# 或直接运行
+go run main.go
+```