hzdyjs/docs/开发文档

开发文档中心

📋 开发文档概述

开发文档中心提供项目开发所需的所有技术文档和规范，为 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. 标准格式

#### 接口名称

**接口地址**: `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) {
        // 实现逻辑
    }
}

文档生成脚本

#!/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 规范

// 标准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. 数据库规范

-- 标准表结构
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 组件规范

<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 类型定义

// 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 调用规范

// 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,
    });
};

🏗️ 技术架构指南

系统整体架构

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 配置

<!-- .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 配置

{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    },
    "typescript.preferences.importModuleSpecifier": "relative",
    "emmet.includeLanguages": {
        "vue": "html"
    }
}

Git 配置

.gitignore 模板

# 编译输出
target/
dist/
build/

# 依赖目录
node_modules/

# IDE文件
.idea/
.vscode/
*.iml

# 日志文件
logs/
*.log

# 配置文件
application-local.yml
.env.local

Git Hooks

#!/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 修复和文档更新

变更记录

## 版本 1.2.3 - 2024-01-15

### 新增

-   新增用户管理 API 文档
-   添加前端开发规范

### 修改

-   更新数据库设计规范
-   优化 API 响应格式

### 修复

-   修正示例代码错误
-   更新过期链接

🚀 持续改进计划

短期目标（1 个月内）

• 完善 API 文档自动生成
• 建立代码质量检查流程
• 优化开发环境配置
• 提升团队规范执行

中期目标（3 个月内）

• 建立文档质量评估体系
• 实现开发流程自动化
• 完善性能监控机制
• 建立知识库体系

长期目标（6 个月内）

• 实现智能化代码审查
• 建立自动化测试体系
• 完善 DevOps 流程
• 建立技术标准库

---

📖 相关文档

• API 接口文档：API.md
• 项目总览：项目总览
• 业务模块：业务模块
• 变更管理：变更管理
• 测试文档：测试文档

---

🎯 目标：通过完善的开发文档体系，为团队提供统一的技术标准，为 Cursor AI 提供准确的开发上下文，提升开发效率和代码质量。