次元取景器
为 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 一次部署
项目已支持一次启动后端、管理端、用户端和基础设施：
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 和端口可以通过环境变量覆盖，常用变量如下：
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. 启动基础设施
docker-compose up -d postgres redis minio
这会启动 PostgreSQL（含 PostGIS）、Redis 和 MinIO。
2. 启动服务端
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 依赖后运行：
cd clients
npm install
然后在 HBuilderX 中选择 运行 → 运行到浏览器 / 运行到小程序模拟器。
也可以构建 H5：
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）