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 刷新

**自定义用户模型：**
```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
   - 配置日志收集
   - 实现自动备份