ZILING系统文档

主题

Ziling2025-03-06
1646
6.3m

贡献指南 ​

我们欢迎所有形式的贡献，包括但不限于代码、文档、问题报告、功能建议等。本指南将帮助您了解如何参与到项目的开发中来。

项目概述 ​

ZILING 是一个基于 FastAPI + Vue 3 的全栈项目，包含以下主要模块：

  • 后端服务: 基于 FastAPI 的 Python Web 服务
  • 管理后台: 基于 Vue 3 + Element Plus 的管理系统
  • 移动端应用: 基于 uni-app 的跨平台移动应用
  • 项目文档: 基于 VitePress 的文档站点

开发环境要求 ​

系统要求 ​

  • 操作系统: Windows 11 / macOS / Linux
  • Python: 3.10 或更高版本
  • Node.js: 18.0 或更高版本
  • 数据库: MySQL 8.0 或更高版本
  • 缓存: Redis 6.0 或更高版本

开发工具推荐 ​

  • IDE: PyCharm / VS Code / Trae AI
  • 数据库管理: Navicat / DBeaver
  • API 测试: Postman / Apifox
  • 版本控制: Git

环境搭建 ​

1. 克隆项目 ​

bash
git clone <项目地址>
cd small-purple-python

2. 后端环境搭建 ​

创建虚拟环境 ​

bash
# Windows
python -m venv .venv
.\.venv\Scripts\activate

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

安装依赖 ​

bash
pip install -r requirements.txt

配置环境变量 ​

复制 example.env 文件为 .env，并根据实际情况修改配置：

bash
cp example.env .env

主要配置项：

  • 数据库连接信息
  • Redis 连接信息
  • JWT 密钥配置
  • 文件上传路径等

数据库初始化 ​

bash
# 导入数据库结构
mysql -u root -p < docs/ziling.sql

启动后端服务 ​

bash
python ./def_server.py

3. 前端环境搭建 ​

管理后台 (zi-admin) ​

bash
cd frontend/zi-admin
npm install
npm run dev

移动端应用 (zi-unibase) ​

bash
cd frontend/zi-unibase
npm install
npm run dev:h5

文档站点 (zi-docs) ​

bash
cd frontend/zi-docs
npm install
npm run dev

开发规范 ​

代码规范 ​

Python 后端规范 ​

  • 代码风格: 遵循 PEP 8 规范
  • 函数注释: 必须添加函数级注释，说明参数、返回值和功能
  • 类型提示: 使用 Python 类型提示 (Type Hints)
  • 异常处理: 合理使用自定义异常类
  • 日志记录: 使用项目统一的日志配置
python
def create_user(user_data: UserCreateSchema) -> UserResponseSchema:
    """
    创建新用户
    
    Args:
        user_data: 用户创建数据
        
    Returns:
        UserResponseSchema: 创建成功的用户信息
        
    Raises:
        BusinessException: 用户名已存在时抛出
    """
    # 实现代码
    pass

前端规范 ​

  • 代码风格: 使用 ESLint + Prettier 进行代码格式化
  • 组件命名: 使用 PascalCase 命名组件
  • 变量命名: 使用 camelCase 命名变量和函数
  • 类型定义: TypeScript 项目必须定义类型
  • 组件注释: 复杂组件需要添加注释说明
typescript
/**
 * 用户管理组件
 * 提供用户的增删改查功能
 */
interface UserManagementProps {
  /** 用户列表数据 */
  users: User[]
  /** 加载状态 */
  loading?: boolean
}

目录结构规范 ​

后端目录结构 ​

src/
├── controllers/     # 控制器层
├── services/       # 业务逻辑层
├── models/         # 数据模型层
├── schemas/        # 数据验证模式
├── middleware/     # 中间件
├── utils/          # 工具函数
├── config/         # 配置文件
├── core/           # 核心模块
└── exceptions/     # 异常定义

前端目录结构 ​

src/
├── views/          # 页面组件
├── components/     # 公共组件
├── stores/         # 状态管理
├── utils/          # 工具函数
├── api/            # API 接口
├── types/          # 类型定义
├── assets/         # 静态资源
└── router/         # 路由配置

Git 提交规范 ​

提交信息格式 ​

使用 Conventional Commits 规范：

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

提交类型 (type) ​

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建过程或辅助工具的变动

示例 ​

bash
feat(user): 添加用户注册功能

- 实现用户注册 API 接口
- 添加邮箱验证功能
- 完善用户数据验证

Closes #123

分支管理规范 ​

分支类型 ​

  • main: 主分支，用于生产环境
  • develop: 开发分支，用于集成开发
  • feature/*: 功能分支，用于开发新功能
  • hotfix/*: 热修复分支，用于紧急修复
  • release/*: 发布分支，用于版本发布

分支命名 ​

bash
feature/user-management    # 用户管理功能
hotfix/login-bug          # 登录 bug 修复
release/v1.2.0            # v1.2.0 版本发布

贡献流程 ​

1. 准备工作 ​

  1. Fork 项目到您的 GitHub 账户
  2. 克隆 Fork 后的项目到本地
  3. 添加原项目为上游仓库：
    bash
    git remote add upstream <原项目地址>

2. 开发流程 ​

  1. 创建功能分支

    bash
    git checkout -b feature/your-feature-name

  2. 进行开发

    • 遵循代码规范
    • 添加必要的注释
    • 确保代码质量

  3. 提交代码

    bash
    git add .
git commit -m "feat: 添加新功能描述"

  4. 推送分支

    bash
    git push origin feature/your-feature-name

  5. 创建 Pull Request

    • 在 GitHub 上创建 PR
    • 填写详细的 PR 描述
    • 等待代码审查

3. 代码审查 ​

  • 所有代码必须经过审查才能合并
  • 审查者会检查代码质量、规范性和功能完整性
  • 根据审查意见进行修改和完善

4. 合并代码 ​

  • 审查通过后，维护者会合并代码
  • 合并后会自动删除功能分支

问题报告 ​

Bug 报告 ​

提交 Bug 时请包含以下信息：

  • 环境信息: 操作系统、浏览器版本、Python 版本等
  • 重现步骤: 详细的操作步骤
  • 预期行为: 期望的正确行为
  • 实际行为: 实际发生的错误行为
  • 错误截图: 如果适用，请提供截图
  • 错误日志: 相关的错误日志信息

功能建议 ​

提交功能建议时请包含：

  • 功能描述: 详细描述建议的功能
  • 使用场景: 说明功能的应用场景
  • 实现思路: 如果有想法，可以提供实现思路
  • 优先级: 说明功能的重要程度

文档贡献 ​

文档类型 ​

  • API 文档: 接口文档和使用说明
  • 开发文档: 开发指南和技术文档
  • 用户文档: 用户使用手册
  • 部署文档: 部署和运维文档

文档规范 ​

  • 使用 Markdown 格式编写
  • 保持文档结构清晰
  • 提供代码示例和截图
  • 及时更新过时内容

社区准则 ​

行为准则 ​

  • 尊重所有贡献者
  • 保持友好和专业的交流
  • 欢迎新手参与
  • 鼓励建设性的讨论

沟通渠道 ​

  • GitHub Issues: 问题报告和功能建议
  • GitHub Discussions: 技术讨论和交流
  • Pull Requests: 代码审查和讨论

许可证 ​

本项目采用 MIT License 许可证。通过贡献代码，您同意将您的贡献按照相同的许可证进行授权。

联系我们 ​

如果您有任何问题或建议，欢迎通过以下方式联系我们：

  • 提交 GitHub Issue
  • 发起 GitHub Discussion
  • 发送邮件至项目维护者

感谢您对 ZILING 项目的贡献！🎉

最近更新