# AGENTS.md

## 全局协作规则

- 默认全程使用中文回答；除非用户明确要求，不切换语言。
- 回答保持简洁直接，避免无效铺垫和空话。
- 需求不清晰时先提问确认；不要自行猜测并执行有风险操作。
- 默认只读优先。创建、修改、删除文件必须有用户明确授权。
- 严格按当前需求工作，不额外加功能、不扩大改动范围。
- 识别到密钥、Token、真实环境变量、账号密码、隐私配置时，禁止展示、复述或输出。
- 不读取、输出或提交 `.env`、`.env.local` 等真实环境文件。

## 项目定位

`WonderQ-Admin` 是独立的 WonderQ 后端 API 服务，当前技术栈为 Python + FastAPI + SQLAlchemy 2 + Alembic + PostgreSQL + JWT + Pydantic。项目为 H5 前台提供 Public API，为后台管理端提供 Admin API，并通过 Docker Compose 部署 API、PostgreSQL 和 Redis。

## 当前目录结构

```text
WonderQ-Admin/
├─ app/
│  ├─ main.py                 # FastAPI 应用入口、CORS、错误处理、路由注册
│  ├─ config.py               # 环境变量配置
│  ├─ database.py             # SQLAlchemy engine/session/Base
│  ├─ models.py               # ORM 模型，兼容原 Prisma 表结构
│  ├─ schemas.py              # Pydantic 请求校验
│  ├─ auth.py                 # JWT 与后台鉴权
│  ├─ serializers.py          # SQLAlchemy 对象响应序列化
│  ├─ content.py              # Python seed 内容源
│  ├─ seed.py                 # 初始化/重置数据命令
│  └─ routers/
│     ├─ public.py            # H5 Public API
│     ├─ admin.py             # 后台 Admin API
│     └─ shared.py            # 路由共享查询
├─ alembic/                   # 数据库迁移 baseline
├─ data/generated-products.json
├─ tests/                     # 单元测试和接口冒烟测试
├─ Dockerfile                 # API 镜像
├─ docker-compose.yml         # api/postgres/redis 编排
├─ requirements.txt           # Python 依赖
├─ pyproject.toml             # Python 项目元数据与 pytest 配置
├─ .env.example               # 环境变量模板
└─ README.md                  # 启动、部署、迁移说明
```

## 启动方式

本地开发：

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
docker compose up -d postgres redis
alembic upgrade head
python -m app.seed
uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
```

Docker 全量启动：

```bash
docker compose up --build
```

健康检查：`http://localhost:4000/health`。

## 测试流程

- 修改 Python 代码后运行 `pytest`。
- 修改数据库模型或迁移后运行 `alembic upgrade head`，并在空库验证 `python -m app.seed`。
- 保留已有 PostgreSQL 数据时，先备份，再使用 `alembic stamp head` 标记 baseline。
- Docker 相关变更后运行 `docker compose up --build` 并检查 `/health`。

## 开发准则

- 优先保持现有 API 路径和响应结构兼容，不主动重设计接口。
- 外部输入必须通过 Pydantic schema 校验。
- 数据库访问统一通过 `app/database.py` 提供的 Session。
- 表名和字段名需要兼容原 Prisma 生成的 mixed-case PostgreSQL 结构。
- Admin API 默认需要 `require_admin`，登录接口除外。
- 后台数据变更继续记录 `AuditLog`。
- 真实密钥只从环境变量读取，禁止写入源码、测试或文档。
- `python -m app.seed` 会重置内容数据，生产环境使用前必须明确确认。

## 锁定核心文件

未经用户明确授权禁止修改：

- `.env`、`.env.local`、生产环境变量和任何密钥配置。
- `app/models.py`、`alembic/versions/*`：数据库结构和迁移。
- `app/auth.py`：后台鉴权逻辑。
- `app/routers/admin.py`、`app/routers/public.py`：核心 API 行为。
- `app/seed.py`、`app/content.py`、`data/generated-products.json`：初始化内容和迁移数据源。
- `Dockerfile`、`docker-compose.yml`：部署入口。
- `requirements.txt`、`pyproject.toml`：依赖和测试配置。

如确需修改上述文件，先说明原因、影响范围、验证方式，并等待用户确认。