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)
287 lines
6.3 KiB
Markdown
287 lines
6.3 KiB
Markdown
# 城市手册 - 项目文档
|
||
|
||
## 文档索引
|
||
|
||
### 核心文档
|
||
|
||
| 文档 | 说明 | 路径 |
|
||
|------|------|------|
|
||
| 📖 需求文档 | 项目需求说明 | [城市手册需求文档.md](../城市手册需求文档.md) |
|
||
| 🏗️ 架构文档 | 系统架构设计 | [ARCHITECTURE.md](./ARCHITECTURE.md) |
|
||
| 🔌 API 文档 | API 接口说明 | [API.md](./API.md) |
|
||
| 📝 实施计划 | 需求实施进度 | [REQUIREMENTS_IMPLEMENTATION.md](../REQUIREMENTS_IMPLEMENTATION.md) |
|
||
|
||
### 开发文档
|
||
|
||
| 文档 | 说明 | 路径 |
|
||
|------|------|------|
|
||
| 💻 开发指南 | 开发环境配置 | [DEVELOPMENT_SUMMARY.md](../DEVELOPMENT_SUMMARY.md) |
|
||
| 🚀 部署指南 | 生产环境部署 | [DEPLOYMENT.md](../DEPLOYMENT.md) |
|
||
| 🧪 测试指南 | 测试方法和用例 | [TESTING.md](../TESTING.md) |
|
||
| 🤖 AI 助手 | AI 协作指南 | [AI_AGENT.md](../AI_AGENT.md) |
|
||
|
||
### 技能文档
|
||
|
||
| 技能 | 说明 | 路径 |
|
||
|------|------|------|
|
||
| 📦 部署技能 | 自动化部署 | [skills/city-manual-deploy/SKILL.md](../skills/city-manual-deploy/SKILL.md) |
|
||
| 🧪 测试技能 | 测试和验证 | [skills/city-manual-test/SKILL.md](../skills/city-manual-test/SKILL.md) |
|
||
| 📝 内容技能 | 内容管理 | [skills/city-manual-content/SKILL.md](../skills/city-manual-content/SKILL.md) |
|
||
|
||
## 快速开始
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone http://10.2.0.100:8989/mashen/chengshishouce.git
|
||
cd chengshishouce/city-manual
|
||
|
||
# 后端启动
|
||
cd backend
|
||
python -m venv venv
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
python manage.py migrate
|
||
python manage.py runserver
|
||
|
||
# 前端启动
|
||
cd ../frontend
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
### 生产部署
|
||
|
||
```bash
|
||
# 使用部署脚本
|
||
cd /root/.openclaw/workspace/city-manual
|
||
./deploy.sh
|
||
|
||
# 或使用 Docker
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
city-manual/
|
||
├── docs/ # 项目文档
|
||
│ ├── ARCHITECTURE.md # 架构文档
|
||
│ ├── API.md # API 文档
|
||
│ └── README.md # 文档索引
|
||
├── skills/ # AgentSkills
|
||
│ ├── city-manual-deploy/ # 部署技能
|
||
│ ├── city-manual-test/ # 测试技能
|
||
│ └── city-manual-content/# 内容技能
|
||
├── backend/ # Django 后端
|
||
│ ├── config/ # 项目配置
|
||
│ ├── apps/ # Django 应用
|
||
│ └── manage.py # Django 管理脚本
|
||
├── frontend/ # React 前端
|
||
│ ├── src/ # 源代码
|
||
│ └── package.json # 依赖配置
|
||
├── scripts/ # 脚本文件
|
||
│ ├── deploy.sh # 部署脚本
|
||
│ └── gunicorn_start.sh # Gunicorn 启动脚本
|
||
└── test_api.py # API 测试脚本
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
### 后端
|
||
- **框架:** Django 4.2
|
||
- **API:** Django REST Framework + GraphQL
|
||
- **认证:** JWT
|
||
- **数据库:** PostgreSQL
|
||
|
||
### 前端
|
||
- **框架:** React 18
|
||
- **状态管理:** MobX
|
||
- **样式:** styled-components
|
||
- **路由:** React Router
|
||
|
||
### 部署
|
||
- **容器:** Docker & Docker Compose
|
||
- **服务器:** Nginx + Gunicorn
|
||
- **监控:** 健康检查 + 日志
|
||
|
||
## 核心功能
|
||
|
||
### 用户系统
|
||
- ✅ 用户注册/登录
|
||
- ✅ JWT 认证
|
||
- ✅ 个人中心
|
||
- ✅ 角色管理
|
||
|
||
### 版块管理
|
||
- ✅ 省→市→县→乡镇→村 五级层级
|
||
- ✅ 版块 CRUD
|
||
- ✅ 版主申请
|
||
|
||
### 内容管理
|
||
- ✅ 文章管理
|
||
- ✅ 特色服务
|
||
- ✅ 内容审核（版主 + AI）
|
||
|
||
### 互动功能
|
||
- ✅ 评论
|
||
- ✅ 评分
|
||
- ✅ 点赞
|
||
- ✅ 收藏
|
||
|
||
## 数据库设计
|
||
|
||
### 核心表
|
||
|
||
| 表名 | 说明 | 主要字段 |
|
||
|------|------|----------|
|
||
| `users_user` | 用户表 | username, email, role |
|
||
| `regions_region` | 版块表 | name, level, parent |
|
||
| `articles_article` | 文章表 | title, content, region, category |
|
||
| `services_featuredservice` | 特色服务表 | name, description, category |
|
||
| `interactions_comment` | 评论表 | content, object_type, object_id |
|
||
| `interactions_rating` | 评分表 | score, object_type, object_id |
|
||
| `interactions_like` | 点赞表 | object_type, object_id |
|
||
| `interactions_favorite` | 收藏表 | object_type, object_id |
|
||
|
||
## API 端点
|
||
|
||
### REST API
|
||
|
||
- `GET /api/users/` - 用户列表
|
||
- `POST /api/auth/token/` - 登录
|
||
- `GET /api/regions/` - 版块列表
|
||
- `GET /api/articles/` - 文章列表
|
||
- `GET /api/services/` - 特色服务列表
|
||
|
||
### GraphQL API
|
||
|
||
- `POST /graphql/` - GraphQL 端点
|
||
- `GET /graphql/?graphiql` - GraphQL Playground
|
||
|
||
## 开发规范
|
||
|
||
### 代码风格
|
||
|
||
**Python:**
|
||
- 遵循 PEP 8
|
||
- 使用 Black 格式化
|
||
- 类型注解
|
||
|
||
**JavaScript:**
|
||
- 使用 ESLint
|
||
- 使用 Prettier
|
||
- ES6+ 语法
|
||
|
||
### Git 工作流
|
||
|
||
```bash
|
||
# 创建功能分支
|
||
git checkout -b feature/feature-name
|
||
|
||
# 提交代码
|
||
git add .
|
||
git commit -m "feat: add new feature"
|
||
|
||
# 推送分支
|
||
git push origin feature/feature-name
|
||
|
||
# 创建 Pull Request
|
||
```
|
||
|
||
### 提交信息规范
|
||
|
||
- `feat:` 新功能
|
||
- `fix:` 修复 bug
|
||
- `docs:` 文档更新
|
||
- `style:` 代码格式
|
||
- `refactor:` 重构
|
||
- `test:` 测试
|
||
- `chore:` 构建/工具
|
||
|
||
## 测试
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 后端测试
|
||
cd backend
|
||
python manage.py test
|
||
|
||
# 前端测试
|
||
cd frontend
|
||
npm test
|
||
|
||
# API 测试
|
||
python test_api.py
|
||
```
|
||
|
||
### 测试覆盖率
|
||
|
||
```bash
|
||
# 后端覆盖率
|
||
coverage run --source='.' manage.py test
|
||
coverage report
|
||
coverage html
|
||
```
|
||
|
||
## 监控和维护
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
curl http://127.0.0.1:8000/admin/
|
||
curl http://127.0.0.1/
|
||
|
||
# 检查数据库
|
||
psql -h 10.2.0.100 -U coder -d cssc -c "SELECT 1"
|
||
|
||
# 检查日志
|
||
tail -f /var/log/nginx/error.log
|
||
tail -f gunicorn.log
|
||
```
|
||
|
||
### 日志管理
|
||
|
||
- **Django 日志:** `backend/logs/`
|
||
- **Nginx 日志:** `/var/log/nginx/`
|
||
- **Gunicorn 日志:** `gunicorn.log`
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何重置数据库？
|
||
|
||
```bash
|
||
cd backend
|
||
python manage.py flush
|
||
python manage.py migrate
|
||
python manage.py createsuperuser
|
||
```
|
||
|
||
### Q: 如何重置管理员密码？
|
||
|
||
```bash
|
||
cd backend
|
||
python manage.py changepassword admin
|
||
```
|
||
|
||
### Q: 如何查看 API 文档？
|
||
|
||
访问：http://localhost:8000/graphql/?graphiql
|
||
|
||
### Q: 如何部署到生产环境？
|
||
|
||
参考 [DEPLOYMENT.md](../DEPLOYMENT.md)
|
||
|
||
## 联系方式
|
||
|
||
- **项目仓库:** http://10.2.0.100:8989/mashen/chengshishouce.git
|
||
- **在线访问:** http://cssc.datalibstar.com/
|
||
- **Admin:** http://cssc.datalibstar.com/admin/
|
||
|
||
## 许可证
|
||
|
||
MIT License
|