# 项目架构规范

## 技术栈

- **前端**: React + TypeScript + Tailwind CSS
- **后端**: Node.js + Express + TypeScript
- **数据库**: SQLite (开发) / PostgreSQL (生产)
- **状态管理**: Zustand
- **API 风格**: RESTful + OpenAPI

## 目录结构

```
ajy/
├── apps/
│   ├── web/              # React 前端应用
│   │   ├── src/
│   │   │   ├── components/   # UI 组件
│   │   │   ├── pages/        # 页面
│   │   │   ├── hooks/        # 自定义 hooks
│   │   │   ├── stores/       # Zustand stores
│   │   │   └── utils/        # 工具函数
│   │   └── package.json
│   │
│   └── api/              # Express 后端 API
│       ├── src/
│       │   ├── routes/       # API 路由
│       │   ├── controllers/  # 控制器
│       │   ├── services/     # 业务逻辑
│       │   ├── models/       # 数据模型
│       │   ├── middleware/   # 中间件
│       │   └── utils/        # 工具函数
│       └── package.json
│
├── packages/
│   └── shared/           # 共享类型和工具
│       └── src/
│           └── types/
│
├── openspec/             # OpenSpec 规范目录
│   ├── specs/            # 当前规范
│   └── changes/          # 变更提案
│
├── docs/                 # 文档
│   └── 艾灸椅功能定义-最新.xlsx
│
└── AGENTS.md             # AI 代理指南
```

## 命名约定

### 文件命名
- React 组件: `PascalCase.tsx` (e.g., `MoxibustionPanel.tsx`)
- 工具函数: `camelCase.ts` (e.g., `formatTime.ts`)
- 常量文件: `SCREAMING_SNAKE_CASE.ts` (e.g., `API_ENDPOINTS.ts`)
- 测试文件: `*.test.ts` 或 `*.spec.ts`

### 代码风格
- **缩进**: 2 空格
- **行尾**: LF (Unix 风格)
- **引号**: 单引号
- **分号**: 必须
- **最大行宽**: 100 字符

## 依赖管理

- 使用 pnpm workspace 管理 monorepo
- 共享包放在 `packages/` 目录
- 应用依赖明确版本号，不使用 `^` 或 `~`

## 构建与部署

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

# 代码检查
pnpm lint
```