chengshishouce/city-manual/docs/ARCHITECTURE.md

# 城市手册 - 系统架构文档

## 1. 系统概述

城市手册是一个地方志兼本地生活服务平台，采用前后端分离架构。

## 2. 技术架构

### 2.1 整体架构

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   用户浏览器 │ ──→ │    Nginx     │ ──→ │   React     │
│             │ ←── │  反向代理    │ ←── │  前端应用   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                           │
                           ↓
                    ┌──────────────┐
                    │   Django     │
                    │  后端 API    │
                    └──────────────┘
                           │
                           ↓
                    ┌──────────────┐
                    │  PostgreSQL  │
                    │   数据库     │
                    └──────────────┘
```

### 2.2 技术栈

**前端：**
- React 18
- MobX（状态管理）
- styled-components（CSS-in-JS）
- React Router（路由）

**后端：**
- Django 4.2
- Django REST Framework
- JWT 认证
- GraphQL (Graphene)
- PostgreSQL

**部署：**
- Docker & Docker Compose
- Nginx（反向代理）
- Gunicorn（WSGI 服务器）

## 3. 目录结构

```
city-manual/
├── frontend/              # React 前端
│   ├── src/
│   │   ├── components/    # React 组件
│   │   ├── stores/        # MobX 状态管理
│   │   ├── services/      # API 服务
│   │   ├── styles/        # 全局样式
│   │   └── utils/         # 工具函数
│   └── public/
├── backend/               # Django 后端
│   ├── config/            # 项目配置
│   ├── apps/
│   │   ├── users/         # 用户管理
│   │   ├── regions/       # 版块管理
│   │   ├── articles/      # 内容管理
│   │   ├── services/      # 特色服务
│   │   └── interactions/  # 互动功能
│   └── static/            # 静态文件
├── docs/                  # 项目文档
├── skills/                # AgentSkills
└── scripts/               # 部署脚本
```

## 4. 核心模块

### 4.1 用户模块 (users)

**功能：**
- 用户注册/登录
- JWT 认证
- 个人中心
- 角色管理（普通用户/版主/管理员）

**数据表：**
- `users_user` - 用户表

### 4.2 版块模块 (regions)

**功能：**
- 省→市→县→乡镇→村 五级层级管理
- 版块 CRUD
- 版主申请

**数据表：**
- `regions_region` - 版块表
- `regions_moderatorapplication` - 版主申请表
- `regions_moderatorpermission` - 版主权限表

### 4.3 内容模块 (articles)

**功能：**
- 文章管理
- 内容审核（版主初审 + AI 审核）
- 发布流程

**数据表：**
- `articles_article` - 文章表

### 4.4 特色服务模块 (services)

**功能：**
- 特色服务管理（衣食住行娱乐旅游文化）
- 服务审核
- 服务展示

**数据表：**
- `services_featuredservice` - 特色服务表

### 4.5 互动模块 (interactions)

**功能：**
- 评论
- 评分
- 点赞
- 收藏

**数据表：**
- `interactions_comment` - 评论表
- `interactions_rating` - 评分表
- `interactions_like` - 点赞表
- `interactions_favorite` - 收藏表

## 5. API 设计

### 5.1 REST API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/users/` | GET, POST | 用户管理 |
| `/api/users/me/` | GET, PUT, PATCH | 当前用户 |
| `/api/auth/token/` | POST | 登录 |
| `/api/auth/token/refresh/` | POST | 刷新令牌 |
| `/api/regions/` | GET, POST | 版块管理 |
| `/api/articles/` | GET, POST | 文章管理 |
| `/api/services/` | GET, POST | 特色服务 |
| `/api/comments/` | GET, POST | 评论 |
| `/api/ratings/` | GET, POST | 评分 |
| `/api/likes/` | GET, POST | 点赞 |
| `/api/favorites/` | GET, POST | 收藏 |

### 5.2 GraphQL API

端点：`/graphql/`

**Query 类型：**
- `user(id: ID!)` - 获取用户
- `region(id: ID!)` - 获取版块
- `article(id: ID!)` - 获取文章
- `featuredService(id: ID!)` - 获取特色服务

**Mutation 类型：**
- `createArticle(input: ArticleInput!)` - 创建文章
- `updateArticle(id: ID!, input: ArticleInput!)` - 更新文章
- `deleteArticle(id: ID!)` - 删除文章

## 6. 审核流程

### 6.1 内容审核

```
用户提交 → 版主初审 → AI 审核 → 发布
            ↓          ↓
         拒绝       拒绝
```

### 6.2 版主申请

```
用户申请 → 征集支持 → 管理员审核 → 授予权限
            ↓
      支持不足（自动取消）
```

## 7. 权限控制

### 7.1 角色权限

| 角色 | 权限 |
|------|------|
| 普通用户 | 浏览、评论、评分、点赞、收藏、申请版主 |
| 版主 | 管辖范围内内容初审、申请创建版块 |
| 管理员 | 全局管理、版主审核、权限管理 |

### 7.2 版主审核权限

版主只能审核其管辖范围内的内容：
- 省级版主 → 全省内容
- 市级版主 → 全市内容
- 县级版主 → 全县内容
- 以此类推

## 8. 部署架构

### 8.1 生产环境

```
用户 → Nginx (80/443) → Gunicorn (8000) → Django
                              ↓
                        PostgreSQL (5432)
```

### 8.2 Docker 服务

- `web` - Django 后端
- `frontend` - React 前端（Nginx）
- `db` - PostgreSQL
- `redis` - 缓存（可选）

## 9. 安全考虑

### 9.1 认证安全
- JWT 令牌认证
- 令牌有效期控制
- 刷新令牌机制

### 9.2 数据安全
- 密码加密存储（PBKDF2）
- SQL 注入防护（Django ORM）
- XSS 防护

### 9.3 访问控制
- CORS 配置
- 权限验证
- 速率限制

## 10. 性能优化

### 10.1 数据库优化
- 索引设计
- 查询优化
- 连接池

### 10.2 缓存策略
- Redis 缓存
- 页面缓存
- API 响应缓存

### 10.3 前端优化
- 代码分割
- 懒加载
- 资源压缩

## 11. 监控和日志

### 11.1 应用监控
- 错误追踪
- 性能监控
- 用户行为分析

### 11.2 日志管理
- Django 日志
- Nginx 日志
- 系统日志

## 12. 扩展性设计

### 12.1 水平扩展
- 无状态服务设计
- 数据库读写分离
- 负载均衡

### 12.2 功能扩展
- 插件化设计
- API 版本控制
- 微服务拆分预留