75f5a5a48b
Add FastAPI admin/public API service, database setup, Docker deployment files, docs, and tests.
99 lines
4.2 KiB
Markdown
99 lines
4.2 KiB
Markdown
# 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`：依赖和测试配置。
|
||
|
||
如确需修改上述文件，先说明原因、影响范围、验证方式，并等待用户确认。
|