ajy/code/智能穴位定位系统设计文档.md

智能穴位定位系统设计文档

一、项目概述

1.1 项目背景

艾灸椅智能穴位定位系统是艾灸椅项目的核心子系统，负责根据用户体型数据计算穴位位置，并通过APP推送给艾灸椅设备，实现精准穴位定位和艾灸理疗。

1.2 三方协作架构

┌─────────────────────────────────────────────────────────────────┐
│                        项目协作架构                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   单位A（硬件）          单位B（APP）           我们（算法+后台）│
│   ┌─────────┐           ┌─────────┐           ┌─────────┐      │
│   │ 艾灸椅  │           │  APP    │           │ 后台管理│      │
│   │ 设备    │◀─────────│ 功能    │◀──────────│ 系统    │      │
│   └─────────┘   推送    └─────────┘   推送    └─────────┘      │
│       ▲                           │               │            │
│       │    传感器数据              │    用户数据   │            │
│       │    设备状态                │    穴位坐标   │            │
│       │                           │    艾灸工艺   │            │
│       └───────────────────────────┴───────────────┘            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

1.3 我们的核心职责

职责	说明	交付物
后台管理系统	从零搭建，全新开发	管理后台
穴位坐标算法	用户体型数据 → 穴位相对偏移	算法服务
艾灸工艺生成	专家方案 → 设备可执行工艺语言	工艺数据
后台-APP接口	RESTful API供APP调用	API接口

1.4 数据流向

我们后台 → APP → 艾灸椅设备（单向推送）

推送内容：
├── 用户信息（用户档案、体型数据）
├── 艾灸模式（一键艾灸、专业模式、自定义模式、延年圣手模式）
├── 艾灸工艺（步骤、穴位相对偏移、艾灸手法）
└── 其他数据

设备存储：
├── 用户档案
├── 穴位对照表（相对偏移）
└── 艾灸方案

设备执行：
├── 传感器检测大椎穴位置
├── 计算实际穴位坐标 = 大椎穴位置 + 相对偏移
└── 控制灸头移动，进行艾灸

数据关系：
穴位管理（基础表 + 艾灸手法）
    ↓ 引用
方案管理（四种模式）
    ↓ 关联
用户管理（用户表）
    ↓ 生成
用户穴位坐标数据（穴位对照表）

---

二、用户角色定义

2.1 三大用户角色

角色	描述	核心需求	入口方式
家庭用户	个人购买艾灸椅在家使用	便捷、安全、个性化穴位定位	APP
系统管理员	平台管理，维护系统运营	用户管理、设备管理、数据监控	后台管理系统
专家	中医专家，发布专业艾灸方案	方案发布、方案管理、效果追踪	小程序/公众号（独立项目）

2.2 专家角色详细说明

专家工作流程：

专家登录（小程序/公众号）
    ↓
创建艾灸理疗方案
    ↓
输入方案描述：
- 症状/功效（如：驱寒、祛湿、活血）
- 穴位组合（如：大椎穴、风门穴、肺俞穴）
- 治疗步骤（温度、时间、顺序）
- 适用人群（性别、年龄范围）
    ↓
系统解析 → 生成工艺语言
    ↓
包含穴位相对偏移（基于标准穴位数据）
    ↓
发布方案（指定用户/公开发布）
    ↓
用户在APP中看到并选择专家方案

2.3 8种专业模式

模式	功效	适用症状
驱寒模式	温阳散寒	怕冷、手脚冰凉
祛湿模式	健脾祛湿	身体困重、大便黏腻
祛风模式	祛风解表	感冒、头痛
化瘀模式	活血化瘀	疼痛、淤青
活血模式	活血通络	血液循环不畅
化痰模式	化痰止咳	咳嗽、痰多
养颜模式	美容养颜	皮肤暗沉
扶阳模式	温补肾阳	腰膝酸软

---

三、核心功能模块

3.1 功能模块清单

艾灸取穴智能穴位识别功能
├── 1. 后台管理系统
│   ├── 用户管理
│   │   ├── 用户列表
│   │   ├── 用户档案（基本信息、体型数据）
│   │   └── 该用户的穴位坐标数据（穴位对照表）
│   │
│   ├── 穴位管理（独立表）
│   │   ├── 基础穴位信息（名称、经络、功效）
│   │   └── 艾灸手法（一键艾灸[默认]、温和灸、雀啄灸、回旋灸等）
│   │
│   ├── 方案管理（每个用户独立存储）
│   │   ├── 一键艾灸（默认艾灸工艺，系统预置）
│   │   ├── 专业模式（8种功效选择）
│   │   ├── 自定义模式（用户自选穴位）
│   │   └── 延年圣手模式（专家方案，最新8个同步至设备，设备快捷键1-8）
│   │
│   ├── 艾灸工艺生成
│   │   ├── 输入：专家方案（使用系统模板输入）
│   │   ├── 处理：解析→验证→生成工艺语言
│   │   └── 输出：系统工艺语言（设备可执行）
│   │
│   └── 系统管理
│       ├── 管理员管理
│       └── 操作日志
│
├── 2. 核心算法模块
│   ├── 指寸估算算法
│   ├── 穴位对照表生成算法
│   ├── 数据验证算法
│   ├── 置信度计算算法
│   └── 工艺语言生成算法
│
├── 3. 数据接口模块
│   ├── APP-后台RESTful API
│   ├── 推送数据格式定义
│   ├── 四种艾灸模式接口
│   └── 设备同步接口（圣手模式8方案同步）
│
└── 4. 专家端对接（独立项目，预留接口）
    ├── 专家端接口规范（对外提供）
    ├── 方案接收接口（接收专家方案数据）
    └── 方案发布接口（发布至指定用户/公开）

艾灸取穴智能穴位识别功能 ├── 1. 后台管理系统 │ ├── 用户管理 │ │ ├── 用户列表 │ │ ├── 用户档案（基本信息、体型数据） │ │ └── 该用户的穴位坐标数据（穴位对照表） │ │ │ ├── 穴位管理（独立表） │ │ ├── 基础穴位信息（名称、经络、功效） │ │ └── 艾灸手法（温和灸、雀啄灸、回旋灸等） │ │ │ ├── 方案管理 │ │ ├── 一键艾灸（默认方案） │ │ ├── 专业模式（8种功效选择） │ │ ├── 自定义模式（用户自选穴位） │ │ └── 延年圣手模式（专家方案） │ │ │ └── 系统管理 │ ├── 管理员管理 │ └── 操作日志 │ ├── 2. 核心算法模块 │ ├── 指寸估算算法 │ ├── 穴位对照表生成算法 │ ├── 数据验证算法 │ └── 置信度计算算法 │ ├── 3. 数据接口模块 │ ├── APP-后台RESTful API │ ├── 推送数据格式定义 │ └── 四种艾灸模式接口 │ └── 4. 专家端（小程序/公众号） ├── 专家登录 ├── 方案创建（使用系统模板） ├── 工艺语言生成 └── 方案发布（指定用户/公开）

3.5 专家方案模板设计

核心原则：专家必须使用系统提供的模板输入方案，确保数据标准化。

模板类型

模板类型	适用场景	说明
专业模式模板	8种功效方案	驱寒、祛湿、祛风、化瘀、活血、化痰、养颜、扶阳
自定义模板	专家自由组合	不限功效，自由选择穴位
症状推荐模板	按症状推荐	系统根据症状推荐穴位组合，专家调整

模板结构

基本信息模板：

• 方案名称（必填）
• 功效类型（必填，8选1）
• 适用症状（必填，多选）
• 适用人群（必填，不限/仅男/仅女）
• 适用年龄（必填，范围）
• 方案描述（选填，200字以内）

治疗步骤模板：

• 穴位选择（必填，从穴位库选择）
• 侧别（必填，单侧/双侧/左侧/右侧）
• 温度设置（必填，35-50°C）
• 时间设置（必填，1-30分钟）
• 艾灸手法（必填，4选1）
• 备注（选填）

8种专业模式预设

模式	必选穴位	可选穴位	默认温度	默认时间	默认手法
驱寒模式	大椎穴、命门穴	关元穴、气海穴	45-48°C	8-10分钟	温和灸
祛湿模式	大椎穴、脾俞穴(双)、肾俞穴(双)	足三里(双)、阴陵泉(双)	42-45°C	5-8分钟	温和灸
祛风模式	大椎穴、风门穴(双)、秉风穴(双)	肺俞穴(双)	40-42°C	5-6分钟	雀啄灸
化瘀模式	大椎穴、膈俞穴(双)、八髎穴	血海穴(双)	43-45°C	6-8分钟	回旋灸
活血模式	大椎穴、膈俞穴(双)、命门穴	足三里(双)	42-45°C	6-8分钟	温和灸
化痰模式	大椎穴、肺俞穴(双)、脾俞穴(双)	丰隆穴(双)	40-43°C	5-7分钟	温和灸
养颜模式	大椎穴、肺俞穴(双)、脾俞穴(双)、肾俞穴(双)	血海穴(双)	40-42°C	5-6分钟	温和灸
扶阳模式	大椎穴、命门穴、至阳穴	关元穴、气海穴	45-48°C	8-10分钟	温和灸

模板验证规则

interface TemplateValidation {
  // 基本信息验证
  name: { required: true; maxLength: 50 };
  efficacyType: { required: true; options: ['驱寒','祛湿','祛风','化瘀','活血','化痰','养颜','扶阳'] };
  symptoms: { required: true; minSelect: 1 };
  targetGender: { required: true; options: ['all','male','female'] };
  ageRange: { required: true; min: 1; max: 120 };
  
  // 步骤验证
  minSteps: 1;
  maxSteps: 10;
  temperature: { min: 35; max: 50; unit: '°C' };
  duration: { min: 1; max: 30; unit: '分钟' };
  totalDurationLimit: 60;  // 总时长限制（分钟）
}

模板使用流程

专家登录
    ↓
选择模板类型（专业模式/自定义/症状推荐）
    ↓
填写方案基本信息
    ↓
配置治疗步骤（从模板预设或穴位库选择）
    ↓
系统验证（必填项、参数范围、总时长）
    ↓
预览方案
    ↓
发布方案

---

3.6 用户模式数据存储与同步机制

核心原则：每个用户拥有独立的四种模式数据存储，设备端同步最新方案。

3.6.1 四种模式存储

模式	存储位置	说明
一键艾灸	用户级存储	默认艾灸工艺，系统预置，每个用户独立存储
专业模式	用户级存储	8种功效方案，每个用户独立存储
自定义模式	用户级存储	用户自选穴位组合，个人方案
延年圣手模式	用户级存储	专家方案，最新8个同步至设备

3.6.2 延年圣手模式同步机制

关键需求：用户接收的圣手模式方案，每次要有最新的8个方案同步到设备里，设备有快捷键1-8分别对应圣手模式的艾灸方案。

同步数据结构：

// 延年圣手模式 - 用户级存储
interface ExpertModeStorage {
  userId: string;
  schemes: ExpertScheme[];        // 用户接收的专家方案列表（可超过8个）
  syncedSchemes: SyncedScheme[];  // 同步到设备的最新8个方案
  updatedAt: Date;
}

// 同步到设备的方案（最新8个）
interface SyncedScheme {
  slot: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;  // 快捷键槽位（1-8）
  schemeId: string;
  schemeName: string;
  processId: string;             // 对应工艺语言ID
  syncedAt: Date;
}

// 设备快捷键映射
interface DeviceHotkeyMap {
  userId: string;
  deviceId: string;
  hotkeys: {
    '1': { schemeId: string; schemeName: string };  // 快捷键1
    '2': { schemeId: string; schemeName: string };  // 快捷键2
    '3': { schemeId: string; schemeName: string };  // 快捷键3
    '4': { schemeId: string; schemeName: string };  // 快捷键4
    '5': { schemeId: string; schemeName: string };  // 快捷键5
    '6': { schemeId: string; schemeName: string };  // 快捷键6
    '7': { schemeId: string; schemeName: string };  // 快捷键7
    '8': { schemeId: string; schemeName: string };  // 快捷键8
  };
  updatedAt: Date;
}

同步流程：

专家发布方案 → 用户接收方案
    ↓
系统检查用户已接收的专家方案数量
    ↓
按发布时间排序，取最新8个方案
    ↓
生成同步数据（slot 1-8对应最新8个方案）
    ↓
推送至APP → 推送至设备存储
    ↓
设备更新快捷键映射（1-8对应方案）
    ↓
用户按下快捷键1-8 → 执行对应圣手方案

---

3.7 艾灸工艺生成需求描述

功能定位：将专家描述的艾灸步骤转化为系统工艺语言，使设备可执行。

3.7.1 输入要求

输入项	来源	说明
专家方案	专家端（模板输入）	方案名称、症状、穴位组合、参数
模板类型	系统预设	专业模式/自定义/症状推荐
用户体型数据	用户档案	肩宽、身长、指寸
穴位坐标数据	穴位对照表	用户专属的穴位相对偏移

3.7.2 输出要求

输出内容：系统工艺语言（MoxaProcess），包含：

• 方案元数据（名称、症状、适用人群、总时长）
• 治疗步骤列表（穴位、温度、时间、手法、侧别）
• 设备可执行指令（移动指令、加热指令、手法指令）

输出格式：

{
  "processId": "工艺ID",
  "schemeId": "方案ID",
  "metadata": {
    "name": "方案名称",
    "symptoms": ["症状列表"],
    "totalDuration": 1560
  },
  "steps": [
    {
      "stepOrder": 1,
      "acupointId": "dazhui",
      "acupointName": "大椎穴",
      "temperature": 45,
      "duration": 480,
      "techniqueId": "oneclick",
      "techniqueName": "一键艾灸",
      "deviceInstruction": {
        "command": "HEAT",
        "target": { "acupointId": "dazhui", "offsetX": 0, "offsetY": 0 },
        "heat": { "mode": "constant", "targetTemp": 45, "duration": 480 }
      }
    }
  ]
}

3.7.3 验证规则

验证项	规则	处理
穴位有效性	穴位必须存在于穴位库	自动新增或报错
温度范围	35-50°C	超出范围拒绝
时间范围	1-30分钟/穴位	超出范围拒绝
总时长	不超过60分钟	超出警告
手法兼容	穴位支持该手法	验证通过

3.7.4 一键艾灸（默认工艺）

定义：一键艾灸是系统预置的默认艾灸工艺，每个用户独立存储。

工艺参数： | 参数 | 默认值 | 说明 | |------|--------|------| | 穴位组合 | 大椎穴、身柱穴、至阳穴、命门穴、腰阳关穴 | 督脉5穴 | | 温度 | 42-45°C | 由低到高渐进 | | 时间 | 每穴5-8分钟 | 总时长约30分钟 | | 手法 | 温和灸 | 固定不动 |

---

3.8 专家端对接接口预留

重要说明：专家端是另外一个独立项目，本次项目不做研发，只预留对接接口。

3.8.1 对接接口清单

接口	方法	路径	说明	状态
方案接收	POST	/api/expert/schemes/receive	接收专家端创建的方案	预留
方案更新	PUT	/api/expert/schemes/{schemeId}	接收专家端更新的方案	预留
方案列表	GET	/api/expert/schemes	获取已接收的专家方案	预留
模板获取	GET	/api/expert/templates	提供系统模板给专家端	预留
穴位库获取	GET	/api/expert/acupoints	提供穴位库给专家端	预留
手法库获取	GET	/api/expert/techniques	提供手法库给专家端	预留

3.8.2 对接数据格式

// 专家端方案推送格式
interface ExpertSchemePush {
  expertId: string;              // 专家ID（由专家端系统分配）
  expertName: string;            // 专家名称
  schemeName: string;            // 方案名称
  efficacyType: string;          // 功效类型
  symptoms: string[];            // 适用症状
  targetGender: 'male' | 'female' | 'all';
  ageRange: { min: number; max: number };
  steps: ExpertStep[];           // 治疗步骤
  publishType: 'public' | 'private';
  targetUserIds?: string[];      // 指定用户（私有发布时）
}

// 专家端治疗步骤
interface ExpertStep {
  stepOrder: number;
  acupointName: string;          // 穴位名称
  temperature: number;           // 温度
  duration: number;              // 时间（分钟）
  techniqueName: string;         // 手法名称
  side: 'single' | 'both' | 'left' | 'right';
}

3.8.3 对接说明

• 本项目不开发专家端应用（小程序/公众号）
• 本项目只提供上述接口规范，供专家端项目对接
• 专家端项目完成后，通过上述接口推送方案数据
• 本项目接收方案后，自动生成工艺语言并存储

---

3.2 支持的穴位（基础库12个）

序号	穴位名称	所属经络	相对大椎穴位置	功效
1	大椎穴	督脉	基准点 (0, 0)	驱寒、祛湿、解表
2	身柱穴	督脉	下3寸	止咳平喘、安神
3	至阳穴	督脉	下7寸	宽胸理气
4	命门穴	督脉	下14寸	补肾壮阳
5	腰阳关穴	督脉	下17寸	强腰健肾
6	风门穴（双）	足太阳膀胱经	下1.5寸，旁开1.5寸	祛风解表
7	秉风穴（双）	手太阳小肠经	下3寸，旁开3寸	祛风散寒
8	肺俞穴（双）	足太阳膀胱经	下3寸，旁开1.5寸	化痰止咳
9	膈俞穴（双）	足太阳膀胱经	下7寸，旁开1.5寸	活血化瘀
10	脾俞穴（双）	足太阳膀胱经	下11寸，旁开1.5寸	健脾养血
11	肾俞穴（双）	足太阳膀胱经	下14寸，旁开1.5寸	补肾益气
12	八髎穴	足太阳膀胱经	下16寸	调理下焦

3.3 艾灸手法（独立表）

手法ID	手法名称	运动模式	适用场景
gentle	温和灸	固定不动	常规艾灸，温补
pecking	雀啄灸	上下移动	强刺激，祛邪
circular	回旋灸	圆周运动	温经散寒
sparrow	麻雀灸	点状移动	局部强刺激

3.4 穴位库动态扩展机制

两种方式： | 方式 | 触发场景 | 说明 | |------|----------|------| | 预置维护 | 管理员主动录入 | 提前维护完整穴位库 | | 自动新增 | 专家发布方案时 | 方案中出现新穴位，系统自动创建 |

自动新增流程：

专家创建方案 → 输入穴位名称（如：委中穴）
    ↓
系统检查穴位库
    ├─ 已存在 → 直接引用
    └─ 不存在 → 触发自动新增流程
        ↓
        系统自动处理：
        1. 创建穴位记录（名称、经络待补全）
        2. 标记为"待完善"状态
        3. 提示专家补充穴位信息（功效、定位方式等）
        ↓
        穴位入库，方案可正常发布
        ↓
        管理员可在后台完善穴位详情

---

四、核心算法设计

4.1 指寸估算算法

当用户未提供指寸数据时，根据肩宽和身长估算：

• 男性：肩宽权重 0.6，身长权重 0.4

• 女性：肩宽权重 0.4，身长权重 0.6

  function estimateFingerWidth(
  shoulderWidth: number,
  bodyLength: number,
  gender: 'male' | 'female'
  ): FingerWidth {
  const STANDARD = {
  male: {
    shoulderWidth: 42,      // 男性平均肩宽（厘米）
    bodyLength: 85,         // 男性平均坐高（厘米）
    cun1: 2.2,              // 男性一寸约2.2cm
    cun1_5: 3.3,            // 男性1.5寸约3.3cm
    cun3: 6.5,              // 男性三寸约6.5cm
    shoulderWeight: 0.6,    // 肩宽权重
    lengthWeight: 0.4       // 身长权重
  },
  female: {
    shoulderWidth: 36,      // 女性平均肩宽（厘米）
    bodyLength: 78,         // 女性平均坐高（厘米）
    cun1: 1.9,              // 女性一寸约1.9cm
    cun1_5: 2.8,            // 女性1.5寸约2.8cm
    cun3: 5.6,              // 女性三寸约5.6cm
    shoulderWeight: 0.4,    // 肩宽权重
    lengthWeight: 0.6       // 身长权重
  }
  };
  
  const ref = STANDARD[gender];
  const widthScale = shoulderWidth / ref.shoulderWidth;
  const lengthScale = bodyLength / ref.bodyLength;
    
  const weightedScale = 
  widthScale * ref.shoulderWeight + 
  lengthScale * ref.lengthWeight;
  
  const estimatedCun1 = ref.cun1 * weightedScale;
    
  return {
  cun1: estimatedCun1,
  cun1_5: estimatedCun1 * 1.5,
  cun3: estimatedCun1 * 3
  };
  }
  

4.2 穴位对照表生成算法

function generateAcupointReferenceTable(
  bodyData: UserBodyData,
  gender: 'male' | 'female'
): AcupointReferenceTable {
  const { shoulderWidth, bodyLength, fingerWidth } = bodyData;

  // 获取或估算指寸
  const cun: FingerWidth = fingerWidth 
    ? fingerWidth 
    : estimateFingerWidth(shoulderWidth, bodyLength, gender);

  // 计算各穴位位置
  const acupoints: CalculatedAcupoint[] = ACUPOINT_OFFSETS.map(ap => {
    // Y方向偏移：指寸数 × 对应指寸值
    const distanceY = ap.cun * cun[ap.cunType];

    // X方向偏移：横向指寸 × 一寸值
    const distanceX = ap.side === 'center' 
      ? 0 
      : (ap.side === 'left' ? -1 : 1) * (ap.lateralOffset || 0) * cun.cun1;

    return {
      id: ap.id + (ap.side !== 'center' ? '_' + ap.side : ''),
      name: ap.name,
      side: ap.side,
      offsetFromDazhui: {
        x: distanceX,
        y: -distanceY  // 负值表示向下
      },
      offsetInCun: ap.cun,
      cunType: ap.cunType
    };
  });

  return {
    bodyData,
    fingerWidthUsed: cun,
    acupoints,
    createdAt: new Date()
  };
}

4.3 数据验证算法

输入验证范围： | 字段 | 男性范围 | 女性范围 | 单位 | |------|---------|---------|------| | 肩宽 | 36-52 | 32-46 | cm | | 身长（坐高） | 75-95 | 70-88 | cm | | 一寸 | 1.5-2.8 | 1.3-2.4 | cm | | 1.5寸 | 2.2-4.0 | 2.0-3.5 | cm | | 三寸 | 4.5-8.0 | 4.0-7.0 | cm |

4.4 置信度计算

数据完整度	综合置信度	预估精度
仅肩宽+身长	50%	±5cm
+ 一寸数据	65%	±4cm
+ 一寸+1.5寸	80%	±3cm
+ 完整指寸	95%	±2cm

4.5 坐标转换算法

核心问题：将穴位相对偏移（相对大椎穴）转换为艾灸椅设备坐标系。

数据流向：

用户穴位坐标数据（相对偏移，存储在后台）
    ↓
推送到APP
    ↓
推送到设备存储
    ↓
设备传感器检测大椎穴位置（设备坐标系）
    ↓
设备计算：穴位实际坐标 = 大椎穴位置 + 相对偏移
    ↓
设备执行：灸头移动到实际坐标

坐标转换公式：

/**
 * 设备坐标系定义（假设）：
 * X轴：横向（左负右正），单位mm
 * Y轴：纵向（上正下负），单位mm
 * Z轴：深度（前正后负），单位mm
 */

interface DeviceCoordinate {
  x: number;  // 横向偏移（mm）
  y: number;  // 纵向偏移（mm）
  z: number;  // 深度偏移（mm）
}

interface AcupointOffset {
  x: number;  // 相对大椎穴横向偏移（cm）
  y: number;  // 相对大椎穴纵向偏移（cm）
}

/**
 * 将穴位相对偏移转换为设备坐标
 * 注意：此算法在设备端执行
 * 
 * @param dazhuiPosition 设备传感器检测的大椎穴位置（设备坐标系，mm）
 * @param acupointOffset 穴位相对偏移（相对大椎穴，cm）
 * @param userBodyData 用户体型数据（用于精度修正）
 * @returns 穴位在设备坐标系中的位置（mm）
 */
function convertToDeviceCoordinate(
  dazhuiPosition: DeviceCoordinate,
  acupointOffset: AcupointOffset,
  userBodyData: UserBodyData
): DeviceCoordinate {
  // 将厘米转换为毫米
  const offsetXmm = acupointOffset.x * 10;
  const offsetYmm = acupointOffset.y * 10;
  
  // 坐标转换
  // 注意：人体坐标系Y轴向下为负，设备坐标系Y轴向下为正
  return {
    x: dazhuiPosition.x + offsetXmm,
    y: dazhuiPosition.y - offsetYmm,  // 转换方向
    z: dazhuiPosition.z  // 深度通常不变
  };
}

/**
 * 批量转换所有穴位坐标
 * 
 * @param dazhuiPosition 设备传感器检测的大椎穴位置
 * @param acupointTable 用户穴位对照表（相对偏移）
 * @returns 所有穴位在设备坐标系中的位置
 */
function convertAllAcupoints(
  dazhuiPosition: DeviceCoordinate,
  acupointTable: AcupointReferenceTable
): Map<string, DeviceCoordinate> {
  const positions = new Map<string, DeviceCoordinate>();
  
  for (const acupoint of acupointTable.acupoints) {
    const deviceCoord = convertToDeviceCoordinate(
      dazhuiPosition,
      acupoint.offsetFromDazhui,
      acupointTable.bodyData
    );
    positions.set(acupoint.id, deviceCoord);
  }
  
  return positions;
}

坐标转换示例：

假设：
- 大椎穴检测位置：{ x: 0, y: 150mm, z: 50mm }
- 身柱穴相对偏移：{ x: 0cm, y: -6.3cm }

转换：
- X坐标：0 + 0*10 = 0mm
- Y坐标：150 - (-6.3)*10 = 150 + 63 = 213mm
- Z坐标：50mm

结果：身柱穴设备坐标 = { x: 0, y: 213mm, z: 50mm }

推送给设备的数据格式：

{
  "userId": "user_001",
  "dazhuiPosition": {
    "x": 0,
    "y": 150,
    "z": 50
  },
  "acupointTable": [
    {
      "id": "dazhui",
      "name": "大椎穴",
      "offsetX": 0,
      "offsetY": 0
    },
    {
      "id": "shenzhu",
      "name": "身柱穴",
      "offsetX": 0,
      "offsetY": -63
    },
    {
      "id": "fengmen_left",
      "name": "风门穴",
      "offsetX": -31.5,
      "offsetY": -48
    }
  ]
}

---

五、数据模型设计

5.1 用户档案

interface UserProfile {
  id: string;
  name: string;
  gender: 'male' | 'female';
  age: number;
  phone: string;
  bodyData: {
    shoulderWidth: number;     // 肩宽（厘米）
    bodyLength: number;        // 身长（厘米）
    fingerWidth?: {
      cun1: number;            // 一寸
      cun1_5: number;          // 1.5寸
      cun3: number;            // 三寸
    };
  };
  fingerprints: string[];      // 指纹ID列表
  devices: DeviceBinding[];    // 关联的设备列表（多对多）
  createdAt: Date;
  updatedAt: Date;
}

// 用户-设备绑定关系
interface DeviceBinding {
  deviceId: string;            // 设备编号（主键）
  deviceName: string;          // 设备名称
  boundAt: Date;               // 绑定时间
  isPrimary: boolean;          // 是否为主设备
}

// 设备信息
interface Device {
  deviceId: string;            // 设备编号（主键，如：AJY001）
  deviceName: string;          // 设备名称
  model: string;               // 设备型号
  serialNumber: string;        // 设备序列号（唯一标识）
  firmwareVersion: string;     // 固件版本
  status: 'online' | 'offline'; // 在线状态
  users: UserBinding[];        // 关联的用户列表（多对多）
  lastOnlineAt: Date;          // 最后在线时间
  createdAt: Date;
  updatedAt: Date;
}

// 设备-用户绑定关系
interface UserBinding {
  userId: string;              // 用户ID
  userName: string;            // 用户姓名
  boundAt: Date;               // 绑定时间
  isPrimary: boolean;          // 是否为主用户
}

5.2 穴位数据（独立表）

// 穴位基础信息
interface Acupoint {
  id: string;
  name: string;
  meridian: string;            // 所属经络
  efficacy: string[];          // 功效列表
  positioning: 'relative' | 'absolute';  // 定位方式
  offset?: {                   // 相对定位偏移
    cun: number;
    cunType: 'cun1' | 'cun1_5' | 'cun3';
    side: 'center' | 'left' | 'right';
    lateralOffset?: number;
  };
  absolutePosition?: {         // 绝对定位坐标
    x: number;
    y: number;
    z: number;
  };
  status: 'active' | 'pending';  // 状态
  source: 'preset' | 'expert';   // 数据来源
  createdAt: Date;
  updatedAt: Date;
}

// 艾灸手法
interface MoxaTechnique {
  id: string;
  name: string;                // 手法名称（一键艾灸[默认]、温和灸、雀啄灸、回旋灸）
  isDefault: boolean;          // 是否为默认手法（一键艾灸为默认）
  description: string;         // 手法描述
  parameters: {
    temperatureRange: { min: number; max: number };  // 温度范围
    durationRange: { min: number; max: number };     // 时间范围（秒）
    movementPattern: 'fixed' | 'vertical' | 'circular' | 'oneclick';  // 运动模式
  };
  createdAt: Date;
  updatedAt: Date;
}

5.3 穴位对照表（相对偏移）

interface AcupointReferenceTable {
  userId: string;
  bodyData: UserBodyData;
  fingerWidthUsed: FingerWidth;
  acupoints: CalculatedAcupoint[];
  createdAt: Date;
}

interface CalculatedAcupoint {
  id: string;
  name: string;
  side: 'center' | 'left' | 'right';
  offsetFromDazhui: {
    x: number;          // 相对大椎穴的横向偏移（厘米）
    y: number;          // 相对大椎穴的纵向偏移（厘米）
  };
  offsetInCun: number;
  cunType: 'cun1' | 'cun1_5' | 'cun3';
}

5.4 方案管理（四种模式）

// 方案模式枚举
enum SchemeMode {
  ONE_CLICK = '一键艾灸',
  PROFESSIONAL = '专业模式',
  CUSTOM = '自定义模式',
  EXPERT = '延年圣手模式'
}

// 用户模式存储（每个用户独立存储四种模式数据）
interface UserModeStorage {
  userId: string;
  oneClickMode: OneClickScheme;          // 一键艾灸（默认工艺）
  professionalMode: ProfessionalScheme[]; // 专业模式（8种功效）
  customMode: CustomScheme[];            // 自定义模式
  expertMode: ExpertModeStorage;         // 延年圣手模式（含8个同步方案）
  updatedAt: Date;
}

// 方案基础结构
interface Scheme {
  id: string;
  schemeName: string;
  mode: SchemeMode;
  creatorType: 'admin' | 'user' | 'expert';  // 创作人类型
  creatorId: string;          // 创作人ID（ADMIN/用户ID/专家ID）
  creatorName: string;        // 创作人显示名称（ADMIN/用户姓名/专家姓名）
  symptoms: string[];          // 适用症状
  targetGender: 'male' | 'female' | 'all';
  ageRange: { min: number; max: number };
  steps: SchemeStep[];
  status: 'draft' | 'published' | 'archived';
  createdAt: Date;
  updatedAt: Date;
}

// 一键艾灸方案（默认艾灸工艺）
interface OneClickScheme extends Scheme {
  mode: SchemeMode.ONE_CLICK;
  isDefault: true;             // 始终为true，是默认工艺
  processId: string;           // 关联的工艺语言ID
}

// 专业模式方案
interface ProfessionalScheme extends Scheme {
  mode: SchemeMode.PROFESSIONAL;
  efficacyType: '驱寒' | '祛湿' | '祛风' | '化瘀' | '活血' | '化痰' | '养颜' | '扶阳';
}

// 自定义模式方案
interface CustomScheme extends Scheme {
  mode: SchemeMode.CUSTOM;
  userId: string;              // 用户ID
  isPersonal: boolean;         // 是否个人方案
}

// 延年圣手模式方案（专家）
interface ExpertScheme extends Scheme {
  mode: SchemeMode.EXPERT;
  expertId: string;            // 专家ID（来自专家端系统）
  expertName: string;          // 专家名称
  publishType: 'public' | 'private';  // 公开/指定
  targetUsers?: string[];      // 指定用户ID列表
}

// 延年圣手模式存储（含8个同步方案到设备）
interface ExpertModeStorage {
  userId: string;
  schemes: ExpertScheme[];                // 用户接收的所有专家方案
  syncedSchemes: SyncedScheme[];          // 同步到设备的最新8个方案
  updatedAt: Date;
}

// 同步到设备的方案（最新8个，对应设备快捷键1-8）
interface SyncedScheme {
  slot: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;  // 快捷键槽位（1-8）
  schemeId: string;                        // 方案ID
  schemeName: string;                      // 方案名称
  processId: string;                       // 关联工艺语言ID
  syncedAt: Date;                          // 同步时间
}

// 设备快捷键映射（推送到设备的数据结构）
interface DeviceHotkeyMap {
  userId: string;
  deviceId: string;
  hotkeys: {
    '1': { schemeId: string; schemeName: string; processId: string };
    '2': { schemeId: string; schemeName: string; processId: string };
    '3': { schemeId: string; schemeName: string; processId: string };
    '4': { schemeId: string; schemeName: string; processId: string };
    '5': { schemeId: string; schemeName: string; processId: string };
    '6': { schemeId: string; schemeName: string; processId: string };
    '7': { schemeId: string; schemeName: string; processId: string };
    '8': { schemeId: string; schemeName: string; processId: string };
  };
  updatedAt: Date;
}

// 方案步骤
interface SchemeStep {
  stepOrder: number;
  acupointId: string;
  acupointName: string;
  sides?: ('left' | 'right')[];  // 双侧穴位
  temperature: number;
  duration: number;            // 秒
  techniqueId: string;         // 艾灸手法ID（含 oneclick）
  techniqueName: string;       // 手法名称（一键艾灸、温和灸、雀啄灸、回旋灸）
}

---

六、API接口设计

6.1 用户管理接口

接口	方法	路径	说明
用户登录	POST	/api/auth/login	手机号+验证码
获取用户列表	GET	/api/users	返回用户列表
获取用户详情	GET	/api/users/{userId}	返回用户信息和体型数据
更新用户档案	PUT	/api/users/{userId}	更新体型数据
获取用户穴位坐标	GET	/api/users/{userId}/acupoint-coordinates	返回该用户的穴位坐标数据
生成穴位坐标	POST	/api/users/{userId}/acupoint-coordinates	根据体型数据生成穴位坐标

6.2 方案管理接口（四种模式）

接口	方法	路径	说明
获取方案列表	GET	/api/schemes	获取所有方案（支持按模式筛选）
获取方案详情	GET	/api/schemes/{schemeId}	返回方案步骤和工艺
创建方案	POST	/api/schemes	创建方案（需指定模式）
更新方案	PUT	/api/schemes/{schemeId}	编辑方案
发布方案	POST	/api/schemes/{schemeId}/publish	发布方案
选择方案	POST	/api/users/{userId}/schemes/{schemeId}	用户选择方案
获取一键艾灸	GET	/api/schemes/one-click	获取一键艾灸默认方案
获取专业模式	GET	/api/schemes/professional	获取专业模式方案列表
获取自定义模式	GET	/api/users/{userId}/custom-schemes	获取用户自定义方案
获取专家方案	GET	/api/schemes/expert	获取专家方案列表
获取用户模式存储	GET	/api/users/{userId}/mode-storage	获取用户四种模式完整数据
同步圣手方案到设备	POST	/api/users/{userId}/devices/{deviceId}/expert-sync	同步最新8个圣手方案到设备（快捷键1-8）

6.3 设备同步接口（延年圣手模式）

接口	方法	路径	说明
获取快捷键映射	GET	/api/users/{userId}/devices/{deviceId}/hotkeys	获取设备快捷键1-8映射
更新快捷键映射	PUT	/api/users/{userId}/devices/{deviceId}/hotkeys	更新设备快捷键映射
触发快捷键方案	POST	/api/users/{userId}/devices/{deviceId}/hotkeys/{slot}/trigger	触发快捷键1-8对应方案

6.4 专家端对接接口（预留）

说明：专家端是独立项目，本次不研发，只预留对接接口。

接口	方法	路径	说明	状态
方案接收	POST	/api/expert/schemes/receive	接收专家端创建的方案	预留
方案更新	PUT	/api/expert/schemes/{schemeId}	接收专家端更新的方案	预留
方案列表	GET	/api/expert/schemes	获取已接收的专家方案	预留
模板获取	GET	/api/expert/templates	提供系统模板给专家端	预留
穴位库获取	GET	/api/expert/acupoints	提供穴位库给专家端	预留
手法库获取	GET	/api/expert/techniques	提供手法库给专家端	预留

6.5 推送给设备的数据格式

6.3 穴位管理接口（独立表）

接口	方法	路径	说明
获取穴位列表	GET	/api/acupoints	返回穴位库（基础穴位信息）
获取穴位详情	GET	/api/acupoints/{acupointId}	返回穴位详情
新增穴位	POST	/api/acupoints	新增穴位
更新穴位	PUT	/api/acupoints/{acupointId}	更新穴位信息
获取艾灸手法	GET	/api/moxa-techniques	返回艾灸手法列表
获取手法详情	GET	/api/moxa-techniques/{techniqueId}	返回手法详情

6.4 推送给设备的数据格式

{
  "userId": "user_001",
  "userName": "张三",
  "bodyData": {
    "shoulderWidth": 42,
    "bodyLength": 85,
    "fingerWidth": {
      "cun1": 2.1,
      "cun1_5": 3.2,
      "cun3": 6.3
    }
  },
  "mode": "专业模式",
  "scheme": {
    "schemeId": "expert_001",
    "schemeName": "春季祛湿方案",
    "steps": [
      {
        "stepOrder": 1,
        "acupointId": "dazhui",
        "acupointName": "大椎穴",
        "offsetX": 0,
        "offsetY": 0,
        "temperature": 45,
        "duration": 480,
        "techniqueId": "gentle",
        "techniqueName": "温和灸"
      },
      {
        "stepOrder": 2,
        "acupointId": "fengmen_left",
        "acupointName": "风门穴",
        "offsetX": -31.5,
        "offsetY": -48,
        "temperature": 42,
        "duration": 360,
        "techniqueId": "pecking",
        "techniqueName": "雀啄灸"
      }
    ]
  }
}

---

七、后台管理系统详细需求

7.1 用户管理

功能说明

管理员通过用户管理系统，对艾灸椅APP注册用户进行统一管理。支持查看用户基本信息、体型数据、穴位坐标数据（穴位对照表）、关联设备信息，支持用户档案的新增、编辑、删除操作，以及数据的导入导出功能。支持一个用户绑定多个设备。

使用角色：系统管理员

使用场景：

• 管理员审核新注册用户，确认体型数据有效性
• 管理员查看/修改用户体型数据，重新生成穴位坐标
• 管理员查看/管理用户绑定的设备列表
• 管理员导出用户数据用于统计分析
• 管理员批量导入用户信息（门店场景）

---

用户列表

多选框	序号	用户ID	姓名	性别	年龄	手机号	设备编号	肩宽(cm)	身长(cm)	穴位表状态	注册时间	操作
☐	1	U001	张三	男	35	138****1234	AJY001,AJY002	42	85	已生成	2026-03-15	查看/编辑/删除
☐	2	U002	李四	女	33	139****5678	AJY001	36	78	已生成	2026-03-18	查看/编辑/删除
☐	3	U003	王五	男	62	137****9012	-	40	82	未生成	2026-03-20	查看/编辑/删除

列表查询条件

查询字段	类型	说明
姓名/手机号	文本输入	支持模糊搜索
设备编号	文本输入	支持模糊搜索，可查该设备关联的所有用户
性别	下拉选择	全部 / 男 / 女
注册时间范围	日期区间	开始日期 ~ 结束日期
穴位表状态	下拉选择	全部 / 已生成 / 未生成

查询规则：

• 支持多条件组合查询
• 点击【查询】按钮：根据输入条件筛选列表
• 点击【重置】按钮：清空所有查询条件，恢复默认列表

列表操作按钮

按钮	功能说明
导入	批量导入用户数据（提供Excel模板下载）
导出	导出当前筛选结果为Excel文件
新增	进入新增用户界面
批量删除	选中多条记录后批量删除（需二次确认）
设备管理	管理用户绑定的设备列表（支持多设备绑定）

新增/编辑操作

新增界面表单字段：

字段名	类型	必填	验证规则	说明
姓名	文本	是	最长50字符	用户真实姓名
性别	单选	是	男 / 女	-
年龄	数字	是	1-120	-
手机号	文本	是	11位手机号格式，唯一值	-
肩宽	数字	是	男性36-52cm / 女性32-46cm	单位：厘米
身长	数字	是	男性75-95cm / 女性70-88cm	单位：厘米（坐高）
一寸	数字	否	男性1.5-2.8cm / 女性1.3-2.4cm	选填，提高精度
1.5寸	数字	否	男性2.2-4.0cm / 女性2.0-3.5cm	选填
三寸	数字	否	男性4.5-8.0cm / 女性4.0-7.0cm	选填

操作按钮： | 按钮 | 功能说明 | |------|----------| | 保存 | 保存用户档案 | | 取消 | 放弃编辑，返回列表 | | 生成穴位坐标 | 根据体型数据计算穴位对照表并保存 |

---

用户设备管理（独立页面）

功能说明：管理单个用户绑定的设备列表，支持添加设备、移除设备、设置主设备。

设备列表：

多选框	序号	设备编号	设备名称	设备型号	绑定时间	是否主设备	在线状态	操作
☐	1	AJY001	艾灸椅-001	AJY-2026	2026-03-15	是	在线	设为主设备/解绑
☐	2	AJY002	艾灸椅-002	AJY-2026	2026-03-18	否	离线	设为主设备/解绑

操作按钮： | 按钮 | 功能说明 | |------|----------| | 添加设备 | 从设备列表选择设备绑定到该用户 | | 批量解绑 | 选中多条记录后批量解除绑定（需二次确认） | | 返回 | 返回用户列表 |

---

7.2 穴位管理

功能说明

管理员维护系统穴位库，包括基础穴位信息（穴位名称、经络、功效、定位参数）和艾灸手法（一键艾灸、温和灸、雀啄灸、回旋灸等）。支持新增穴位、编辑穴位信息、设置穴位定位参数。专家方案中出现的新穴位会自动添加（状态：待完善），管理员需补充完善穴位信息后方可正式启用。

使用角色：系统管理员

使用场景：

• 管理员维护基础穴位库（12个常用穴位）
• 管理员审核自动新增的穴位（待完善状态），补充经络、功效、定位参数
• 管理员配置艾灸手法参数（温度范围、运动模式）
• 管理员扩展新增穴位以支持更多治疗方案

---

穴位列表

多选框	序号	穴位ID	穴位名称	所属经络	功效	定位方式	状态	操作
☐	1	dazhui	大椎穴	督脉	驱寒、祛湿	相对定位	活跃	查看/编辑/删除
☐	2	fengmen	风门穴	足太阳膀胱经	祛风解表	相对定位	活跃	查看/编辑/删除
☐	3	weizhong	委中穴	-	待完善	待完善	待完善	完善/编辑/删除

列表查询条件

查询字段	类型	说明
穴位名称	文本输入	支持模糊搜索
所属经络	下拉选择	全部 / 督脉 / 足太阳膀胱经 / 手太阳小肠经 / 其他
定位方式	下拉选择	全部 / 相对定位 / 绝对定位
状态	下拉选择	全部 / 活跃 / 待完善

查询规则：

• 点击【查询】按钮：根据输入条件筛选列表
• 点击【重置】按钮：清空所有查询条件

列表操作按钮

按钮	功能说明
导入	批量导入穴位数据（提供Excel模板下载）
导出	导出穴位库数据为Excel文件
新增	进入新增穴位界面
批量删除	选中多条记录后批量删除（需二次确认）

新增/编辑操作

新增穴位表单字段：

字段名	类型	必填	验证规则	说明
穴位名称	文本	是	最长50字符	如：合谷穴
所属经络	下拉选择	是	从经络库选择	督脉/膀胱经/小肠经/胃经/其他
功效描述	多选标签	是	至少选1项	驱寒/祛湿/祛风/化瘀/活血/化痰/养颜/扶阳
定位方式	单选	是	相对定位 / 绝对定位	-
相对大椎穴纵向偏移	数字	定位方式为相对时必填	-	单位：寸（一寸类型）
相对大椎穴横向偏移	数字	否	-	单位：寸（一寸类型），双侧穴位必填
侧别	单选	是	中心 / 左侧 / 右侧 / 双侧	-
指寸类型	下拉选择	定位方式为相对时必填	一寸 / 1.5寸 / 三寸	-
绝对坐标X	数字	定位方式为绝对时必填	-	单位：mm
绝对坐标Y	数字	定位方式为绝对时必填	-	单位：mm
绝对坐标Z	数字	定位方式为绝对时必填	-	单位：mm
适用性别	单选	是	不限 / 仅男 / 仅女	-

操作按钮： | 按钮 | 功能说明 | |------|----------| | 保存 | 保存穴位信息 | | 取消 | 放弃编辑，返回列表 |

---

艾灸手法列表

多选框	序号	手法ID	手法名称	运动模式	温度范围	时间范围	状态	操作
☐	1	oneclick	一键艾灸	默认工艺	42-45°C	30分钟	启用	编辑/禁用
☐	2	gentle	温和灸	固定不动	35-50°C	1-30分钟	启用	编辑/禁用
☐	3	pecking	雀啄灸	上下移动	35-50°C	1-30分钟	启用	编辑/禁用
☐	4	circular	回旋灸	圆周运动	35-50°C	1-30分钟	启用	编辑/禁用
☐	5	sparrow	麻雀灸	点状移动	35-50°C	1-30分钟	启用	编辑/禁用

新增/编辑艾灸手法表单

字段名	类型	必填	验证规则	说明
手法名称	文本	是	最长50字符	-
运动模式	下拉选择	是	固定不动 / 上下移动 / 圆周运动 / 点状移动	-
温度范围最小值	数字	是	35-50°C	-
温度范围最大值	数字	是	≥最小值，35-50°C	-
时间范围最小值	数字	是	1-30分钟	-
时间范围最大值	数字	是	≥最小值，1-30分钟	-
运动幅度	数字	否	1-20mm	运动模式非"固定不动"时必填
运动速度	数字	否	1-10mm/s	运动模式非"固定不动"时必填
状态	单选	是	启用 / 禁用	-
备注	文本域	否	最长200字符	-

操作按钮： | 按钮 | 功能说明 | |------|----------| | 保存 | 保存手法配置 | | 取消 | 放弃编辑，返回列表 |

---

7.3 方案管理

功能说明

管理员管理艾灸方案，包括一键艾灸（默认工艺）、专业模式（8种功效）、自定义模式（用户自选）、延年圣手模式（专家方案）。支持方案的新增、编辑、发布、下架操作，以及查看方案的使用统计。延年圣手模式方案将同步至用户设备，对应设备快捷键1-8。

使用角色：系统管理员

使用场景：

• 管理员维护一键艾灸默认方案的穴位组合和参数
• 管理员审核专家提交的延年圣手方案
• 管理员发布/下架方案
• 管理员查看方案使用统计

---

方案列表

多选框	序号	方案ID	方案名称	模式类型	功效类型	创作人	步骤数	状态	创建时间	操作
☐	1	S001	一键艾灸（默认）	一键艾灸	-	ADMIN	5	已发布	2026-01-01	查看/编辑
☐	2	S002	春季祛湿方案	专业模式	祛湿	ADMIN	4	已发布	2026-03-20	查看/编辑/下架
☐	3	S003	个人调理方案	自定义模式	-	张三	3	草稿	2026-03-25	查看/编辑/删除
☐	4	S004	张专家驱寒方案	延年圣手	驱寒	张专家	5	已发布	2026-03-28	查看/下架

创作人显示规则： | 方案模式 | 创作人显示 | |----------|-----------| | 一键艾灸 | ADMIN（系统默认） | | 专业模式 | ADMIN（系统预设）或管理员账号名 | | 自定义模式 | 创建该方案的用户姓名 | | 延年圣手模式 | 方案所属专家姓名 |

列表查询条件

查询字段	类型	说明
方案名称	文本输入	支持模糊搜索
模式类型	下拉选择	全部 / 一键艾灸 / 专业模式 / 自定义模式 / 延年圣手
功效类型	下拉选择	全部 / 驱寒 / 祛湿 / 祛风 / 化瘀 / 活血 / 化痰 / 养颜 / 扶阳
创作人	文本输入	支持模糊搜索，可搜索ADMIN或用户/专家姓名
状态	下拉选择	全部 / 已发布 / 草稿 / 已下架
创建时间范围	日期区间	开始日期 ~ 结束日期

查询规则：

• 点击【查询】按钮：根据输入条件筛选列表
• 点击【重置】按钮：清空所有查询条件

列表操作按钮

按钮	功能说明
导入	批量导入方案数据（提供JSON模板下载）
导出	导出方案数据为JSON文件
新增	进入新增方案界面（先选择模板类型）
批量删除	选中多条草稿记录后批量删除（需二次确认）
批量发布	选中多条草稿记录后批量发布
批量下架	选中多条已发布记录后批量下架

新增/编辑操作

步骤1：选择模板类型 | 模板类型 | 说明 | |----------|------| | 一键艾灸 | 系统默认工艺，预设督脉5穴，可编辑参数 | | 专业模式 | 选择功效类型，系统预设对应穴位组合，可调整 | | 自定义模式 | 自由选择穴位组合，自定义参数 | | 延年圣手 | 专家方案模板，可设置发布范围 |

步骤2：填写方案基本信息

字段名	类型	必填	验证规则	说明
方案名称	文本	是	最长100字符	-
功效类型	下拉选择	是	专业模式时必选	驱寒/祛湿/祛风/化瘀/活血/化痰/养颜/扶阳
适用症状	多选标签	是	至少选1项	怕冷/感冒/咳嗽/痰多/疼痛/腰酸/失眠/疲劳/皮肤暗沉/手脚冰凉/其他
适用人群	单选	是	不限 / 仅男 / 仅女	-
适用年龄范围	数字区间	是	最小1岁，最大120岁	-
方案描述	文本域	否	最长200字符	专家可填写方案原理、注意事项等

步骤3：配置治疗步骤

步骤	字段名	类型	必填	说明
-	步骤序号	数字	是	自动生成，可拖拽排序
1	穴位选择	下拉搜索	是	从穴位库选择
2	侧别	单选	是	单侧 / 双侧 / 左侧 / 右侧
3	温度	数字	是	35-50°C
4	时间	数字	是	1-30分钟
5	艾灸手法	下拉选择	是	一键艾灸/温和灸/雀啄灸/回旋灸/麻雀灸
6	备注	文本	否	最长100字符

操作按钮： | 按钮 | 功能说明 | |------|----------| | + 添加步骤 | 新增一个治疗步骤 | | - 删除步骤 | 删除当前步骤（至少保留1个） | | 预览方案 | 查看方案完整步骤和预计总时长 | | 保存为草稿 | 保存但不发布 | | 发布方案 | 发布后用户可见 | | 取消 | 放弃编辑，返回列表 |

---

方案详情查看（独立页面）

功能说明：查看方案的详细信息，包括基本信息、治疗步骤列表、预计总时长、使用统计等。支持从方案列表点击"查看"按钮进入。

页面布局：

第一部分：方案基本信息

字段	显示内容
方案ID	S001
方案名称	一键艾灸（默认）
模式类型	一键艾灸
功效类型	-
创作人	ADMIN
状态	已发布
创建时间	2026-01-01 10:00:00
更新时间	2026-03-15 14:30:00
适用症状	-
适用人群	不限
适用年龄	1-120岁
方案描述	系统默认一键艾灸方案，针对督脉5穴进行温和艾灸...

第二部分：治疗步骤列表

步骤序号	穴位名称	侧别	温度	时间	艾灸手法	备注
1	大椎穴	中心	42°C	5分钟	温和灸	基准穴位
2	身柱穴	中心	43°C	5分钟	温和灸	-
3	至阳穴	中心	44°C	6分钟	温和灸	-
4	命门穴	中心	44°C	7分钟	温和灸	-
5	腰阳关穴	中心	45°C	7分钟	温和灸	-

第三部分：方案统计

统计项	数值
总时长	30分钟
使用人数	156人
平均评分	4.8分
最后使用时间	2026-04-01 09:30:00

第四部分：使用记录（最近10条）

序号	用户	设备	使用时间	时长	评分
1	张三	AJY001	2026-04-01 09:00:00	30分钟	5分
2	李四	AJY002	2026-03-31 20:00:00	30分钟	4分

操作按钮： | 按钮 | 功能说明 | |------|----------| | 编辑 | 进入编辑界面（草稿状态可用） | | 发布/下架 | 切换方案状态 | | 导出 | 导出方案数据为JSON文件 | | 返回 | 返回方案列表 |

---

7.4 设备管理

功能说明

管理员管理艾灸椅设备信息，包括设备绑定用户（支持多用户绑定）、设备状态监控、设备固件版本管理。支持设备的新增、编辑、删除，以及查看设备与用户的多对多绑定关系。一个设备可以被多个用户绑定使用，一个用户也可以绑定多个设备。

使用角色：系统管理员

使用场景：

• 管理员绑定设备与用户关系（支持一个设备绑定多个用户）
• 管理员查看设备在线状态
• 管理员管理设备固件版本
• 管理员查看设备关联的用户列表

---

设备列表

多选框	序号	设备编号	设备名称	设备型号	绑定用户数	绑定用户列表	在线状态	固件版本	最后在线时间	操作
☐	1	AJY001	艾灸椅-001	AJY-2026	2	张三、李四	在线	v1.2.0	2026-04-01	查看/编辑/用户管理
☐	2	AJY002	艾灸椅-002	AJY-2026	1	王五	离线	v1.1.0	2026-03-30	查看/编辑/用户管理

列表查询条件

查询字段	类型	说明
设备编号	文本输入	支持模糊搜索，设备编号为主键
设备名称	文本输入	支持模糊搜索
绑定用户	文本输入	支持模糊搜索，可查询该设备关联的所有用户
在线状态	下拉选择	全部 / 在线 / 离线
固件版本	下拉选择	全部 / v1.2.0 / v1.1.0

查询规则：

• 点击【查询】按钮：根据输入条件筛选列表
• 点击【重置】按钮：清空所有查询条件

列表操作按钮

按钮	功能说明
导入	批量导入设备信息
导出	导出设备列表为Excel文件
新增	进入新增设备界面
批量删除	选中多条记录后批量删除（需二次确认）
用户管理	管理设备绑定的用户列表（支持多用户绑定）

新增/编辑操作

新增设备表单字段：

字段名	类型	必填	验证规则	说明
设备编号	文本	是	唯一值，如AJY001	设备编号为主键，不可修改
设备名称	文本	是	最长100字符	如：艾灸椅-001
设备型号	下拉选择	是	AJY-2026 / AJY-2025	-
设备序列号	文本	是	唯一值，最长50字符	设备唯一标识
绑定用户	多选下拉	否	从用户列表选择，可多选	支持一个设备绑定多个用户
固件版本	文本	是	如：v1.2.0	-
备注	文本域	否	最长200字符	-

操作按钮： | 按钮 | 功能说明 | |------|----------| | 保存 | 保存设备信息 | | 取消 | 放弃编辑，返回列表 | | 用户管理 | 管理该设备绑定的用户列表（添加/移除用户） |

---

设备用户管理（独立页面）

功能说明：管理单个设备绑定的用户列表，支持添加用户、移除用户、设置主用户。

用户列表：

多选框	序号	用户ID	用户姓名	手机号	绑定时间	是否主用户	操作
☐	1	U001	张三	138****1234	2026-03-15	是	设为主用户/解绑
☐	2	U002	李四	139****5678	2026-03-18	否	设为主用户/解绑

操作按钮： | 按钮 | 功能说明 | |------|----------| | 添加用户 | 从用户列表选择用户绑定到该设备 | | 批量解绑 | 选中多条记录后批量解除绑定（需二次确认） | | 返回 | 返回设备列表 |

---

7.5 系统管理

7.5.1 管理员管理

功能说明：管理后台系统管理员账号，包括新增管理员、分配权限、禁用/启用账号。

管理员列表：

多选框	序号	管理员ID	用户名	姓名	角色	状态	最后登录时间	操作
☐	1	A001	admin	张管理员	超级管理员	启用	2026-04-01	编辑/禁用
☐	2	A002	operator	李操作员	运营人员	启用	2026-03-31	编辑/禁用

查询条件：用户名/姓名（模糊搜索）、角色（下拉）、状态（下拉）

操作按钮：新增、批量删除

新增表单字段：

字段名	类型	必填	验证规则	说明
用户名	文本	是	4-20字符，唯一值	登录账号
密码	密码	是	8-20字符，含字母和数字	-
姓名	文本	是	最长50字符	-
角色	下拉选择	是	超级管理员 / 运营人员 / 只读用户	-
状态	单选	是	启用 / 禁用	-

---

7.5.2 操作日志

功能说明：记录所有管理员的操作日志，支持查询和导出，用于审计和问题追溯。

日志列表：

序号	操作人	操作类型	操作模块	操作内容	IP地址	操作时间
1	张管理员	新增	用户管理	新增用户：张三	192.168.1.100	2026-04-01 10:30:00
2	李操作员	编辑	方案管理	发布方案：春季祛湿方案	192.168.1.101	2026-04-01 09:15:00

查询条件： | 查询字段 | 类型 | 说明 | |----------|------|------| | 操作人 | 下拉选择 | 全部 / 各管理员 | | 操作类型 | 下拉选择 | 全部 / 新增 / 编辑 / 删除 / 导入 / 导出 | | 操作模块 | 下拉选择 | 全部 / 用户管理 / 穴位管理 / 方案管理 / 设备管理 | | 操作时间范围 | 日期区间 | 开始日期 ~ 结束日期 |

操作按钮：导出（导出日志为Excel文件）

---

八、验收标准

8.1 功能验收

功能	验收标准	优先级
穴位定位精度	≤ 2cm（指寸数据完整时）	🔴 高
穴位库扩展	支持动态新增穴位	🔴 高
专家方案	支持创建、发布8种专业模式	🔴 高
工艺生成	系统自动生成工艺语言	🔴 高
数据接口	API响应时间 < 200ms	🔴 高
经络图	支持点击、缩放交互	🟡 中
症状推荐	覆盖率 80%+	🟡 中

8.2 数据验证

验证项	验证规则
肩宽	男性 36-52cm，女性 32-46cm
身长	男性 75-95cm，女性 70-88cm
一寸	男性 1.5-2.8cm，女性 1.3-2.4cm
1.5寸	男性 2.2-4.0cm，女性 2.0-3.5cm
三寸	男性 4.5-8.0cm，女性 4.0-7.0cm

---

九、技术选型

层级	技术	理由
后端框架	Spring Boot 2.x	与现有后端项目一致
数据库	MySQL 8 + MyBatis-Plus	与现有数据库一致
API风格	RESTful	标准化、易维护
前端管理	Vue.js + Element UI	快速开发管理后台
专家端	微信小程序	用户基数大、易推广

---

十、实施阶段

Phase 1: 基础功能（2周）

• 用户管理模块
• 穴位管理模块
• 核心算法实现
• 数据验证算法

Phase 2: 方案管理（2周）

• 专家方案模块
• 工艺语言生成
• 8种专业模式

Phase 3: 接口对接（1周）

• APP-后台接口
• 推送数据格式
• 四种艾灸模式接口

Phase 4: 后台管理（2周）

• 管理后台开发
• 用户管理界面
• 穴位管理界面
• 方案管理界面

Phase 5: 测试验收（1周）

• 功能测试
• 性能测试
• 验收测试

---

十一、参考标准

• GB/T 12346-2006《腧穴名称与定位》
• GB/T 10000-1988《中国成年人人体尺寸》
• 《针灸学》教材（穴位定位方法）