# 开发文档中心

## 📋 开发文档概述

开发文档中心提供项目开发所需的所有技术文档和规范，为 **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="&#10;" />
    <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 提供准确的开发上下文，提升开发效率和代码质量。