81632c1b35
- 添加架构文档 (ARCHITECTURE.md) - 添加 API 文档 (API.md) - 添加文档索引 (docs/README.md) - 添加部署技能 (skills/city-manual-deploy/SKILL.md) - 添加测试技能 (skills/city-manual-test/SKILL.md) - 添加内容管理技能 (skills/city-manual-content/SKILL.md)
279 lines
6.5 KiB
Markdown
279 lines
6.5 KiB
Markdown
# 城市手册 - 系统架构文档
|
||
|
||
## 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 版本控制
|
||
- 微服务拆分预留
|