# 次元取景器

> 为 Coser 和摄影师打造的二次元取景地发现与分享平台

## 项目结构

```
├── clients/         # 用户端 — uni-app Vue3 (HBuilderX 项目 + Pinia)
├── server/          # 服务端 — Python (FastAPI + SQLAlchemy 2.x)
│   └── app/admin/   # 管理端 — sqladmin（挂载在 FastAPI 上）
├── docker-compose.yml
└── docs.md          # 产品功能规划文档
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 用户端 | uni-app Vue3 (HBuilderX) · Pinia · 高德地图 |
| 服务端 | FastAPI · SQLAlchemy 2.x · Alembic · PostgreSQL + PostGIS · Redis |
| 管理端 | sqladmin（基于 FastAPI） |
| 存储 | MinIO（S3 兼容） |
| 容器 | Docker Compose（Nginx / PostgreSQL / Redis / MinIO） |

## Docker Compose 一次部署

项目已支持一次启动后端、管理端、用户端和基础设施：

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

默认访问地址：

- 用户端 H5：http://localhost:5173
- 管理前端：http://localhost:5174
- 后端 API：http://localhost:5173/api
- API 文档：http://localhost:5173/docs

除 Nginx 网关外，后端、PostgreSQL、Redis、MinIO 和前端静态容器都只在 Docker 内部网络通信，不绑定宿主机端口。

默认数据库、Redis、MinIO 和端口可以通过环境变量覆盖，常用变量如下：

```bash
POSTGRES_USER=shiran
POSTGRES_PASSWORD=zxh2488252513
POSTGRES_DB=ciyuan_viewfinder
CLIENT_WEB_PORT=5173
ADMIN_WEB_PORT=5174
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
SECRET_KEY=change-me-before-production
TENCENT_MAP_KEY=
```

后端容器启动时会执行应用内启动迁移逻辑。用户端 H5 和管理前端会在镜像构建阶段生成静态文件，并由 nginx 托管。

## 本地开发

### 1. 启动基础设施

```bash
docker-compose up -d postgres redis minio
```

这会启动 PostgreSQL（含 PostGIS）、Redis 和 MinIO。

### 2. 启动服务端

```bash
cd server

# 创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
# source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制并编辑环境变量
cp .env.example .env

# 执行数据库迁移
alembic upgrade head

# 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

API 文档：http://localhost:8000/docs
管理后台：http://localhost:8000/admin

### 3. 启动用户端 HBuilderX

使用 HBuilderX 打开 `clients/` 目录，安装 Pinia 依赖后运行：

```bash
cd clients
npm install
```

然后在 HBuilderX 中选择 运行 → 运行到浏览器 / 运行到小程序模拟器。

也可以构建 H5：

```bash
cd clients
npm install
npm run build:h5
```

## 功能阶段

| 阶段 | 内容 |
|------|------|
| **MVP（阶段 1）** | 登录注册、地图发现、地点详情、上传地点、我的 |
| **阶段 2** | 评论评分、标签筛选、搜索 |
| **阶段 3** | 约拍广场、报名匹配、站内私信 |
| **阶段 4** | 活动发布与报名 |
| **阶段 5** | 商业化（推广位、会员） |

## 开发约定

- 服务端 API 前缀：`/api/v1/`
- 所有 UGC 内容需审核（`audit_status`：pending → approved / rejected）
- 前端统一请求封装，自动携带 Token、统一错误处理
- 管理端使用 RBAC（admin / moderator / user）