docs: 添加项目文档和 AgentSkills

- 添加架构文档 (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)
2026-04-12 13:36:21 +00:00
parent 572a06a12c
commit 81632c1b35
6 changed files with 1772 additions and 0 deletions
--- a/city-manual/docs/ARCHITECTURE.md
+++ b/city-manual/docs/ARCHITECTURE.md
@@ -0,0 +1,278 @@
+# 城市手册 - 系统架构文档
+
+## 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 版本控制
+- 微服务拆分预留