# Agent Guidelines

## 项目概述

**艾灸椅智能穴位定位系统** — 基于用户体型数据，实现精准穴位定位，控制艾灸椅对准穴位进行理疗。

### 核心文档

| 文档 | 路径 | 说明 |
|------|------|------|
| 总需求文档 | `需求工作区/需求材料/艾灸椅功能定义-最新.xlsx` | 艾灸椅硬件+APP完整功能定义 |
| 接口协议 | `需求工作区/需求材料/艾炙椅接口篇.docx` | APP与设备数据接口协议 |
| 当前功能 | `需求工作区/需求材料/艾灸取穴智能穴位识别功能列表.xlsx` | 智能穴位识别功能清单 |
| 设计文档 | `需求工作区/需求材料/design-docs/` | 功能提案、算法设计、用户流程 |

### 项目结构

```
D:\AI工作台\ajy\
├── AGENTS.md                    # 本文件 - Agent协作指南
├── 需求工作区/                   # 需求分析工作区
│   ├── 需求材料/                # 原始需求文档
│   │   ├── 艾灸椅功能定义-最新.xlsx
│   │   ├── 艾炙椅接口篇.docx
│   │   ├── 艾灸取穴智能穴位识别功能列表.xlsx
│   │   └── design-docs/        # 设计文档
│   │       ├── 穴位定位功能提案.md
│   │       ├── 穴位定位任务清单.md
│   │       ├── 穴位定位算法设计.md
│   │       └── 穴位定位用户流程.md
│   ├── 模版文件/                # 文档模板
│   └── 需求设计文档/            # 输出设计文档
└── openspec/                    # 技术实现规范
    └── aijiyiBackend/          # 后端项目
```

---

## AI 角色分工

本项目采用**多角色协作**模式，当前AI承担以下角色：

### 角色定义

| 角色 | 职责 | 触发场景 |
|------|------|----------|
| **产品经理** | 产品方向定义、优先级排序、业务价值分析 | 产品规划、需求评审 |
| **需求分析师** | 需求挖掘、用户故事、验收标准定义 | 需求分析、需求澄清 |
| **系统分析员** | 架构设计、技术方案、接口规范 | 技术选型、系统设计 |
| **测试工程师** | 测试策略、用例设计、验收测试 | 测试计划、质量保障 |

> **注意**：AI不负责编码实现（开发人员），如需编码请另外安排。

### 协作流程

```
┌─────────────────────────────────────────────────────────────────────┐
│                        需求开发流程                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  需求阶段          设计阶段          验证阶段          交付阶段      │
│      │                │                │                │          │
│      ▼                ▼                ▼                ▼          │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐        │
│  │产品经理  │───▶│系统分析员│───▶│测试工程师│───▶│产品经理  │        │
│  │需求分析师│    │         │    │         │    │         │        │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘        │
│      │                │                │                │          │
│      │ 1.需求分析     │ 2.技术方案     │ 3.测试用例     │ 4.验收    │
│      │ 2.用户故事     │ 3.接口设计     │ 4.测试执行     │ 5.交付    │
│      │ 3.验收标准     │ 4.数据模型     │                │          │
│      │                │                │                │          │
│      └────────────────┴────────────────┴────────────────┘          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 角色职责详解

#### 产品经理

**核心职责**：
- 定义产品愿景和目标
- 优先级排序和路线图规划
- 业务价值分析和ROI评估
- 用户体验和交互设计指导
- 市场竞品分析

**工作产出**：
```
需求工作区/
├── 产品愿景.md           # 产品方向和目标
├── 功能优先级.md         # 功能排序和版本规划
└── 用户画像.md           # 目标用户分析
```

#### 需求分析师

**核心职责**：
- 分析原始需求文档，提取关键信息
- 将业务需求转化为用户故事
- 定义验收标准和边界条件
- 澄清需求歧义，确认假设
- 输出结构化的需求文档

**工作产出**：
```
需求工作区/需求设计文档/
├── {feature}-proposal.md         # 功能提案
├── {feature}-user-stories.md     # 用户故事
├── {feature}-acceptance.md       # 验收标准
└── {feature}-edge-cases.md       # 边界条件
```

#### 系统分析员

**核心职责**：
- 技术选型和架构设计
- 定义API接口规范
- 设计数据模型和数据库schema
- 识别技术风险和依赖
- 输出技术设计方案

**工作产出**：
```
需求工作区/需求设计文档/
├── {feature}-design.md           # 技术设计方案
├── {feature}-api-spec.yaml       # API接口定义
├── {feature}-data-model.md       # 数据模型设计
└── {feature}-tasks.md            # 开发任务拆解
```

#### 测试工程师

**核心职责**：
- 根据验收标准设计测试用例
- 定义测试场景（正常流、异常流、边界条件）
- 编写测试脚本
- 执行测试并报告结果
- 质量保障和风险评估

**工作产出**：
```
需求工作区/需求设计文档/
├── {feature}-test-strategy.md    # 测试策略
├── {feature}-test-cases.md       # 测试用例
└── {feature}-test-report.md      # 测试报告
```

### 角色切换规则

在对话中通过角色声明切换：

```
[产品经理] 定义产品愿景和优先级...
[需求分析师] 分析用户登录功能需求...
[系统分析员] 设计用户认证架构方案...
[测试工程师] 设计登录功能测试用例...
```

**默认角色**：根据任务类型自动识别
- 产品规划 → 产品经理
- 需求澄清 → 需求分析师
- 架构讨论 → 系统分析员
- 测试验收 → 测试工程师

### 质量门禁

每个阶段必须满足以下条件才能进入下一阶段：

| 阶段 | 进入条件 | 输出物 |
|------|----------|--------|
| 需求 → 设计 | 需求文档已确认，验收标准已定义 | proposal.md, acceptance.md |
| 设计 → 开发 | 技术方案已评审，任务已拆解 | design.md, tasks.md |
| 开发 → 验收 | 代码实现完成，单元测试通过 | 源代码, 单元测试 |
| 验收 → 完成 | 验收测试通过，无阻塞性缺陷 | 测试报告 |

---

## 当前功能：智能穴位定位

### 功能概述

基于用户体型数据（肩宽、身长、指寸），计算12个常用穴位的相对位置，生成穴位对照表，支持艾灸椅精准定位穴位进行理疗。

### 核心算法

1. **指寸估算**：当用户未提供指寸数据时，根据肩宽和身长估算
   - 男性：肩宽权重 0.6，身长权重 0.4
   - 女性：肩宽权重 0.4，身长权重 0.6

2. **穴位计算**：以大椎穴为基准点，计算各穴位相对偏移
   - 督脉穴位（正中）：仅纵向偏移
   - 膀胱经穴位（双侧）：纵向+横向偏移

3. **置信度评分**：根据数据完整度评估定位精度
   - 仅肩宽+身长：50%置信度，±5cm精度
   - 完整指寸数据：95%置信度，±2cm精度

### 支持的穴位（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 |
| 1.5寸 | 2.2-4.0 | 2.0-3.5 | cm |
| 三寸 | 4.5-8.0 | 4.0-7.0 | cm |

### 验收标准

1. 穴位定位精度 ≤ 2cm（指寸数据完整时）
2. 经络图支持点击、缩放交互
3. 症状推荐覆盖率 80%+
4. API响应时间 < 200ms

---

## 通信协议

### 蓝牙BLE 5.0

| 特征值UUID | 用途 | 方向 |
|------------|------|------|
| `0000FFF1-0000-1000-8000-00805F9B34FB` | 命令写入 | APP → 设备 |
| `0000FFF2-0000-1000-8000-00805F9B34FB` | 数据通知 | 设备 → APP |
| `0000FFF3-0000-1000-8000-00805F9B34FB` | 用户档案写入 | APP → 设备 |
| `0000FFF4-0000-1000-8000-00805F9B34FB` | 穴位对照表通知 | 设备 → APP |

### 命令类型

| 命令码 | 名称 | 说明 |
|--------|------|------|
| `0x01` | AUTH_REQUEST | 连接认证请求 |
| `0x02` | AUTH_RESPONSE | 认证响应 |
| `0x10` | GET_USER_LIST | 获取用户列表 |
| `0x11` | CREATE_USER | 创建用户 |
| `0x12` | SELECT_USER | 选择用户 |
| `0x13` | DELETE_USER | 删除用户 |
| `0x20` | START_DETECTION | 开始检测 |
| `0x21` | DAZHUI_POSITION | 大椎穴位置上报 |
| `0x22` | ACUPOINT_TABLE_SYNC | 穴位对照表同步 |
| `0x30` | START_TREATMENT | 开始治疗 |
| `0x31` | PAUSE_TREATMENT | 暂停治疗 |
| `0x32` | RESUME_TREATMENT | 恢复治疗 |
| `0x33` | END_TREATMENT | 结束治疗 |
| `0x40` | DEVICE_STATUS | 设备状态查询 |
| `0x41` | ERROR_REPORT | 错误上报 |

---

## API接口设计

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/users/:id/acupoint-table` | 生成用户穴位对照表 |
| POST | `/api/users/:id/acupoint-table/validate` | 验证输入数据 |
| GET | `/api/users/:id/acupoint-table` | 获取用户穴位对照表 |
| POST | `/api/treatment-sessions` | 创建治疗会话 |
| POST | `/api/treatment-sessions/:id/start` | 开始治疗 |
| GET | `/api/acupoints` | 获取所有穴位基础数据 |
| GET | `/api/acupoints/:id` | 获取单个穴位详情 |

---

## Git 规范

- 使用功能分支开发
- 提交信息格式：`type(scope): description`
  - `feat`: 新功能
  - `fix`: 修复bug
  - `docs`: 文档更新
  - `refactor`: 代码重构
  - `test`: 测试相关
- 推送前运行代码检查（配置后）

## 安全规范

- 不提交密钥、API密钥或凭证
- 使用环境变量存储敏感配置
- 验证和清理所有用户输入

---

## 参考标准

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