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. 便于查看：这样安排便于快速查看最近的变更情况

正确的排序示例：

# 代码调整记录

## 调整记录 - 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. 检查当日文件是否存在：

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

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

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

3. 记录变更时：

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

👥 多用户协作规范

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

📋 每日变更文件标准格式

# 代码调整记录 - 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 文档的成功模板：

# [模块名]管理 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. 测试文档必含信息

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

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

测试文档标准模板格式：

# [功能模块]测试报告

## 🎯 测试概览

**测试时间**: 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. 文件权限预设：

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

4. 冲突解决策略：

   • 同名文件自动添加版本后缀
   • 中文路径自动转换为 UTF-8 编码