hzdyjs/.cursor/cursorrules-docs.md

# Cursor Rules - 项目文档管理规范

## 项目结构说明

-   **前端工程**：`web/` (基于 Vue 3 + TypeScript + Element Plus)
-   **后端工程**：`backend/` (基于 RuoYi-Vue-Plus + Spring Boot 3.4.6)
-   **移动端工程**：`mobile/` (基于 uniapp + uView UI 构建的校园管理移动端应用)
-   **文档管理**：`docs/` (项目的需求、设计、开发、测试、部署文档)

---

# 项目文档管理规范

## 1. 文档结构管理 (docs/)

### 🔴 文档目录组织（中文化架构）

```
docs/
├── 项目总览/               # 项目基本信息和架构概览
│   ├── README.md          # 项目总览主文档
│   └── 项目总览模板.md     # 项目总览标准模板
├── 业务模块/               # 业务模块文档（为AI提供业务上下文）
│   ├── README.md          # 业务模块管理总览
│   ├── 业务模块开发模板.md  # 业务模块标准开发模板
│   ├── hq-satisfaction-survey/     # 后勤满意度调查模块
│   ├── hall-reservation/          # 报告厅预约模块
│   ├── system-management/         # 系统管理模块
│   └── user-management/           # 用户管理模块
├── 变更管理/               # 变更管理中心
│   ├── README.md          # 变更管理流程和规范
│   └── code-adjust-record.md      # 代码调整记录
├── 开发文档/               # 开发指南和技术规范
│   ├── README.md          # 开发文档总览
│   ├── API.md             # API接口完整文档
│   └── API文档模板.md      # API文档标准模板
├── 设计文档/               # 设计文档
│   ├── README.md          # 设计文档说明
│   └── database/          # 数据库设计
│       ├── hzdyjs_xg.sql         # 完整数据库模型
│       ├── 01-workflow-module.sql        # 工作流模块SQL
│       ├── 02-code-generator-module.sql  # 代码生成模块SQL
│       ├── 03-logistics-module.sql       # 后勤管理模块SQL
│       ├── 04-job-scheduler-module.sql   # 任务调度模块SQL
│       ├── 05-system-management-module.sql # 系统管理模块SQL
│       ├── 06-test-module.sql            # 测试模块SQL
│       ├── SQL文件说明.md                # SQL文件拆分说明
│       ├── mysql-database-standard.md   # MySQL数据库建设规范
│       ├── database_msg.md              # 环境配置信息
│       └── README.md                    # 数据库设计说明
├── 需求文档/               # 需求文档
│   ├── README.md          # 需求管理说明
│   ├── 后勤报告厅预约需求/ # 报告厅预约系统需求
│   └── 后勤满意度调查需求/ # 满意度调查系统需求
├── 测试文档/               # 测试文档（按需求维度组织）
│   ├── README.md          # 测试文档管理总览
│   ├── 后勤管理/           # 后勤管理相关测试文档
│   │   ├── 物业报修/       # 物业报修系统测试文档
│   │   ├── 满意度调查/     # 满意度调查系统测试文档
│   │   └── 报告厅预约/     # 报告厅预约系统测试文档
│   ├── 系统管理/           # 系统管理相关测试文档
│   ├── 用户管理/           # 用户管理相关测试文档
│   └── 工作流管理/         # 工作流管理相关测试文档
├── 部署文档/               # 部署文档
│   └── README.md          # 部署指南
├── 中间件配置/             # 中间件配置文档
│   ├── README.md          # 中间件配置说明
│   └── mysql-config.md    # MySQL配置文档
├── 知识库/                 # 知识库
├── 报告文档/               # 报告文档
├── structure-optimization-plan.md # 文档结构优化方案
└── README.md              # 文档体系总说明
```

### 🔴 重要文档说明

-   **工程本地启动指导.md** (项目根目录)：包含完整的环境配置和启动指南
-   **技术要求更新**：Node.js 20.15.x+, npm 10.7.x+
-   **数据库环境**：支持本地安装或使用阿里云测试环境
-   **前端访问地址**：http://localhost (非 3000 端口)

## 2. 🚨 强制性文档同步更新规则

### 📋 核心原则：代码与文档必须同步更新

**⚠️ 超级重要：每次使用 Cursor AI 进行代码调整后，必须立即同步更新相应的项目文档！**

### 🔴 强制更新触发条件

每次代码调整必须检查并更新以下文档：

#### 后端代码调整时的强制文档更新：

-   **✅ API 接口变更**：

    -   必须立即更新 `docs/开发文档/API.md`
    -   新增接口：添加完整接口文档（地址、参数、响应、权限、示例）
    -   修改接口：更新参数说明、响应格式、错误码
    -   删除接口：标记为已废弃，说明替代方案
    -   权限变更：更新权限要求说明

-   **✅ 数据库变更**：

    -   更新 `docs/设计文档/database/` 下的相关文档
    -   新增表：添加表结构说明和字段注释
    -   修改表：更新字段变更和索引调整
    -   数据迁移：记录迁移脚本和注意事项

-   **✅ 业务逻辑变更**：

    -   更新对应 `docs/业务模块/[模块名称]/` 下的业务文档
    -   更新业务流程图和业务规则说明
    -   修改用户故事和功能需求

-   **✅ 配置变更**：
    -   更新 `docs/中间件配置/` 下的配置文档
    -   更新 `docs/部署文档/` 下的部署说明

#### 前端代码调整时的强制文档更新：

-   **✅ 页面功能变更**：

    -   更新对应业务模块的用户操作文档
    -   更新 UI 设计规范文档

-   **✅ API 调用变更**：

    -   检查前端 API 调用是否与后端 API 文档一致
    -   更新 API 对接说明文档

-   **✅ 组件变更**：
    -   更新组件使用说明和属性文档

#### 移动端代码调整时的强制文档更新：

-   **✅ 功能变更**：更新移动端功能说明文档
-   **✅ API 对接变更**：更新移动端 API 调用文档
-   **✅ 用户流程变更**：更新用户操作指南

#### 📚 docs 文档变更时的强制同步更新规则：

**⚠️ 超级重要：每当 docs/目录下的文档结构或重要内容发生变更时，必须立即同步更新.cursorrules 文件！**

-   **🔴 文档结构变更**：

    -   新增/删除目录：同步更新.cursorrules 中的"文档目录组织"章节
    -   重命名目录：更新所有相关路径引用
    -   调整文档层级：更新文档结构说明

-   **🔴 重要文档变更**：

    -   新增标准模板：在"文档模板体系"中添加说明
    -   更新开发规范：同步调整.cursorrules 中对应的规范要求
    -   修改工作流程：更新"文档更新标准工作流程"

-   **🔴 技术环境变更**：

    -   环境要求调整：更新.cursorrules 中的技术栈规范
    -   配置信息变更：同步更新相关配置说明
    -   启动流程调整：更新开发指导相关内容

-   **🔴 业务模块变更**：
    -   新增业务模块：在.cursorrules 中添加模块说明
    -   模块架构调整：更新业务模块文档管理规范
    -   API 接口变更：确保.cursorrules 中的 API 规范同步

**强制检查清单**：

-   [ ] .cursorrules 中的文档目录结构是否与实际一致
-   [ ] 重要文档路径引用是否全部更新
-   [ ] 新增的开发规范是否已同步到.cursorrules
-   [ ] 技术要求和环境配置是否保持一致

### ⏰ 时间填写强制性规范

**🚨 重要：每次记录变更必须填写真实的当前时间！**

#### 强制性时间填写要求：

1. **变更时间**：必须填写变更发生的实际时间，不得使用错误或虚假时间
2. **时间格式**：严格按照 `YYYY-MM-DD HH:mm:ss` 格式填写
3. **时区规范**：使用北京时间（UTC+8）
4. **获取方法**：
    - 在 macOS/Linux 系统中使用 `date "+%Y-%m-%d %H:%M:%S"` 命令
    - 在 Windows 系统中使用 `Get-Date -Format "yyyy-MM-dd HH:mm:ss"` 命令
    - 或使用当前系统显示的时间
5. **验证要求**：变更时间必须与实际代码修改时间相符

#### 错误示例：

-   ❌ 使用 1 月份时间但实际是 6 月份
-   ❌ 使用固定模板时间不修改
-   ❌ 时间格式不正确

#### 正确示例：

-   ✅ 2025-06-30 15:43:20 （实际是 6 月 30 日下午 3 点 43 分）
-   ✅ 2025-06-30 18:30:00 （实际是 6 月 30 日晚上 6 点 30 分）

### 📝 变更记录排序规范

**🚨 重要：变更记录必须按照倒序排列，最新记录在最上面！**

#### 记录排序要求：

1. **排序原则**：按时间倒序排列，最新的变更记录放在文件最上面
2. **新增记录**：每次新增变更记录都必须插入到文件开头（标题下方）
3. **时间顺序**：确保后面的记录时间早于前面的记录时间
4. **便于查看**：这样安排便于快速查看最近的变更情况

#### 正确的排序示例：

```markdown
# 代码调整记录

## 调整记录 - 2025-06-30 18:30:00 ← 最新记录

## 调整记录 - 2025-06-30 15:43:20 ← 次新记录

## 调整记录 - 2025-06-29 10:20:00 ← 更早记录

## 调整记录 - 2025-06-28 14:15:00 ← 最早记录
```

#### 错误示例：

-   ❌ 新记录添加到文件末尾
-   ❌ 时间顺序混乱
-   ❌ 按正序排列（最早在上面）

### 🔄 文档更新标准工作流程

#### Cursor AI 辅助开发的文档更新流程：

```
1. **AI代码生成/修改完成**
   ↓
2. **立即检查文档更新需求**
   - 是否涉及API变更？
   - 是否涉及数据库变更？
   - 是否涉及业务逻辑变更？
   - 是否涉及配置变更？
   - 是否涉及docs文档结构变更？
   ↓
3. **立即更新相关文档**（不得延后！）
   - 使用标准模板格式
   - 确保信息准确完整
   - 添加真实示例
   - ⚠️ 填写真实的当前时间，不得使用模板时间
   ↓
4. **检查并更新.cursorrules文件**（重要！）
   - 如有docs文档结构变更，同步更新.cursorrules
   - 如有技术要求变更，同步更新技术栈规范
   - 如有开发流程变更，同步更新工作流程
   ↓
5. **记录变更日志**（按倒序插入到当日文件开头！）
   - 检查并创建当日变更记录文件：`code-adjust-record-YYYY-MM-DD-{username}.md`
   - 在当日文件开头添加新记录（倒序排列）
   - 无需维护索引文件，专注于自己的变更记录
   - 标注已同步更新的文档列表
   - 标注是否已更新.cursorrules文件
   ↓
6. **验证文档准确性**
   - 确保文档与实际代码一致
   - 验证示例可以正常运行
   - 验证.cursorrules与实际项目状态一致
   - 确认记录时间排序正确
   ↓
7. **提交代码和文档变更**
```

### 📝 变更记录文件管理规范

**🚨 重要：从 2025-06-30 开始，变更记录按日期和用户分文件管理！**

#### 📁 文件命名规范

-   **文件格式**: `code-adjust-record-YYYY-MM-DD-{username}.md`
-   **存放位置**: `docs/变更管理/` 目录
-   **命名示例**: `code-adjust-record-2025-06-30-zlwu.md`
-   **获取用户名**: 使用 `git config --get user.name` 命令获取
-   **获取日期**: 使用 `date "+%Y-%m-%d"` 命令获取

#### 🔄 文件创建和使用流程

1. **检查当日文件是否存在**：

    ```bash
    USERNAME=$(git config --get user.name)
    TODAY=$(date "+%Y-%m-%d")
    FILENAME="docs/变更管理/code-adjust-record-${TODAY}-${USERNAME}.md"
    ```

2. **文件不存在时创建新文件**：

    - 使用标准模板创建当日变更记录文件
    - 文件头包含日期、用户名、排序说明

3. **记录变更时**：
    - 在当日文件开头插入新记录（倒序排列）
    - 无需维护索引文件，每人管理自己的变更记录

#### 👥 多用户协作规范

-   **独立管理**: 每个用户有独立的日变更文件，完全避免多人同时编辑冲突
-   **无需协调**: 不需要维护共享索引文件，每人管理自己的变更记录
-   **用户名一致性**: 确保 git 用户名配置正确，保持文件命名的一致性
-   **文件归档**: 历史文件保留，便于追溯和审计
-   **查找便利**: 通过文件名快速定位特定日期和用户的变更记录

#### 📋 每日变更文件标准格式

```markdown
# 代码调整记录 - YYYY-MM-DD - {username}

> 📅 **记录日期**: YYYY-MM-DD  
> 👤 **记录人员**: {username}  
> 📌 **排序说明**: 本文件按照时间倒序排列，最新的变更记录在最上面

## 调整记录 - YYYY-MM-DD HH:mm:ss

**变更 ID**: CHG-YYYYMMDD-001
**变更时间**: YYYY-MM-DD HH:mm:ss （⚠️ 必须填写真实的当前时间！）
**变更人员**: [开发者姓名/Cursor AI 辅助]
**变更类型**: 🆕 新功能/🐛Bug 修复/🔧 重构优化/📚 文档更新/⚙️ 配置调整
**影响级别**: 🔴 重大变更/🟡 中等变更/🟢 小变更

### 📋 变更概述

**变更目的**: [简述变更原因和目标，1-2 句话]
**影响范围**: [列出受影响的模块、功能或文件]

### 📁 涉及文件

**后端文件**:

-   backend/[具体文件路径 1]
-   backend/[具体文件路径 2]

**前端文件**:

-   web/[具体文件路径 1]
-   web/[具体文件路径 2]

**配置文件**:

-   [配置文件路径]

### 🔧 变更内容详述

**业务逻辑变更**:

1. [具体业务逻辑的变更说明]
2. [新增或修改的业务规则]

**技术实现变更**:

1. [技术方案的调整说明]
2. [代码结构的优化内容]

**接口变更**:

-   **新增接口**: [新增接口列表]
-   **修改接口**: [修改的接口及变更内容]
-   **废弃接口**: [废弃的接口及替代方案]

**数据库变更**:

-   **新增表**: [新增表及字段说明]
-   **修改表**: [表结构变更内容]
-   **数据迁移**: [数据迁移脚本或说明]

### 📖 文档同步更新记录

**API 文档**:

-   [ ] ✅ 已更新 docs/开发文档/API.md
-   [ ] ✅ 已更新模块 API 接口设计文档

**业务文档**:

-   [ ] ✅ 已更新业务模块文档
-   [ ] ✅ 已更新用户操作手册

**技术文档**:

-   [ ] ✅ 已更新数据库设计文档
-   [ ] ✅ 已更新架构设计文档

**其他文档**:

-   [ ] ✅ 已更新部署文档
-   [ ] ✅ 已更新配置文档

**规范文件**:

-   [ ] ✅ 已检查并同步更新.cursorrules 文件
-   [ ] ✅ 已确认文档结构与.cursorrules 一致

### 🧪 测试验证

**功能测试**:

-   [ ] 单元测试通过
-   [ ] 集成测试通过
-   [ ] 功能验收测试通过

**文档验证**:

-   [ ] 文档内容与代码实现一致
-   [ ] 示例代码可以正常运行
-   [ ] 接口文档已验证准确性

### 📝 备注

**已知问题**: [如有已知问题需要说明]
**后续计划**: [后续的改进或扩展计划]
**相关链接**: [相关的 Issue、PR 或文档链接]

---
```

## 3. 🔧 业务模块文档管理（为 Cursor AI 提供完整上下文）

### 业务模块文档标准结构

每个业务模块都必须包含以下完整文档：

```
业务模块/[模块名称]/
├── README.md                    # 模块总览
├── 需求分析/
│   ├── 业务需求说明.md           # 详细业务需求
│   ├── 功能需求清单.md           # 功能点清单
│   ├── 非功能需求.md             # 性能、安全要求
│   └── 用户故事.md               # 用户使用场景
├── 技术设计/
│   ├── 数据库设计.md             # 表结构设计
│   ├── API接口设计.md            # 接口定义
│   ├── 架构设计.md               # 模块架构
│   └── 技术选型.md               # 技术决策说明
├── 实现文档/
│   ├── 后端实现说明.md           # 后端代码结构
│   ├── 前端实现说明.md           # 前端代码结构
│   ├── 关键业务逻辑.md           # 核心算法逻辑
│   └── 代码规范.md               # 编码规范
├── 测试文档/
│   ├── 测试计划.md               # 测试策略
│   ├── 测试用例.md               # 具体测试用例
│   └── 测试报告.md               # 测试结果
└── 运维文档/
    ├── 部署指南.md               # 部署步骤
    ├── 监控配置.md               # 监控指标
    └── 故障处理.md               # 常见问题
```

### 🤖 Cursor AI 开发提示词模板

#### 新功能开发提示词：

```
基于以下业务模块文档为 [功能名称] 开发代码：

业务上下文：docs/业务模块/[模块名称]/需求分析/
技术规范：docs/业务模块/[模块名称]/技术设计/
代码结构：docs/业务模块/[模块名称]/实现文档/
API规范：docs/开发文档/API.md

请确保：
1. 遵循项目编码规范
2. 使用标准的代码结构
3. 添加完整的注释
4. 生成单元测试代码
5. 立即更新相关文档

开发完成后请同步更新：
- docs/开发文档/API.md（如涉及API）
- docs/业务模块/[模块名称]/相关文档
- docs/变更管理/code-adjust-record.md
```

#### 文档更新提示词：

```
根据刚才的代码变更，请更新以下文档：

变更内容：[具体变更说明]
影响模块：[模块名称]

需要更新的文档：
1. docs/开发文档/API.md - [具体更新内容]
2. docs/业务模块/[模块名称]/[具体文档] - [具体更新内容]
3. docs/设计文档/database/ - [如涉及数据库变更]

请使用标准的文档模板格式，确保信息准确完整。
```

## 4. 📚 API 文档管理规范

### 💡 基于场地预约 API 开发实践的文档管理最佳实践

**⚠️ 本规范基于场地预约管理系统的完整开发流程制定，为所有 API 模块开发提供标准参考**

#### 🚨 API 开发文档管理完整流程

**基于`docs/开发文档/API/场地预约管理API.md`的成功模式**：

```
步骤1: 需求文档创建
├── docs/需求文档/[模块名]/系统需求说明.md     # 详细业务需求
└── docs/业务模块/[模块名]/README.md          # 技术架构说明

步骤2: 数据库设计文档
├── docs/设计文档/database/[模块名]-module.sql   # 数据表结构
├── docs/设计文档/database/[模块名]-data.sql     # 字典数据
└── docs/设计文档/database/[模块名]-menu.sql     # 菜单权限

步骤3: API接口开发文档
├── docs/开发文档/API/[模块名]管理API.md         # 完整API文档
└── docs/开发文档/API/API文档总览.md             # 更新导航索引

步骤4: 测试脚本文档
└── test/[模块名]API测试脚本.py                  # 自动化测试脚本

步骤5: 变更记录文档
└── docs/变更管理/code-adjust-record-YYYY-MM-DD-{username}.md
```

#### 📋 API 文档标准结构（400+行标准）

**基于场地预约 API 文档的成功模板**：

````markdown
# [模块名]管理 API

## 📖 概述

**功能描述**: [模块核心功能说明]
**模块路径**: [API 路径前缀]
**权限要求**: [权限标识前缀]
**开发状态**: ✅ 已完成

## 🔑 核心功能

-   [功能 1] - [功能描述]
-   [功能 2] - [功能描述]
-   [功能 3] - [功能描述]

## 🏢 [主实体]信息管理 API

### 1. 查询[主实体]列表

**接口地址**: `GET /[module]/[entity]/list`
**权限要求**: `@SaCheckPermission("[module]:[entity]:list")`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页数量，默认 10 |

**响应示例**:

```json
{
    "total": 5,
    "rows": [
        {
            "id": 1,
            "name": "示例数据",
            "createTime": "2025-07-01 20:30:00"
        }
    ],
    "code": 200,
    "msg": "查询成功"
}
```
````

### 2. 查询[主实体]详情

**接口地址**: `GET /[module]/[entity]/{id}`
**权限要求**: `@SaCheckPermission("[module]:[entity]:query")`

### 3. 新增[主实体]

**接口地址**: `POST /[module]/[entity]`
**权限要求**: `@SaCheckPermission("[module]:[entity]:add")`

### 4. 修改[主实体]

**接口地址**: `PUT /[module]/[entity]`
**权限要求**: `@SaCheckPermission("[module]:[entity]:edit")`

### 5. 删除[主实体]

**接口地址**: `DELETE /[module]/[entity]/{ids}`
**权限要求**: `@SaCheckPermission("[module]:[entity]:remove")`

### 6. 获取可用[主实体]

**接口地址**: `GET /[module]/[entity]/available`
**权限要求**: `@SaCheckPermission("[module]:[entity]:query")`

## 📅 [业务实体]管理 API

### 7. 查询[业务实体]列表

### 8. 查询我的[业务实体]

### 9. 查询待审批[业务实体]

### 10. 查询[业务实体]详情

### 11. 新增[业务实体]

### 12. 修改[业务实体]

### 13. 删除[业务实体]

### 14. [业务规则]检查

### 15. 审批[业务实体]

### 16. 导出[业务实体]

## 📋 数据字典

### [实体类型]字典

| 值    | 标签   | 说明        |
| ----- | ------ | ----------- |
| type1 | 类型 1 | 类型 1 说明 |
| type2 | 类型 2 | 类型 2 说明 |

## 🔐 权限配置

### 菜单权限配置

| 权限 ID | 权限名称   | 权限标识               | 权限类型 |
| ------- | ---------- | ---------------------- | -------- |
| 2200    | [模块]管理 | [module]:main          | 目录     |
| 2210    | [实体]管理 | [module]:[entity]:list | 菜单     |

## 📏 业务规则

### [业务规则 1]

### [业务规则 2]

## ❌ 错误码说明

| 错误码 | 错误信息 | 说明             |
| ------ | -------- | ---------------- |
| 400    | 参数错误 | 请求参数格式错误 |
| 401    | 未认证   | Token 无效或过期 |

`````

#### 🔄 API文档更新工作流程

**基于场地预约开发的完整流程**：

1. **代码开发完成** → 立即创建/更新API文档
2. **API文档完成** → 更新API文档总览的导航
3. **测试脚本完成** → 在API文档中添加测试脚本说明
4. **文档验证** → 确保API文档与实际代码一致
5. **变更记录** → 在变更日志中记录文档更新

#### 📊 API文档质量标准

**基于场地预约API文档的质量标准**：

- ✅ **完整性**: 16个标准接口的完整文档
- ✅ **准确性**: 所有参数和响应与实际代码一致
- ✅ **详细性**: 包含完整的业务规则和错误码说明
- ✅ **规范性**: 使用统一的文档模板和格式
- ✅ **可测试性**: 提供真实的请求响应示例

### 🔴 强制性 API 文档更新规则

**⚠️ 超级重要：任何 API 接口的新增、修改、删除都必须立即同步更新 `docs/开发文档/API.md` 文档！**

### API 文档标准格式

使用 `docs/开发文档/API/API文档模板.md` 中的标准格式：

````markdown
#### 接口名称

**接口地址**: `HTTP方法 /api/路径`
**接口描述**: 接口功能的详细描述
**权限要求**: 权限代码或"需要登录"

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| param1 | String | Y | 参数说明 | "example" |

**响应示例**:

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {}
}
`````

````

**错误码**:
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 400001 | 参数错误 | 检查请求参数 |

```

### 🚨 API变更强制检查清单

当进行以下操作时，必须更新 `docs/开发文档/API.md`：

**Controller层变更**：
- [ ] 新增Controller类 → 在API.md中添加新的模块章节
- [ ] 新增@RequestMapping方法 → 添加完整的接口文档
- [ ] 修改@RequestMapping路径 → 更新接口地址
- [ ] 修改HTTP方法 → 更新接口方法
- [ ] 删除接口方法 → 标记为已废弃并说明替代方案

**参数和响应变更**：
- [ ] 新增请求参数 → 更新请求参数表格
- [ ] 修改参数类型或必填属性 → 更新参数说明
- [ ] 修改响应数据结构 → 更新响应示例
- [ ] 新增错误码 → 更新错误码说明表

**权限和安全变更**：
- [ ] 新增@SaCheckPermission注解 → 更新权限要求
- [ ] 修改权限代码 → 更新权限说明
- [ ] 修改接口访问级别 → 更新权限要求说明

## 5. 📊 文档模板体系

### 已创建的标准模板：
- **`docs/项目总览/项目总览模板.md`** - 项目基本信息模板
- **`docs/业务模块/业务模块开发模板.md`** - 业务模块开发标准模板
- **`docs/开发文档/API/API文档模板.md`** - API接口文档标准模板

### 模板使用规范：
1. **新项目或模块开发时**：复制对应模板，替换占位符
2. **文档更新时**：参考模板格式，保持结构一致
3. **Cursor AI生成文档时**：使用模板作为格式参考

## 6. 🔍 文档质量控制

### 文档完整性检查清单：
- [ ] 文档结构符合标准模板
- [ ] 内容与实际代码实现一致
- [ ] API文档包含完整示例
- [ ] 业务逻辑描述清晰准确
- [ ] 技术实现说明详细
- [ ] 变更历史有完整记录
- [ ] 所有占位符已替换为真实内容

### 文档准确性验证：
- [ ] API接口示例可以正常调用
- [ ] 数据库脚本可以成功执行
- [ ] 配置文档与实际配置一致
- [ ] 部署文档可以成功部署

## 7. 🧪 测试文档管理规范

### 🔴 测试文档组织原则
- **按需求维度分类**：测试文档必须按照业务需求模块进行组织，不得混合存放
- **结论性文档独立存放**：测试结论性文档必须存放在 `docs/测试文档/` 目录下
- **测试代码独立存放**：测试相关代码必须只存放在 `test/` 目录下
- **日期标识规范**：每次创建的测试文档必须以日期结尾来区分版本

### 🔴 测试文档目录结构规范
```

docs/测试文档/
├── README.md # 测试文档管理总览
├── [业务模块]/ # 按业务模块分类
│ ├── [具体功能]/ # 具体功能测试
│ │ ├── [功能]接口测试报告-YYYY-MM-DD.md # 接口测试报告
│ │ ├── [功能]功能测试报告-YYYY-MM-DD.md # 功能测试报告
│ │ ├── [功能]性能测试报告-YYYY-MM-DD.md # 性能测试报告
│ │ └── [功能]集成测试报告-YYYY-MM-DD.md # 集成测试报告
│ └── ...
└── ...

test/
├── package.json # 测试依赖配置
├── [功能]-api-test.js # API 接口测试脚本
├── [功能]-detailed-test.js # 详细测试分析脚本
├── [功能]-performance-test.js # 性能测试脚本
└── ...

```

### 🔴 测试文档强制要求

#### 1. 测试结论性文档放置规则
- **强制位置**：必须放置在 `docs/测试文档/` 目录下
- **分类方式**：按照需求维度创建子文件夹存放
- **命名规范**：文档名称必须以日期结尾（格式：YYYY-MM-DD）
- **示例路径**：
```

docs/测试文档/后勤管理/物业报修/物业报修接口测试报告-2025-01-26.md
docs/测试文档/系统管理/用户管理/用户管理功能测试报告-2025-01-26.md

```

#### 2. 测试代码存放规则
- **强制位置**：只能存放在 `test/` 目录下
- **禁止混合**：test目录下不得存放测试结论性文档
- **代码分类**：按功能模块组织测试脚本
- **示例文件**：
```

test/pm-repair-api-test.js # 物业报修 API 测试
test/user-management-test.js # 用户管理测试
test/custom-login-script.js # 登录认证工具

````

#### 3. 测试文档必含信息

每个测试结论性文档必须包含以下信息：

-   **📁 测试代码路径**：明确标注对应的测试脚本位置
-   **🔧 使用方法**：详细说明如何运行测试脚本
-   **📊 测试结果**：完整的测试结果和数据分析
-   **🎯 结论建议**：明确的测试结论和改进建议
-   **⚠️ 问题记录**：发现的问题和解决方案

#### 测试文档标准模板格式：

````markdown
# [功能模块]测试报告

## 🎯 测试概览

**测试时间**: YYYY-MM-DD HH:mm:ss （⚠️ 必须填写真实的当前时间！）
**测试范围**: [具体测试范围]
**需求模块**: [所属业务模块]

## 📁 测试代码路径

**测试脚本位置**:

-   **主要测试脚本**: `test/[功能]-api-test.js`
-   **详细分析脚本**: `test/[功能]-detailed-test.js`
-   **辅助工具脚本**: `test/[工具名].js`

**使用方法**:

```bash
cd test
npm install
node [功能]-api-test.js
```
````

## ✅ 测试结果总结

[测试结果详细内容]

## 🎯 结论

[测试结论和建议]

---

**测试执行**: 基于 `test/` 目录下的测试脚本
**文档路径**: `docs/测试文档/[模块]/[功能]/[报告名称]-YYYY-MM-DD.md`

```

### 🔴 强制工作流程

#### 测试执行流程：
```

1. **编写测试代码**
    - 在 test/ 目录下创建测试脚本
    - 确保代码可独立运行
      ↓
2. **执行测试**
    - 运行测试脚本获取结果
    - 记录详细的测试数据
      ↓
3. **创建测试报告**
    - 在 docs/测试文档/ 按需求维度创建报告
    - 文档名称必须包含日期后缀
    - 必须包含测试代码路径信息
      ↓
4. **清理 test 目录**
    - 删除 test 目录下的结论性文档
    - 只保留测试代码和配置文件
      ↓
5. **更新文档索引**
    - 更新相关 README.md 文件
    - 在变更记录中记录测试活动

```

### 🔴 违规检查和纠正
- **检查要点**：
  - [ ] test/目录下是否只有代码文件
  - [ ] docs/测试文档/下是否按需求维度组织
  - [ ] 测试报告是否包含代码路径信息
  - [ ] 文档命名是否包含日期后缀

- **纠正措施**：
  - 立即移动错误放置的文档到正确位置
  - 补充缺失的测试代码路径信息
  - 按规范重新组织文档结构
```

### 原型文件自动保存规范

1. **文件位置**：

    - 移动端原型 → `docs/原型文件/移动端/`
    - Web 端原型 → `docs/原型文件/web端/`

2. **自动保存触发条件**：

    - 新建原型文件时自动创建目录结构
    - 修改文件时自动保留历史版本（按`[功能]_v[版本]_[日期]`格式）

3. **文件权限预设**：

    ```bash
    chmod 755 docs/原型文件/  # 确保目录可写
    ```

4. **冲突解决策略**：
    - 同名文件自动添加版本后缀
    - 中文路径自动转换为 UTF-8 编码