# Agent Guidelines

## Project Overview

**艾灸椅功能管理系统** — 智能艾灸设备的云端管理平台。

需求文档：`需求材料/艾灸椅功能定义-最新.xlsx`

## AI 角色分工

本项目采用**多角色协作**模式，不同角色负责不同阶段：

### 角色定义

| 角色 | 职责 | 触发场景 |
|------|------|----------|
| **需求工程师**<br>(兼测评工程师) | 需求分析、验收标准、测试用例设计 | 新功能规划、需求澄清 |
| **系统分析员** | 架构设计、技术方案、接口定义 | 技术选型、系统设计 |
| **开发人员** | 代码实现、单元测试、代码审查 | 具体编码任务 |

### 协作流程

```
需求阶段          设计阶段          开发阶段          验收阶段
    │                │                │                │
    ▼                ▼                ▼                ▼
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│需求工程师│───▶│系统分析员│───▶│开发人员  │───▶│需求工程师│
│(测评)   │    │         │    │         │    │(测评)   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
    │                                              │
    │  1. 需求文档                                 │  4. 验收测试
    │  2. 验收标准                                 │
    │  3. 测试用例                                 │
    └──────────────────────────────────────────────┘
```

### 角色职责详解

#### 需求工程师 (兼测评工程师)

**需求职责：**
- 分析 `需求材料/艾灸椅功能定义-最新.xlsx` 中的功能需求
- 将业务需求转化为用户故事和验收标准
- 澄清需求歧义，确认边界条件
- 输出：`openspec/changes/{feature}/proposal.md`

**测评职责：**
- 根据验收标准设计测试用例
- 定义测试场景（正常流、异常流、边界条件）
- 编写验收测试脚本
- 执行验收测试并签署通过/不通过
- 输出：`tests/acceptance/{feature}.test.ts`

**工作产出：**
```
需求阶段:
├── proposal.md      # 需求提案
├── acceptance-criteria.md  # 验收标准
└── test-cases.md    # 测试用例设计

验收阶段:
└── {feature}.test.ts  # 验收测试脚本
```

#### 系统分析员

**职责：**
- 技术选型和架构设计
- 定义 API 接口规范
- 设计数据模型和数据库 schema
- 识别技术风险和依赖
- 输出：`openspec/changes/{feature}/design.md`

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

#### 开发人员

**职责：**
- 按设计文档实现功能代码
- 编写单元测试（TDD：先写测试再写代码）
- 代码自审和互审
- 修复 bug 和技术债务
- 输出：`apps/{web,api}/src/`

**工作产出：**
```
apps/
├── web/src/
│   ├── components/  # UI 组件
│   ├── pages/       # 页面
│   └── hooks/       # 自定义 hooks
└── api/src/
    ├── routes/      # API 路由
    ├── services/    # 业务逻辑
    └── models/      # 数据模型
```

### 角色切换规则

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

```
[需求工程师] 分析用户登录功能需求...
[系统分析员] 设计用户认证架构方案...
[开发人员] 实现登录 API 和前端表单...
[测评工程师] 执行登录功能验收测试...
```

**默认角色**：根据任务类型自动识别
- 需求澄清 → 需求工程师
- 架构讨论 → 系统分析员
- 代码实现 → 开发人员
- 测试验收 → 测评工程师（需求工程师兼任）

### 质量门禁

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

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

## Build / Lint / Test Commands

**None configured.** This repo has no `package.json`, `Makefile`, `pyproject.toml`, or any build configuration.

When a project is added, document commands here. Common patterns:

```bash
# Node.js / npm
npm install          # install deps
npm run dev          # dev server
npm run build        # production build
npm test             # run all tests
npm test -- --testPathPattern=filename  # single test

# Python
pip install -r requirements.txt
pytest tests/test_file.py::TestClass::test_method  # single test
pytest -k test_name   # single test by name

# Go
go build ./...
go test -run TestName ./...

# Rust
cargo build
cargo test test_name
```

## Code Style Guidelines

**No code exists yet.** When adding code, follow these defaults unless project-specific configs dictate otherwise:

### Imports
- Group: stdlib → third-party → local
- Sort alphabetically within groups
- Use explicit imports, no wildcards

### Formatting
- Match existing file indentation (2 or 4 spaces)
- Max line length: 80-120 chars
- Consistent line endings (CRLF on Windows, LF elsewhere)

### Naming
- **Files**: kebab-case or PascalCase
- **Classes**: PascalCase (`UserService`)
- **Functions/Vars**: camelCase (`getUserById`)
- **Constants**: SCREAMING_SNAKE_CASE (`MAX_RETRIES`)
- **Booleans**: `is`/`has`/`should` prefix (`isActive`)

### Error Handling
- Use specific error types, not generic
- Include context in error messages
- Never silently swallow errors

### Types (if TypeScript)
- Explicit annotations on params and returns
- Avoid `any` — use `unknown` if truly unknown
- Enable strict mode

## Working with This Repository

1. **Read first** — Always check existing files before editing
2. **Understand domain** — Review `需求材料/艾灸椅功能定义-最新.xlsx` before implementing
3. **Follow conventions** — Match whatever pattern the added project uses
4. **Test changes** — Run appropriate tests when available
5. **Commit responsibly** — Atomic, focused commits with clear messages

## Git Conventions

- Feature branches for new work
- Atomic commits with clear messages
- Run linters before committing (once configured)
- Review changes before pushing

## Security

- Never commit secrets, API keys, or credentials
- Use environment variables for sensitive config
- Validate and sanitize all user inputs

## Cursor / Copilot Rules

No Cursor rules (`.cursorrules`, `.cursor/rules/`) or Copilot instructions (`.github/copilot-instructions.md`) found.