253 lines
13 KiB
Markdown
253 lines
13 KiB
Markdown
# docs 文件夹结构优化方案
|
||
|
||
## 📋 优化目标
|
||
|
||
1. **全过程管理**：从项目需求到项目交付的完整文档记录
|
||
2. **AI 辅助开发**：便于 Cursor AI 快速理解业务上下文和技术细节
|
||
3. **模块化管理**：同一业务模块的文档聚合，便于查找和维护
|
||
4. **版本追踪**：完善的变更记录和版本管理
|
||
|
||
## 🏗️ 新的目录结构设计
|
||
|
||
```
|
||
docs/
|
||
├── 📋 项目总览/ # 项目总览（新增）
|
||
│ ├── README.md # 项目整体介绍
|
||
│ ├── tech-stack.md # 技术栈说明
|
||
│ ├── project-timeline.md # 项目时间线
|
||
│ └── team-roles.md # 团队角色分工
|
||
│
|
||
├── 📊 业务模块/ # 业务模块文档（新增）
|
||
│ ├── README.md # 业务模块总览
|
||
│ ├── user-management/ # 用户管理模块
|
||
│ │ ├── requirements.md # 需求文档
|
||
│ │ ├── design.md # 设计文档
|
||
│ │ ├── api.md # API接口文档
|
||
│ │ ├── database.md # 数据库设计
|
||
│ │ └── test-cases.md # 测试用例
|
||
│ ├── hq-satisfaction-survey/ # 后勤满意度调查
|
||
│ │ ├── requirements.md
|
||
│ │ ├── design.md
|
||
│ │ ├── api.md
|
||
│ │ ├── database.md
|
||
│ │ └── workflow.md
|
||
│ ├── hall-reservation/ # 报告厅预约
|
||
│ │ ├── requirements.md
|
||
│ │ ├── design.md
|
||
│ │ ├── api.md
|
||
│ │ └── database.md
|
||
│ └── system-management/ # 系统管理模块
|
||
│ ├── requirements.md
|
||
│ ├── design.md
|
||
│ ├── api.md
|
||
│ └── database.md
|
||
│
|
||
├── 🎯 需求文档/ # 需求阶段文档（保留并优化）
|
||
│ ├── README.md # 需求管理总说明
|
||
│ ├── project-requirements.md # 项目整体需求
|
||
│ ├── functional-requirements/ # 功能需求
|
||
│ │ ├── README.md
|
||
│ │ └── [各模块功能需求].md
|
||
│ ├── non-functional-requirements/ # 非功能需求
|
||
│ │ ├── performance.md # 性能需求
|
||
│ │ ├── security.md # 安全需求
|
||
│ │ └── usability.md # 可用性需求
|
||
│ └── requirements-traceability.md # 需求追踪矩阵
|
||
│
|
||
├── 🏗️ 设计文档/ # 设计阶段文档（保留并优化）
|
||
│ ├── README.md # 设计文档总说明
|
||
│ ├── architecture/ # 系统架构设计
|
||
│ │ ├── system-architecture.md # 系统架构图
|
||
│ │ ├── technology-selection.md # 技术选型
|
||
│ │ └── deployment-architecture.md # 部署架构
|
||
│ ├── database/ # 数据库设计（保留现有）
|
||
│ │ ├── README.md
|
||
│ │ ├── hzdyjs_xg.sql # 完整数据库脚本
|
||
│ │ ├── database_msg.md # 环境配置信息
|
||
│ │ ├── er-diagram.md # ER图
|
||
│ │ └── data-dictionary.md # 数据字典
|
||
│ ├── api-design/ # API设计
|
||
│ │ ├── api-standards.md # API设计规范
|
||
│ │ ├── api-authentication.md # 认证设计
|
||
│ │ └── api-versioning.md # 版本管理
|
||
│ ├── ui-design/ # UI设计
|
||
│ │ ├── design-system.md # 设计系统
|
||
│ │ ├── prototypes/ # 原型文件
|
||
│ │ └── style-guide.md # 样式指南
|
||
│ └── security-design.md # 安全设计
|
||
│
|
||
├── 💻 开发文档/ # 开发阶段文档（保留并优化）
|
||
│ ├── README.md # 开发指南总说明
|
||
│ ├── environment-setup/ # 环境搭建
|
||
│ │ ├── local-development.md # 本地开发环境
|
||
│ │ ├── docker-setup.md # Docker环境
|
||
│ │ └── ide-configuration.md # IDE配置
|
||
│ ├── coding-standards/ # 编码规范
|
||
│ │ ├── java-standards.md # Java规范
|
||
│ │ ├── vue-standards.md # Vue规范
|
||
│ │ ├── database-standards.md # 数据库规范
|
||
│ │ └── git-workflow.md # Git工作流
|
||
│ ├── API.md # 完整API文档（保留）
|
||
│ ├── code-templates/ # 代码模板
|
||
│ │ ├── controller-template.md # Controller模板
|
||
│ │ ├── service-template.md # Service模板
|
||
│ │ └── vue-component-template.md # Vue组件模板
|
||
│ ├── integration-guides/ # 集成指南
|
||
│ │ ├── third-party-services.md # 第三方服务集成
|
||
│ │ ├── payment-integration.md # 支付集成
|
||
│ │ └── auth-integration.md # 认证集成
|
||
│ └── troubleshooting.md # 问题排查指南
|
||
│
|
||
├── 🧪 测试文档/ # 测试阶段文档（保留并优化）
|
||
│ ├── README.md # 测试文档总说明
|
||
│ ├── test-strategy.md # 测试策略
|
||
│ ├── test-plans/ # 测试计划
|
||
│ │ ├── unit-test-plan.md # 单元测试计划
|
||
│ │ ├── integration-test-plan.md # 集成测试计划
|
||
│ │ └── system-test-plan.md # 系统测试计划
|
||
│ ├── test-cases/ # 测试用例
|
||
│ │ ├── functional-test-cases.md # 功能测试用例
|
||
│ │ ├── performance-test-cases.md # 性能测试用例
|
||
│ │ └── security-test-cases.md # 安全测试用例
|
||
│ ├── test-data/ # 测试数据
|
||
│ │ ├── test-data-setup.md # 测试数据准备
|
||
│ │ └── sample-data.sql # 示例数据
|
||
│ └── test-reports/ # 测试报告
|
||
│ ├── test-execution-reports.md # 测试执行报告
|
||
│ └── bug-reports.md # 缺陷报告
|
||
│
|
||
├── 🚀 部署文档/ # 部署阶段文档（保留并优化）
|
||
│ ├── README.md # 部署指南总说明
|
||
│ ├── environments/ # 环境配置
|
||
│ │ ├── development.md # 开发环境
|
||
│ │ ├── staging.md # 测试环境
|
||
│ │ └── production.md # 生产环境
|
||
│ ├── infrastructure/ # 基础设施
|
||
│ │ ├── server-requirements.md # 服务器要求
|
||
│ │ ├── network-configuration.md # 网络配置
|
||
│ │ └── monitoring-setup.md # 监控配置
|
||
│ ├── deployment-guides/ # 部署指南
|
||
│ │ ├── manual-deployment.md # 手动部署
|
||
│ │ ├── docker-deployment.md # Docker部署
|
||
│ │ └── ci-cd-pipeline.md # CI/CD流水线
|
||
│ └── maintenance/ # 运维文档
|
||
│ ├── backup-restore.md # 备份恢复
|
||
│ ├── performance-tuning.md # 性能调优
|
||
│ └── troubleshooting.md # 故障排除
|
||
│
|
||
├── ⚙️ 中间件配置/ # 中间件配置（保留并扩展）
|
||
│ ├── README.md # 中间件配置总说明
|
||
│ ├── database/ # 数据库配置
|
||
│ │ ├── mysql-config.md # MySQL配置（保留）
|
||
│ │ ├── redis-config.md # Redis配置
|
||
│ │ └── connection-pool.md # 连接池配置
|
||
│ ├── web-server/ # Web服务器
|
||
│ │ ├── nginx-config.md # Nginx配置
|
||
│ │ └── ssl-certificate.md # SSL证书配置
|
||
│ ├── message-queue/ # 消息队列
|
||
│ │ ├── rabbitmq-config.md # RabbitMQ配置
|
||
│ │ └── kafka-config.md # Kafka配置
|
||
│ └── monitoring/ # 监控组件
|
||
│ ├── prometheus-config.md # Prometheus配置
|
||
│ └── grafana-config.md # Grafana配置
|
||
│
|
||
├── 📝 变更管理/ # 变更管理（新增，整合现有记录）
|
||
│ ├── README.md # 变更管理说明
|
||
│ ├── code-adjust-record.md # 代码调整记录（迁移）
|
||
│ ├── requirement-changes.md # 需求变更记录
|
||
│ ├── database-changes.md # 数据库变更记录
|
||
│ ├── api-changes.md # API变更记录
|
||
│ └── deployment-changes.md # 部署变更记录
|
||
│
|
||
├── 📚 知识库/ # 知识库（新增）
|
||
│ ├── README.md # 知识库说明
|
||
│ ├── best-practices/ # 最佳实践
|
||
│ │ ├── coding-best-practices.md # 编码最佳实践
|
||
│ │ ├── security-best-practices.md # 安全最佳实践
|
||
│ │ └── performance-best-practices.md # 性能最佳实践
|
||
│ ├── lessons-learned/ # 经验教训
|
||
│ │ ├── project-retrospectives.md # 项目回顾
|
||
│ │ └── technical-decisions.md # 技术决策记录
|
||
│ ├── external-resources/ # 外部资源
|
||
│ │ ├── useful-links.md # 有用链接
|
||
│ │ └── reference-materials.md # 参考资料
|
||
│ └── faq.md # 常见问题
|
||
│
|
||
└── 📊 报告文档/ # 报告文档（新增）
|
||
├── README.md # 报告说明
|
||
├── project-progress/ # 项目进度
|
||
│ ├── weekly-reports.md # 周报
|
||
│ └── milestone-reports.md # 里程碑报告
|
||
├── quality-reports/ # 质量报告
|
||
│ ├── code-quality.md # 代码质量报告
|
||
│ └── test-coverage.md # 测试覆盖率报告
|
||
└── delivery-reports/ # 交付报告
|
||
├── release-notes.md # 发布说明
|
||
└── deployment-reports.md # 部署报告
|
||
```
|
||
|
||
## 🎯 优化亮点
|
||
|
||
### 1. 双重导航体系
|
||
|
||
- **按阶段导航**：requirements → design → development → testing → deployment
|
||
- **按模块导航**：business-modules 下按业务模块组织，包含该模块的全生命周期文档
|
||
|
||
### 2. Cursor AI 友好设计
|
||
|
||
- **business-modules**：让 AI 快速理解各业务模块的完整上下文
|
||
- **code-templates**：提供标准代码模板，便于 AI 生成规范代码
|
||
- **API.md**：集中的 API 文档，便于 AI 理解接口设计
|
||
|
||
### 3. 全过程管理
|
||
|
||
- **project-overview**：项目整体信息一目了然
|
||
- **change-management**：完善的变更追踪体系
|
||
- **reports**：定期的项目报告和质量报告
|
||
|
||
### 4. 知识积累
|
||
|
||
- **knowledge-base**：积累项目经验和最佳实践
|
||
- **lessons-learned**：记录项目中的经验教训
|
||
|
||
## 🔄 迁移计划
|
||
|
||
### 第一阶段：保持现有结构运行
|
||
|
||
1. 不破坏现有文档结构
|
||
2. 在现有基础上补充新的目录
|
||
|
||
### 第二阶段：逐步迁移和整合
|
||
|
||
1. 创建新的目录结构
|
||
2. 将现有文档按业务模块重新组织
|
||
3. 建立文档间的交叉引用
|
||
|
||
### 第三阶段：优化和完善
|
||
|
||
1. 完善文档内容
|
||
2. 建立文档维护流程
|
||
3. 定期审查和更新
|
||
|
||
## 📋 实施建议
|
||
|
||
### 立即执行
|
||
|
||
1. 创建`业务模块`目录，按业务模块组织文档
|
||
2. 将`code-adjust-record.md`迁移到`变更管理`目录
|
||
3. 完善`API.md`文档的模块化组织
|
||
|
||
### 逐步完善
|
||
|
||
1. 补充`项目总览`相关文档
|
||
2. 建立`知识库`知识库
|
||
3. 完善各阶段文档的模块化组织
|
||
|
||
### 长期维护
|
||
|
||
1. 建立文档更新机制，与代码变更同步
|
||
2. 定期审查文档结构的合理性
|
||
3. 根据项目发展调整文档组织方式
|
||
|
||
这个优化方案既保持了项目全过程管理的清晰性，又便于 Cursor AI 理解具体业务上下文，同时为项目的长期发展提供了良好的文档基础。
|