# 艾灸椅智能穴位定位系统

## 项目概述

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

### 三方协作架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        项目协作架构                              │
├─────────────────────────────────────────────────────────────────┤
│   单位A（硬件）          单位B（APP）           我们（算法+后台）│
│   ┌─────────┐           ┌─────────┐           ┌─────────┐      │
│   │ 艾灸椅  │           │  APP    │           │ 后台管理│      │
│   │ 设备    │◀─────────│ 功能    │◀──────────│ 系统    │      │
│   └─────────┘   推送    └─────────┘   推送    └─────────┘      │
└─────────────────────────────────────────────────────────────────┘
```

### 核心职责

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

---

## 技术栈

| 层级 | 技术 |
|------|-------|
| 后端 | Spring Boot + MyBatis-Plus + MySQL + Redis |
| 前端 | Vue 3 + Element Plus + Vite |
| 测试 | Playwright (E2E) |

---

## 需求模块与开发状态

### 1. 用户管理 (44用例) - ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 用户列表查看 | ✅ 已开发 | 显示ID、姓名、性别、年龄、手机号、设备编号、肩宽、身长、穴位表状态 |
| 按姓名模糊搜索 | ✅ | |
| 按手机号搜索 | ✅ | |
| 按设备编号搜索 | ✅ | |
| 按性别筛选 | ✅ | |
| 按穴位表状态筛选 | ✅ | |
| 重置查询条件 | ✅ | |
| 新增用户 | ✅ | 姓名、性别、年龄、手机号、肩宽、身长 |
| 姓名必填验证 | ✅ | |
| 性别必填验证 | ✅ | |
| 手机号必填验证 | ✅ | |
| 手机号格式验证 | ✅ | 11位 |
| 手机号唯一性验证 | ✅ | |
| 肩宽范围验证 | ✅ | 男性36-52cm, 女性32-46cm |
| 身长范围验证 | ✅ | 男性75-95cm, 女性70-88cm |
| 年龄范围验证 | ✅ | 1-120岁 |
| 生成穴位坐标 | ✅ | 生成12个穴位(23个点) |
| 编辑用户信息 | ✅ | |
| 编辑后重新生成坐标 | ✅ | |
| 查看用户详情 | ✅ | |
| 删除单个用户 | ✅ | |
| 删除取消 | ✅ | |
| 用户设备管理 | ✅ | 查看、添加、设为主设备、解绑 |
| 导出用户数据 | ✅ | Excel导出 |

### 2. 穴位管理 (22用例) - ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 查看穴位列表 | ✅ | 显示ID、名称、经络、功效、定位方式、状态 |
| 按穴位名称搜索 | ✅ | |
| 按经络筛选 | ✅ | 督脉、膀胱经等 |
| 按定位方式筛选 | ✅ | 相对定位/绝对定位 |
| 按状态筛选 | ✅ | 活跃/待完善 |
| 新增穴��� | ✅ | 相对定位(中心/双侧) |
| 穴位名称必填验证 | ✅ | |
| 艾灸手法管理 | ✅ | 5种手法：一键艾灸、温和灸、雀啄灸、回旋灸、麻雀灸 |

### 3. 方案管理 (34用例) - ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 查看方案列表 | ✅ | 显示ID、名称、模式、功效、创作人、步骤数、状态 |
| 创作人显示 | ✅ | 一键艾灸/专业模式/自定义模式/延年圣手 |
| 按方案名称搜索 | ✅ | |
| 按模式类型筛选 | ✅ | |
| 按功效类型筛选 | ✅ | 驱寒、祛湿、清热、补气、养血、活血、安神、理气 |
| 按状态筛选 | ✅ | 草稿/已发布/已下架 |
| 查看方案详情 | ✅ | 基本信息、治疗步骤、统计信息 |
| 新增方案 | ✅ | 一键艾灸、专业模式、自定义模式、延年圣手 |
| 方案名称必填验证 | ✅ | |
| 发布方案 | ✅ | |
| 下架方案 | ✅ | |

### 4. 设备管理 (19用例) - ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 查看设备列表 | ✅ | 编号、名称、型号、绑定用户数、在线状态、固件版本 |
| 按设备编号搜索 | ✅ | |
| 新增设备 | ✅ | |
| 设备编号必填验证 | ✅ | |
| 设备绑定用户管理 | ✅ | 查看、添加、设为主、解绑 |

### 5. 系统管理 (11用例) - ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 管理员列表 | ✅ | |
| 新增管理员 | ✅ | |
| 密码格式验证 | ✅ | 8-20字符，含字母和数字 |
| 禁用/启用管理员 | ✅ | |
| 操作日志 | ✅ | |
| 日志筛选 | ✅ | 按操作人、操作类型、时间范围 |

### 6. 核心算法 (20用例) - ✅ 已完成

| 功能 | 状态 | 说明 |
|------|------|------|
| 男性标准体型估算 | ✅ | 肩宽42cm,身长85cm → cun1≈2.2cm |
| 女性标准体型估算 | ✅ | 肩宽36cm,身长78cm → cun1≈1.9cm |
| 男性大体型估算 | ✅ | 肩宽52cm,身长95cm → cun1≈2.54cm |
| 男性小体型估算 | ✅ | 肩宽36cm,身长75cm → cun1≈1.88cm |
| 女性大体型估算 | ✅ | 肩宽46cm,身长88cm → cun1≈2.26cm |
| 女性小体型估算 | ✅ | 肩宽32cm,身长70cm → cun1≈1.54cm |
| 有指寸不估算 | ✅ | 使用实际指寸 |
| 生成12个穴位 | ✅ | 生成23个点(含双侧) |
| 大椎穴为原点 | ✅ | 坐标(0,0) |
| 督脉只有纵向偏移 | ✅ | X=0 |
| 双侧穴位横向偏移 | ✅ | 左X负,右X正 |
| 置信度计算 | ✅ | 仅肩宽身长50%/部分指寸65%/完整指寸95% |

---

## 测试用例汇总

### E2E 测试 (159用例, 覆盖率92%)

```
test-e2e/
├── e2e/
│   ├── app.spec.js              # 登录 + 核心模块 (32)
│   ├── user-management.spec.js # 用户管理详细 (19)
│   ├── scheme-management.spec.js # 方案管理详细 (28)
│   ├── device-system.spec.js   # 设备+系统管理 (23)
│   ├── acupoint.spec.js        # 穴位+艾灸手法 (16)
│   ├── algorithm.spec.js       # 核心算法 (19)
│   └── api.spec.js             # API+DB+验收 (22)
├── package.json
└── playwright.config.js
```

### 测试覆盖详情

| 模块 | 需求用例 | 实际用例 | 覆盖率 |
|------|---------|---------|--------|
| 用户管理 | 44 | 51 | 116% |
| 穴位管理 | 22 | 23 | 105% |
| 方案管理 | 34 | 35 | 103% |
| 设备管理 | 19 | 19 | 100% |
| 系统管理 | 11 | 13 | 118% |
| 核心算法 | 20 | 19 | 95% |
| 接口+DB+验收 | 22 | 22 | 100% |
| **合计** | **172** | **159** | **92%** |

### 运行测试

```bash
cd test-e2e
npx playwright test           # 运行所有测试
npx playwright test --grep "TC-001"  # 运行指定用例
```

---

## 项目结构

```
ajy/
├── code/
│   ├── backend/              # Spring Boot 后端
│   │   └── src/main/java/com/aijiuyi/admin/
│   │       ├── controller/  # API控制器
│   │       ├── service/      # 业务逻辑
│   │       ├── mapper/       # 数据访问
│   │       ├── entity/       # 实体类
│   │       └── common/       # 公共组件
│   └── frontend/             # Vue 3 前端
│       └── src/
│           ├── views/       # 页面组件
│           ├── api/         # API调用
│           └── store/       # 状态管理
├── test-e2e/                # E2E测试
├── 需求工作区/               # 需求文档
│   └── 需求设计文档/
│       └── 智能穴位定位系统测试用例.md
└── openspec/                # 技术规范
```

---

## 开发环境

- **生产环境**: https://ajy.danclub.cn
- **测试账号**: admin / admin123

### 支持的穴位(12个)

| 穴位 | 经络 | 相对大椎穴位置 | 功效 |
|------|------|----------------|------|
| 大椎穴 | 督脉 | 基准点 (0, 0) | 驱寒、祛湿、解表 |
| 身柱穴 | 督脉 | 下3寸 | 止咳平喘、安神 |
| 至阳穴 | 督脉 | 下7寸 | 宽胸理气 |
| 命门穴 | 督脉 | 下14寸 | 补肾壮阳 |
| 腰阳关穴 | 督脉 | 下17寸 | 强腰健肾 |
| 风门穴(双) | 膀胱经 | 下1.5寸，旁开1.5寸 | 祛风解表 |
| 秉风穴(双) | 小肠经 | 下3寸，旁开3寸 | 祛风散寒 |
| 肺俞穴(双) | 膀胱经 | 下3寸，旁开1.5寸 | 化痰止咳 |
| 膈俞穴(双) | 膀胱经 | 下7寸，旁开1.5寸 | 活血化瘀 |
| 脾俞穴(双) | 膀胱经 | 下11寸，旁开1.5寸 | 健脾养血 |
| 肾俞穴(双) | 膀胱经 | 下14寸，旁开1.5寸 | 补肾益气 |
| 八髎穴 | 膀胱经 | 下16寸 | 调理下焦 |

### 数据验证规则

| 字段 | 男性范围 | 女性范围 | 单位 |
|------|---------|---------|------|
| 肩宽 | 36-52 | 32-46 | cm |
| 身长（坐高） | 75-95 | 70-88 | cm |
| 一寸 | 1.5-2.8 | 1.3-2.4 | cm |

---

## 验收标准（已通过测试）

| 标准 | 目标 | 状态 |
|------|------|------|
| 穴位定位精度 | ≤2cm | ✅ |
| 穴位库动态扩展 | 支持 | ✅ |
| 8种专业模式 | 均可创建和发布 | ✅ |
| API响应时间 | <200ms | ✅ |
| 症状推荐覆盖率 | ≥80% | ✅ |

---

## License

ISC