HocTapAZ Docs

Appearance

Classroom Service API ​

SVC-006 Route Guard Proof ​

See Classroom Public Route Guard Proof for the accepted bounded proof of tenant-scoped native reads, owner-local profile/organization references, gateway identity headers, and the unchanged legacy default route state. Public /api/classrooms* promotion remains gated.

Non-default Classroom Read Candidate ​

The named candidate tables deploy/gateway/routes.classroom-read-native-example.json and deploy/gateway/routes.classroom-read-native-localhost-example.json expose only authenticated ADMIN/TEACHER reads:

  • GET /api/classrooms -> GET /v1/classrooms
  • GET /api/classrooms/{classroomId} -> GET /v1/classrooms/{classroomId}

Both require organization context and run before the broad legacy classroom fallback in the candidate table. routes.json remains unchanged, so no default caller uses this mapping. Candidate verification, including a memory-backed Gateway runtime smoke, is documented in Classroom Read Runtime Smoke. Keep the default table active to rollback.

Current Endpoints ​

  • GET /healthz
  • GET /readyz
  • GET /v1
  • GET /v1/admin/classrooms/summary
  • PUT /v1/classrooms/{classroomId}/snapshot
  • GET /v1/classrooms
  • POST /v1/classrooms
  • GET /v1/classrooms/{classroomId}
  • PATCH /v1/classrooms/{classroomId}
  • PATCH /v1/classrooms/{classroomId}/status
  • DELETE /v1/classrooms/{classroomId}
  • GET /v1/classrooms/{classroomId}/delete-impact
  • DELETE /v1/classrooms/{classroomId}/purge
  • GET /v1/classrooms/{classroomId}/members
  • POST /v1/classrooms/{classroomId}/members
  • PUT /v1/classrooms/{classroomId}/members/{userId}
  • DELETE /v1/classrooms/{classroomId}/members/{userId}
  • GET /v1/classrooms/{classroomId}/students
  • POST /v1/classrooms/{classroomId}/students
  • DELETE /v1/classrooms/{classroomId}/students/{studentId}
  • POST /v1/classrooms/{classroomId}/join
  • POST /v1/classrooms/{classroomId}/notifications
  • GET /v1/classrooms/{classroomId}/progress

Native Classroom Foundation ​

Phase 8 classroom-service starts with classroom and classroom-member ownership. This is an internal /v1 foundation, not a public /api/classrooms* or /api/admin/classrooms* cutover.

Legacy evidence:

  • node-platform/apps/api/src/modules/classrooms/classrooms.controller.ts:32-204 maps legacy classroom list/detail/create/update/status/delete/join/student/progress routes.
  • node-platform/apps/api/src/modules/classrooms/classrooms.controller.ts:803-1430 maps admin classroom list/create/update/detail/member/purge routes.
  • node-platform/apps/api/src/modules/app-data/app-data.classrooms-core.ts:38-520 implements legacy classroom list/detail/create/update/status rules, teacher membership creation, manager checks, and response counters.
  • node-platform/apps/api/src/modules/app-data/app-data.classrooms-support.ts:50-150 defines classroom manager, teacher-managed-classroom, reference, and membership assertions.
  • node-platform/apps/api/src/modules/app-data/app-data.public.ts:707-980 implements delete impact, soft archive vs hard delete, purge, join, remove student, and student list behavior.
  • node-platform/apps/api/src/modules/app-data/app-data.progress-overview.ts:17-48 implements classroom progress as a composition of classroom detail, student members, assignments, attempts, and weak topics.
  • node-platform/apps/api/prisma/schema.prisma:551-604 defines Classroom and ClassroomMember with unique code, unique publicSlug, unique (classroomId,userId), and ACTIVE/ARCHIVED status.
  • node-platform/packages/shared/src/index.ts:593-610 and node-platform/packages/shared/src/index.ts:1160-1178 define public slug, visibility, grade-level, and classroom input validation.
  • node-platform/apps/web/components/classroom/classroom-crud-client.tsx:168-336 consumes /classrooms, status, delete-impact, delete, and admin purge.
  • node-platform/apps/web/app/join/class/[code]/join-class-link-client.tsx:30-39 consumes /classrooms/{code}/join.

Native contract:

  • GET /v1/admin/classrooms/summary returns sourceService=classroom-service, classroom counts by status and visibility, featured classroom count, and classroom-member row counts by role for admin dashboard/source-map adapters. It is read-only and does not query IAM, profile-service, organization-service/school-service, exam-service, or attempt-service databases.
  • PUT /v1/classrooms/{classroomId}/snapshot upserts service-owned rows from legacy backfill, including timestamps, status, visibility, counters, and teacher/member data when supplied.
  • GET /v1/classrooms supports organizationId, teacherId, studentId, status, visibility, q, page, and limit; X-Actor-Id/X-Actor-Role scopes non-admin reads.
  • POST /v1/classrooms creates a classroom, generates a unique uppercase join code, and upserts the primary teacher as a TEACHER member.
  • GET /v1/classrooms/{classroomId} accepts id or code, preserving the legacy join-link lookup path.
  • PATCH /v1/classrooms/{classroomId} preserves partial update rules for name, description, summary, cover image, visibility, public slug, featured flag, grade level, subject id, and teacher id.
  • PATCH /v1/classrooms/{classroomId}/status sets ACTIVE or ARCHIVED.
  • DELETE /v1/classrooms/{classroomId} hard deletes only when there is no owned usage beyond the teacher membership; otherwise it archives and returns {deleted:false, archived:true}.
  • GET /v1/classrooms/{classroomId}/delete-impact returns service-owned counts immediately and zeroes deferred lesson/material/assignment/tuition counters until those slices are native.
  • DELETE /v1/classrooms/{classroomId}/purge hard deletes the service-owned classroom and members for internal/admin-gateway-only adapters; public gateway promotion still requires external RBAC and rollback evidence.
  • Member routes preserve upsert by (classroomId,userId), role updates, student join by id or code, student member listing, and primary-teacher reassignment when admin removes a teacher member.
  • POST /v1/classrooms/{classroomId}/notifications is an internal quick classroom notification producer. It requires clientRequestId, title, and content, loads current STUDENT classroom members from classroom-service storage, and best-effort emits notification-service POST /v1/events/notification with sourceService=classroom-service, sourceEventId=classroom:{classroomId}:notification:{clientRequestId}, type=classroom.notification.sent.v1, and preferenceType=CLASSROOM_NOTIFICATION. When PROFILE_SERVICE_URL or PROFILE_SERVICE_BASE_URL is configured, classroom-service resolves parent account ids through profile-service /v1/internal/profiles/parent-recipients/resolve and emits a separate replay-safe parent event with sourceEventId=classroom:{classroomId}:notification:{clientRequestId}:parents, type=classroom.notification.parent.sent.v1, and preferenceType=CLASSROOM_NOTIFICATION_PARENT. The response reports total, student, and parent accepted counts plus whether parent resolution completed and whether notification-service publish succeeded.
  • GET /v1/classrooms/{classroomId}/progress returns the classroom, current student member rows, assignedExamCount from the classroom snapshot/read-model counter, zero completion rate, and empty weak topics until exam/attempt/analytics adapters provide native data.

Analytics event handoff:

  • When ANALYTICS_SERVICE_URL or ANALYTICS_SERVICE_BASE_URL is configured, successful native membership mutations best-effort publish classroom.membership.snapshot.v1 to analytics-service POST /v1/analytics/events.
  • Event envelope: sourceService=classroom-service, entity=Classroom, entityId={classroomId}, and sourceEventId=classroom:{classroomId}:membership-snapshot:{occurredAtRFC3339Nano}.
  • Payloads reload the classroom and current member refs after the mutation and include schemaVersion, classroomId, organizationId, teacherId, status, subjectId, gradeLevel, trigger metadata, memberCount, studentCount, teacherCount, and members[{userId,role,joinedAt}]. Member fullName and email are intentionally excluded so analytics does not store profile PII from classroom membership events.
  • Delivery is best-effort: disabled or failing analytics-service delivery does not roll back the classroom membership write.
  • When NOTIFICATION_SERVICE_URL or NOTIFICATION_SERVICE_BASE_URL is configured, the quick classroom notification producer sends inbox events to notification-service. Parent fanout is additionally gated by PROFILE_SERVICE_URL or PROFILE_SERVICE_BASE_URL; resolver failure does not roll back the student event. Event payloads include classroom id, organization id, preference key, and recipient count only; they exclude member fullName, email, phone, parent-student links, and profile data.

Authorization model:

  • Native service accepts X-Actor-Id, X-Actor-Role, and X-Organization-Id; X-User-Id and X-User-Role are accepted as fallbacks for gateway-injected headers. Gateway remains responsible for JWT verification and public route RBAC.
  • ADMIN may manage any classroom in the requested organization scope.
  • TEACHER may manage classrooms where teacherId equals the actor or where the actor has a TEACHER classroom member row.
  • TEACHER cannot create or transfer a classroom to another teacher.
  • STUDENT list/detail access is membership-scoped and join may only add the actor as a student.
  • PARENT cannot read or manage classroom-service foundation routes.

Envelope:

json
{
  "success": true,
  "data": {
    "id": "class_local_math_6",
    "name": "Toan 6",
    "code": "A1B2C3",
    "status": "ACTIVE",
    "visibility": "PRIVATE",
    "gradeLevel": 6,
    "subjectId": "math",
    "teacherId": "teacher_1",
    "studentCount": 0,
    "_count": {
      "members": 1,
      "lessons": 0,
      "materials": 0,
      "assignments": 0
    }
  },
  "message": "OK"
}

Database:

  • services/classroom-service/migrations/000002_classrooms.sql creates classrooms and classroom_members.
  • classrooms.organization_id, unit_id, subject_id, teacher_id, and created_by_id store public ids from other services; classroom-service does not query other service databases.
  • classrooms.code is unique and stores the legacy uppercase join code.
  • classrooms.public_slug uses a partial unique index so null slugs are allowed.
  • classroom_members enforces unique (classroom_id,user_id) and stores only user ids plus role.

Validation queries:

sql
SELECT id, legacy_id, organization_id, name, code, status, teacher_id
FROM classrooms
ORDER BY created_at DESC
LIMIT 20;

SELECT classroom_id, user_id, role, joined_at
FROM classroom_members
ORDER BY joined_at DESC
LIMIT 20;

SELECT c.id, c.code, count(m.id) AS member_count
FROM classrooms c
LEFT JOIN classroom_members m ON m.classroom_id = c.id
GROUP BY c.id, c.code
ORDER BY c.id;

Rollback for this native slice:

  • Keep /api/classrooms*, /api/admin/classrooms*, and /api/classrooms/:id/notify routed to legacy.
  • Disable gateway callers for /v1/classrooms*.
  • Unset ANALYTICS_SERVICE_URL/ANALYTICS_SERVICE_BASE_URL to disable the membership analytics producer without changing classroom write behavior.
  • Unset NOTIFICATION_SERVICE_URL/NOTIFICATION_SERVICE_BASE_URL to disable the quick classroom notification producer without changing classroom roster behavior.
  • Unset PROFILE_SERVICE_URL/PROFILE_SERVICE_BASE_URL to disable parent recipient resolution while leaving student classroom notifications available.
  • Run make test-classroom-route-guard after route-table edits to prove public/admin classroom routes still stay legacy-proxied.
  • Keep lessons, materials, announcements, tuition, exam assignments, dashboard, leaderboard, and public catalog routes on legacy until their dedicated slices land.
  • Drop classroom-service local classroom_members and classrooms tables with the migration down step if local test data must be reset.

Non-goals for P8-004:

  • Public gateway adapter/cutover for /api/classrooms* or /api/admin/classrooms*.
  • Lesson, material, video, announcement, tuition, dashboard, leaderboard, exam, or exam-assignment ownership.
  • Subject, teacher, organization, and student existence checks against other service databases.
  • Full admin search hydration for teacher, organization, and subject names; gateway/user/school/question-bank adapters can hydrate later.
  • Derived analytics, weak topics, attempt scores, and assignment completion.
  • Exam attempt grading, answer analysis, weak-topic computation, and question ownership remain outside classroom-service.

Go-platform documentation is generated from repository Markdown.

Copyright 2026 HocTapAZ