wudizhanshen012 imaotai-project-conventions
语言 & 环境
- Python 3.10+
- 虚拟环境：
venv（目录名.venv，加入.gitignore） - 依赖管理：
requirements.txt（固定版本号）
项目结构
imaotai_autobuy/
├── config/
│ ├── config.yaml # 实际配置（gitignore）
│ └── config.example.yaml # 配置模板（提交到 git）
├── core/ # 核心业务逻辑
├── api/ # i茅台 API 封装层
├── scheduler/ # 定时任务
├── utils/ # 工具函数
├── tests/ # 测试文件（与模块一一对应）
├── logs/ # 运行日志（gitignore）
├── main.py
├── requirements.txt
└── .gitignore
配置管理
- 账号、Token、device_id 等敏感信息只存
config/config.yaml，绝不硬编码 config/config.yaml加入.gitignore，只提交config.example.yaml- 使用
PyYAML读取配置
日志规范
- 统一使用
loguru - 格式：
{time:YYYY-MM-DD HH:mm:ss} | {level} | {name} | {message} - 日志文件：
logs/app_{time:YYYY-MM-DD}.log，按天轮转，保留 7 天 - 控制台同步输出，级别 INFO 及以上
错误处理
- 网络请求失败：最多重试 3 次，指数退避（1s → 2s → 4s）
- 关键操作失败（申购、登录）必须记录 ERROR 日志
- 不允许裸 except:，必须捕获具体异常类型
测试规范
- 使用
pytest - 每个独立模块完成后必须编写对应测试，测试文件放
tests/下，命名test_<module>.py - 测试通过后方可提交 git，禁止带测试失败的代码提交
- 网络请求测试使用 mock，不发真实请求
Git 管理规范
Commit 格式（Conventional Commits）
<type>(<scope>): <subject>
type：
feat— 新功能fix— Bug 修复test— 测试refactor— 重构docs— 文档chore— 构建/依赖/配置
示例：
feat(api): 添加申购接口封装
fix(scheduler): 修复9点定时偏差问题
test(api): 添加登录接口单元测试
chore: 初始化项目结构和 .gitignore
提交时机（强制）
- 每个独立模块功能完成 → 运行测试 → 全部通过 → 立即 commit
- 一个 commit 只做一件事，禁止多模块混合提交
- 提交前检查：不含调试代码（print、hardcode token）、不含敏感信息
分支策略
main— 稳定可运行，只接受 merge，禁止 force pushdev— 日常开发feature/xxx— 独立功能分支，完成后合并 dev
版本 Tag
- 里程碑节点打 tag，格式：
v0.1.0（语义化版本） - 示例里程碑：基础申购跑通 v0.1.0、多账号支持 v0.2.0、耐力值自动维护 v0.3.0
.gitignore 必须包含
.venv/
config/config.yaml
logs/
__pycache__/
*.pyc
.env