次元取景器

为 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）