点我展开：基本信息

以南方电网为基础，记录团队项目协作基本规则。

 人员结构

人员分配主要分为三级，大领导、两个项目组长、七个开发人员，大领导负责整体的项目方向把握，项目组长负责对应小组的任务分配、对齐需求以及项目验收，开发人员在理解需求后进行对应模块的开发。

 项目管理

创建（微信/钉钉）工作群，以该群为联系中心，每周三项目组长跟进项目进度，每周五开组会确定进度和确定是否存在项目卡点。

通过协作文档来确定任务和当前进度，优先微信会议语音沟通，之后才进行文字，讨论均在大群里进行，要确保工作留痕。

项目所需资料和各个开发人员代码均依托Github远程仓库进行管理，branch开发提交PR进行审核，基本开发流程：

1. 你：git checkout -b feature/xxx   (创建分支)
2. 你：coding… commit… commit…       (本地折腾)
3. 你：git push -u origin feature/xxx (push 到远程)
4. 你：在 GitHub 点 “Compare & Pull Request” 发起 PR
5. 同事：review + 自动化测试通过
6. Maintainer：点击 “Merge into main”
7. 所有人：git pull origin main      (同步最新正式版)

常规使用fastAPI进行服务器部署及测试。

项目结构

项目结构主要以模块化进行管理，便于团队合作开发，以南方电网项目为例：

  • data存放数据
  • src存放功能代码
  • unit_test存放测试代码
  • server存放服务代码
  • utils存放工具代码
  • config存放配置文件
construction_fees_inspection: 安全文明施工费辅助检查
cost_utilization_review: 费用使用智能审查
design_intelligent_review: 设计智能审查
plan_compliance_review: 计划合规性审查

一般情况在自己的模块下进行开发，调用main中统一的工具和外部API。

编码规范

必须使用面向对象的编程思想，能够模块化的尽量模块化，不要使用 procedural programming

（一）运行环境配置

  1. 创建运行环境：conda create -n test python=3.12 -y
  2. 进入运行环境：conda activate test
  3. 下载相关Python库：pip install -r requirements.txt

（二）命名

参照一下规则

  • 模块名: module_name;
  • 包名: package_name;
  • 类名: ClassName;
  • 方法名: method_name;
  • 异常名: ExceptionName;
  • 函数名: function_name, query_proper_noun_for_thing, send_acronym_via_https;
  • 全局常量名: GLOBAL_CONSTANT_NAME;
  • 全局变量名: global_var_name;
  • 实例名: instance_var_name;
  • 函数参数名: function_parameter_name;
  • 局部变量名: local_var_name.

（三）缩进

缩进使用4个空格，即一个tab。

（三）换行

  • 函数和类方法参数列表换行时，每个参数占一行
  • 函数与函数用两个换行符间隔
  • 类与类用两个换行符间隔
  • 类方法与类方法用一个换行符间隔

（四）注释

  • 代码需要有详细的注释
  • 函数和类方法需要有类型注释
def my_method(
    self,
    first_var: int,
    second_var: Foo,
    third_var: Bar | None,
) -> int:
    pass

（五）空格

  • 参数与运算法之间必须要有空格，如：
a = 1
a = [1, 2, 3]
a = {1: 2, 3: 4}
a = (1, 2, 3)

（六）import

使用绝对import，不要使用相对import，项目目录已加入sys.path

# 模块导入不依赖当前文件的路径，选用该种方式导入对应模块
from myproject.utils.helper import my_function

# 模块导入依赖当前文件的路径
from ..utils.helper import my_function

（七）脚本

  • 每个脚本开头必须加上以下内容：
# coding: utf-8
# @author: your self
# @file: xxx.py

其他

（一）测试

  • 每个功能必须有功能代码测试和服务代码测试，放在unit_test目录下
  • 在push前必须运行单元测试

（二）服务

  • 每个功能必须要写相应的服务，放在server目录下
  • 服务统一使用fastapi框架，使用uvicorn作为web服务器

（三）日志

  • 日志统一使用loguru模块，已放在src.utils.set_logger.py中, 直接from src.utils.set_logger import logger
  • 在必要的位置添加日志，不要整个功能运行完没有一行日志，一般是入口，中间启动信息，异常信息，返回信息等

（四）第三方库

所有用到的第三方库，必须放到requirements.txt中，不要使用pip install xxx安装，否则无法保证版本一致性。

赏

SZUer继续加油！