项目架构规范
技术栈
- 前端: 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/ 目录
- 应用依赖明确版本号，不使用
^ 或 ~
构建与部署
# 安装依赖
pnpm install
# 开发模式
pnpm dev
# 构建
pnpm build
# 测试
pnpm test
# 代码检查
pnpm lint
