feat: Add WonderQ-MiniAPP Public API documentation

- Introduced a comprehensive API contract for the WonderQ-MiniAPP, detailing endpoints for site configuration, product listings, and lead submissions.
- Defined data types for various entities including HeroSlide, Destination, Theme, CtaBanner, PublicProduct, and more.
- Specified request and response formats, including error handling guidelines.

chore: Update requirements to include python-multipart

- Added python-multipart dependency to requirements.txt for handling file uploads.

test: Implement API contract tests

- Created test suite for API contracts, validating serializers and endpoints for public products and leads.
- Included tests for destination and product serializers, ensuring correct data handling and validation.

test: Add configuration tests for OSS settings

- Implemented tests to verify that OSS settings are correctly loaded from environment variables.

README.md

@@ -2,46 +2,105 @@
 
 独立的 WonderQ 后端 API 服务，基于 Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT 和 Pydantic。
 
-## 本地启动
+## 本地手动启动
 
-1. 复制环境变量：
+以下命令默认在项目根目录执行：`D:\www\znkj\WonderQ-Admin`。
 
-```bash
-cp .env.example .env
+### 1. 准备环境变量
+
+首次启动先复制环境变量模板：
+
+```powershell
+Copy-Item .env.example .env
 ```
 
-2. 创建虚拟环境并安装依赖：
+然后编辑 `.env`，至少确认以下配置：
 
-```bash
+- `DATABASE_URL`：本地 Docker PostgreSQL 默认使用 `localhost:5433`。
+- `JWT_SECRET`：生产环境必须替换为高强度随机值。
+- `OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`、`OSS_ENDPOINT`、`OSS_BUCKET_NAME`：填写实际 OSS 配置；真实密钥只放在 `.env` 或部署平台密钥中，不提交到 Git。
+
+### 2. 创建并启用 Python 虚拟环境
+
+首次启动或 `.venv` 不存在时执行：
+
+```powershell
 python -m venv .venv
-.venv\Scripts\activate
+.\.venv\Scripts\Activate.ps1
 pip install -r requirements.txt
 ```
 
-3. 启动 PostgreSQL 和 Redis：
+如果 PowerShell 阻止执行激活脚本，可临时允许当前进程执行脚本后再激活：
 
-```bash
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\.venv\Scripts\Activate.ps1
+```
+
+后续日常启动只需要重新激活虚拟环境：
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+### 3. 启动依赖服务
+
+启动本地 PostgreSQL 和 Redis：
+
+```powershell
 docker compose up -d postgres redis
 ```
 
-4. 初始化数据库结构并导入初始内容：
+确认容器状态：
 
-```bash
+```powershell
+docker compose ps
+```
+
+### 4. 初始化或升级数据库
+
+首次启动、迁移变更后执行：
+
+```powershell
 alembic upgrade head
+```
+
+空库首次导入初始化内容时执行：
+
+```powershell
 python -m app.seed
 ```
 
-5. 启动 API：
+注意：`python -m app.seed` 会重置站点内容、产品、目的地、活动和媒体数据；已有业务数据时不要重复执行。只需要确保默认后台账号存在时，用：
 
-```bash
+```powershell
+python -m app.seed --no-reset
+```
+
+### 5. 启动 API 服务
+
+开发模式启动：
+
+```powershell
 uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
 ```
 
-访问：
+启动后访问：
 
 - 健康检查：http://localhost:4000/health
+- OpenAPI 文档：http://localhost:4000/docs
 - 默认后台账号：admin@example.com / ChangeMe123!
 
+### 日常启动速查
+
+数据库已经初始化后，通常只需要：
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+docker compose up -d postgres redis
+uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
+```
+
 ## Docker 部署
 
 完整本地部署：
@@ -114,6 +173,7 @@ Python 版保留原有核心路径：
 - `GET /api/admin/leads`
 - `PATCH /api/admin/leads/{id}/status`
 - `GET /api/admin/media-assets`
+- `POST /api/admin/media-assets/upload`
 - `POST /api/admin/reset-guizhou-content`
 - `POST /api/admin/publish`