650 lines
15 KiB
Markdown
650 lines
15 KiB
Markdown
# 开发文档中心
|
||
|
||
## 📋 开发文档概述
|
||
|
||
开发文档中心提供项目开发所需的所有技术文档和规范，为 **Cursor AI 辅助开发** 提供完整的技术上下文和开发指南。
|
||
|
||
## 🎯 文档目标
|
||
|
||
### 为 Cursor AI 提供的价值
|
||
|
||
- **🔧 技术规范**：统一的编码规范和开发标准
|
||
- **📚 API 文档**：完整的接口定义和使用说明
|
||
- **⚙️ 架构指南**：系统架构和技术选型说明
|
||
- **🛠️ 工具配置**：开发工具和环境配置指南
|
||
|
||
### 文档维护原则
|
||
|
||
- **实时同步**：API 变更时立即更新文档
|
||
- **详细准确**：提供完整的技术细节和示例
|
||
- **版本管理**：记录文档版本和变更历史
|
||
- **易于理解**：清晰的结构和标准化描述
|
||
|
||
## 📁 文档结构
|
||
|
||
```
|
||
开发文档/
|
||
├── README.md # 本文件 - 开发文档总览
|
||
├── API.md # API接口完整文档
|
||
├── 开发规范/
|
||
│ ├── 后端开发规范.md # Java/Spring Boot开发规范
|
||
│ ├── 前端开发规范.md # Vue3/TypeScript开发规范
|
||
│ ├── 数据库规范.md # 数据库设计和操作规范
|
||
│ ├── 代码审查规范.md # 代码审查流程和标准
|
||
│ └── Git使用规范.md # Git分支和提交规范
|
||
├── 技术架构/
|
||
│ ├── 系统架构设计.md # 整体系统架构
|
||
│ ├── 技术选型说明.md # 技术栈选择理由
|
||
│ ├── 安全架构设计.md # 安全体系设计
|
||
│ └── 性能优化指南.md # 性能优化策略
|
||
├── 环境配置/
|
||
│ ├── 开发环境搭建.md # 本地开发环境配置
|
||
│ ├── 测试环境配置.md # 测试环境搭建
|
||
│ ├── 生产环境部署.md # 生产环境部署指南
|
||
│ └── 工具配置指南.md # IDE和工具配置
|
||
├── 最佳实践/
|
||
│ ├── 代码结构设计.md # 代码组织和结构设计
|
||
│ ├── 异常处理规范.md # 异常处理最佳实践
|
||
│ ├── 日志记录规范.md # 日志记录标准
|
||
│ └── 测试策略指南.md # 测试策略和方法
|
||
└── 第三方集成/
|
||
├── 中间件集成.md # Redis、MQ等中间件集成
|
||
├── 第三方服务.md # 第三方API和服务集成
|
||
└── 工具库使用.md # 常用工具库使用指南
|
||
```
|
||
|
||
## 🔌 API 文档管理
|
||
|
||
### API 文档结构
|
||
|
||
#### 1. 完整性要求
|
||
|
||
- **接口地址**：完整的请求路径和 HTTP 方法
|
||
- **参数说明**：详细的请求参数和数据类型
|
||
- **响应格式**：标准的响应体结构和示例
|
||
- **错误码**：完整的错误码定义和处理
|
||
|
||
#### 2. 实时性要求
|
||
|
||
- **同步更新**：代码变更时立即更新 API 文档
|
||
- **版本管理**：记录 API 版本变更历史
|
||
- **兼容性说明**：重大变更的向后兼容性说明
|
||
|
||
#### 3. 标准格式
|
||
|
||
````markdown
|
||
#### 接口名称
|
||
|
||
**接口地址**: `HTTP方法 /api/路径`
|
||
|
||
**接口描述**: 接口功能的详细描述
|
||
|
||
**权限要求**: 权限代码或"需要登录"
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| param1 | String | Y | 参数说明 | "example" |
|
||
| param2 | Integer | N | 参数说明 | 100 |
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "示例"
|
||
}
|
||
}
|
||
```
|
||
````
|
||
|
||
**错误码**:
|
||
| 错误码 | 说明 | 解决方案 |
|
||
|--------|------|----------|
|
||
| 400001 | 参数错误 | 检查请求参数 |
|
||
| 401001 | 未登录 | 请先登录 |
|
||
|
||
````
|
||
|
||
### API 文档自动生成
|
||
|
||
#### Swagger/OpenAPI 集成
|
||
```java
|
||
@RestController
|
||
@RequestMapping("/api/user")
|
||
@Api(tags = "用户管理")
|
||
public class UserController {
|
||
|
||
@ApiOperation(value = "获取用户列表", notes = "分页查询用户列表")
|
||
@ApiImplicitParams({
|
||
@ApiImplicitParam(name = "pageNum", value = "页码", defaultValue = "1"),
|
||
@ApiImplicitParam(name = "pageSize", value = "每页大小", defaultValue = "10")
|
||
})
|
||
@GetMapping("/list")
|
||
public Result<PageInfo<UserVo>> list(UserQueryBo queryBo, PageQuery pageQuery) {
|
||
// 实现逻辑
|
||
}
|
||
}
|
||
````
|
||
|
||
#### 文档生成脚本
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# API文档生成脚本
|
||
generate_api_docs() {
|
||
echo "生成API文档..."
|
||
mvn clean compile
|
||
mvn swagger2markup:convertSwagger2markup
|
||
echo "API文档生成完成：docs/开发文档/API.md"
|
||
}
|
||
```
|
||
|
||
## 💻 开发规范体系
|
||
|
||
### 后端开发规范
|
||
|
||
#### 1. Java 编码规范
|
||
|
||
- **命名规范**：遵循 Java 命名约定
|
||
- **代码结构**：标准的 MVC 分层架构
|
||
- **注释规范**：完整的 JavaDoc 注释
|
||
- **异常处理**：统一的异常处理机制
|
||
|
||
#### 2. Spring Boot 规范
|
||
|
||
```java
|
||
// 标准Controller结构
|
||
@RestController
|
||
@RequestMapping("/api/module")
|
||
@Slf4j
|
||
public class ModuleController extends BaseController {
|
||
|
||
@Autowired
|
||
private IModuleService moduleService;
|
||
|
||
@SaCheckPermission("module:list")
|
||
@GetMapping("/list")
|
||
@Operation(summary = "查询列表")
|
||
public TableDataInfo<ModuleVo> list(ModuleBo bo, PageQuery pageQuery) {
|
||
return moduleService.queryPageList(bo, pageQuery);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 数据库规范
|
||
|
||
```sql
|
||
-- 标准表结构
|
||
CREATE TABLE `module_table` (
|
||
`id` BIGINT(20) NOT NULL COMMENT '主键ID',
|
||
`name` VARCHAR(100) NOT NULL COMMENT '名称',
|
||
`status` TINYINT(1) DEFAULT 1 COMMENT '状态：1启用，0禁用',
|
||
`tenant_id` VARCHAR(20) NOT NULL COMMENT '租户ID',
|
||
`create_by` BIGINT(20) NOT NULL COMMENT '创建人',
|
||
`create_time` DATETIME NOT NULL COMMENT '创建时间',
|
||
`update_by` BIGINT(20) DEFAULT NULL COMMENT '更新人',
|
||
`update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
|
||
`deleted` TINYINT(1) DEFAULT 0 COMMENT '删除标记',
|
||
PRIMARY KEY (`id`),
|
||
KEY `idx_tenant_id` (`tenant_id`),
|
||
KEY `idx_status` (`status`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='模块表';
|
||
```
|
||
|
||
### 前端开发规范
|
||
|
||
#### 1. Vue3 组件规范
|
||
|
||
```vue
|
||
<template>
|
||
<div class="module-container">
|
||
<el-form ref="formRef" :model="formData" :rules="rules">
|
||
<!-- 表单内容 -->
|
||
</el-form>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts" name="ModuleForm">
|
||
import { ref, reactive } from 'vue';
|
||
import type { FormRules } from 'element-plus';
|
||
|
||
// 响应式数据
|
||
const formRef = ref();
|
||
const formData = reactive({
|
||
name: '',
|
||
status: 1,
|
||
});
|
||
|
||
// 表单验证规则
|
||
const rules: FormRules = {
|
||
name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
|
||
};
|
||
|
||
// 方法定义
|
||
const handleSubmit = () => {
|
||
// 提交逻辑
|
||
};
|
||
</script>
|
||
|
||
<style lang="scss" scoped>
|
||
.module-container {
|
||
padding: 20px;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### 2. TypeScript 类型定义
|
||
|
||
```typescript
|
||
// api/types.ts
|
||
export interface ModuleVo {
|
||
id: number;
|
||
name: string;
|
||
status: number;
|
||
createTime: string;
|
||
}
|
||
|
||
export interface ModuleBo {
|
||
name?: string;
|
||
status?: number;
|
||
}
|
||
|
||
export interface ModuleForm {
|
||
id?: number;
|
||
name: string;
|
||
status: number;
|
||
}
|
||
```
|
||
|
||
#### 3. API 调用规范
|
||
|
||
```typescript
|
||
// api/module.ts
|
||
import request from '@/utils/request';
|
||
import type { AxiosPromise } from 'axios';
|
||
|
||
export const listModule = (query?: ModuleBo): AxiosPromise<ModuleVo[]> => {
|
||
return request({
|
||
url: '/api/module/list',
|
||
method: 'get',
|
||
params: query,
|
||
});
|
||
};
|
||
|
||
export const createModule = (data: ModuleForm): AxiosPromise<void> => {
|
||
return request({
|
||
url: '/api/module',
|
||
method: 'post',
|
||
data: data,
|
||
});
|
||
};
|
||
```
|
||
|
||
## 🏗️ 技术架构指南
|
||
|
||
### 系统整体架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "前端层"
|
||
A1[Web管理端<br/>Vue3 + Element Plus]
|
||
A2[移动端<br/>UniApp + uView UI]
|
||
end
|
||
|
||
subgraph "网关层"
|
||
B1[API Gateway<br/>Spring Cloud Gateway]
|
||
B2[负载均衡<br/>Nginx]
|
||
end
|
||
|
||
subgraph "应用层"
|
||
C1[用户服务<br/>Spring Boot]
|
||
C2[业务服务<br/>Spring Boot]
|
||
C3[文件服务<br/>Spring Boot]
|
||
end
|
||
|
||
subgraph "数据层"
|
||
D1[MySQL<br/>主数据库]
|
||
D2[Redis<br/>缓存/会话]
|
||
D3[MinIO<br/>文件存储]
|
||
end
|
||
|
||
subgraph "基础设施"
|
||
E1[Docker<br/>容器化]
|
||
E2[Jenkins<br/>CI/CD]
|
||
E3[ELK<br/>日志监控]
|
||
end
|
||
|
||
A1 --> B2
|
||
A2 --> B2
|
||
B2 --> B1
|
||
B1 --> C1
|
||
B1 --> C2
|
||
B1 --> C3
|
||
|
||
C1 --> D1
|
||
C2 --> D1
|
||
C3 --> D1
|
||
|
||
C1 --> D2
|
||
C2 --> D2
|
||
|
||
C3 --> D3
|
||
```
|
||
|
||
### 技术选型说明
|
||
|
||
#### 后端技术栈
|
||
|
||
- **Spring Boot 3.4.6**：主框架，提供依赖注入和自动配置
|
||
- **Spring Cloud 2023.0.x**：微服务架构支持
|
||
- **MyBatis-Plus 3.5.12**：ORM 框架，简化数据库操作
|
||
- **Sa-Token 1.42.0**：权限认证框架
|
||
- **Redis 7.0**：缓存和会话存储
|
||
- **MySQL 8.0**：主数据库
|
||
|
||
#### 前端技术栈
|
||
|
||
- **Vue 3.5.13**：渐进式 JavaScript 框架
|
||
- **TypeScript 5.8.3**：静态类型检查
|
||
- **Element Plus 2.9.8**：UI 组件库
|
||
- **Vite 7.0.9**：构建工具
|
||
- **Pinia**：状态管理
|
||
|
||
## 🛠️ 开发工具配置
|
||
|
||
### IDE 配置
|
||
|
||
#### IntelliJ IDEA 配置
|
||
|
||
```xml
|
||
<!-- .idea/codeStyles/Project.xml -->
|
||
<component name="ProjectCodeStyleConfiguration">
|
||
<code_scheme name="Project" version="173">
|
||
<option name="LINE_SEPARATOR" value=" " />
|
||
<option name="RIGHT_MARGIN" value="120" />
|
||
<JavaCodeStyleSettings>
|
||
<option name="IMPORT_LAYOUT_TABLE">
|
||
<value>
|
||
<package name="" withSubpackages="true" static="false" />
|
||
</value>
|
||
</option>
|
||
</JavaCodeStyleSettings>
|
||
</code_scheme>
|
||
</component>
|
||
```
|
||
|
||
#### VSCode 配置
|
||
|
||
```json
|
||
{
|
||
"editor.formatOnSave": true,
|
||
"editor.codeActionsOnSave": {
|
||
"source.fixAll.eslint": true
|
||
},
|
||
"typescript.preferences.importModuleSpecifier": "relative",
|
||
"emmet.includeLanguages": {
|
||
"vue": "html"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Git 配置
|
||
|
||
#### .gitignore 模板
|
||
|
||
```bash
|
||
# 编译输出
|
||
target/
|
||
dist/
|
||
build/
|
||
|
||
# 依赖目录
|
||
node_modules/
|
||
|
||
# IDE文件
|
||
.idea/
|
||
.vscode/
|
||
*.iml
|
||
|
||
# 日志文件
|
||
logs/
|
||
*.log
|
||
|
||
# 配置文件
|
||
application-local.yml
|
||
.env.local
|
||
```
|
||
|
||
#### Git Hooks
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# pre-commit hook
|
||
echo "运行代码检查..."
|
||
|
||
# Java代码检查
|
||
mvn checkstyle:check
|
||
if [ $? -ne 0 ]; then
|
||
echo "Java代码规范检查失败！"
|
||
exit 1
|
||
fi
|
||
|
||
# 前端代码检查
|
||
cd web && npm run lint
|
||
if [ $? -ne 0 ]; then
|
||
echo "前端代码规范检查失败！"
|
||
exit 1
|
||
fi
|
||
|
||
echo "代码检查通过！"
|
||
```
|
||
|
||
## 🔧 Cursor AI 开发指南
|
||
|
||
### AI 辅助开发流程
|
||
|
||
#### 1. 需求理解阶段
|
||
|
||
```
|
||
请根据以下需求文档和技术规范，为我开发[功能名称]：
|
||
|
||
业务需求：docs/需求文档/[具体需求文档]
|
||
技术规范：docs/开发文档/[相关规范文档]
|
||
API设计：docs/开发文档/API.md
|
||
|
||
请确保代码符合项目规范，包括：
|
||
1. 遵循编码规范
|
||
2. 添加完整注释
|
||
3. 包含单元测试
|
||
4. 更新API文档
|
||
```
|
||
|
||
#### 2. 代码生成阶段
|
||
|
||
```
|
||
基于以下技术架构生成代码：
|
||
|
||
后端：Spring Boot + MyBatis-Plus + Sa-Token
|
||
前端：Vue3 + TypeScript + Element Plus
|
||
数据库：MySQL 8.0
|
||
|
||
请生成以下文件：
|
||
1. Controller层 - REST API接口
|
||
2. Service层 - 业务逻辑
|
||
3. Mapper层 - 数据访问
|
||
4. DTO/VO类 - 数据传输对象
|
||
5. 前端页面 - Vue3组件
|
||
6. API调用 - TypeScript接口
|
||
```
|
||
|
||
#### 3. 文档更新阶段
|
||
|
||
```
|
||
根据刚才生成的代码，请更新以下文档：
|
||
|
||
1. API文档：docs/开发文档/API.md
|
||
- 新增的接口定义
|
||
- 请求参数说明
|
||
- 响应示例
|
||
|
||
2. 数据库文档：docs/设计文档/database/
|
||
- 新增的表结构
|
||
- 字段说明
|
||
|
||
3. 变更记录：docs/变更管理/code-adjust-record.md
|
||
- 本次变更的详细记录
|
||
|
||
请保持文档格式一致。
|
||
```
|
||
|
||
### 提示词模板库
|
||
|
||
#### 后端开发模板
|
||
|
||
```
|
||
# 生成Spring Boot Controller
|
||
请为[实体名称]生成标准的Spring Boot Controller，要求：
|
||
1. 包含CRUD操作接口
|
||
2. 使用Sa-Token权限控制
|
||
3. 参数验证和异常处理
|
||
4. 完整的Swagger注解
|
||
5. 统一响应格式
|
||
|
||
实体字段：[字段列表]
|
||
权限前缀：[权限代码]
|
||
```
|
||
|
||
#### 前端开发模板
|
||
|
||
```
|
||
# 生成Vue3组件
|
||
请为[功能名称]生成Vue3组件，要求：
|
||
1. 使用TypeScript
|
||
2. Element Plus组件
|
||
3. 响应式设计
|
||
4. 表单验证
|
||
5. API调用集成
|
||
|
||
页面类型：[列表页/表单页/详情页]
|
||
功能要求：[具体功能说明]
|
||
```
|
||
|
||
#### 数据库设计模板
|
||
|
||
```
|
||
# 生成数据库表
|
||
请为[业务实体]设计MySQL表结构，要求：
|
||
1. 符合项目命名规范
|
||
2. 包含标准基础字段
|
||
3. 合理的索引设计
|
||
4. 外键关系定义
|
||
5. 注释完整
|
||
|
||
业务字段：[字段需求]
|
||
关联表：[关联关系]
|
||
```
|
||
|
||
## 📋 质量控制标准
|
||
|
||
### 代码质量检查
|
||
|
||
#### 自动化检查
|
||
|
||
- **代码规范**：Checkstyle + ESLint
|
||
- **代码覆盖率**：JaCoCo > 80%
|
||
- **安全扫描**：SonarQube
|
||
- **依赖检查**：OWASP Dependency Check
|
||
|
||
#### 人工审查
|
||
|
||
- **架构合理性**：是否符合系统架构
|
||
- **业务逻辑正确性**：是否满足业务需求
|
||
- **代码可读性**：注释完整，命名规范
|
||
- **性能考虑**：是否有性能优化
|
||
|
||
### 文档质量标准
|
||
|
||
#### 完整性检查
|
||
|
||
- [ ] API 文档覆盖所有接口
|
||
- [ ] 参数说明详细准确
|
||
- [ ] 响应示例真实有效
|
||
- [ ] 错误码定义完整
|
||
|
||
#### 准确性检查
|
||
|
||
- [ ] 文档与代码实现一致
|
||
- [ ] 示例可以正常运行
|
||
- [ ] 版本信息正确
|
||
- [ ] 链接地址有效
|
||
|
||
### 版本管理
|
||
|
||
#### 文档版本规则
|
||
|
||
- **主版本**：重大架构变更
|
||
- **次版本**：新增功能模块
|
||
- **修订版本**：Bug 修复和文档更新
|
||
|
||
#### 变更记录
|
||
|
||
```markdown
|
||
## 版本 1.2.3 - 2024-01-15
|
||
|
||
### 新增
|
||
|
||
- 新增用户管理 API 文档
|
||
- 添加前端开发规范
|
||
|
||
### 修改
|
||
|
||
- 更新数据库设计规范
|
||
- 优化 API 响应格式
|
||
|
||
### 修复
|
||
|
||
- 修正示例代码错误
|
||
- 更新过期链接
|
||
```
|
||
|
||
## 🚀 持续改进计划
|
||
|
||
### 短期目标（1 个月内）
|
||
|
||
- [ ] 完善 API 文档自动生成
|
||
- [ ] 建立代码质量检查流程
|
||
- [ ] 优化开发环境配置
|
||
- [ ] 提升团队规范执行
|
||
|
||
### 中期目标（3 个月内）
|
||
|
||
- [ ] 建立文档质量评估体系
|
||
- [ ] 实现开发流程自动化
|
||
- [ ] 完善性能监控机制
|
||
- [ ] 建立知识库体系
|
||
|
||
### 长期目标（6 个月内）
|
||
|
||
- [ ] 实现智能化代码审查
|
||
- [ ] 建立自动化测试体系
|
||
- [ ] 完善 DevOps 流程
|
||
- [ ] 建立技术标准库
|
||
|
||
---
|
||
|
||
## 📖 相关文档
|
||
|
||
- **API 接口文档**：[API.md](./API.md)
|
||
- **项目总览**：[项目总览](../项目总览/README.md)
|
||
- **业务模块**：[业务模块](../业务模块/README.md)
|
||
- **变更管理**：[变更管理](../变更管理/README.md)
|
||
- **测试文档**：[测试文档](../测试文档/README.md)
|
||
|
||
---
|
||
|
||
**🎯 目标**：通过完善的开发文档体系，为团队提供统一的技术标准，为 Cursor AI 提供准确的开发上下文，提升开发效率和代码质量。
|