Initial commit: React + Django 城市手册项目

- Django 4.2 + DRF + JWT + GraphQL
- React 18 + MobX + styled-components
- PostgreSQL 数据库
- Docker + Docker Compose + Nginx
- 完整的功能模块（用户、版块、文章、服务、交互、版主管理）
- 完整的文档（需求、部署、测试）

backend/apps/regions/__init__.py

@@ -0,0 +1 @@
+# Regions app

backend/apps/regions/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class RegionsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'apps.regions'
+    verbose_name = '版块管理'

backend/apps/regions/models.py

@@ -0,0 +1,54 @@
+from django.db import models
+
+
+class Region(models.Model):
+    """Region model for hierarchical administrative divisions."""
+
+    LEVEL_CHOICES = [
+        ('province', '省'),
+        ('city', '市'),
+        ('county', '县'),
+        ('town', '乡镇/街道'),
+        ('village', '村/居委会'),
+    ]
+
+    STATUS_CHOICES = [
+        ('active', '正常'),
+        ('inactive', '停用'),
+    ]
+
+    name = models.CharField(max_length=100, verbose_name='版块名称')
+    level = models.CharField(max_length=20, choices=LEVEL_CHOICES, verbose_name='版块级别')
+    parent = models.ForeignKey(
+        'self',
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name='children',
+        verbose_name='上级版块'
+    )
+    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='active', verbose_name='状态')
+    created_at = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')
+    updated_at = models.DateTimeField(auto_now=True, verbose_name='更新时间')
+
+    class Meta:
+        db_table = 'regions'
+        verbose_name = '版块'
+        verbose_name_plural = '版块'
+        ordering = ['level', 'name']
+
+    def __str__(self):
+        return self.name
+
+    def get_full_path(self):
+        """Get the full hierarchical path of this region."""
+        path = [self.name]
+        parent = self.parent
+        while parent:
+            path.insert(0, parent.name)
+            parent = parent.parent
+        return ' → '.join(path)
+
+    def get_children(self):
+        """Get all direct children of this region."""
+        return self.children.filter(status='active')

backend/apps/regions/serializers.py

@@ -0,0 +1,53 @@
+from rest_framework import serializers
+from .models import Region
+
+
+class RegionSerializer(serializers.ModelSerializer):
+    """Serializer for Region model."""
+
+    level_display = serializers.CharField(source='get_level_display', read_only=True)
+    status_display = serializers.CharField(source='get_status_display', read_only=True)
+    parent_name = serializers.CharField(source='parent.name', read_only=True, allow_null=True)
+    children_count = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Region
+        fields = ('id', 'name', 'level', 'level_display', 'parent', 'parent_name',
+                  'status', 'status_display', 'children_count', 'created_at', 'updated_at')
+        read_only_fields = ('id', 'created_at', 'updated_at')
+
+    def get_children_count(self, obj):
+        return obj.children.count()
+
+
+class RegionDetailSerializer(serializers.ModelSerializer):
+    """Detailed serializer for Region model."""
+
+    level_display = serializers.CharField(source='get_level_display', read_only=True)
+    status_display = serializers.CharField(source='get_status_display', read_only=True)
+    parent = RegionSerializer(read_only=True)
+    children = RegionSerializer(many=True, read_only=True)
+    full_path = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Region
+        fields = ('id', 'name', 'level', 'level_display', 'parent', 'children',
+                  'status', 'status_display', 'full_path', 'created_at', 'updated_at')
+        read_only_fields = ('id', 'created_at', 'updated_at')
+
+    def get_full_path(self, obj):
+        return obj.get_full_path()
+
+
+class RegionTreeSerializer(serializers.ModelSerializer):
+    """Serializer for Region tree structure."""
+
+    children = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Region
+        fields = ('id', 'name', 'level', 'status', 'children')
+
+    def get_children(self, obj):
+        children = obj.get_children()
+        return RegionTreeSerializer(children, many=True).data

backend/apps/regions/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from .views import RegionViewSet
+
+router = DefaultRouter()
+router.register(r'regions', RegionViewSet, basename='region')
+
+urlpatterns = [
+    path('', include(router.urls)),
+]

backend/apps/regions/views.py

@@ -0,0 +1,141 @@
+from rest_framework import viewsets, permissions, filters
+from rest_framework.decorators import action
+from rest_framework.response import Response
+from django.shortcuts import get_object_or_404
+from .models import Region
+from .serializers import (
+    RegionSerializer,
+    RegionDetailSerializer,
+    RegionTreeSerializer
+)
+from apps.interactions.models import Rating, Favorite
+
+
+class RegionViewSet(viewsets.ModelViewSet):
+    """ViewSet for Region model."""
+
+    queryset = Region.objects.filter(status='active')
+    permission_classes = [permissions.IsAuthenticatedOrReadOnly]
+    filter_backends = [filters.SearchFilter, filters.OrderingFilter]
+    search_fields = ['name']
+    ordering_fields = ['name', 'level', 'created_at']
+    ordering = ['level', 'name']
+
+    def get_serializer_class(self):
+        if self.action == 'retrieve':
+            return RegionDetailSerializer
+        elif self.action == 'tree':
+            return RegionTreeSerializer
+        return RegionSerializer
+
+    def perform_create(self, serializer):
+        # Only admin can create regions
+        if not self.request.user.is_admin():
+            from rest_framework.exceptions import PermissionDenied
+            raise PermissionDenied("Only admins can create regions")
+        serializer.save()
+
+    def perform_update(self, serializer):
+        # Only admin can update regions
+        if not self.request.user.is_admin():
+            from rest_framework.exceptions import PermissionDenied
+            raise PermissionDenied("Only admins can update regions")
+        serializer.save()
+
+    @action(detail=False, methods=['get'])
+    def provinces(self, request):
+        """Get all provinces (top-level regions)."""
+        provinces = self.queryset.filter(parent__isnull=True)
+        serializer = self.get_serializer(provinces, many=True)
+        return Response(serializer.data)
+
+    @action(detail=True, methods=['get'])
+    def children(self, request, pk=None):
+        """Get children of a region."""
+        region = self.get_object()
+        children = region.get_children()
+        serializer = self.get_serializer(children, many=True)
+        return Response(serializer.data)
+
+    @action(detail=True, methods=['get'])
+    def path(self, request, pk=None):
+        """Get full path of a region."""
+        region = self.get_object()
+        path = []
+        current = region
+        while current:
+            serializer = self.get_serializer(current)
+            path.insert(0, serializer.data)
+            current = current.parent
+        return Response(path)
+
+    @action(detail=False, methods=['get'])
+    def tree(self, request):
+        """Get region tree structure."""
+        root_regions = self.queryset.filter(parent__isnull=True)
+        serializer = RegionTreeSerializer(root_regions, many=True)
+        return Response(serializer.data)
+
+    @action(detail=True, methods=['get'])
+    def articles(self, request, pk=None):
+        """Get articles for a region."""
+        region = self.get_object()
+        articles = region.articles.filter(publish_status='published')
+        from apps.articles.serializers import ArticleListSerializer
+        serializer = ArticleListSerializer(articles, many=True)
+        return Response(serializer.data)
+
+    @action(detail=True, methods=['get'])
+    def services(self, request, pk=None):
+        """Get featured services for a region."""
+        region = self.get_object()
+        services = region.featured_services.filter(publish_status='published')
+        from apps.featured_services.serializers import FeaturedServiceListSerializer
+        serializer = FeaturedServiceListSerializer(services, many=True)
+        return Response(serializer.data)
+
+    @action(detail=True, methods=['get'])
+    def stats(self, request, pk=None):
+        """Get statistics for a region."""
+        region = self.get_object()
+        return Response({
+            'articles_count': region.articles.filter(publish_status='published').count(),
+            'services_count': region.featured_services.filter(publish_status='published').count(),
+            'children_count': region.children.count(),
+        })
+
+    @action(detail=True, methods=['post'])
+    def rate(self, request, pk=None):
+        """Rate a region."""
+        region = self.get_object()
+        serializer = RatingCreateSerializer(data=request.data)
+        if serializer.is_valid():
+            serializer.save(target_type='region', target_id=region.id)
+            return Response({'message': 'Rating saved'}, status=201)
+        return Response(serializer.errors, status=400)
+
+    @action(detail=True, methods=['get'])
+    def my_rating(self, request, pk=None):
+        """Get user's rating for a region."""
+        region = self.get_object()
+        try:
+            rating = Rating.objects.get(
+                user=request.user,
+                target_type='region',
+                target_id=region.id
+            )
+            return Response({'score': rating.score})
+        except Rating.DoesNotExist:
+            return Response({'score': None})
+
+    @action(detail=True, methods=['post'])
+    def favorite(self, request, pk=None):
+        """Favorite or unfavorite a region."""
+        region = self.get_object()
+        serializer = FavoriteCreateSerializer(data=request.data)
+        if serializer.is_valid():
+            result = serializer.save(target_type='region', target_id=region.id)
+            if result is None:
+                return Response({'message': 'Unfavorited'}, status=200)
+            return Response({'message': 'Favorited'}, status=201)
+        return Response(serializer.errors, status=400)