geo/docs/03-开发指南/coding-standards.md

代码规范

Python后端规范

代码风格

遵循PEP 8规范，使用Black进行代码格式化：

# 安装格式化工具
pip install black isort

# 格式化代码
black .
isort .

导入顺序

1. 标准库
2. 第三方库
3. 本地应用/库

# 1. 标准库
import os
from datetime import datetime

# 2. 第三方库
from fastapi import APIRouter, Depends
from sqlalchemy import select

# 3. 本地应用
from app.models import User
from app.schemas import UserCreate

命名规范

类型	规范	示例
模块	小写下划线	user_service.py
类	大驼峰	UserService
函数	小写下划线	get_user_by_id
常量	全大写下划线	MAX_RETRY_COUNT
变量	小写下划线	user_name

类型注解

所有函数必须包含类型注解：

from typing import Optional

def get_user_by_id(user_id: int) -> Optional[User]:
    """根据ID获取用户"""
    ...

异步函数

使用async/await进行异步编程：

async def get_user(user_id: int) -> User:
    async with async_session() as session:
        result = await session.execute(
            select(User).where(User.id == user_id)
        )
        return result.scalar_one_or_none()

TypeScript前端规范

代码风格

使用Prettier和ESLint：

npm run lint    # 检查代码
npm run format  # 格式化代码

组件规范

• 使用函数组件
• 使用TypeScript严格模式
• Props接口定义

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export function Button({ label, onClick, variant = 'primary' }: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {label}
    </button>
  );
}

目录结构

frontend/
├── app/              # Next.js App Router页面
├── components/       # React组件
│   ├── ui/         # 基础UI组件
│   └── features/    # 业务组件
├── lib/             # 工具函数
└── types/           # 类型定义

提交规范

遵循Conventional Commits：

feat: 添加新功能
fix: 修复bug
docs: 文档更新
style: 代码格式（不影响功能）
refactor: 重构
test: 测试相关
chore: 构建/工具

示例：

feat(auth): 添加邮箱验证功能
fix(dashboard): 修复图表数据加载问题
docs(api): 更新API文档