# 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 等敏感信息请避免写入日志。