131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# 次元取景器
|
||
|
||
> 为 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）
|