xkyy/xk-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化

Browse Source
This commit is contained in:
李琦
2026-07-08 15:04:42 +08:00
commit 70264153e5
129 changed files with 13797 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
docs/.vitepress/config.ts Normal file
View File

@@ -0,0 +1,244 @@
import { defineConfig } from 'vitepress'
import { withMermaid } from 'vitepress-plugin-mermaid'
export default withMermaid(
defineConfig({
title: 'XK 项目文档',
description: '萧康新医疗系统技术文档',
lang: 'zh-CN',
lastUpdated: true,
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '指南', link: '/guide/introduction' },
{
text: '项目',
items: [
{ text: 'xk-admin (管理后台)', link: '/projects/xk-admin/overview' },
{ text: 'xk-api (新API)', link: '/projects/xk-api/overview' },
{ text: 'xk-api-yii (旧API)', link: '/projects/xk-api-yii/overview' },
{ text: 'xk-client-wx (用户端)', link: '/projects/xk-client-wx/overview' },
{ text: 'xk-doctor-wx (医生端)', link: '/projects/xk-doctor-wx/overview' },
{ text: 'xk-data (数据大屏)', link: '/projects/xk-data/overview' },
{ text: 'xk-hy-forward-go (监管转发)', link: '/projects/xk-hy-forward-go/overview' },
],
},
{
text: '数据库',
items: [
{ text: '总览', link: '/database/overview' },
{ text: 'z_xk (新库)', link: '/database/z-xk' },
{ text: 'z_o_xk (旧库)', link: '/database/z-o-xk' },
],
},
],
sidebar: {
'/guide/': [
{
text: '指南',
items: [
{ text: '项目介绍', link: '/guide/introduction' },
{ text: '系统架构', link: '/guide/architecture' },
],
},
],
'/projects/xk-admin/': [
{
text: 'xk-admin 管理后台',
items: [
{ text: '概览', link: '/projects/xk-admin/overview' },
{ text: '基类架构', link: '/projects/xk-admin/architecture' },
{ text: '通用组件', link: '/projects/xk-admin/components' },
{ text: '设计思路', link: '/projects/xk-admin/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-admin/modules/index' },
{ text: '系统管理', link: '/projects/xk-admin/modules/system' },
{ text: '业务管理', link: '/projects/xk-admin/modules/business' },
{ text: '药品管理', link: '/projects/xk-admin/modules/drug' },
{ text: '医生管理', link: '/projects/xk-admin/modules/doctor' },
{ text: '门店管理', link: '/projects/xk-admin/modules/store' },
{ text: '财务管理', link: '/projects/xk-admin/modules/finance' },
{ text: '销售推广', link: '/projects/xk-admin/modules/salesperson' },
{ text: '特色处方', link: '/projects/xk-admin/modules/special-prescription' },
{ text: '监管审计', link: '/projects/xk-admin/modules/hy-audit' },
{ text: '仪表盘', link: '/projects/xk-admin/modules/dashboard' },
{ text: '日志管理', link: '/projects/xk-admin/modules/log' },
{ text: '通知公告', link: '/projects/xk-admin/modules/notice' },
],
},
],
'/projects/xk-api/': [
{
text: 'xk-api 新API服务',
items: [
{ text: '概览', link: '/projects/xk-api/overview' },
{ text: '基类架构', link: '/projects/xk-api/architecture' },
{ text: '模型分析', link: '/projects/xk-api/models' },
{ text: '通用组件', link: '/projects/xk-api/components' },
{ text: '定时命令', link: '/projects/xk-api/commands' },
{ text: '重点功能', link: '/projects/xk-api/features' },
{ text: '设计思路', link: '/projects/xk-api/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-api/modules/index' },
{ text: '系统管理', link: '/projects/xk-api/modules/system' },
{ text: '处方管理', link: '/projects/xk-api/modules/prescription' },
{ text: '订单管理', link: '/projects/xk-api/modules/order' },
{ text: '药品管理', link: '/projects/xk-api/modules/drug' },
{ text: '医生管理', link: '/projects/xk-api/modules/doctor' },
{ text: '门店管理', link: '/projects/xk-api/modules/store' },
{ text: '财务结算', link: '/projects/xk-api/modules/finance' },
{ text: '销售推广', link: '/projects/xk-api/modules/salesperson' },
{ text: '特色处方', link: '/projects/xk-api/modules/special-prescription' },
{ text: '监管上报', link: '/projects/xk-api/modules/hy-supervise' },
{ text: '聊天通讯', link: '/projects/xk-api/modules/chat' },
{ text: '画布表格', link: '/projects/xk-api/modules/spreadsheet' },
],
},
],
'/projects/xk-api-yii/': [
{
text: 'xk-api-yii 旧API服务',
items: [
{ text: '概览', link: '/projects/xk-api-yii/overview' },
{ text: '基类架构', link: '/projects/xk-api-yii/architecture' },
{ text: '模型分析', link: '/projects/xk-api-yii/models' },
{ text: '设计思路', link: '/projects/xk-api-yii/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-api-yii/modules/index' },
{ text: '管理后台', link: '/projects/xk-api-yii/modules/admin' },
{ text: '会员端', link: '/projects/xk-api-yii/modules/member' },
{ text: '平台端', link: '/projects/xk-api-yii/modules/platform' },
{ text: '服务端', link: '/projects/xk-api-yii/modules/service' },
],
},
],
'/projects/xk-client-wx/': [
{
text: 'xk-client-wx 用户端小程序',
items: [
{ text: '概览', link: '/projects/xk-client-wx/overview' },
{ text: '基类架构', link: '/projects/xk-client-wx/architecture' },
{ text: '通用组件', link: '/projects/xk-client-wx/components' },
{ text: '设计思路', link: '/projects/xk-client-wx/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-client-wx/modules/index' },
{ text: '首页模块', link: '/projects/xk-client-wx/modules/home' },
{ text: '问诊模块', link: '/projects/xk-client-wx/modules/consultation' },
{ text: '购药模块', link: '/projects/xk-client-wx/modules/product' },
{ text: '挂号模块', link: '/projects/xk-client-wx/modules/register' },
{ text: '处方模块', link: '/projects/xk-client-wx/modules/prescription' },
{ text: '转诊模块', link: '/projects/xk-client-wx/modules/transfer' },
{ text: '个人中心', link: '/projects/xk-client-wx/modules/mine' },
],
},
],
'/projects/xk-doctor-wx/': [
{
text: 'xk-doctor-wx 医生端小程序',
items: [
{ text: '概览', link: '/projects/xk-doctor-wx/overview' },
{ text: '基类架构', link: '/projects/xk-doctor-wx/architecture' },
{ text: '通用组件', link: '/projects/xk-doctor-wx/components' },
{ text: '设计思路', link: '/projects/xk-doctor-wx/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-doctor-wx/modules/index' },
{ text: '医生模块', link: '/projects/xk-doctor-wx/modules/doctor' },
{ text: '药师模块', link: '/projects/xk-doctor-wx/modules/pharmacist' },
{ text: '门店管理', link: '/projects/xk-doctor-wx/modules/clinic-admin' },
{ text: '平台管理', link: '/projects/xk-doctor-wx/modules/platform-admin' },
{ text: '推广员模块', link: '/projects/xk-doctor-wx/modules/salesperson' },
],
},
],
'/projects/xk-data/': [
{
text: 'xk-data 数据大屏',
items: [
{ text: '概览', link: '/projects/xk-data/overview' },
{ text: '设计思路', link: '/projects/xk-data/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-data/modules/index' },
{ text: '数据展示', link: '/projects/xk-data/modules/charts' },
],
},
],
'/projects/xk-hy-forward-go/': [
{
text: 'xk-hy-forward-go 监管转发',
items: [
{ text: '概览', link: '/projects/xk-hy-forward-go/overview' },
{ text: '基类架构', link: '/projects/xk-hy-forward-go/architecture' },
{ text: '设计思路', link: '/projects/xk-hy-forward-go/design' },
],
},
{
text: '功能模块',
collapsed: false,
items: [
{ text: '模块总览', link: '/projects/xk-hy-forward-go/modules/index' },
{ text: '监管数据转发', link: '/projects/xk-hy-forward-go/modules/forward' },
{ text: '健康检查', link: '/projects/xk-hy-forward-go/modules/health' },
],
},
],
'/database/': [
{
text: '数据库',
items: [
{ text: '总览', link: '/database/overview' },
{ text: 'z_xk 新库', link: '/database/z-xk' },
{ text: 'z_o_xk 旧库', link: '/database/z-o-xk' },
],
},
],
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/' },
],
search: {
provider: 'local',
},
outline: {
level: [2, 3],
label: '页面导航',
},
lastUpdated: {
text: '最后更新于',
},
docFooter: {
prev: '上一篇',
next: '下一篇',
},
},
}),
)

9
docs/.vitepress/dayjs-shim.mjs Normal file
View File

@@ -0,0 +1,9 @@
// dayjs ESM shim
import * as dayjsAll from 'dayjs'
const dayjsFn = dayjsAll.default || dayjsAll
export default dayjsFn
export const extend = dayjsFn?.extend
export const unix = dayjsFn?.unix
export const utc = dayjsFn?.utc
export const duration = dayjsFn?.duration
export const isDayjs = dayjsFn?.isDayjs

612
docs/.vitepress/theme/HomePage.vue Normal file
View File

@@ -0,0 +1,612 @@
<template>
<div class="home-page">
<!-- Hero Section -->
<section class="hero">
<div class="hero-bg"></div>
<div class="hero-content">
<div class="hero-badge">技术文档</div>
<h1 class="hero-title">XK 项目文档</h1>
<p class="hero-subtitle">萧康新医疗系统</p>
<p class="hero-desc">互联网中医诊疗 · 药品供应链 · 监管合规</p>
<div class="hero-actions">
<a href="/guide/introduction" class="btn btn-primary">
<component :is="BookOpen" :size="18" />
项目介绍
</a>
<a href="/guide/architecture" class="btn btn-secondary">
<component :is="GitBranch" :size="18" />
系统架构
</a>
<a href="/database/overview" class="btn btn-secondary">
<component :is="Database" :size="18" />
数据库总览
</a>
</div>
</div>
</section>
<!-- Stats Section -->
<section class="stats">
<div class="stats-grid">
<div class="stat-card" v-for="stat in stats" :key="stat.label">
<div class="stat-icon">
<component :is="stat.icon" :size="24" />
</div>
<div class="stat-value">{{ stat.value }}</div>
<div class="stat-label">{{ stat.label }}</div>
</div>
</div>
</section>
<!-- Projects Section -->
<section class="projects">
<h2 class="section-title">项目总览</h2>
<p class="section-desc">XK 系统由 7 个核心子项目组成，覆盖完整的互联网中医诊疗业务链</p>
<div class="projects-grid">
<a
v-for="project in projects"
:key="project.name"
:href="project.link"
class="project-card"
>
<div class="project-header">
<div class="project-icon-box" :style="{ background: project.color + '15', color: project.color }">
<component :is="project.icon" :size="22" />
</div>
<span class="project-status" :class="project.status">{{ project.statusText }}</span>
</div>
<h3 class="project-name">{{ project.name }}</h3>
<p class="project-desc">{{ project.desc }}</p>
<div class="project-tech">
<span v-for="tech in project.tech" :key="tech" class="tech-tag">{{ tech }}</span>
</div>
</a>
</div>
</section>
<!-- Tech Stack Section -->
<section class="tech-stack">
<h2 class="section-title">技术栈</h2>
<div class="stack-grid">
<div class="stack-item" v-for="item in techStack" :key="item.name">
<div class="stack-icon" :style="{ color: item.color }">
<component :is="item.icon" :size="20" />
</div>
<span class="stack-name">{{ item.name }}</span>
</div>
</div>
</section>
</div>
</template>
<script setup>
import {
BookOpen,
GitBranch,
Database,
Folder,
Table2,
Plug,
Zap,
LayoutDashboard,
Server,
History,
Smartphone,
Stethoscope,
BarChart3,
Link,
CircleDot,
Code,
Cpu,
HardDrive,
Wifi,
Cloud,
} from '@lucide/vue'
const stats = [
{ icon: Folder, value: '7', label: '子项目' },
{ icon: Table2, value: '167+', label: '数据表' },
{ icon: Plug, value: '50+', label: 'API 接口' },
{ icon: Zap, value: '8', label: '消息队列任务' },
]
const projects = [
{
name: 'xk-admin',
icon: LayoutDashboard,
color: '#2563EB',
desc: '管理后台 — Vue 3 + Vben Admin Pro，总后台 / 门店端管理界面',
tech: ['Vue 3', 'Vben Admin', 'TypeScript'],
status: 'active',
statusText: '活跃',
link: '/projects/xk-admin/overview',
},
{
name: 'xk-api',
icon: Server,
color: '#0077B6',
desc: '新 API 服务 — Laravel 12，核心业务逻辑、支付、处方、监管上报',
tech: ['Laravel 12', 'PHP 8.4', 'MySQL'],
status: 'active',
statusText: '活跃',
link: '/projects/xk-api/overview',
},
{
name: 'xk-api-yii',
icon: History,
color: '#D97706',
desc: '旧 API 服务 — Yii2 Advanced，遗留系统，部分接口仍在使用',
tech: ['Yii2', 'PHP', 'MySQL'],
status: 'legacy',
statusText: '遗留',
link: '/projects/xk-api-yii/overview',
},
{
name: 'xk-client-wx',
icon: Smartphone,
color: '#16A34A',
desc: '用户端小程序 — uni-app，患者问诊、购药、挂号、转诊',
tech: ['uni-app', 'Vue 3', '微信小程序'],
status: 'active',
statusText: '活跃',
link: '/projects/xk-client-wx/overview',
},
{
name: 'xk-doctor-wx',
icon: Stethoscope,
color: '#7C3AED',
desc: '医生端小程序 — uni-app，医生接诊、开方、药师审方、门店管理',
tech: ['uni-app', 'Vue 3', '微信小程序'],
status: 'active',
statusText: '活跃',
link: '/projects/xk-doctor-wx/overview',
},
{
name: 'xk-data',
icon: BarChart3,
color: '#DC2626',
desc: '数据大屏 — Vue 3 + ECharts，业务数据可视化',
tech: ['Vue 3', 'ECharts', 'DataV'],
status: 'active',
statusText: '活跃',
link: '/projects/xk-data/overview',
},
{
name: 'xk-hy-forward-go',
icon: Link,
color: '#0891B2',
desc: '监管转发服务 — Go，内网双通道转发至浙江省政务云',
tech: ['Go', 'HTTP Proxy', 'AES'],
status: 'active',
statusText: '活跃',
link: '/projects/xk-hy-forward-go/overview',
},
]
const techStack = [
{ icon: CircleDot, name: 'Laravel 12', color: '#FF2D20' },
{ icon: Code, name: 'Vue 3', color: '#42B883' },
{ icon: Smartphone, name: 'uni-app', color: '#2B9939' },
{ icon: Cpu, name: 'Go', color: '#00ADD8' },
{ icon: Database, name: 'MySQL', color: '#4479A1' },
{ icon: HardDrive, name: 'Redis', color: '#DC382D' },
{ icon: Wifi, name: 'RabbitMQ', color: '#FF6600' },
{ icon: Cloud, name: '阿里云 OSS', color: '#FF6A00' },
]
</script>
<style scoped>
.home-page {
max-width: 1100px;
margin: 0 auto;
padding: 0 24px;
font-family: 'Noto Sans SC', 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}
/* Hero */
.hero {
position: relative;
text-align: center;
padding: 72px 0 48px;
overflow: hidden;
}
.hero-bg {
position: absolute;
top: -60%;
left: -20%;
width: 140%;
height: 200%;
background: radial-gradient(ellipse at 50% 0%, #0077B6 0%, transparent 60%);
opacity: 0.06;
pointer-events: none;
}
.hero-content {
position: relative;
z-index: 1;
}
.hero-badge {
display: inline-block;
padding: 6px 16px;
background: linear-gradient(135deg, #0077B608, #0077B615);
color: #0077B6;
border: 1px solid #0077B625;
border-radius: 20px;
font-size: 13px;
font-weight: 600;
margin-bottom: 20px;
letter-spacing: 0.5px;
}
.hero-title {
font-size: 52px;
font-weight: 800;
margin: 0 0 12px;
line-height: 1.15;
color: #0F172A;
letter-spacing: -1px;
}
.hero-subtitle {
font-size: 26px;
font-weight: 600;
color: #334155;
margin: 0 0 10px;
}
.hero-desc {
font-size: 16px;
color: #64748B;
margin: 0 0 36px;
}
.hero-actions {
display: flex;
gap: 14px;
justify-content: center;
flex-wrap: wrap;
}
.btn {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 12px 28px;
border-radius: 10px;
font-size: 15px;
font-weight: 600;
text-decoration: none;
transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
cursor: pointer;
position: relative;
overflow: hidden;
}
.btn-primary {
background: linear-gradient(135deg, #0077B6, #0096D6);
color: white;
box-shadow: 0 2px 8px rgba(0, 119, 182, 0.25);
}
.btn-primary:hover {
background: linear-gradient(135deg, #005F8F, #0077B6);
transform: translateY(-2px);
box-shadow: 0 6px 20px rgba(0, 119, 182, 0.35);
}
.btn-primary:active {
transform: translateY(0);
box-shadow: 0 2px 8px rgba(0, 119, 182, 0.25);
}
.btn-secondary {
background: white;
color: #334155;
border: 1px solid #E2E8F0;
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.04);
}
.btn-secondary:hover {
border-color: #0077B6;
color: #0077B6;
background: #F0F9FF;
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(0, 119, 182, 0.12);
}
.btn-secondary:active {
transform: translateY(0);
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.04);
}
/* Stats */
.stats {
padding: 32px 0;
}
.stats-grid {
display: grid;
grid-template-columns: repeat(4, 1fr);
gap: 16px;
}
.stat-card {
text-align: center;
padding: 28px 16px;
background: linear-gradient(180deg, #FFFFFF, #F8FAFC);
border-radius: 14px;
border: 1px solid #E2E8F0;
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.04);
}
.stat-card:hover {
border-color: #0077B630;
box-shadow: 0 8px 24px rgba(0, 119, 182, 0.1);
transform: translateY(-4px);
}
.stat-icon {
display: inline-flex;
align-items: center;
justify-content: center;
width: 48px;
height: 48px;
border-radius: 12px;
background: linear-gradient(135deg, #0077B610, #0077B608);
color: #0077B6;
margin-bottom: 12px;
transition: all 0.3s ease;
}
.stat-card:hover .stat-icon {
background: linear-gradient(135deg, #0077B620, #0077B615);
transform: scale(1.08);
}
.stat-value {
font-size: 36px;
font-weight: 800;
color: #0F172A;
margin-bottom: 4px;
letter-spacing: -0.5px;
}
.stat-label {
font-size: 13px;
color: #64748B;
font-weight: 500;
}
/* Section Title */
.section-title {
font-size: 28px;
font-weight: 700;
text-align: center;
margin: 56px 0 10px;
color: #0F172A;
letter-spacing: -0.5px;
}
.section-desc {
text-align: center;
color: #64748B;
margin: 0 0 36px;
font-size: 15px;
}
/* Projects */
.projects-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
gap: 16px;
}
.project-card {
display: block;
padding: 24px;
background: linear-gradient(180deg, #FFFFFF, #FAFBFC);
border: 1px solid #E2E8F0;
border-left: 3px solid transparent;
border-radius: 12px;
text-decoration: none;
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
cursor: pointer;
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.04);
}
.project-card:hover {
border-color: #E2E8F0;
border-left-color: #0077B6;
box-shadow: 0 8px 28px rgba(0, 0, 0, 0.08);
transform: translateY(-4px);
}
.project-header {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 14px;
}
.project-icon-box {
width: 44px;
height: 44px;
border-radius: 12px;
display: flex;
align-items: center;
justify-content: center;
transition: all 0.3s ease;
}
.project-card:hover .project-icon-box {
transform: scale(1.08);
}
.project-status {
font-size: 12px;
font-weight: 600;
padding: 4px 12px;
border-radius: 14px;
}
.project-status.active {
background: linear-gradient(135deg, #DCFCE7, #BBF7D0);
color: #15803D;
}
.project-status.legacy {
background: linear-gradient(135deg, #FEF3C7, #FDE68A);
color: #B45309;
}
.project-name {
font-size: 18px;
font-weight: 700;
color: #0F172A;
margin: 0 0 8px;
}
.project-desc {
font-size: 14px;
color: #64748B;
margin: 0 0 16px;
line-height: 1.6;
}
.project-tech {
display: flex;
gap: 6px;
flex-wrap: wrap;
}
.tech-tag {
font-size: 12px;
padding: 5px 10px;
background: linear-gradient(135deg, #F1F5F9, #E2E8F0);
border: none;
border-radius: 6px;
color: #475569;
font-weight: 500;
}
/* Tech Stack */
.tech-stack {
padding: 32px 0 72px;
}
.stack-grid {
display: flex;
justify-content: center;
gap: 12px;
flex-wrap: wrap;
}
.stack-item {
display: flex;
align-items: center;
gap: 10px;
padding: 12px 20px;
background: linear-gradient(135deg, #FFFFFF, #F8FAFC);
border: 1px solid #E2E8F0;
border-radius: 10px;
font-size: 14px;
font-weight: 500;
color: #334155;
transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
cursor: default;
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.03);
}
.stack-item:hover {
border-color: #0077B630;
box-shadow: 0 4px 12px rgba(0, 119, 182, 0.08);
transform: translateY(-2px);
}
.stack-icon {
display: flex;
align-items: center;
transition: transform 0.25s ease;
}
.stack-item:hover .stack-icon {
transform: scale(1.12);
}
.stack-name {
white-space: nowrap;
}
/* Responsive */
@media (max-width: 768px) {
.hero-title {
font-size: 34px;
}
.hero-subtitle {
font-size: 20px;
}
.stats-grid {
grid-template-columns: repeat(2, 1fr);
}
.projects-grid {
grid-template-columns: 1fr;
}
}
/* Dark mode */
:root.dark .home-page {
color: #E2E8F0;
}
:root.dark .hero-title {
color: #F1F5F9;
}
:root.dark .hero-subtitle {
color: #CBD5E1;
}
:root.dark .hero-badge {
background: linear-gradient(135deg, #38BDF808, #38BDF815);
color: #38BDF8;
border-color: #38BDF825;
}
:root.dark .btn-secondary {
background: #1E293B;
border-color: #334155;
color: #E2E8F0;
}
:root.dark .btn-secondary:hover {
border-color: #38BDF8;
color: #38BDF8;
background: #1E3A5F;
}
:root.dark .stat-card,
:root.dark .project-card,
:root.dark .stack-item {
background: linear-gradient(180deg, #1E293B, #1A2332);
border-color: #334155;
}
:root.dark .stat-card:hover,
:root.dark .project-card:hover,
:root.dark .stack-item:hover {
border-color: #38BDF840;
box-shadow: 0 8px 24px rgba(56, 189, 248, 0.08);
}
:root.dark .stat-icon {
background: linear-gradient(135deg, #38BDF810, #38BDF808);
color: #38BDF8;
}
:root.dark .stat-value,
:root.dark .project-name {
color: #F1F5F9;
}
:root.dark .stat-label,
:root.dark .project-desc {
color: #94A3B8;
}
:root.dark .tech-tag {
background: linear-gradient(135deg, #0F172A, #1E293B);
color: #94A3B8;
}
</style>

237
docs/.vitepress/theme/ImagePreview.vue Normal file
View File

@@ -0,0 +1,237 @@
<template>
<Teleport to="body">
<Transition name="preview">
<div v-if="visible" class="image-preview-overlay" @click.self="close">
<div class="image-preview-toolbar">
<button @click="zoomIn" title="放大">
<component :is="ZoomIn" :size="16" />
</button>
<button @click="zoomOut" title="缩小">
<component :is="ZoomOut" :size="16" />
</button>
<button @click="reset" title="重置">
<component :is="RotateCcw" :size="16" />
</button>
<span class="zoom-level">{{ Math.round(scale * 100) }}%</span>
<button class="close-btn" @click="close" title="关闭">
<component :is="X" :size="16" />
</button>
</div>
<div
class="image-preview-canvas"
ref="canvasRef"
@wheel.prevent="onWheel"
@mousedown="onMouseDown"
@mousemove="onMouseMove"
@mouseup="onMouseUp"
@mouseleave="onMouseUp"
>
<div
class="image-preview-content"
ref="contentRef"
:style="contentStyle"
></div>
</div>
</div>
</Transition>
</Teleport>
</template>
<script setup>
import { ref, computed, watch, nextTick, onUnmounted } from 'vue'
import { ZoomIn, ZoomOut, RotateCcw, X } from '@lucide/vue'
const props = defineProps({
visible: Boolean,
html: String,
})
const emit = defineEmits(['close'])
const canvasRef = ref(null)
const contentRef = ref(null)
const scale = ref(1)
const translateX = ref(0)
const translateY = ref(0)
const isDragging = ref(false)
const lastX = ref(0)
const lastY = ref(0)
const contentStyle = computed(() => ({
transform: `translate(${translateX.value}px, ${translateY.value}px) scale(${scale.value})`,
transformOrigin: '0 0',
}))
watch(() => props.visible, (val) => {
if (val) {
scale.value = 1
translateX.value = 0
translateY.value = 0
nextTick(() => {
if (contentRef.value && props.html) {
contentRef.value.innerHTML = props.html
centerContent()
}
})
document.body.style.overflow = 'hidden'
} else {
document.body.style.overflow = ''
}
})
function centerContent() {
if (!canvasRef.value || !contentRef.value) return
const cw = canvasRef.value.clientWidth
const ch = canvasRef.value.clientHeight
const iw = contentRef.value.scrollWidth
const ih = contentRef.value.scrollHeight
const fitScale = Math.min(cw / iw, ch / ih, 1) * 0.85
scale.value = fitScale
translateX.value = (cw - iw * fitScale) / 2
translateY.value = (ch - ih * fitScale) / 2
}
function zoomIn() {
scale.value = Math.min(scale.value * 1.25, 5)
}
function zoomOut() {
scale.value = Math.max(scale.value * 0.8, 0.1)
}
function reset() {
centerContent()
}
function close() {
emit('close')
}
function onWheel(e) {
const delta = e.deltaY > 0 ? 0.9 : 1.1
const newScale = Math.min(Math.max(scale.value * delta, 0.1), 5)
const rect = canvasRef.value.getBoundingClientRect()
const cx = e.clientX - rect.left
const cy = e.clientY - rect.top
translateX.value = cx - (cx - translateX.value) * (newScale / scale.value)
translateY.value = cy - (cy - translateY.value) * (newScale / scale.value)
scale.value = newScale
}
function onMouseDown(e) {
if (e.button !== 0) return
isDragging.value = true
lastX.value = e.clientX
lastY.value = e.clientY
}
function onMouseMove(e) {
if (!isDragging.value) return
translateX.value += e.clientX - lastX.value
translateY.value += e.clientY - lastY.value
lastX.value = e.clientX
lastY.value = e.clientY
}
function onMouseUp() {
isDragging.value = false
}
function onKeydown(e) {
if (e.key === 'Escape') close()
if (e.key === '+' || e.key === '=') zoomIn()
if (e.key === '-') zoomOut()
if (e.key === '0') reset()
}
if (typeof window !== 'undefined') {
window.addEventListener('keydown', onKeydown)
onUnmounted(() => window.removeEventListener('keydown', onKeydown))
}
</script>
<style scoped>
.image-preview-overlay {
position: fixed;
inset: 0;
z-index: 9999;
background: rgba(0, 0, 0, 0.85);
display: flex;
flex-direction: column;
cursor: default;
}
.image-preview-toolbar {
display: flex;
align-items: center;
gap: 2px;
padding: 8px 12px;
background: rgba(0, 0, 0, 0.6);
backdrop-filter: blur(8px);
z-index: 1;
}
.image-preview-toolbar button {
display: inline-flex;
align-items: center;
justify-content: center;
width: 30px;
height: 30px;
border: none;
border-radius: 6px;
background: transparent;
color: #fff;
cursor: pointer;
transition: background 0.15s;
}
.image-preview-toolbar button:hover {
background: rgba(255, 255, 255, 0.15);
}
.close-btn {
margin-left: auto;
}
.zoom-level {
font-size: 13px;
color: rgba(255, 255, 255, 0.7);
min-width: 48px;
text-align: center;
font-variant-numeric: tabular-nums;
}
.image-preview-canvas {
flex: 1;
overflow: hidden;
cursor: grab;
position: relative;
}
.image-preview-canvas:active {
cursor: grabbing;
}
.image-preview-content {
position: absolute;
color: #fff;
}
.image-preview-content :deep(svg) {
max-width: none;
height: auto;
}
/* Transition */
.preview-enter-active,
.preview-leave-active {
transition: opacity 0.25s ease;
}
.preview-enter-from,
.preview-leave-to {
opacity: 0;
}
</style>

221
docs/.vitepress/theme/Mermaid.vue Normal file
View File

@@ -0,0 +1,221 @@
<template>
<div class="mermaid-wrapper" ref="wrapperRef">
<div class="mermaid svg-mermaid" ref="mermaidRef" :data-graph="graph" @click="openPreview"></div>
<button class="mermaid-expand" @click.stop="openPreview" title="全屏预览">
<Maximize2 :size="8" />
</button>
<ImagePreview :visible="showPreview" :html="renderedHtml" @close="showPreview = false" />
</div>
</template>
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { Maximize2 } from '@lucide/vue'
import ImagePreview from './ImagePreview.vue'
const props = defineProps({
graph: {
type: String,
default: '',
},
id: {
type: String,
default: () => `mermaid-${Math.random().toString(36).slice(2, 9)}`,
},
})
const wrapperRef = ref(null)
const mermaidRef = ref(null)
const showPreview = ref(false)
const renderedHtml = ref('')
let mut = null
// Zoom/pan state
let scale = 1
let translateX = 0
let translateY = 0
let isDragging = false
let lastX = 0
let lastY = 0
const updateTransform = () => {
if (!mermaidRef.value) return
mermaidRef.value.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`
mermaidRef.value.style.transformOrigin = '0 0'
}
const onWheel = (e) => {
e.preventDefault()
const delta = e.deltaY > 0 ? 0.9 : 1.1
const newScale = Math.min(Math.max(scale * delta, 0.2), 5)
const rect = wrapperRef.value.getBoundingClientRect()
const cx = e.clientX - rect.left
const cy = e.clientY - rect.top
translateX = cx - (cx - translateX) * (newScale / scale)
translateY = cy - (cy - translateY) * (newScale / scale)
scale = newScale
updateTransform()
}
const onMouseDown = (e) => {
if (e.button !== 0) return
isDragging = true
lastX = e.clientX
lastY = e.clientY
wrapperRef.value.style.cursor = 'grabbing'
}
const onMouseMove = (e) => {
if (!isDragging) return
translateX += e.clientX - lastX
translateY += e.clientY - lastY
lastX = e.clientX
lastY = e.clientY
updateTransform()
}
const onMouseUp = () => {
isDragging = false
if (wrapperRef.value) wrapperRef.value.style.cursor = 'grab'
}
const onDblClick = () => {
scale = 1
translateX = 0
translateY = 0
updateTransform()
}
function openPreview() {
if (mermaidRef.value && mermaidRef.value.innerHTML) {
renderedHtml.value = mermaidRef.value.innerHTML
showPreview.value = true
}
}
const renderMermaid = async () => {
if (!mermaidRef.value) return
try {
const mermaid = (await import('mermaid')).default
mermaid.initialize({
startOnLoad: false,
theme: document.documentElement.classList.contains('dark') ? 'dark' : 'default',
securityLevel: 'loose',
})
const graphData = props.graph || mermaidRef.value.getAttribute('data-graph') || ''
if (!graphData) return
const decoded = decodeURIComponent(graphData)
const { svg } = await mermaid.render(props.id, decoded)
mermaidRef.value.innerHTML = svg
// Reset zoom/pan on re-render
scale = 1
translateX = 0
translateY = 0
updateTransform()
} catch (error) {
console.error('Mermaid render error:', error)
mermaidRef.value.innerHTML = `<pre style="color: red;">Mermaid Error: ${error.message}</pre>`
}
}
onMounted(() => {
renderMermaid()
mut = new MutationObserver(() => renderMermaid())
mut.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
const el = wrapperRef.value
if (el) {
el.addEventListener('wheel', onWheel, { passive: false })
el.addEventListener('mousedown', onMouseDown)
window.addEventListener('mousemove', onMouseMove)
window.addEventListener('mouseup', onMouseUp)
el.addEventListener('dblclick', onDblClick)
}
})
onUnmounted(() => {
if (mut) mut.disconnect()
const el = wrapperRef.value
if (el) {
el.removeEventListener('wheel', onWheel)
el.removeEventListener('mousedown', onMouseDown)
el.removeEventListener('dblclick', onDblClick)
}
window.removeEventListener('mousemove', onMouseMove)
window.removeEventListener('mouseup', onMouseUp)
})
</script>
<style scoped>
.mermaid-wrapper {
overflow: hidden;
cursor: grab;
border: 1px solid var(--vp-c-divider);
border-radius: 8px;
padding: 24px;
margin: 24px 0;
position: relative;
width: 100%;
min-height: 200px;
}
.mermaid-wrapper:active {
cursor: grabbing;
}
.mermaid {
width: 100%;
text-align: center;
}
.mermaid :deep(.svg-mermaid) {
width: 100%;
height: auto;
min-width: 600px;
}
.mermaid-expand {
position: absolute;
top: 8px;
right: 8px;
width: 28px !important;
height: 28px !important;
min-width: 28px !important;
min-height: 28px !important;
max-width: 28px !important;
max-height: 28px !important;
display: flex;
align-items: center;
justify-content: center;
border: 1px solid var(--vp-c-divider);
border-radius: 6px;
background: var(--vp-c-bg);
color: var(--vp-c-text-2);
cursor: pointer;
/* opacity: 0;
transition: opacity 0.2s;*/
z-index: 2;
flex-shrink: 0;
padding: 0;
margin: 0;
line-height: 1;
}
/*
.mermaid-wrapper:hover .mermaid-expand {
opacity: 1;
}*/
.mermaid-expand:hover {
border-color: var(--vp-c-brand-1);
color: var(--vp-c-brand-1);
}
</style>

13
docs/.vitepress/theme/index.ts Normal file
View File

@@ -0,0 +1,13 @@
import DefaultTheme from 'vitepress/theme'
import Mermaid from './Mermaid.vue'
import HomePage from './HomePage.vue'
import type { Theme } from 'vitepress'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('Mermaid', Mermaid)
app.component('HomePage', HomePage)
},
setup() {},
} satisfies Theme

18
docs/.vitepress/theme/mermaid-plugin.ts Normal file
View File

@@ -0,0 +1,18 @@
import type { MarkdownRenderer } from 'vitepress'
export function mermaidPlugin(md: MarkdownRenderer) {
const defaultFence = md.renderer.rules.fence.bind(md.renderer.rules)
md.renderer.rules.fence = (tokens, idx, options, env, self) => {
const token = tokens[idx]
const info = token.info.trim()
if (info === 'mermaid') {
const id = `mermaid-${idx}`
const encoded = encodeURIComponent(token.content)
return `<Mermaid graph="${encoded}" id="${id}"></Mermaid>`
}
return defaultFence(tokens, idx, options, env, self)
}
}

175
docs/database/overview.md Normal file
View File

@@ -0,0 +1,175 @@
# 数据库总览
XK 系统使用两个 MySQL 数据库，分别存储新旧系统的数据。
## 数据库概况
| 数据库 | 表数量 | 状态 | 说明 |
|--------|--------|------|------|
| **z_xk** | 67 张 | 活跃使用 | 新库，当前核心业务表 |
| **z_o_xk** | ~100 张 | 部分使用 | 旧库，Yii2 时代遗留 |
## 双库关系
```mermaid
graph TB
subgraph ZXK["z_xk 新库 67张表"]
A1[管理后台]
A2[财务结算]
A3[销售推广]
A4[特色处方]
A5[监管日志]
A6[系统配置]
A7[聊天消息]
A8[中医疾病库]
end
subgraph OXK["z_o_xk 旧库 ~100张表"]
B1[药品目录]
B2[订单系统]
B3[处方系统]
B4[用户系统]
B5[门店系统]
B6[医生系统]
B7[支付系统]
B8[物流系统]
end
API[xk-api] --> A1
API --> A2
API --> A3
API --> B1
API --> B2
API --> B3
API --> B4
API --> B5
```
::: warning 跨库约束
- 新库和旧库之间**不允许 JOIN 查询**
- 需要跨库关联时使用两步查询
- 定时任务中需要特别注意数据一致性
:::
## 表活跃状态
### z_xk (新库) — 全部活跃
所有 67 张表均在当前系统中使用。
### z_o_xk (旧库) — 部分活跃
| 状态 | 表数量 | 说明 |
|------|--------|------|
| **仍在使用** | ~40 张 | 药品、订单、处方、用户、门店、医生、支付等核心表 |
| **已废弃** | ~60 张 | 旧配置表、旧 IM 表、旧日志表、旧迁移表等 |
### 仍在使用的核心表 (z_o_xk)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_drug` | 药品目录 | xk-api, xk-admin |
| `yii_drug_store_relations` | 药品-门店定价 | xk-api, xk-admin |
| `yii_drug_categories` | 药品分类 | xk-api, xk-admin |
| `yii_drug_nature` | 药品配伍 | xk-api |
| `yii_product_order` | 产品订单 | xk-api, xk-admin |
| `yii_product_order_items` | 订单明细 | xk-api, xk-admin |
| `yii_register` | 挂号订单 | xk-api, xk-admin |
| `yii_prescription` | 主处方表 | xk-api, xk-admin, xk-doctor-wx |
| `yii_prescription_chinese` | 中药处方 | xk-api, xk-doctor-wx |
| `yii_prescription_west` | 西药处方 | xk-api, xk-doctor-wx |
| `yii_prescription_granular` | 颗粒处方 | xk-api, xk-doctor-wx |
| `yii_prescription_server` | 服务包处方 | xk-api, xk-doctor-wx |
| `yii_user` | 用户表 | xk-api, xk-client-wx |
| `yii_user_patient` | 就诊人 | xk-api, xk-client-wx |
| `yii_store` | 门店表 | xk-api, xk-admin, xk-doctor-wx |
| `yii_doctor_info` | 医生信息 | xk-api, xk-admin, xk-doctor-wx |
| `yii_doctor_service` | 医生服务设置 | xk-api, xk-doctor-wx |
| `yii_pharmacist_info` | 药师信息 | xk-api, xk-admin, xk-doctor-wx |
| `yii_service_user` | 服务用户 | xk-api |
| `yii_payment_order` | 咨询支付 | xk-api |
| `yii_payment_product_order` | 产品支付 | xk-api |
| `yii_payment_register` | 挂号支付 | xk-api |
| `yii_ledger` | 分账记录 | xk-api, xk-admin |
| `yii_fund_water` | 资金流水 | xk-api, xk-admin |
| `yii_cash_account` | 提现账户 | xk-api, xk-admin |
| `yii_cash_apply` | 提现申请 | xk-api, xk-admin |
| `yii_reconciliation` | 对账记录 | xk-api, xk-admin |
| `yii_order` | 咨询订单 | xk-api |
| `yii_order_refund` | 咨询退款 | xk-api |
| `yii_product_order_refund` | 产品退款 | xk-api |
| `yii_register_refund` | 挂号退款 | xk-api |
| `yii_transfer_prescription` | 转诊处方 | xk-api, xk-admin |
| `yii_chinese_recipe` | 中药处方笺 | xk-api |
| `yii_west_recipe` | 西药处方笺 | xk-api |
| `yii_granular_recipe` | 颗粒处方笺 | xk-api |
| `yii_im_message` | IM 消息 | xk-api |
| `yii_im_message_session` | IM 会话 | xk-api |
| `yii_examine_log` | 药师审核记录 | xk-api |
| `yii_reviewer` | 审方人 | xk-api |
| `yii_region` | 地区 | xk-api, xk-admin |
| `yii_express_nos` | 快递单号 | xk-api |
| `yii_express_companies` | 快递公司 | xk-api, xk-admin |
## 数据库设计规范
### 表命名
- 新表：`xk_` 前缀 + 业务域 + 功能名（如 `xk_salesperson_commission_record`）
- 旧表：`yii_` 前缀（Yii2 框架约定）
### 字段命名
- 主键：`id`（自增 bigint）
- 时间戳：`created_at`, `updated_at`
- 软删除：`deleted_at`
- 外键：`{关联表名}_id`（如 `store_id`, `user_id`）
- 状态字段：`status`（使用枚举值）
### 索引设计
- 主键索引：`id`
- 唯一索引：`uk_` 前缀（如 `uk_order_item_sp_type`）
- 普通索引：`idx_` 前缀（如 `idx_store_id`）
- 联合索引：多字段组合（如 `idx_anchor_step`）
### 数据类型
- 金额：`decimal(10,2)` 或 `decimal(12,2)`
- 大文本：`text` 或 `mediumtext`
- JSON：`json` 或 `text`（存储 JSON 字符串）
- 状态/类型：`tinyint` 或 `int`
- 手机号：`varchar(20)`
- 银行卡：`varchar(30)`
## ER 关系图
### 核心业务关系
```mermaid
erDiagram
yii_user ||--o{ yii_user_patient : "拥有"
yii_user ||--o{ yii_product_order : "下单"
yii_user ||--o{ yii_register : "挂号"
yii_user ||--o{ yii_order : "问诊"
yii_store ||--o{ yii_product_order : "归属"
yii_store ||--o{ yii_register : "归属"
yii_store ||--o{ yii_drug_store_relations : "定价"
yii_doctor_info ||--o{ yii_prescription : "开方"
yii_doctor_info ||--o{ yii_order : "接诊"
yii_doctor_info ||--o{ yii_register : "接诊"
yii_prescription ||--o{ yii_prescription_chinese : "中药"
yii_prescription ||--o{ yii_prescription_west : "西药"
yii_prescription ||--o{ yii_prescription_granular : "颗粒"
yii_product_order ||--o{ yii_product_order_items : "明细"
yii_product_order ||--o{ yii_payment_product_order : "支付"
yii_product_order ||--o{ yii_product_order_refund : "退款"
yii_product_order ||--o{ yii_ledger : "分账"
yii_register ||--o{ yii_payment_register : "支付"
yii_register ||--o{ yii_register_refund : "退款"
xk_clinic_salesperson ||--o{ xk_salesperson_commission_record : "佣金"
xk_salesperson_commission_record ||--o{ xk_salesperson_settlement_record : "结算"
xk_salesperson_settlement ||--o{ xk_salesperson_settlement_record : "包含"
```

196
docs/database/z-o-xk.md Normal file
View File

@@ -0,0 +1,196 @@
# z_o_xk 旧库
z_o_xk 是 XK 系统的旧数据库，约 100 张表，Yii2 时代遗留。部分表仍在使用，部分已废弃。
## 表状态总览
| 状态 | 表数量 | 说明 |
|------|--------|------|
| 仍在使用 | ~40 张 | 核心业务表，xk-api 和前端仍在读写 |
| 已废弃 | ~60 张 | 旧配置、旧日志、旧迁移等，仅保留数据 |
## 仍在使用的核心表
### 药品 (drug/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_drug` | 药品主表 | xk-api, xk-admin |
| `yii_drug_categories` | 药品分类 | xk-api, xk-admin |
| `yii_drug_store_relations` | 药品-门店定价 | xk-api, xk-admin |
| `yii_drug_nature` | 药品配伍（十八反十九畏） | xk-api |
| `yii_drug_dosage` | 中药剂量 | xk-api |
| `yii_drug_use_frequency` | 用药频率 | xk-api |
| `yii_drug_use_num` | 用药数量 | xk-api |
| `yii_drug_use_time` | 用药时间 | xk-api |
| `yii_drug_use_type` | 用药方式 | xk-api |
| `yii_drug_use_way` | 煎煮方式 | xk-api |
| `yii_process_rule` | 加工规则 | xk-api |
| `yii_process_rule_note` | 加工规则说明 | xk-api |
| `yii_west_unit` | 西药单位 | xk-api |
| `yii_package_method` | 包装方式 | xk-api |
### 订单 (order/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_product_order` | 产品订单 | xk-api, xk-admin |
| `yii_product_order_items` | 订单明细 | xk-api, xk-admin |
| `yii_register` | 挂号订单 | xk-api, xk-admin |
| `yii_order` | 咨询订单 | xk-api |
| `yii_order_refund` | 咨询退款 | xk-api |
| `yii_product_order_refund` | 产品退款 | xk-api |
| `yii_register_refund` | 挂号退款 | xk-api |
| `yii_order_number_change` | 回复次数变更 | xk-api |
| `yii_order_video_info` | 视频通话信息 | xk-api |
| `yii_order_log` | 订单日志 | xk-api |
### 处方 (prescription/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_prescription` | 主处方表 | xk-api, xk-admin, xk-doctor-wx |
| `yii_prescription_chinese` | 中药处方 | xk-api, xk-doctor-wx |
| `yii_prescription_west` | 西药处方 | xk-api, xk-doctor-wx |
| `yii_prescription_granular` | 颗粒处方 | xk-api, xk-doctor-wx |
| `yii_prescription_server` | 服务包处方 | xk-api, xk-doctor-wx |
| `yii_transfer_prescription` | 转诊处方 | xk-api, xk-admin |
| `yii_chinese_recipe` | 中药处方笺 | xk-api |
| `yii_west_recipe` | 西药处方笺 | xk-api |
| `yii_granular_recipe` | 颗粒处方笺 | xk-api |
| `yii_chinese_medicine` | 中药饮片 | xk-api |
| `yii_granular_medicine` | 颗粒药品 | xk-api |
| `yii_server_recipe` | 服务包处方笺 | xk-api |
| `yii_prescription_log` | 处方日志 | xk-api |
| `yii_prescrip_order_log` | 处方订单日志 | xk-api |
| `yii_prescrip_order_refund` | 处方订单退款 | xk-api |
| `yii_examine_log` | 药师审核记录 | xk-api |
| `yii_reviewer` | 审方人 | xk-api |
### 用户 (user/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_user` | 用户表 | xk-api, xk-client-wx |
| `yii_user_patient` | 就诊人 | xk-api, xk-client-wx |
| `yii_user_patient_case` | 患者病历 | xk-api |
| `yii_user_patient_record` | 患者档案 | xk-api |
| `yii_user_patient_health_inquiry` | 健康问诊 | xk-api |
| `yii_user_patient_ill` | 患者疾病 | xk-api |
| `yii_user_inquiry` | 用户问诊 | xk-api |
| `yii_user_collect` | 用户收藏 | xk-api |
| `yii_user_comment` | 用户评价 | xk-api |
| `yii_address` | 收货地址 | xk-api |
| `yii_service_user` | 服务用户（医生/药师） | xk-api |
| `yii_service_user_token` | 服务用户令牌 | xk-api |
### 医生 (doctor/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_doctor_info` | 医生信息 | xk-api, xk-admin, xk-doctor-wx |
| `yii_doctor_service` | 医生服务设置 | xk-api, xk-doctor-wx |
| `yii_doctor_identity` | 医生身份验证 | xk-api |
| `yii_doctor_practicing` | 医生执业证书 | xk-api |
| `yii_doctor_register` | 医生挂号 | xk-api |
| `yii_doctor_rostering` | 医生排班 | xk-api |
| `yii_doctor_notice` | 医生停诊通知 | xk-api |
| `yii_doctor_patient` | 医生患者列表 | xk-api |
| `yii_doctor_patient_remark` | 患者备注 | xk-api |
| `yii_doctor_article` | 医生文章 | xk-api, xk-admin |
| `yii_doctor_common` | 医生常用药品 | xk-api |
| `yii_doctor_tag_ill` | 医生疾病标签 | xk-api |
| `yii_doctor_tag_word` | 医生常用语 | xk-api |
| `yii_doctor_title` | 医生职称 | xk-api |
| `yii_doctor_apply` | 医生升级申请 | xk-api |
| `yii_store_doctor` | 门店-医生关联 | xk-api |
| `yii_department` | 科室 | xk-api |
| `yii_diagnose_common` | 常用医嘱 | xk-api |
| `yii_disease` | 疾病库 | xk-api |
| `yii_disease_common` | 常用疾病 | xk-api |
| `yii_patient_visit_record` | 就诊记录 | xk-api |
| `yii_pharmacist_info` | 药师信息 | xk-api, xk-admin, xk-doctor-wx |
| `yii_pharmacist_identity` | 药师身份验证 | xk-api |
| `yii_pharmacist_practicing` | 药师执业证书 | xk-api |
| `yii_serv_info` | 客服信息 | xk-api |
### 门店 (store/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_store` | 门店表 | xk-api, xk-admin, xk-doctor-wx |
| `yii_store_department` | 门店-科室关联 | xk-api |
| `yii_store_user` | 门店-用户关联 | xk-api |
### 财务 (finance/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_ledger` | 分账记录 | xk-api, xk-admin |
| `yii_ledger_log` | 分账变更日志 | xk-api |
| `yii_cash_account` | 提现账户 | xk-api, xk-admin |
| `yii_cash_apply` | 提现申请 | xk-api, xk-admin |
| `yii_fund_water` | 资金流水 | xk-api, xk-admin |
| `yii_reconciliation` | 对账记录 | xk-api, xk-admin |
| `yii_refund_bills` | 退款账单 | xk-api |
| `yii_charge_cash_pay_record` | 代理付款记录 | xk-api |
### 支付 (payment/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_payment_order` | 咨询支付 | xk-api |
| `yii_payment_product_order` | 产品支付 | xk-api |
| `yii_payment_register` | 挂号支付 | xk-api |
| `yii_payment_refund` | 咨询退款记录 | xk-api |
| `yii_payment_product_refund` | 产品退款记录 | xk-api |
| `yii_payment_register_refund` | 挂号退款记录 | xk-api |
| `yii_pay_config` | 支付配置 | xk-api |
| `yii_bills` | 账单 | xk-api |
### IM (im/)
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_im_message` | IM 消息 | xk-api |
| `yii_im_message_session` | IM 会话 | xk-api |
| `yii_im_message_session_order` | 会话-订单关联 | xk-api |
### 其他仍在使用的表
| 表名 | 说明 | 使用方 |
|------|------|--------|
| `yii_region` | 地区 | xk-api, xk-admin |
| `yii_express_companies` | 快递公司 | xk-api, xk-admin |
| `yii_express_nos` | 快递单号 | xk-api |
| `yii_express_details` | 快递详情 | xk-api |
| `yii_express_fees` | 快递费用 | xk-api |
| `yii_base_config` | 基础配置 | xk-api |
| `yii_system_notice` | 系统通知 | xk-api |
| `yii_inquiry_refuse_reason` | 问诊拒绝原因 | xk-api |
| `yii_refund_reason` | 退款原因 | xk-api |
| `yii_replay_template` | 快捷回复模板 | xk-api |
| `yii_replay_template_group` | 回复模板分组 | xk-api |
| `yii_follow_doctor` | 用户关注医生 | xk-api |
| `yii_follow_user` | 医生关注用户 | xk-api |
## 已废弃的表
以下表已不再使用，仅保留历史数据：
| 类别 | 表 | 说明 |
|------|-----|------|
| 旧配置 | `yii_admin`, `yii_admin_access_token`, `yii_admin_role` | 已迁移到 `xk_admin` |
| 旧 RBAC | `yii_auth_assignment`, `yii_auth_item`, `yii_auth_item_child` | 已迁移到 `xk_role` |
| 旧菜单 | `yii_menu`, `yii_role_menu` | 已迁移到 `xk_menu`, `xk_role_menu_relations` |
| 旧平台 | `yii_plate`, `yii_platform` | 已迁移到 `xk_platform` |
| 旧配置 | `yii_config`, `yii_system_config` | 已迁移到 `xk_system_config` |
| 旧日志 | `yii_log`, `yii_op_log` | 已迁移到 `xk_api_op_log` |
| 旧附件 | `yii_attachment`, `yii_attachment_group` | 已迁移到 `xk_file` |
| 旧迁移 | `yii_migration`, `yii_migrations` | 迁移记录 |
| 旧队列 | `yii_queue`, `yii_queue4`, `yii_failed_jobs` | 已迁移到 RabbitMQ |
| 旧 IM | `z_yii_im_message` | 旧 IM 消息 |
| 体检 | `yii_physical_package`, `yii_physical_reserve`, `yii_physical_reserve_total` | 体检功能 |
| 医院 | `yii_hospital`, `yii_hospital_yard`, `yii_hospital_department_intro` | 医院信息 |
| 商品 | `yii_carts` | 购物车（已迁移） |
| 其他 | `yii_categories`, `yii_healthy_news`, `yii_orther_info` | 杂项 |

121
docs/database/z-xk.md Normal file
View File

@@ -0,0 +1,121 @@
# z_xk 新库
z_xk 是 XK 系统的新数据库，包含 67 张表，全部在当前系统中活跃使用。
## 管理后台 (14张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_admin` | 管理员用户 | login_account, password, role_id, store_id, supplier_id |
| `xk_admin_notice` | 管理员消息 | title, content, type, status |
| `xk_admin_notice_relations` | 用户通知关联 | notice_id, user_id, status |
| `xk_admin_salesperson` | 管理员-推广员关联 | admin_id, salesperson_id, store_id |
| `xk_card` | 用户银行卡 | bank_user_name, bank_card, bank_name |
| `xk_menu` | 菜单定义 | title, icon, path, pid, sort |
| `xk_notice` | 公告 | title, content, status |
| `xk_platform` | 平台信息 | name, logo, introduce |
| `xk_queue_job` | 业务队列任务 | title, job_name, status |
| `xk_role` | 角色定义 | user_type, name, value, pid |
| `xk_role_menu_relations` | 角色-菜单绑定 | role_id, menu_id |
| `xk_role_quick_nav` | 角色快捷导航 | role_id, menu_id, title, url |
| `xk_supplier` | 供应商 | name, logo, business_license |
| `xk_platform_qualifications` | 平台资质 | 各类许可证图片, store_id |
## 财务 (3张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_account_balance` | 账户余额 | user_id, type, total, balance, frozen, withdrawn |
| `xk_account_balance_change_record` | 余额变更记录 | user_id, order_id, amount |
| `xk_account_able_change_log` | 可提现金额变更日志 | user_id, user_type, before_amount, after_amount, source_type |
## 销售 (11张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_clinic_salesperson` | 门店推广员 | phone, nick_name, split, split_type |
| `xk_salesperson_commission_record` | 佣金记录 | salesperson_id, drug_id, commission_amount, split_type |
| `xk_salesperson_commission_template` | 佣金模板 | store_id, name |
| `xk_salesperson_commission_template_item` | 佣金模板明细 | template_id, drug_id, commission |
| `xk_salesperson_drug_commission` | 药品佣金配置 | salesperson_id, drug_id, commission |
| `xk_salesperson_qr_code` | 推广员二维码 | salesperson_id, qr_code, status |
| `xk_salesperson_settlement` | 推广员结算单 | settlement_no, amount, period_start, period_end |
| `xk_salesperson_settlement_record` | 结算-佣金关联 | settlement_id, commission_record_id |
| `xk_salesperson_store_config` | 推广员门店配置 | store_id, see_price |
| `xk_user_salesperson` | 用户-推广员绑定 | user_id, salesperson_id, type, status |
| `xk_admin_salesperson` | 管理员-推广员关联 | admin_id, salesperson_id |
## 特色处方 (7张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_special_prescription` | 特色处方主表 | name, category_id, price_per_dose, status, store_id |
| `xk_special_prescription_category` | 处方分类 | name, sort, status |
| `xk_special_prescription_sku` | SKU 剂量规格 | sku_name, dose_count, buy_price, sale_price |
| `xk_special_prescription_drug_price` | 药品分摊价格 | drug_id, buy_price, sell_price |
| `xk_special_prescription_order` | 处方订单快照 | product_order_id, dose_count, sku_sale_price |
| `xk_special_prescription_patient_record` | 患者处方记录 | user_id, dose_count, status |
| `xk_special_prescription_introduction_images` | 介绍图片 | image_url, sort |
## 系统 (9张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_store_input` | 门店预填表单 | name, type, province_id, city_id, status |
| `xk_store_input_contract` | 门店合同文件 | file_url, file_name |
| `xk_store_input_nav` | 门店轮播图 | pic, sort |
| `xk_doctor_input` | 医生预填表单 | name, mobile, title_id, type, status |
| `xk_doctor_input_store` | 医生-门店绑定 | doctor_input_id, store_id |
| `xk_store_bank_card_report` | 门店银行卡上报 | bank_card, report_status, epl_state |
| `xk_spreadsheet_table_config` | 画布表格配置 | table_name, sheet_key, config |
| `xk_spreadsheet_edit_history` | 画布编辑历史 | table_name, action, before_snapshot, after_snapshot |
| `xk_spreadsheet_formula` | 画布公式库 | code, name, expression_template |
## 监管日志 (8张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_hy_transit_batch` | 监管同步批次 | anchor_date, step, pull_status, total_count |
| `xk_hy_transit_record` | 监管拉取/回调记录 | biz_key, payload_json, pull_status, push_status, callback_status |
| `xk_api_op_log` | 新 API 操作日志 | url, method, param, result, platform_type |
| `xk_error_log` | 错误日志 | type, content |
| `xk_product_order_price_adjust_log` | 订单改价日志 | old_price, new_price, adjust_amount |
| `xk_store_drug_update_log` | 药品价格变更日志 | old_buy, new_buy, old_price, new_price |
| `xk_sync_china_order_log` | ERP 同步日志 | order_id, content, is_success |
| `xk_spreadsheet_edit_history` | 画布编辑历史 | action, before_snapshot, after_snapshot |
## 其他 (15张表)
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `xk_chat_messages` | 聊天消息 | room_id, sender_user_id, message_type, message_content |
| `xk_chat_room` | 聊天房间 | sender_user_id, receiver_user_id |
| `xk_system_config` | 系统配置 | config_key, config_value, value_type |
| `xk_file` | 文件管理 | url, original_name, file_size, type |
| `xk_file_group` | 文件分组 | name, sort |
| `xk_file_group_rel` | 文件-分组关联 | file_id, group_id |
| `xk_file_type` | 文件类型 | name, value, suffix |
| `xk_home_zones` | 首页分区 | title, type, store_id |
| `xk_transfer_assistant_config` | 转诊助手配置 | name, avatar |
| `xk_transfer_question` | 转诊问题模板 | question, answers, type |
| `xk_transfer_prescription_question` | 转诊处方问答 | transfer_prescription_id, question_id, answer |
| `xk_register_info` | 挂号就诊信息 | register_id, user_id, drug_id, type |
| `xk_register_info_drug` | 挂号关联药品 | register_info_id, drug_id, quantity |
| `xk_user_patient_guardian` | 患者监护人 | guardian_name, guardian_id_card, guardian_mobile |
| `xk_subjects` | 医学学科 | name, code, pid |
| `xk_doctor_order` | 医嘱 | name |
| `xk_doctor_quick_reply` | 医生快捷回复 | doctor_id, content, sort_order |
| `xk_doctor_wx_phone_openid` | 医生手机-微信绑定 | phone, openid |
| `xk_drug_introduction_images` | 药品介绍图片 | drug_id, image_url |
| `xk_store_subscribe` | 门店价格订阅 | store_id, status |
| `xk_traditional_chinese_medicine_diseases` | 中医疾病库 | code, name |
| `xk_traditional_chinese_medicine_method` | 中医治法库 | code, name |
| `xk_traditional_chinese_medicine_syndrome` | 中医证候库 | code, name |
| `xk_prescription_disease` | 处方-疾病关联 | prescription_id, disease_id |
| `xk_prescription_method` | 处方-治法关联 | prescription_id, method_id |
| `xk_prescription_syndrome` | 处方-证候关联 | prescription_id, syndrome_id |
| `xk_monthly_payment` | 月结账单 | store_id, amount, status |
| `xk_monthly_payment_settlement` | 月结结算记录 | store_id, amount |
| `xk_product_order_export_scheme` | 订单导出方案 | admin_id, config |
| `xk_monthly_payment` | 月结账单 | store_id, order_id, amount, status |
| `xk_monthly_payment_settlement` | 月结结算记录 | url, store_id, amount |

199
docs/guide/architecture.md Normal file
View File

@@ -0,0 +1,199 @@
# 系统架构
## 整体架构
```mermaid
graph TB
subgraph 客户端
U[患者小程序<br/>xk-client-wx]
D[医生小程序<br/>xk-doctor-wx]
A[管理后台<br/>xk-admin]
S[数据大屏<br/>xk-data]
end
subgraph API层
API[xk-api<br/>Laravel 12]
YII[xk-api-yii<br/>Yii2 遗留]
end
subgraph 数据层
DB1[(z_xk<br/>新库)]
DB2[(z_o_xk<br/>旧库)]
RD[(Redis)]
MQ[(RabbitMQ)]
OSS[(阿里云 OSS)]
end
subgraph 外部集成
PAY1[微信支付]
PAY2[易票联支付]
SMS[短信服务]
HY[xk-hy-forward-go<br/>Go 转发]
GOV[浙江省政务云<br/>监管平台]
MES[和利康 MES<br/>中药智造]
ERP[ERP 系统]
KUAI100[快递100]
end
U --> API
D --> API
A --> API
S --> API
API --> DB1
API --> DB2
API --> RD
API --> MQ
API --> OSS
API --> PAY1
API --> PAY2
API --> SMS
API --> HY
API --> MES
API --> ERP
API --> KUAI100
HY --> GOV
```
## 双数据库策略
系统同时连接两个 MySQL 数据库：
```mermaid
graph LR
subgraph z_xk 新库 67张表
A1[管理后台 xk_admin]
A2[财务 xk_account_*]
A3[销售 xk_salesperson_*]
A4[处方 xk_special_prescription*]
A5[监管 xk_hy_transit_*]
A6[系统配置 xk_system_config]
end
subgraph z_o_xk 旧库 约100张表
B1[药品 yii_drug]
B2[订单 yii_product_order]
B3[处方 yii_prescription]
B4[用户 yii_user]
B5[门店 yii_store]
B6[医生 yii_doctor_info]
B7[挂号 yii_register]
end
API[xk-api] -->|读写| A1
API -->|读写| A2
API -->|读写| A3
API -->|读写| B1
API -->|读写| B2
API -->|读写| B3
```
::: warning 跨库注意事项
- 新库和旧库之间**不允许 JOIN 查询**
- 跨库关联需要在应用层做两步查询
- 定时任务 `app:accrue-salesperson-commission` 需要同时查两个库
:::
## API 路由架构
xk-api 通过路由文件划分不同端的接口：
| 路由文件 | 前缀 | 用途 | 认证方式 |
|----------|------|------|----------|
| `admin.php` | `/api/admin` | 管理后台 API | JWT (AdminAuthMiddleware) |
| `mobile.php` | `/api/mobile` | 患者小程序 API | JWT (MobileAuthMiddleware) |
| `doctor.php` | `/api/doctor` | 医生端小程序 API | 多种角色中间件 |
| `hy.php` | `/api/hy` | 互联网医院监管 API | HyTransitApiMiddleware |
| `callback.php` | `/api/callback` | 支付回调 | 签名验证 |
| `open-api.php` | `/api/open` | 开放 API | 无/简单认证 |
## 中间件链
```mermaid
graph LR
REQ[请求] --> CORS[CORS]
CORS --> THROTTLE[限流]
THROTTLE --> AUTH{认证中间件}
AUTH -->|Admin| JWT[JWT验证]
AUTH -->|Mobile| MJWT[Mobile JWT]
AUTH -->|Doctor| DROLE[角色验证]
AUTH -->|Hy| HTOKEN[Hy Transit Token]
JWT --> LOG[操作日志]
MJWT --> LOG
DROLE --> LOG
HTOKEN --> LOG
LOG --> CTRL[Controller]
```
## 消息队列架构
```mermaid
graph TB
subgraph 生产者
P1[订单支付回调]
P2[挂号支付回调]
P3[退款回调]
P4[定时任务]
end
subgraph RabbitMQ
Q1[default 队列]
Q2[failed_jobs]
end
subgraph 消费者 Job
J1[ProductOrderPaidJob<br/>分账结算]
J2[RegisterPaidJob<br/>挂号分账]
J3[ProductOrderRefundJob<br/>退款处理]
J4[SalespersonCommissionRefundJob<br/>佣金冲销]
J5[AutoConfirmReceiptOrderJob<br/>自动确认收货]
J6[AutomaticallyCancelTheOrderJob<br/>自动取消订单]
J7[AutoExpirePrescriptionHandlerJob<br/>处方过期处理]
J8[SyncDrugPriceBySubscribeJob<br/>药品价格同步]
end
P1 --> Q1
P2 --> Q1
P3 --> Q1
P4 --> Q1
Q1 --> J1
Q1 --> J2
Q1 --> J3
Q1 --> J4
Q1 --> J5
Q1 --> J6
Q1 --> J7
Q1 --> J8
```
## 监管数据流转
```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. 更新批次状态
```
## 部署架构
| 服务 | 部署方式 | 说明 |
|------|----------|------|
| xk-api | 服务器 + LaravelS | PHP-FPM + LaravelS 常驻进程 |
| xk-admin | CDN / Nginx | 静态资源部署 |
| xk-client-wx | 微信小程序平台 | HBuilderX 上传 |
| xk-doctor-wx | 微信小程序平台 | HBuilderX 上传 |
| xk-data | 服务器 / CDN | 静态页面 |
| xk-hy-forward-go | 内网服务器 | Windows 部署，run.bat 启动 |
| MySQL | 服务器 | 双库部署 |
| Redis | 服务器 | 缓存 / 队列 |
| RabbitMQ | 服务器 | 消息队列 |

67
docs/guide/introduction.md Normal file
View File

@@ -0,0 +1,67 @@
# 项目介绍
XK（萧康）是一套完整的互联网中医诊疗与药品供应链系统，涵盖患者端问诊购药、医生端接诊开方、药师审方、门店管理、财务结算、以及浙江省互联网医院监管平台数据上报。
## 项目组成
| 项目 | 技术栈 | 说明 |
|------|--------|------|
| **xk-admin** | Vue 3 + Vben Admin Pro v5.5.1 + Ant Design Vue | 管理后台前端，支持总后台、门店端、平台端多角色 |
| **xk-api** | Laravel 12 (PHP 8.4+) + Sanctum | 新 API 服务，核心业务逻辑所在 |
| **xk-api-yii** | Yii2 Advanced | 旧 API 服务，历史业务逻辑，逐步迁移中 |
| **xk-client-wx** | uni-app (Vue 3) + uview-ui | 患者微信小程序，问诊 / 购药 / 挂号 |
| **xk-doctor-wx** | uni-app (Vue) + uview-ui | 医生 / 药师 / 门店管理员微信小程序 |
| **xk-data** | Vue 3 + ECharts | 业务数据大屏 |
| **xk-hy-forward-go** | Go 1.22 | 互联网医院监管数据内网转发至浙江省政务云 |
## 技术栈概览
```mermaid
graph TB
subgraph 前端
A[xk-admin<br/>Vue3 + Vben] --> B[xk-api<br/>Laravel 12]
C[xk-client-wx<br/>uni-app] --> B
D[xk-doctor-wx<br/>uni-app] --> B
E[xk-data<br/>Vue3 + ECharts] --> B
end
subgraph 后端
B --> F[(z_xk<br/>新库 MySQL)]
B --> G[(z_o_xk<br/>旧库 MySQL)]
B --> H[RabbitMQ]
B --> I[Redis]
B --> J[阿里云 OSS]
B --> K[易票联支付]
B --> L[微信支付]
end
subgraph 外部系统
B --> M[xk-hy-forward-go<br/>Go 转发]
M --> N[浙江省政务云<br/>监管平台]
B --> O[和利康 MES<br/>中药智造]
B --> P[ERP 系统]
end
```
## 数据库
系统使用两个 MySQL 数据库：
- **z_xk**（新库）：67 张表，当前活跃使用，包含管理后台、财务、销售、处方流转等核心业务表
- **z_o_xk**（旧库）：约 100 张表，Yii2 时代遗留，部分表仍在使用（如药品、订单、处方、用户等），部分已废弃
详见 [数据库总览](/database/overview)。
## 多端角色
系统支持多种用户角色，通过不同的小程序端和后台访问：
| 角色 | 入口 | 说明 |
|------|------|------|
| 平台管理员 | xk-admin 总后台 | 全局管理、审核、财务 |
| 门店管理员 | xk-admin 门店端 / xk-doctor-wx | 门店运营、仓库、结算 |
| 医生 | xk-doctor-wx | 接诊、开方、患者管理 |
| 药师 | xk-doctor-wx (审方页) | 处方审核、处方追溯 |
| 门店推广员 | xk-doctor-wx | 门店推广、佣金管理 |
| 患者 | xk-client-wx | 问诊、购药、挂号 |
| 供应商 | xk-admin | 药品供应 |

7
docs/index.md Normal file
View File

@@ -0,0 +1,7 @@
---
layout: page
---
<ClientOnly>
<HomePage />
</ClientOnly>

55
docs/projects/xk-admin/architecture.md Normal file
View File

@@ -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 # 代码检查
```

30
docs/projects/xk-admin/components.md Normal file
View File

@@ -0,0 +1,30 @@
# xk-admin 通用组件
## 布局组件
| 组件 | 说明 |
|------|------|
| `layouts/` | 页面整体布局（侧边栏 + 顶栏 + 内容区） |
| 侧边栏 | 菜单导航，支持多级折叠 |
| 顶栏 | 面包屑、搜索、通知、用户信息 |
| 标签页 | 多标签页切换 |
## 业务组件
| 组件 | 说明 |
|------|------|
| 权限指令 | `v-access:code` 按钮级权限控制 |
| API 适配器 | 统一请求格式和错误处理 |
| 数据表格 | Ant Design Vue Table 封装 |
| 表单组件 | 搜索表单、编辑表单 |
| 文件上传 | 图片、文件上传组件 |
| 富文本编辑 | Markdown / 富文本编辑器 |
| 图表 | ECharts 集成（数据大屏） |
## 工具函数
| 工具 | 说明 |
|------|------|
| `utils/` | 通用工具函数 |
| `composables/` | Vue Composition API 复用逻辑 |
| `locales/` | 国际化资源 |

45
docs/projects/xk-admin/design.md Normal file
View File

@@ -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 | 类型安全 |

43
docs/projects/xk-admin/modules/business.md Normal file
View File

@@ -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[患者购药]
```

52
docs/projects/xk-admin/modules/dashboard.md Normal file
View File

@@ -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` | 服务层 |

51
docs/projects/xk-admin/modules/doctor.md Normal file
View File

@@ -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
```

44
docs/projects/xk-admin/modules/drug.md Normal file
View File

@@ -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 | 正常销售 |

48
docs/projects/xk-admin/modules/finance.md Normal file
View File

@@ -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[打款成功]
```

38
docs/projects/xk-admin/modules/hy-audit.md Normal file
View File

@@ -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[更新状态]
```

22
docs/projects/xk-admin/modules/index.md Normal file
View File

@@ -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) |

95
docs/projects/xk-admin/modules/log.md Normal file
View File

@@ -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` | 监管记录服务 |

64
docs/projects/xk-admin/modules/notice.md Normal file
View File

@@ -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 |

43
docs/projects/xk-admin/modules/salesperson.md Normal file
View File

@@ -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%** 利润
:::

35
docs/projects/xk-admin/modules/special-prescription.md Normal file
View File

@@ -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 | 正常销售 |

34
docs/projects/xk-admin/modules/store.md Normal file
View File

@@ -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 | 中医诊所 |

36
docs/projects/xk-admin/modules/system.md Normal file
View File

@@ -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>
```
## 角色列表
| 角色 | 说明 | 主要功能 |
|------|------|----------|
| 超级管理员 | 全局管理 | 所有功能 |
| 管理员 | 普通管理 | 日常管理操作 |
| 省经理 | 省级管理 | 区域门店管理 |
| 市经理 | 市级管理 | 区域门店管理 |
| 区经理 | 区级管理 | 区域门店管理 |
| 供应商 | 药品供应 | 药品管理 |
| 门店管理员 | 门店运营 | 门店端功能 |
| 总部财务 | 财务管理 | 财务功能 |

64
docs/projects/xk-admin/overview.md Normal file
View File

@@ -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>
```

56
docs/projects/xk-api-yii/architecture.md Normal file
View File

@@ -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 中开发，旧功能逐步迁移

35
docs/projects/xk-api-yii/design.md Normal file
View File

@@ -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 |
| 状态 | 维护模式 | 活跃开发 |
| 功能 | 旧功能 | 新功能 + 迁移功能 |

140
docs/projects/xk-api-yii/models.md Normal file
View File

@@ -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` | 快递费用 |

29
docs/projects/xk-api-yii/modules/admin.md Normal file
View File

@@ -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` — 角色-菜单绑定

14
docs/projects/xk-api-yii/modules/index.md Normal file
View File

@@ -0,0 +1,14 @@
# xk-api-yii 功能模块
::: warning 状态说明
xk-api-yii 是旧系统，核心功能已逐步迁移到 xk-api (Laravel)。以下模块仍可能在旧系统中运行。
:::
## 模块清单
| 模块 | 说明 | 页面 |
|------|------|------|
| 管理后台 | 管理员、RBAC、配置 | [管理后台](./admin.md) |
| 会员端 | 用户、患者、购物车、订单 | [会员端](./member.md) |
| 平台端 | 门店、医生、药品、财务 | [平台端](./platform.md) |
| 服务端 | 医生工作台、药师审方、IM | [服务端](./service.md) |

33
docs/projects/xk-api-yii/modules/member.md Normal file
View File

@@ -0,0 +1,33 @@
# 会员端模块
## 模块说明
| 模块 | 说明 |
|------|------|
| 用户管理 | 用户注册、登录、信息管理 |
| 患者管理 | 就诊人管理、病历 |
| 购物车 | 药品购物车 |
| 产品订单 | 产品订单管理 |
| 挂号订单 | 挂号预约管理 |
| 处方查看 | 处方记录查看 |
| 健康资讯 | 健康文章浏览 |
## 目录结构
```
member/
├── controllers/ # 控制器
├── models/ # 模型
├── views/ # 视图
└── config/ # 配置
```
## 主要功能
- 用户注册/登录
- 就诊人管理
- 药品浏览/购物车
- 订单管理
- 挂号预约
- 处方查看
- 健康资讯

33
docs/projects/xk-api-yii/modules/platform.md Normal file
View File

@@ -0,0 +1,33 @@
# 平台端模块
## 模块说明
| 模块 | 说明 |
|------|------|
| 门店管理 | 门店审核、配置 |
| 医生管理 | 医生审核、信息管理 |
| 药师管理 | 药师审核 |
| 药品管理 | 药品上架、下架、定价 |
| 订单管理 | 订单处理、发货 |
| 财务管理 | 分账、结算、提现 |
| 数据统计 | 业务数据统计 |
## 目录结构
```
platform/
├── controllers/ # 控制器
├── models/ # 模型
├── views/ # 视图
└── config/ # 配置
```
## 主要功能
- 门店审核/管理
- 医生审核/管理
- 药师审核/管理
- 药品管理
- 订单处理
- 财务结算
- 数据统计

27
docs/projects/xk-api-yii/modules/service.md Normal file
View File

@@ -0,0 +1,27 @@
# 服务端模块
## 模块说明
| 模块 | 说明 |
|------|------|
| 医生工作台 | 接诊、开方、患者管理 |
| 药师审方 | 处方审核 |
| 即时通讯 | 医患聊天 |
| 常用处方 | 处方模板管理 |
## 目录结构
```
service/
├── controllers/ # 控制器
├── models/ # 模型
├── views/ # 视图
└── config/ # 配置
```
## 主要功能
- 医生接诊/开方
- 药师审方
- 医患聊天
- 处方模板

60
docs/projects/xk-api-yii/overview.md Normal file
View File

@@ -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**: 服务端（医生/药师）

121
docs/projects/xk-api/architecture.md Normal file
View File

@@ -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` | 十八反、十九畏、有毒药材 |

67
docs/projects/xk-api/commands.md Normal file
View File

@@ -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` 确认收货。

111
docs/projects/xk-api/components.md Normal file
View File

@@ -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
- 通用工具方法
- 错误处理

115
docs/projects/xk-api/design.md Normal file
View File

@@ -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`

236
docs/projects/xk-api/features.md Normal file
View File

@@ -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 下各药品的分摊价格 |
| 患者记录 | 患者选择特色处方的记录（待应用→已应用→完成） |

142
docs/projects/xk-api/models.md Normal file
View File

@@ -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` 等 |

62
docs/projects/xk-api/modules/chat.md Normal file
View File

@@ -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 | 转诊处方 |

213
docs/projects/xk-api/modules/doctor.md Normal file
View File

@@ -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` | 改价日志 |

217
docs/projects/xk-api/modules/drug.md Normal file
View File

@@ -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` | 加工规则说明 |

219
docs/projects/xk-api/modules/finance.md Normal file
View File

@@ -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` | 业务服务 |

180
docs/projects/xk-api/modules/hy-supervise.md Normal file
View File

@@ -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 | 具体失败原因 |

64
docs/projects/xk-api/modules/index.md Normal file
View File

@@ -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) |

173
docs/projects/xk-api/modules/order.md Normal file
View File

@@ -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` | 业务服务 |

270
docs/projects/xk-api/modules/prescription.md Normal file
View File

@@ -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` | 业务服务 |

228
docs/projects/xk-api/modules/salesperson.md Normal file
View File

@@ -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=是 |

201
docs/projects/xk-api/modules/special-prescription.md Normal file
View File

@@ -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` | 模板服务 |

130
docs/projects/xk-api/modules/spreadsheet.md Normal file
View File

@@ -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 | 状态 |

176
docs/projects/xk-api/modules/store.md Normal file
View File

@@ -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
[*] --> 待上报: 创建上报
待上报 --> 上报中: 提交易票联
上报中 --> 已通过: 审核通过
上报中 --> 已拒绝: 审核拒绝
已拒绝 --> 待上报: 重新上报
已通过 --> 已修改: 信息变更
已修改 --> 上报中: 重新上报
```

259
docs/projects/xk-api/modules/system.md Normal file
View File

@@ -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` | 管理员消息 |

79
docs/projects/xk-api/overview.md Normal file
View File

@@ -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 系统接口规范 |

50
docs/projects/xk-client-wx/architecture.md Normal file
View File

@@ -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: 新模块状态

29
docs/projects/xk-client-wx/components.md Normal file
View File

@@ -0,0 +1,29 @@
# xk-client-wx 通用组件
## 页面组件
| 组件 | 说明 |
|------|------|
| 医生卡片 | 医生信息展示（头像、姓名、职称、擅长） |
| 药品卡片 | 药品信息展示（图片、名称、规格、价格） |
| 处方卡片 | 处方信息展示（处方内容、状态） |
| 订单卡片 | 订单信息展示（商品、金额、状态） |
| 地址选择 | 收货地址选择组件 |
## 功能组件
| 组件 | 说明 |
|------|------|
| 登录弹窗 | 微信授权登录 |
| 加载更多 | 列表分页加载 |
| 空状态 | 空数据提示 |
| 价格显示 | 价格格式化显示 |
| 状态标签 | 订单/处方状态标签 |
## 工具函数
| 工具 | 说明 |
|------|------|
| `request/` | HTTP 请求封装 |
| `utils/` | 工具函数 |
| `common/` | 公共方法 |

44
docs/projects/xk-client-wx/design.md Normal file
View File

@@ -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. 等待发货 → 查看物流

41
docs/projects/xk-client-wx/modules/consultation.md Normal file
View File

@@ -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[结束问诊]
```
## 聊天消息类型
| 类型 | 说明 |
|------|------|
| 文字 | 文本消息 |
| 图片 | 图片消息 |
| 语音 | 语音消息 |
| 处方 | 处方卡片 |
| 病历 | 病历文件 |
| 视频通话 | 视频通话 |
| 结束问诊 | 结束问诊 |

26
docs/projects/xk-client-wx/modules/home.md Normal file
View File

@@ -0,0 +1,26 @@
# 首页模块
## 页面
| 页面 | 路径 | 说明 |
|------|------|------|
| 首页 | `pages/home/` | 门店信息、医生列表、药品推荐、特色处方入口 |
## 功能
- 门店信息展示
- 医生推荐列表
- 药品推荐列表
- 特色处方入口
- 健康资讯入口
## 页面结构
```mermaid
graph TB
HOME[首页] --> STORE[门店信息]
HOME --> DOC[医生推荐]
HOME --> DRUG[药品推荐]
HOME --> SP[特色处方]
HOME --> NEWS[健康资讯]
```

13
docs/projects/xk-client-wx/modules/index.md Normal file
View File

@@ -0,0 +1,13 @@
# xk-client-wx 功能模块
## 模块清单
| 模块 | 说明 | 页面 |
|------|------|------|
| 首页模块 | 门店信息、医生推荐、药品推荐 | [首页模块](./home.md) |
| 问诊模块 | 医生浏览、图文问诊、在线聊天 | [问诊模块](./consultation.md) |
| 购药模块 | 商品浏览、购物车、下单支付 | [购药模块](./product.md) |
| 挂号模块 | 挂号预约、挂号记录 | [挂号模块](./register.md) |
| 处方模块 | 处方查看、特色处方、复诊续方 | [处方模块](./prescription.md) |
| 转诊模块 | 转诊咨询 | [转诊模块](./transfer.md) |
| 个人中心 | 我的、就诊人、设置 | [个人中心](./mine.md) |

38
docs/projects/xk-client-wx/modules/mine.md Normal file
View File

@@ -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[客服]
```

38
docs/projects/xk-client-wx/modules/prescription.md Normal file
View File

@@ -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[处方生效]
```

37
docs/projects/xk-client-wx/modules/product.md Normal file
View File

@@ -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[确认收货]
```
## 订单状态
| 状态 | 说明 |
|------|------|
| 待支付 | 订单已创建 |
| 待发货 | 已支付，等待发货 |
| 待收货 | 已发货，等待收货 |
| 已收货 | 已确认收货 |
| 已取消 | 订单已取消 |
| 退款中 | 退款处理中 |
| 已退款 | 退款完成 |

28
docs/projects/xk-client-wx/modules/register.md Normal file
View File

@@ -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 | 线上复诊挂号 |

37
docs/projects/xk-client-wx/modules/transfer.md Normal file
View File

@@ -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%** 利润
:::

68
docs/projects/xk-client-wx/overview.md Normal file
View File

@@ -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` | 个人中心 |
## 主要功能
- 医生浏览和问诊（图文问诊）
- 商品浏览和购药
- 挂号预约
- 处方查看
- 特色药方
- 在线问诊聊天
- 转诊咨询
- 商城订单、购物车、物流
- 设置、协议、客服

25
docs/projects/xk-data/design.md Normal file
View File

@@ -0,0 +1,25 @@
# xk-data 设计思路
## 架构决策
### 独立部署
数据大屏作为独立的前端应用部署：
- 不依赖管理后台框架
- 简化的技术栈（Vue CLI + ECharts）
- 可独立部署为静态页面
### 数据聚合
通过后端 Open API 获取聚合数据：
- 前端只负责展示，不做数据计算
- 后端 `DashboardDataController` 负责数据聚合
- 支持缓存，减少数据库查询
### 大屏适配
针对大屏显示优化：
- 全屏布局
- 高对比度配色
- 自适应分辨率
- 数字动画效果

32
docs/projects/xk-data/modules/charts.md Normal file
View File

@@ -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[趋势图表]
```

24
docs/projects/xk-data/modules/index.md Normal file
View File

@@ -0,0 +1,24 @@
# xk-data 功能模块
## 模块清单
| 模块 | 说明 | 页面 |
|------|------|------|
| 数据展示 | 统计总览、趋势图表 | [数据展示](./charts.md) |
## 数据展示
| 模块 | 说明 |
|------|------|
| 统计总览 | 订单数、用户数、门店数等核心指标 |
| 热门药品 | 热销药品排行 |
| 门店统计 | 门店数量、分布 |
| 趋势图表 | 订单/用户/收入趋势折线图 |
## 数据来源
通过 `open-api.php` 的 `/api/open/data/*` 接口获取数据：
- `data/count` — 统计总数
- `data/top-drugs` — 热门药品
- `data/store-number` — 门店数量
- `data/trend` — 趋势数据

38
docs/projects/xk-data/overview.md Normal file
View File

@@ -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` — 趋势数据

66
docs/projects/xk-doctor-wx/architecture.md Normal file
View File

@@ -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 接口调用，按角色和功能组织。

21
docs/projects/xk-doctor-wx/components.md Normal file
View File

@@ -0,0 +1,21 @@
# xk-doctor-wx 通用组件
## 页面组件
| 组件 | 说明 |
|------|------|
| 工作台卡片 | 数据统计卡片（待办、收入、患者数） |
| 患者卡片 | 患者信息展示（头像、姓名、最近就诊） |
| 处方卡片 | 处方信息展示（类型、状态、金额） |
| 订单卡片 | 订单信息展示（商品、金额、状态） |
| 审方卡片 | 待审处方展示（处方内容、患者信息） |
## 功能组件
| 组件 | 说明 |
|------|------|
| 角色切换 | 多角色身份切换 |
| 状态标签 | 订单/处方/审核状态标签 |
| 加载更多 | 列表分页加载 |
| 空状态 | 空数据提示 |
| 操作确认 | 危险操作确认弹窗 |

44
docs/projects/xk-doctor-wx/design.md Normal file
View File

@@ -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. 提现管理 → 申请提现

38
docs/projects/xk-doctor-wx/modules/clinic-admin.md Normal file
View File

@@ -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[申请提现]
```
## 功能说明
| 功能 | 说明 |
|------|------|
| 工作台 | 门店数据概览、待办事项 |
| 提现管理 | 提现申请、提现记录 |
| 对账管理 | 对账单查看、导出 |
| 订单管理 | 订单列表、发货操作 |
| 仓库管理 | 药品库存、价格查看 |
| 结算管理 | 分账记录、结算操作 |

51
docs/projects/xk-doctor-wx/modules/doctor.md Normal file
View File

@@ -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[处方生效]
```

11
docs/projects/xk-doctor-wx/modules/index.md Normal file
View File

@@ -0,0 +1,11 @@
# xk-doctor-wx 功能模块
## 模块清单
| 模块 | 说明 | 页面 |
|------|------|------|
| 医生模块 | 工作台、接诊、开方、患者管理 | [医生模块](./doctor.md) |
| 药师模块 | 审方、处方追溯、IM 聊天 | [药师模块](./pharmacist.md) |
| 门店管理模块 | 门店工作台、提现、对账、结算 | [门店管理](./clinic-admin.md) |
| 平台管理模块 | 平台工作台、审核、门店管理 | [平台管理](./platform-admin.md) |
| 推广员模块 | 推广员管理、佣金、结算 | [推广员模块](./salesperson.md) |

45
docs/projects/xk-doctor-wx/modules/pharmacist.md Normal file
View File

@@ -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[患者购药]
```
## 处方状态
| 状态 | 说明 |
|------|------|
| 待审核 | 医生已开方，等待审核 |
| 通过 | 审核通过 |
| 未通过 | 审核拒绝 |
| 无需审核 | 免审处方 |

36
docs/projects/xk-doctor-wx/modules/platform-admin.md Normal file
View File

@@ -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[生效]
```

54
docs/projects/xk-doctor-wx/modules/salesperson.md Normal file
View File

@@ -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
```

69
docs/projects/xk-doctor-wx/overview.md Normal file
View File

@@ -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 | 工作台、收益、线索、佣金、邀请、结算 |

47
docs/projects/xk-hy-forward-go/architecture.md Normal file
View File

@@ -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[返回给调用方]
```

42
docs/projects/xk-hy-forward-go/design.md Normal file
View File

@@ -0,0 +1,42 @@
# xk-hy-forward-go 设计思路
## 架构决策
### 内网转发
采用内网双通道转发架构：
- 外部网络 `xk-hy-transit-go` 只能访问本服务
- 本服务负责转发至浙江省政务云
- 内外网隔离，确保政务云安全
### Go 实现
选择 Go 语言：
- 高性能、低资源消耗
- 原生支持并发
- 适合做透明代理
- 部署简单（单二进制文件）
### 透明转发
服务本身不做业务逻辑处理：
- 只做请求转发和响应返回
- 请求头白名单过滤
- IP 白名单控制
- 日志记录
### Echo 模式
支持 Echo 模式用于调试：
- 不实际转发请求
- 返回请求详情
- 方便开发和测试
## 安全考虑
| 措施 | 说明 |
|------|------|
| IP 白名单 | `ALLOW_IPS` 配置允许访问的 IP |
| 共享密钥 | `FORWARD_SHARED_SECRET` 验证调用方 |
| 请求头过滤 | 只转发白名单中的请求头 |
| 内网部署 | 部署在内网服务器，外部无法直接访问 |

49
docs/projects/xk-hy-forward-go/modules/forward.md Normal file
View File

@@ -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 模式：
- 不实际转发请求
- 返回请求的详细信息（用于调试）
- 适合开发和测试环境

30
docs/projects/xk-hy-forward-go/modules/health.md Normal file
View File

@@ -0,0 +1,30 @@
# 健康检查模块
## 接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 服务健康状态检查 |
| GET | `/t` | 政务云连通性测试页面 |
## 健康检查
- **路径**: `GET /health`
- **说明**: 服务健康状态检查
- **返回**: 200 OK
## 测试页面
- **路径**: `GET /t`
- **说明**: 政务云连通性测试页面
- **用途**: 验证服务能否正常转发至政务云
## 日志系统
### API 日志
- 记录每个请求的方法、路径、状态码、耗时
- 格式化输出，便于排查问题
### 应用日志
- 记录服务启动、配置加载、错误信息
- 输出到控制台和日志文件

32
docs/projects/xk-hy-forward-go/modules/index.md Normal file
View File

@@ -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
```

73
docs/projects/xk-hy-forward-go/overview.md Normal file
View File

@@ -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
```