Enforces repo standing orders:…

# GitHub 仓库规范化方案（my-shop/inventory-api）

一、统一 src 目录结构

推荐采用 src 布局，避免打包与测试环境污染：

```

inventory-api/

├── src/

│ └── inventory_api/

│ ├── __init__.py

│ ├── api/ # 路由与接口层

│ ├── services/ # 业务逻辑层

│ ├── models/ # 数据模型

│ ├── schemas/ # Pydantic/DTO

│ ├── utils/ # 工具函数

│ └── config.py # 配置

├── tests/

│ ├── unit/

│ └── integration/

├── docs/

├── scripts/

├── pyproject.toml

└── README.md

```

迁移步骤：

1. 将现有包目录移入 src/inventory_api/

2. 更新导入路径（可用 isort 辅助检查）

3. 在 pyproject.toml 中配置 [tool.setuptools] 指定 package-dir = {"" = "src"}

二、配置 flake8 与 pytest

安装依赖：

```bash

pip install flake8 pytest pytest-cov

```

flake8 配置（.flake8 文件）：

```ini

[flake8]

max-line-length = 100

exclude = .git,__pycache__,venv,build

extend-ignore = E203, W503

```

pytest 配置（写入 pyproject.toml）：

```toml

[tool.pytest.ini_options]

testpaths = ["tests"]

addopts = "-v --cov=src --cov-report=term-missing"

```

CI 集成（.github/workflows/ci.yml）：在 GitHub Actions 中添加 lint（flake8）与 test（pytest）两个 job，每次 push/PR 自动触发，不通过则阻止合并。

三、Commit Message 强制带 Issue 编号

规范格式：

```

feat: 支持库存扣减接口 (#123)

fix: 修复并发下单超卖问题 (#456)

```

落地手段（多层防护）：

1. commit-msg 钩子：用 commitlint 或自定义脚本校验消息结尾含 (#数字)，不合规则拒绝提交；配合 husky（或 pre-commit）自动安装钩子

2. 分支保护规则：在仓库 Settings → Branches 中启用 PR 必须关联 Issue，要求 PR 描述含 issue 引用

3. CI 校验兜底：在 workflow 中用正则检查 PR 的 commit message，不符合则标记失败

4. 文档宣导：在 CONTRIBUTING.md 中写明提交规范与示例

四、落地顺序建议

1. 先迁移目录结构并跑通测试 → 2. 添加 flake8/pytest 配置与 CI → 3. 加 commit 校验钩子与分支保护 → 4. 更新 R