CSMS Internal API

Version: CSMS v0.3.0+ · RESTful · prefix /api · JSON

This document describes the internal API used by the admin web frontend (Session auth) and the student client (Token auth). For the external third-party API, see External Open API v1.

Overview

• All endpoints are prefixed with /api.
• Request and response bodies are JSON (Content-Type: application/json).
• Admin endpoints require a Session cookie; student endpoints require a student Token.

Authentication

Session (Admin)

Step	Endpoint	Notes
1. Login	POST /api/auth/login	Returns a Session cookie
2. Current user	GET /api/auth/me	Read current admin profile
3. Update profile	PATCH /api/auth/me	Change own info / password
4. Logout	POST /api/auth/logout	Invalidates the session

Token (Student)

Step	Endpoint	Notes
1. Login	POST /api/auth/student/login	Returns a student token
2. Current info	GET /api/auth/student/me	Read own profile
3. Update info	PATCH /api/auth/student/me	Edit personal info (e.g. username)
4. Logout	POST /api/auth/student/logout	Invalidates the token

Unified Response Format

{
  "success": true,
  "data": { },
  "message": ""
}

Field	Type	Notes
success	boolean	true on success
data	any	Payload; may be null
message	string	Error / info message on failure

Note: this envelope (success/data/message) differs from the External Open API v1 envelope (code/message/data/requestId).

Endpoint Catalog

Admin Auth

Method	Path	Description
POST	/api/auth/login	Admin login → Session cookie
POST	/api/auth/logout	Admin logout
GET	/api/auth/me	Get current admin
PATCH	/api/auth/me	Update current admin

Student Auth

Method	Path	Description
POST	/api/auth/student/login	Student login → token
POST	/api/auth/student/logout	Student logout
GET	/api/auth/student/me	Get current student
PATCH	/api/auth/student/me	Update current student

School Management

Method	Path	Description
GET	/api/schools	List schools
GET	/api/schools/:id	Get one school
POST	/api/schools	Create school
PATCH	/api/schools/:id	Update school
DELETE	/api/schools/:id	Delete school

Grade Management

Method	Path	Description
GET	/api/grades	List grades
POST	/api/grades	Create grade
DELETE	/api/grades/:id	Delete grade

Class Management

Method	Path	Description
GET	/api/classes	List classes
POST	/api/classes	Create class
DELETE	/api/classes/:id	Delete class

User / Student Management

Method	Path	Description
GET	/api/users	List students
GET	/api/users/:id	Get one student
POST	/api/users	Create student
PATCH	/api/users/:id	Update student
DELETE	/api/users/:id	Delete student

Score Management

Method	Path	Description
POST	/api/scores/add	Add a score record
GET	/api/scores/logs	Get score logs
GET	/api/scores/templates	Get score templates
POST	/api/scores/templates	Create score template

Seating

Method	Path	Description
GET	/api/seats/data	Get seat data
POST	/api/seats/data/generate	Generate seating layout
PATCH	/api/seats/data/:id	Save seat data

Statistics

Method	Path	Description
GET	/api/stats/overview	Overview statistics
GET	/api/stats/records	Score-record statistics

Announcements

Method	Path	Description
GET	/api/announcements	Public announcement list
GET	/api/announcements/admin	Admin announcement list
POST	/api/announcements	Create announcement
PATCH	/api/announcements/:id	Update announcement
DELETE	/api/announcements/:id	Delete announcement

Onboarding Applications

Method	Path	Description
GET	/api/applications	List applications
POST	/api/applications	Submit application
PATCH	/api/applications/:id	Review application (approve / reject)

Teacher / Admin Management

Method	Path	Description
GET	/api/admin/list	List all admins
GET	/api/admin/manage	List manageable admins
GET	/api/admin/manage/:id	Get one admin
POST	/api/admin/manage	Create admin
PATCH	/api/admin/manage/:id	Update admin (affiliation, etc.)
DELETE	/api/admin/manage/:id	Delete admin

Term Management

Method	Path	Description
POST	/api/admin/term-switch	Switch current term

Student-side

Method	Path	Description
GET	/api/student/classmates	List classmates
GET	/api/student/logs	Get personal score logs

Error Codes

Failures return success: false with a message. Common categories: authentication failures (invalid/missing session or token), authorization failures (out of management scope), validation errors (missing/invalid fields), and not-found (404). See the Chinese 内部接口 reference for the full numeric error table.

Notes

• All admin operations are scoped by the caller's role (super/school/grade/class admin) — see .
• Student APIs are isolated from admin Session auth and only expose the student's own data.
• Score mutations are appended to score_logs for audit; the response envelope here is {success, data, message}, distinct from the v1 Open API.