-
GEOMETRY BOARD
几何画板
依次点击构造点、线段和圆；支持中点、长度与坐标测量。
-
diff --git a/backend/toolbox/admin.py b/backend/toolbox/admin.py
new file mode 100644
index 0000000..2b0a326
--- /dev/null
+++ b/backend/toolbox/admin.py
@@ -0,0 +1,20 @@
+from django.contrib import admin
+
+from .models import BoardSession
+
+
+@admin.register(BoardSession)
+class BoardSessionAdmin(admin.ModelAdmin):
+ list_display = (
+ "code",
+ "mode",
+ "host",
+ "guest",
+ "status",
+ "guest_score",
+ "created_at",
+ )
+ list_filter = ("mode", "status")
+ search_fields = ("code", "host__username", "guest__username")
+ readonly_fields = ("code", "target", "created_at", "completed_at")
+ ordering = ("-created_at",)
diff --git a/backend/toolbox/board_services.py b/backend/toolbox/board_services.py
new file mode 100644
index 0000000..0d48426
--- /dev/null
+++ b/backend/toolbox/board_services.py
@@ -0,0 +1,147 @@
+import secrets
+from datetime import timedelta
+
+from asgiref.sync import async_to_sync
+from channels.layers import get_channel_layer
+from django.db import transaction
+from django.utils import timezone
+from rest_framework.exceptions import ValidationError
+
+from .models import BoardSession
+
+BOARD_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+BOARD_TTL = timedelta(minutes=30)
+DRAW_GUESS_TARGETS = (
+ "抛物线",
+ "三角形",
+ "勾股定理",
+ "质数",
+ "圆",
+ "正弦函数",
+ "分数",
+ "坐标系",
+)
+
+
+def _new_board_code():
+ for _ in range(20):
+ code = "".join(secrets.choice(BOARD_CODE_ALPHABET) for _ in range(6))
+ if not BoardSession.objects.filter(code=code).exists():
+ return code
+ raise ValidationError("暂时无法生成画板联机码，请稍后重试")
+
+
+def broadcast_board(session_id, reason):
+ channel_layer = get_channel_layer()
+ if channel_layer is None:
+ return
+ async_to_sync(channel_layer.group_send)(
+ f"board_{session_id}",
+ {
+ "type": "board.state",
+ "reason": reason,
+ },
+ )
+
+
+def board_payload(session, user):
+ is_host = session.host_id == user.id
+ reveal_target = (
+ session.mode == BoardSession.Mode.DRAW_GUESS
+ and (is_host or session.status == BoardSession.Status.COMPLETED)
+ )
+ return {
+ "session_id": session.id,
+ "code": session.code,
+ "mode": session.mode,
+ "mode_label": session.get_mode_display(),
+ "status": session.status,
+ "role": "host" if is_host else "guest",
+ "target": session.target if reveal_target else None,
+ "host": session.host.nickname,
+ "guest": session.guest.nickname if session.guest else None,
+ "host_score": session.host_score,
+ "guest_score": session.guest_score,
+ "expires_at": session.expires_at,
+ "websocket_path": f"/ws/v1/toolbox/boards/{session.id}/",
+ }
+
+
+@transaction.atomic
+def create_board(user, mode):
+ if mode not in BoardSession.Mode.values:
+ raise ValidationError({"mode": "不支持的画板联机模式"})
+ BoardSession.objects.filter(
+ host=user,
+ status=BoardSession.Status.WAITING,
+ ).update(status=BoardSession.Status.CANCELLED)
+ return BoardSession.objects.create(
+ code=_new_board_code(),
+ mode=mode,
+ host=user,
+ target=(
+ secrets.choice(DRAW_GUESS_TARGETS)
+ if mode == BoardSession.Mode.DRAW_GUESS
+ else ""
+ ),
+ expires_at=timezone.now() + BOARD_TTL,
+ )
+
+
+@transaction.atomic
+def join_board(user, code):
+ normalized = str(code or "").strip().upper()
+ if len(normalized) != 6 or any(
+ character not in BOARD_CODE_ALPHABET for character in normalized
+ ):
+ raise ValidationError({"code": "画板联机码应为 6 位大写字母或数字"})
+ try:
+ session = (
+ BoardSession.objects.select_for_update()
+ .select_related("host", "guest")
+ .get(code=normalized)
+ )
+ except BoardSession.DoesNotExist as exc:
+ raise ValidationError({"code": "画板联机码不存在"}) from exc
+ if session.host_id == user.id:
+ raise ValidationError({"code": "不能加入自己创建的画板"})
+ if session.status != BoardSession.Status.WAITING:
+ raise ValidationError({"code": "画板联机码已失效或已被使用"})
+ if session.expires_at <= timezone.now():
+ session.status = BoardSession.Status.CANCELLED
+ session.save(update_fields=["status"])
+ raise ValidationError({"code": "画板联机码已经过期"})
+ session.guest = user
+ session.status = BoardSession.Status.ACTIVE
+ session.save(update_fields=["guest", "status"])
+ transaction.on_commit(lambda: broadcast_board(session.id, "joined"))
+ return session
+
+
+@transaction.atomic
+def submit_guess(user, session_id, raw_guess):
+ session = (
+ BoardSession.objects.select_for_update()
+ .select_related("host", "guest")
+ .get(id=session_id)
+ )
+ if session.guest_id != user.id:
+ raise ValidationError("只有猜题方可以提交答案")
+ if (
+ session.mode != BoardSession.Mode.DRAW_GUESS
+ or session.status != BoardSession.Status.ACTIVE
+ ):
+ raise ValidationError("当前画板不接受猜题")
+ guess = str(raw_guess or "").strip()
+ if not guess or len(guess) > 40:
+ raise ValidationError({"guess": "请输入不超过 40 个字符的数学对象"})
+ correct = guess.replace(" ", "").lower() == session.target.replace(" ", "").lower()
+ if correct:
+ session.guest_score += 1
+ session.status = BoardSession.Status.COMPLETED
+ session.completed_at = timezone.now()
+ session.save(
+ update_fields=["guest_score", "status", "completed_at"]
+ )
+ transaction.on_commit(lambda: broadcast_board(session.id, "completed"))
+ return session, correct
diff --git a/backend/toolbox/consumers.py b/backend/toolbox/consumers.py
new file mode 100644
index 0000000..38e595e
--- /dev/null
+++ b/backend/toolbox/consumers.py
@@ -0,0 +1,100 @@
+import json
+
+from channels.db import database_sync_to_async
+from channels.generic.websocket import AsyncJsonWebsocketConsumer
+
+from .models import BoardSession
+
+
+class BoardConsumer(AsyncJsonWebsocketConsumer):
+ async def connect(self):
+ self.session_id = self.scope["url_route"]["kwargs"]["session_id"]
+ self.group_name = f"board_{self.session_id}"
+ user = self.scope["user"]
+ if not user.is_authenticated or not await self._is_participant(user.id):
+ await self.close(code=4403)
+ return
+ await self.channel_layer.group_add(self.group_name, self.channel_name)
+ await self.accept()
+ await self.send_json(
+ {
+ "type": "connected",
+ "session_id": str(self.session_id),
+ }
+ )
+
+ async def disconnect(self, close_code):
+ if hasattr(self, "group_name"):
+ await self.channel_layer.group_discard(
+ self.group_name,
+ self.channel_name,
+ )
+
+ async def receive_json(self, content, **kwargs):
+ event_type = content.get("type")
+ if event_type == "ping":
+ await self.send_json({"type": "pong"})
+ return
+ if event_type not in {"canvas", "geometry"}:
+ await self.send_json({"type": "error", "message": "不支持的画板消息"})
+ return
+ if not await self._is_active():
+ await self.send_json({"type": "error", "message": "画板尚未开始或已经结束"})
+ return
+ payload = content.get("payload")
+ if event_type == "canvas":
+ valid = (
+ isinstance(payload, str)
+ and payload.startswith("data:image/")
+ and len(payload) <= 700_000
+ )
+ else:
+ valid = isinstance(payload, dict) and len(
+ json.dumps(payload, ensure_ascii=False)
+ ) <= 100_000
+ if not valid:
+ await self.send_json({"type": "error", "message": "画板消息无效或过大"})
+ return
+ await self.channel_layer.group_send(
+ self.group_name,
+ {
+ "type": "board.update",
+ "event_type": event_type,
+ "payload": payload,
+ "user_id": str(self.scope["user"].id),
+ },
+ )
+
+ async def board_update(self, event):
+ await self.send_json(
+ {
+ "type": event["event_type"],
+ "payload": event["payload"],
+ "user_id": event["user_id"],
+ }
+ )
+
+ async def board_state(self, event):
+ await self.send_json(
+ {
+ "type": "state",
+ "reason": event["reason"],
+ "session_id": str(self.session_id),
+ }
+ )
+
+ @database_sync_to_async
+ def _is_participant(self, user_id):
+ return BoardSession.objects.filter(id=self.session_id).filter(
+ host_id=user_id
+ ).exists() or BoardSession.objects.filter(
+ id=self.session_id,
+ guest_id=user_id,
+ ).exists()
+
+ @database_sync_to_async
+ def _is_active(self):
+ return BoardSession.objects.filter(
+ id=self.session_id,
+ status=BoardSession.Status.ACTIVE,
+ ).exists()
diff --git a/backend/toolbox/migrations/0001_initial.py b/backend/toolbox/migrations/0001_initial.py
new file mode 100644
index 0000000..4ac8131
--- /dev/null
+++ b/backend/toolbox/migrations/0001_initial.py
@@ -0,0 +1,38 @@
+# Generated by Django 4.2.23 on 2026-08-09 16:35
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+import uuid
+
+
+class Migration(migrations.Migration):
+
+ initial = True
+
+ dependencies = [
+ migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='BoardSession',
+ fields=[
+ ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+ ('code', models.CharField(max_length=6, unique=True)),
+ ('mode', models.CharField(choices=[('collaborate', '协作展示'), ('draw_guess', '数学你画我猜')], default='collaborate', max_length=16)),
+ ('target', models.CharField(blank=True, max_length=40)),
+ ('host_score', models.PositiveSmallIntegerField(default=0)),
+ ('guest_score', models.PositiveSmallIntegerField(default=0)),
+ ('status', models.CharField(choices=[('waiting', '等待加入'), ('active', '进行中'), ('completed', '已完成'), ('cancelled', '已取消')], default='waiting', max_length=16)),
+ ('expires_at', models.DateTimeField()),
+ ('created_at', models.DateTimeField(auto_now_add=True)),
+ ('completed_at', models.DateTimeField(blank=True, null=True)),
+ ('guest', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='joined_board_sessions', to=settings.AUTH_USER_MODEL)),
+ ('host', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='hosted_board_sessions', to=settings.AUTH_USER_MODEL)),
+ ],
+ options={
+ 'ordering': ['-created_at'],
+ },
+ ),
+ ]
diff --git a/backend/toolbox/migrations/__init__.py b/backend/toolbox/migrations/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/toolbox/models.py b/backend/toolbox/models.py
new file mode 100644
index 0000000..6350f09
--- /dev/null
+++ b/backend/toolbox/models.py
@@ -0,0 +1,53 @@
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class BoardSession(models.Model):
+ class Mode(models.TextChoices):
+ COLLABORATE = "collaborate", "协作展示"
+ DRAW_GUESS = "draw_guess", "数学你画我猜"
+
+ class Status(models.TextChoices):
+ WAITING = "waiting", "等待加入"
+ ACTIVE = "active", "进行中"
+ COMPLETED = "completed", "已完成"
+ CANCELLED = "cancelled", "已取消"
+
+ id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+ code = models.CharField(max_length=6, unique=True)
+ mode = models.CharField(
+ max_length=16,
+ choices=Mode.choices,
+ default=Mode.COLLABORATE,
+ )
+ host = models.ForeignKey(
+ settings.AUTH_USER_MODEL,
+ on_delete=models.CASCADE,
+ related_name="hosted_board_sessions",
+ )
+ guest = models.ForeignKey(
+ settings.AUTH_USER_MODEL,
+ null=True,
+ blank=True,
+ on_delete=models.CASCADE,
+ related_name="joined_board_sessions",
+ )
+ target = models.CharField(max_length=40, blank=True)
+ host_score = models.PositiveSmallIntegerField(default=0)
+ guest_score = models.PositiveSmallIntegerField(default=0)
+ status = models.CharField(
+ max_length=16,
+ choices=Status.choices,
+ default=Status.WAITING,
+ )
+ expires_at = models.DateTimeField()
+ created_at = models.DateTimeField(auto_now_add=True)
+ completed_at = models.DateTimeField(null=True, blank=True)
+
+ class Meta:
+ ordering = ["-created_at"]
+
+ def __str__(self):
+ return f"{self.code} · {self.get_mode_display()}"
diff --git a/backend/toolbox/routing.py b/backend/toolbox/routing.py
new file mode 100644
index 0000000..35de309
--- /dev/null
+++ b/backend/toolbox/routing.py
@@ -0,0 +1,10 @@
+from django.urls import path
+
+from .consumers import BoardConsumer
+
+websocket_urlpatterns = [
+ path(
+ "ws/v1/toolbox/boards//",
+ BoardConsumer.as_asgi(),
+ ),
+]
diff --git a/backend/toolbox/test_consumers.py b/backend/toolbox/test_consumers.py
new file mode 100644
index 0000000..9eaebdf
--- /dev/null
+++ b/backend/toolbox/test_consumers.py
@@ -0,0 +1,78 @@
+from datetime import timedelta
+
+import pytest
+from asgiref.sync import async_to_sync
+from channels.routing import URLRouter
+from channels.testing import WebsocketCommunicator
+from django.urls import path
+from django.utils import timezone
+
+from accounts.models import User
+from toolbox.consumers import BoardConsumer
+from toolbox.models import BoardSession
+
+
+@pytest.mark.django_db(transaction=True)
+def test_board_consumer_参与者同步画布并拒绝局外人():
+ host = User.objects.create_user(
+ username="board_socket_host",
+ password="StrongPass_2026",
+ nickname="WS 房主",
+ )
+ guest = User.objects.create_user(
+ username="board_socket_guest",
+ password="StrongPass_2026",
+ nickname="WS 访客",
+ )
+ outsider = User.objects.create_user(
+ username="board_socket_outsider",
+ password="StrongPass_2026",
+ nickname="WS 局外人",
+ )
+ session = BoardSession.objects.create(
+ code="ABC234",
+ host=host,
+ guest=guest,
+ status=BoardSession.Status.ACTIVE,
+ expires_at=timezone.now() + timedelta(minutes=30),
+ )
+ application = URLRouter(
+ [
+ path(
+ "ws/test//",
+ BoardConsumer.as_asgi(),
+ )
+ ]
+ )
+
+ async def scenario():
+ outsider_socket = WebsocketCommunicator(
+ application,
+ f"/ws/test/{session.id}/",
+ )
+ outsider_socket.scope["user"] = outsider
+ connected, close_code = await outsider_socket.connect()
+ assert not connected
+ assert close_code == 4403
+
+ host_socket = WebsocketCommunicator(application, f"/ws/test/{session.id}/")
+ guest_socket = WebsocketCommunicator(application, f"/ws/test/{session.id}/")
+ host_socket.scope["user"] = host
+ guest_socket.scope["user"] = guest
+ assert (await host_socket.connect())[0]
+ assert (await guest_socket.connect())[0]
+ assert (await host_socket.receive_json_from())["type"] == "connected"
+ assert (await guest_socket.receive_json_from())["type"] == "connected"
+
+ payload = "data:image/png;base64,AAAA"
+ await host_socket.send_json_to({"type": "canvas", "payload": payload})
+ host_event = await host_socket.receive_json_from()
+ guest_event = await guest_socket.receive_json_from()
+ assert host_event["payload"] == payload
+ assert guest_event["payload"] == payload
+ assert guest_event["user_id"] == str(host.id)
+
+ await host_socket.disconnect()
+ await guest_socket.disconnect()
+
+ async_to_sync(scenario)()
diff --git a/backend/toolbox/test_views.py b/backend/toolbox/test_views.py
index bb92f10..91137a1 100644
--- a/backend/toolbox/test_views.py
+++ b/backend/toolbox/test_views.py
@@ -1,5 +1,8 @@
import pytest
+from accounts.models import User
+from toolbox.models import BoardSession
+
@pytest.mark.django_db
def test_calculator_api_公开访问并返回精确值(client):
@@ -23,3 +26,54 @@ def test_calculator_api_危险表达式返回四百(client):
assert response.status_code == 400
assert "error" in response.json()
+
+
+@pytest.mark.django_db
+def test_board_api_联机码加入你画我猜并服务端计分(client):
+ host = User.objects.create_user(
+ username="board_host",
+ password="StrongPass_2026",
+ nickname="画板房主",
+ )
+ guest = User.objects.create_user(
+ username="board_guest",
+ password="StrongPass_2026",
+ nickname="猜题玩家",
+ )
+ client.force_login(host)
+ created = client.post(
+ "/api/v1/toolbox/boards/",
+ {"mode": "draw_guess"},
+ content_type="application/json",
+ )
+ target = created.json()["target"]
+ code = created.json()["code"]
+ session_id = created.json()["session_id"]
+
+ client.force_login(guest)
+ joined = client.post(
+ "/api/v1/toolbox/boards/join/",
+ {"code": code.lower()},
+ content_type="application/json",
+ )
+ wrong = client.post(
+ f"/api/v1/toolbox/boards/{session_id}/guess/",
+ {"guess": "不是答案"},
+ content_type="application/json",
+ )
+ correct = client.post(
+ f"/api/v1/toolbox/boards/{session_id}/guess/",
+ {"guess": target},
+ content_type="application/json",
+ )
+
+ assert created.status_code == 201
+ assert created.json()["role"] == "host"
+ assert target
+ assert joined.status_code == 200
+ assert joined.json()["target"] is None
+ assert joined.json()["status"] == BoardSession.Status.ACTIVE
+ assert wrong.json()["correct"] is False
+ assert correct.json()["correct"] is True
+ assert correct.json()["guest_score"] == 1
+ assert correct.json()["status"] == BoardSession.Status.COMPLETED
diff --git a/backend/toolbox/urls.py b/backend/toolbox/urls.py
index 18f34de..0d66295 100644
--- a/backend/toolbox/urls.py
+++ b/backend/toolbox/urls.py
@@ -1,7 +1,21 @@
from django.urls import path
-from .views import CalculatorView
+from .views import (
+ BoardCreateView,
+ BoardGuessView,
+ BoardJoinView,
+ BoardStateView,
+ CalculatorView,
+)
urlpatterns = [
path("calculate/", CalculatorView.as_view(), name="toolbox-calculate"),
+ path("boards/", BoardCreateView.as_view(), name="board-create"),
+ path("boards/join/", BoardJoinView.as_view(), name="board-join"),
+ path("boards//", BoardStateView.as_view(), name="board-state"),
+ path(
+ "boards//guess/",
+ BoardGuessView.as_view(),
+ name="board-guess",
+ ),
]
diff --git a/backend/toolbox/views.py b/backend/toolbox/views.py
index 38d359c..b908b7a 100644
--- a/backend/toolbox/views.py
+++ b/backend/toolbox/views.py
@@ -1,10 +1,19 @@
+from django.db.models import Q
+from django.shortcuts import get_object_or_404
from rest_framework import permissions
from rest_framework.exceptions import ValidationError
from rest_framework.response import Response
from rest_framework.throttling import ScopedRateThrottle
from rest_framework.views import APIView
+from .board_services import (
+ board_payload,
+ create_board,
+ join_board,
+ submit_guess,
+)
from .engine import calculate
+from .models import BoardSession
class CalculatorView(APIView):
@@ -20,3 +29,42 @@ class CalculatorView(APIView):
except (ArithmeticError, NotImplementedError, TypeError, ValueError) as exc:
raise ValidationError({"expression": "该计算暂时无法完成，请缩小表达式范围"}) from exc
return Response(payload)
+
+
+class BoardCreateView(APIView):
+ def post(self, request):
+ session = create_board(
+ request.user,
+ request.data.get("mode", BoardSession.Mode.COLLABORATE),
+ )
+ return Response(board_payload(session, request.user), status=201)
+
+
+class BoardJoinView(APIView):
+ def post(self, request):
+ session = join_board(request.user, request.data.get("code"))
+ return Response(board_payload(session, request.user))
+
+
+class BoardStateView(APIView):
+ def get(self, request, session_id):
+ session = get_object_or_404(
+ BoardSession.objects.select_related("host", "guest").filter(
+ Q(host=request.user) | Q(guest=request.user)
+ ),
+ id=session_id,
+ )
+ return Response(board_payload(session, request.user))
+
+
+class BoardGuessView(APIView):
+ def post(self, request, session_id):
+ session, correct = submit_guess(
+ request.user,
+ session_id,
+ request.data.get("guess"),
+ )
+ payload = board_payload(session, request.user)
+ payload["correct"] = correct
+ payload["message"] = "猜对了，得 1 分" if correct else "还不对，再观察一下画板"
+ return Response(payload)