| name | imaotai-project-conventions |
| description | i茅台抢购项目开发规范。开发 imaotai_autobuy 项目中任何模块时必须激活此 skill，包含：项目结构、Python 规范、配置管理、日志、错误处理、测试要求、Git 管理规范。 |
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
