Files

duanshuwen 75f5a5a48b feat: add WonderQ admin backend

Add FastAPI admin/public API service, database setup, Docker deployment files, docs, and tests.

2026-06-30 13:56:45 +08:00

4.2 KiB

Raw Permalink Blame History

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。

当前目录结构

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                  # 启动、部署、迁移说明

启动方式

本地开发：

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 全量启动：

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：依赖和测试配置。

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

4.2 KiB Raw Permalink Blame History Unescape Escape