chengshishouce/city-manual/docs/README.md

城市手册 - 项目文档

文档索引

核心文档

文档	说明	路径
📖 需求文档	项目需求说明	城市手册需求文档.md
🏗️ 架构文档	系统架构设计	ARCHITECTURE.md
🔌 API 文档	API 接口说明	API.md
📝 实施计划	需求实施进度	REQUIREMENTS_IMPLEMENTATION.md

开发文档

文档	说明	路径
💻 开发指南	开发环境配置	DEVELOPMENT_SUMMARY.md
🚀 部署指南	生产环境部署	DEPLOYMENT.md
🧪 测试指南	测试方法和用例	TESTING.md
🤖 AI 助手	AI 协作指南	AI_AGENT.md

技能文档

技能	说明	路径
📦 部署技能	自动化部署	skills/city-manual-deploy/SKILL.md
🧪 测试技能	测试和验证	skills/city-manual-test/SKILL.md
📝 内容技能	内容管理	skills/city-manual-content/SKILL.md

快速开始

开发环境

# 克隆项目
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

生产部署

# 使用部署脚本
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 工作流

# 创建功能分支
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: 构建/工具

测试

运行测试

# 后端测试
cd backend
python manage.py test

# 前端测试
cd frontend
npm test

# API 测试
python test_api.py

测试覆盖率

# 后端覆盖率
coverage run --source='.' manage.py test
coverage report
coverage html

监控和维护

健康检查

# 检查服务状态
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: 如何重置数据库？

cd backend
python manage.py flush
python manage.py migrate
python manage.py createsuperuser

Q: 如何重置管理员密码？

cd backend
python manage.py changepassword admin

Q: 如何查看 API 文档？

访问：http://localhost:8000/graphql/?graphiql

Q: 如何部署到生产环境？

参考 DEPLOYMENT.md

联系方式

• 项目仓库: http://10.2.0.100:8989/mashen/chengshishouce.git
• 在线访问: http://cssc.datalibstar.com/
• Admin: http://cssc.datalibstar.com/admin/

许可证

MIT License