Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (141 loc) · 5.66 KB

CONTRIBUTING.md

File metadata and controls

202 lines (141 loc) · 5.66 KB

贡献指南

欢迎为 CIMS-backend 贡献代码！无论是修复 Bug、完善文档还是新增功能，你的贡献都非常有价值。

贡献流程

1. Fork & 创建分支

# Fork 后克隆你的仓库
git clone https://github.com/<你的用户名>/CIMS-backend.git
cd CIMS-backend

# 从 main 创建功能分支
git checkout -b feature/your-feature-name

2. 搭建开发环境

按照 DEVELOPMENT.md 完成环境搭建（需要 PostgreSQL 和 Redis）。

3. 进行修改

4. 验证改动

# 格式化
uv run black .

# Lint 检查（自动修复可加 --fix）
uv run ruff check .

# 运行全部测试
uv run pytest

# 查看覆盖率
uv run pytest --cov=app --cov-report=term-missing

5. 提交 Pull Request

确保 CI 全绿后，提交 PR 至 main 分支并等待维护者审查。

多租户开发约定

CIMS 采用行级多租户隔离，开发时需严格遵循以下规则：

规则 说明
模型必须包含 tenant_id 所有新增的 SQLAlchemy 模型必须包含 tenant_id 字段，并将其纳入复合主键或唯一约束
查询必须过滤 tenant_id 所有数据库查询语句必须使用 .where(Model.tenant_id == tenant_id) 进行行级过滤
获取租户 ID 在 API 端点中通过 get_tenant_id() 获取当前请求所属的租户 ID
Redis Key 前缀 会话管理和资源令牌的 Redis Key 必须以 tenant_id 为前缀，避免跨租户数据泄露
gRPC Interceptor gRPC 服务通过 TenantInterceptor 自动从 :authority 或 tenant-id metadata 中解析租户

示例：新增一个租户隔离模型

# app/models/your_model.py
from sqlalchemy import Column, String, ForeignKey
from app.models.base import Base

class YourModel(Base):
    __tablename__ = "your_table"

    id = Column(String, primary_key=True)
    tenant_id = Column(String, primary_key=True)  # ← 必须
    name = Column(String, nullable=False)

代码规范

工具链

工具 用途 命令
black 代码格式化 uv run black .
ruff Lint 检查 uv run ruff check .
pyright 类型检查 uv run pyright
pytest 测试 uv run pytest

编码约定

  • 文件长度：单文件建议不超过 35 行（黑线 50 行），确保模块职责单一
  • 注释语言：所有代码注释和 docstring 使用中文
  • 文件编码：UTF-8，Unix 换行符（LF）
  • Import 顺序：标准库 → 第三方库 → 项目内部模块（ruff 会自动排序）
  • 异步优先：数据库和 Redis 操作统一使用 async/await

提交信息约定

使用 Conventional Commits 格式：

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

[optional body]

常用 type：

Type 说明
feat 新功能
fix Bug 修复
refactor 重构（不改变外部行为）
docs 文档变更
test 测试相关
ci CI/CD 变更
chore 杂项（依赖更新等）

Protobuf 代码生成

修改 api/Protobuf/ 下的 .proto 文件后，运行以下命令重新生成 Python 代码：

uv run python -m grpc_tools.protoc \
  -Iapi/ \
  --python_out=app/grpc \
  --grpc_python_out=app/grpc \
  --pyi_out=app/grpc \
  api/Protobuf/Service/*.proto \
  api/Protobuf/Client/*.proto \
  api/Protobuf/Server/*.proto \
  api/Protobuf/Enum/*.proto \
  api/Protobuf/Command/*.proto \
  api/Protobuf/AuditEvent/*.proto

生成的文件位于 app/grpc/api/Protobuf/，包含：

  • *_pb2.py — Protobuf 消息类
  • *_pb2_grpc.py — gRPC 服务桩
  • *_pb2.pyi — 类型存根（供 IDE 提示）

⚠️ 生成的文件不应手动编辑，它们会被代码生成覆盖。

测试

前提：需要运行中的 PostgreSQL 和 Redis 实例（可用 Docker 快速启动，见 DEVELOPMENT.md）。

# 运行全部测试
uv run pytest

# 运行并查看覆盖率（含未覆盖行号）
uv run pytest --cov=app --cov-report=term-missing

# 仅运行特定测试文件
uv run pytest tests/test_api.py

# 仅运行匹配名称的测试
uv run pytest -k "test_admin_create"

测试文件说明

文件 覆盖范围
test_api.py Client API、Command API、资源管理
test_admin_tenant.py Admin API、租户 CRUD、Auth 中间件、Redis、资源令牌
test_grpc.py gRPC 五项服务、SessionManager、在线状态
test_coverage.py 边界情况补充、异常路径覆盖

提交 Issue

如果你发现了 Bug 或有功能建议，请在 GitHub 上提交 Issue，并尽量包含以下信息：

  • 清晰的标题和详细描述
  • 复现步骤（Bug）或使用场景（功能建议）
  • 相关的日志输出或错误截图
  • 运行环境信息（OS、Python 版本、依赖版本）

Pull Request 清单

提交 PR 前，请确认以下事项：

  • 代码通过 uv run black --check .
  • 代码通过 uv run ruff check .
  • 所有测试通过 uv run pytest
  • 新增功能已编写对应测试
  • 相关文档已更新
  • 提交信息遵循 Conventional Commits 格式