Initial commit: React + Django 城市手册项目
- Django 4.2 + DRF + JWT + GraphQL - React 18 + MobX + styled-components - PostgreSQL 数据库 - Docker + Docker Compose + Nginx - 完整的功能模块（用户、版块、文章、服务、交互、版主管理） - 完整的文档（需求、部署、测试）
This commit is contained in:
mashen
262
PROJECT_DOCS.md
Normal file
262
PROJECT_DOCS.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 项目架构文档
|
||||
|
||||
## 技术栈
|
||||
|
||||
### 后端 (Django)
|
||||
- **框架**: Django 4.2
|
||||
- **API 框架**: Django REST Framework
|
||||
- **认证**: JWT (djangorestframework-simplejwt)
|
||||
- **GraphQL**: graphene-django
|
||||
- **数据库**: PostgreSQL
|
||||
- **静态文件**: Whitenoise
|
||||
- **生产服务器**: Gunicorn
|
||||
|
||||
### 前端 (React)
|
||||
- **框架**: React 18
|
||||
- **构建工具**: Create React App
|
||||
- **状态管理**: MobX + mobx-react-lite
|
||||
- **样式**: styled-components
|
||||
- **路由**: React Router 6
|
||||
- **HTTP 客户端**: axios
|
||||
|
||||
### 部署
|
||||
- **容器化**: Docker + Docker Compose
|
||||
- **反向代理**: Nginx
|
||||
- **进程管理**: Gunicorn
|
||||
|
||||
## 项目结构
|
||||
|
||||
### 后端结构
|
||||
```
|
||||
backend/
|
||||
├── config/
|
||||
│ ├── settings/
|
||||
│ │ ├── base.py # 基础配置
|
||||
│ │ ├── dev.py # 开发环境
|
||||
│ │ └── prod.py # 生产环境
|
||||
│ ├── urls.py # 主路由
|
||||
│ ├── wsgi.py # WSGI 配置
|
||||
│ └── asgi.py # ASGI 配置
|
||||
├── apps/
|
||||
│ ├── users/ # 用户管理
|
||||
│ │ ├── models.py # User 模型
|
||||
│ │ ├── serializers.py
|
||||
│ │ ├── views.py # ViewSets
|
||||
│ │ └── urls.py
|
||||
│ ├── core/ # 核心业务
|
||||
│ └── api/ # API 配置
|
||||
│ ├── serializers.py
|
||||
│ ├── views.py
|
||||
│ ├── urls.py
|
||||
│ ├── schema.py # GraphQL schema
|
||||
│ └── graphql_urls.py
|
||||
├── static/ # 静态文件
|
||||
├── media/ # 媒体文件
|
||||
├── requirements.txt
|
||||
├── manage.py
|
||||
└── start.sh # 快速启动脚本
|
||||
```
|
||||
|
||||
### 前端结构
|
||||
```
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── components/ # React 组件
|
||||
│ ├── stores/ # MobX stores
|
||||
│ │ ├── AuthStore.js
|
||||
│ │ └── UserStore.js
|
||||
│ ├── services/ # API 服务
|
||||
│ │ └── api.js # axios 配置
|
||||
│ ├── styles/ # 全局样式
|
||||
│ │ └── global.js
|
||||
│ ├── App.js # 主应用
|
||||
│ └── index.js # 入口文件
|
||||
├── public/ # 公共资源
|
||||
├── package.json
|
||||
├── .env.example
|
||||
├── nginx.conf # Nginx 配置
|
||||
├── Dockerfile
|
||||
└── start.sh # 快速启动脚本
|
||||
```
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 1. 用户认证
|
||||
|
||||
**JWT 认证流程：**
|
||||
1. 用户发送 email + password 到 `/api/auth/login/`
|
||||
2. 后端验证并返回 access_token 和 refresh_token
|
||||
3. 前端保存 tokens 到 localStorage
|
||||
4. 后续请求在 Header 中携带 Bearer token
|
||||
5. Token 过期时自动使用 refresh_token 刷新
|
||||
|
||||
**自定义用户模型：**
|
||||
```python
|
||||
# apps/users/models.py
|
||||
class User(AbstractUser):
|
||||
email = models.EmailField(unique=True)
|
||||
avatar = models.ImageField(upload_to='avatars/')
|
||||
USERNAME_FIELD = 'email'
|
||||
```
|
||||
|
||||
### 2. REST API
|
||||
|
||||
**端点：**
|
||||
- `POST /api/auth/login/` - 登录获取 token
|
||||
- `POST /api/auth/token/refresh/` - 刷新 token
|
||||
- `GET /api/users/` - 获取用户列表
|
||||
- `GET /api/users/me/` - 获取当前用户
|
||||
- `GET /api/users/:id/` - 获取特定用户
|
||||
|
||||
### 3. GraphQL
|
||||
|
||||
**Schema：**
|
||||
```graphql
|
||||
type User {
|
||||
id: ID!
|
||||
email: String!
|
||||
username: String!
|
||||
}
|
||||
|
||||
type Query {
|
||||
allUsers: [User!]!
|
||||
me: User
|
||||
}
|
||||
```
|
||||
|
||||
访问 `/graphql/?graphiql` 查看调试界面。
|
||||
|
||||
### 4. 状态管理 (MobX)
|
||||
|
||||
**AuthStore：**
|
||||
- 管理认证状态
|
||||
- 处理登录/登出
|
||||
- 保存和读取 tokens
|
||||
|
||||
**UserStore：**
|
||||
- 获取当前用户信息
|
||||
- 管理用户数据状态
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 1. 添加新的 API 端点
|
||||
|
||||
```python
|
||||
# apps/yourapp/views.py
|
||||
class YourViewSet(viewsets.ModelViewSet):
|
||||
queryset = YourModel.objects.all()
|
||||
serializer_class = YourSerializer
|
||||
|
||||
# apps/yourapp/urls.py
|
||||
router = DefaultRouter()
|
||||
router.register(r'endpoint', YourViewSet)
|
||||
```
|
||||
|
||||
### 2. 添加新的 MobX Store
|
||||
|
||||
```javascript
|
||||
// src/stores/YourStore.js
|
||||
import { makeAutoObservable } from 'mobx';
|
||||
|
||||
class YourStore {
|
||||
data = null;
|
||||
loading = false;
|
||||
|
||||
constructor() {
|
||||
makeAutoObservable(this);
|
||||
}
|
||||
|
||||
async fetchData() {
|
||||
this.loading = true;
|
||||
// API 调用
|
||||
this.loading = false;
|
||||
}
|
||||
}
|
||||
|
||||
export default YourStore;
|
||||
```
|
||||
|
||||
### 3. 添加新的 React 组件
|
||||
|
||||
```javascript
|
||||
// src/components/YourComponent.js
|
||||
import React from 'react';
|
||||
import styled from 'styled-components';
|
||||
|
||||
const Container = styled.div`
|
||||
padding: 20px;
|
||||
`;
|
||||
|
||||
function YourComponent() {
|
||||
return <Container>Your content</Container>;
|
||||
}
|
||||
|
||||
export default YourComponent;
|
||||
```
|
||||
|
||||
## 部署配置
|
||||
|
||||
### Docker Compose 服务
|
||||
|
||||
**backend：**
|
||||
- 基于 Python 3.11
|
||||
- 运行 Gunicorn
|
||||
- 暴露 8000 端口
|
||||
- 挂载 static 和 media 卷
|
||||
|
||||
**frontend：**
|
||||
- 基于 Node 18 构建
|
||||
- 使用 nginx 作为服务器
|
||||
- 暴露 80 端口
|
||||
- 代理 API 请求到 backend
|
||||
|
||||
**db：**
|
||||
- PostgreSQL 15
|
||||
- 持久化数据卷
|
||||
|
||||
### Nginx 配置
|
||||
|
||||
- `/` → React 应用
|
||||
- `/api/*` → Django 后端
|
||||
- `/graphql/*` → Django GraphQL
|
||||
- `/media/*` → Django media
|
||||
- `/static/*` → Django static
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
1. **生产环境必须：**
|
||||
- 设置 `DJANGO_SECRET_KEY` 为强随机值
|
||||
- `DEBUG=False`
|
||||
- 配置 `ALLOWED_HOSTS`
|
||||
- 启用 HTTPS
|
||||
- 设置 `CORS_ALLOWED_ORIGINS`
|
||||
|
||||
2. **数据库：**
|
||||
- 使用强密码
|
||||
- 不暴露到公网
|
||||
- 定期备份
|
||||
|
||||
3. **JWT：**
|
||||
- Token 过期时间合理配置
|
||||
- 刷新 token 轮换
|
||||
- 生产环境使用 HTTPS
|
||||
|
||||
## 下一步开发建议
|
||||
|
||||
1. **后端：**
|
||||
- 添加更多业务 apps
|
||||
- 实现权限控制
|
||||
- 添加 API 文档 (Swagger)
|
||||
- 实现文件上传功能
|
||||
|
||||
2. **前端：**
|
||||
- 创建登录/注册页面
|
||||
- 添加路由保护
|
||||
- 实现加载状态处理
|
||||
- 添加错误处理
|
||||
|
||||
3. **部署：**
|
||||
- 配置 HTTPS (Let's Encrypt)
|
||||
- 设置 CI/CD
|
||||
- 配置日志收集
|
||||
- 实现自动备份
|
||||
Reference in New Issue
Block a user