AGENTS.md

Repository Guidelines

项目结构与模块组织

本项目是基于 FastAPI 的团队管理与兑换系统，核心代码在 app/。路由在 app/routes/，业务逻辑在 app/services/，模板与静态资源分别在 app/templates/ 与 app/static/，通用工具在 app/utils/。配置入口是 app/config.py，数据库初始化脚本为 init_db.py。根目录包含 requirements.txt、Dockerfile、docker-compose.yml、.env.example 以及集成说明 integration_docs.md。

构建、测试与本地运行

常用命令如下：

• pip install -r requirements.txt 安装依赖
• python init_db.py 初始化本地 SQLite 数据库（默认生成 team_manage.db）
• python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8008 启动开发服务
• docker compose up -d 使用 Docker 启动服务
• docker compose logs -f 查看容器日志
• docker compose down 停止并清理容器

编码风格与命名约定

代码以 Python 风格为准，使用 4 空格缩进，函数与变量采用 snake_case，类采用 PascalCase。保持导入顺序为标准库、第三方、项目内模块。注释与用户可见文本使用中文，字符串格式优先使用 f-string。业务逻辑放在 services，路由只做参数校验与编排。

测试指南

当前仅提供 test_webhook.py 作为手动联调脚本，默认在 pytest 中被跳过。需要联调时建议直接执行 python test_webhook.py，它会修改本地数据库配置。新增测试建议采用 test_*.py 命名，并集中放置在根目录或新建 tests/ 目录。

提交与合并请求规范

提交信息遵循简短动词开头的陈述式，例如 Update README for settings panel navigation。避免多行冗长描述，必要时在 PR 说明中补充细节。PR 需说明变更范围，若涉及页面调整请附截图；若涉及接口或配置更新，请同步更新 README.md 或 integration_docs.md。

安全与配置提示

不要提交真实的 .env 或数据库文件；新增配置项时同步更新 .env.example。生产环境必须修改 SECRET_KEY 与 ADMIN_PASSWORD。代理与 webhook 等敏感信息请避免写入日志。