---
description: Markdown 文档编写规范和模板
globs: ["**/*.md", "**/docs/**/*", "**/README.md"]
alwaysApply: false
---

# Markdown 文档规范

## 📚 项目文档结构

### README.md 标准模板
```markdown
# 项目名称

## 📋 目录
- [🚀 快速开始](#快速开始)
- [📁 项目结构](#项目结构)
- [🛠️ 开发指南](#开发指南)
- [🧪 测试](#测试)
- [🚀 部署](#部署)
- [📚 API 文档](#api-文档)
- [🤝 贡献指南](#贡献指南)

## 🚀 快速开始

### 环境要求
- Node.js >= 18.0.0
- npm >= 8.0.0
- PostgreSQL >= 13.0
- Redis >= 6.0

### 安装步骤
1. 克隆仓库
```bash
git clone https://github.com/username/project.git
cd project
```

2. 安装依赖
```bash
npm install
```

3. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env 文件，填入必要的配置
```

4. 启动开发服务器
```bash
npm run dev
```

## 📁 项目结构

```
project/
├── src/                    # 源代码目录
│   ├── components/         # Vue 组件
│   ├── composables/        # 组合式函数
│   ├── services/          # API 服务
│   ├── types/             # TypeScript 类型定义
│   └── utils/             # 工具函数
├── server/                # 后端代码
│   ├── controllers/       # 控制器
│   ├── services/         # 业务服务
│   ├── entities/         # 数据库实体
│   └── dto/              # 数据传输对象
├── tests/                 # 测试文件
├── docs/                  # 项目文档
└── public/                # 静态资源
```

## 🛠️ 开发指南

### 代码规范
项目使用 ESLint 和 Prettier 进行代码格式化：

```bash
# 检查代码规范
npm run lint

# 自动修复代码格式
npm run format
```

### 提交规范
使用 Conventional Commits 规范：

```bash
# 功能提交
git commit -m "feat: 添加用户认证功能"

# 修复提交
git commit -m "fix: 修复登录页面样式问题"

# 文档提交
git commit -m "docs: 更新 API 文档"
```

## 🧪 测试

### 运行测试
```bash
# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行端到端测试
npm run test:e2e

# 生成测试覆盖率报告
npm run test:coverage
```

### 测试覆盖率
项目要求测试覆盖率不低于 80%：
- 单元测试覆盖率：≥ 80%
- 集成测试覆盖率：≥ 70%
- 端到端测试覆盖率：≥ 60%

## 🚀 部署

### Docker 部署
```bash
# 构建镜像
docker build -t myapp .

# 运行容器
docker run -p 3000:3000 myapp
```

### Kubernetes 部署
```bash
# 应用配置
kubectl apply -f k8s/

# 检查部署状态
kubectl get pods
kubectl get services
```

## 📚 API 文档

### 用户管理 API

#### 创建用户
```http
POST /api/users
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "firstName": "John",
  "lastName": "Doe"
}
```

**响应：**
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "user",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```

#### 获取用户列表
```http
GET /api/users?page=1&limit=10&role=user
```

**响应：**
```json
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}
```

## 🤝 贡献指南

### 开发流程
1. Fork 项目
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'feat: add amazing feature'`
4. 推送分支：`git push origin feature/amazing-feature`
5. 创建 Pull Request

### 代码审查
所有代码提交都需要通过以下检查：
- [ ] ESLint 检查通过
- [ ] Prettier 格式化通过
- [ ] TypeScript 类型检查通过
- [ ] 单元测试通过
- [ ] 测试覆盖率达标
- [ ] 代码审查通过

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
```

## 📊 API 文档模板

### API 文档标准格式
```markdown
# API 文档

## 认证

所有 API 请求都需要在请求头中包含有效的 JWT Token：

```http
Authorization: Bearer <your-jwt-token>
```

## 错误处理

API 使用标准的 HTTP 状态码：

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

错误响应格式：
```json
{
  "statusCode": 400,
  "message": "请求参数错误",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "path": "/api/users"
}
```

## 分页

支持分页的 API 使用以下参数：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| page | number | 1 | 页码 |
| limit | number | 10 | 每页数量 |
| sort | string | createdAt | 排序字段 |
| order | string | desc | 排序方向 |

分页响应格式：
```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}
```
```

## 📝 更新日志模板

### CHANGELOG.md 标准格式
```markdown
# 更新日志

所有重要的项目更改都会记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [未发布]

### 新增
- 新功能描述

### 更改
- 功能更改描述

### 修复
- 问题修复描述

## [1.2.0] - 2024-01-15

### 新增
- 添加用户管理功能
- 实现 JWT 认证
- 添加单元测试

### 更改
- 优化数据库查询性能
- 更新 UI 组件库版本

### 修复
- 修复登录页面样式问题
- 修复 API 响应格式不一致

## [1.1.0] - 2024-01-01

### 新增
- 添加用户注册功能
- 实现密码重置

### 修复
- 修复跨域请求问题

## [1.0.0] - 2023-12-01

### 新增
- 初始版本发布
- 基础用户认证功能
- 管理后台界面
```

## 🎯 Markdown 最佳实践

### 必需配置项
- ✅ 使用清晰的目录结构
- ✅ 提供完整的安装和配置说明
- ✅ 包含 API 文档和示例
- ✅ 使用表格和代码块格式化内容
- ✅ 遵循语义化版本控制

### 参考文件
- `README.md` - 项目主文档
- `docs/API.md` - API 文档
- `CHANGELOG.md` - 更新日志
- `CONTRIBUTING.md` - 贡献指南