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 版本控制
• 微服务拆分预留