chengshishouce/city-manual/docs/README.md

# 城市手册 - 项目文档

## 文档索引

### 核心文档

| 文档 | 说明 | 路径 |
|------|------|------|
| 📖 需求文档 | 项目需求说明 | [城市手册需求文档.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