chengshishouce/PROJECT_DOCS.md

项目架构文档

技术栈

后端 (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 刷新

自定义用户模型：

# 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：

type User {
  id: ID!
  email: String!
  username: String!
}

type Query {
  allUsers: [User!]!
  me: User
}

访问 /graphql/?graphiql 查看调试界面。

4. 状态管理 (MobX)

AuthStore：

• 管理认证状态
• 处理登录/登出
• 保存和读取 tokens

UserStore：

• 获取当前用户信息
• 管理用户数据状态

开发流程

1. 添加新的 API 端点

# 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

// 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 组件

// 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
   • 配置日志收集
   • 实现自动备份