ruoyi-vue-pro/tools/education-student-harness/endpoint-matrix.md

Endpoint matrix

All paths below are browser-relative /app-api routes. The server derives authenticated user and tenant context; the harness never sends those as business fields.

Capability	Method	Relative route	Request/query used by harness	Expected data shape	Notes
Tenant resolution	GET	/education/tenant/resolve	deployment-specific resolver query; not called automatically	tenant resolution object	Use server entry-point/domain policy; do not accept a client tenant override.
Education context	GET	/education/context	none	{ userId, tenantId, tenantName, displayName }	Authenticated; verifies active tenant.
Regions	GET	/education/catalog/regions	none	array of region objects	Catalog read gate applies.
Categories	GET	/education/catalog/categories	subjectId, optional nodeId	array	Catalog read gate applies.
Subjects	GET	/education/catalog/subjects	optional regionId, schoolId, majorId, moduleId, type	array	Catalog read gate applies.
Question collections	GET	/education/catalog/question-collections	optional regionId, entryId, nodeId, collectionType, limit	array of collections	Harness uses this as the practice start list.
Safe question page	GET	/education/questions/page	collectionId, pageNo, pageSize	page result { list, total }	Must not include answers or explanations.
Practice preview	GET	/education/practice-config/preview	request VO query fields	preview object	Validates criteria without creating a session.
Create practice	POST	/education/practice-session/create	{ clientSessionId, collectionId, nodeId?, type?, difficulty?, questionCount }	practice session	Idempotent by client session ID.
Current practice	GET	/education/practice-session/current	none	session or null	Used for refresh recovery.
Practice by ID	GET	/education/practice-session/get	id	session	Ownership and tenant checks are server-side.
Save answer	PUT	/education/practice-session/answer	{ sessionId, questionSequence, selectedAnswer, idempotencyKey, clientSequence, expectedSessionVersion }	answer save result with version	Idempotent and stale-write resistant.
Submit practice	POST	/education/practice-session/submit	{ sessionId, idempotencyKey, expectedSessionVersion }	submit/report result	Atomic one-way transition; safe retry.
Report	GET	/education/practice-session/report	sessionId	report with details	Correct answers/explanations only after submit.
Report history	GET	/education/practice-session/reports	pageNo, pageSize	page result	Current student only.
Wrong questions	GET	/education/wrong-question/page	pageNo, pageSize, optional masterStatus	page result	Current student only.
Wrong question detail	GET	/education/wrong-question/get	id	detail	Includes answer/explanation after failure is recorded.
Mark mastered	PUT	/education/wrong-question/master	id	boolean	Idempotent.
Unmark mastered	PUT	/education/wrong-question/unmaster	id	boolean	Idempotent.
Wrong-question review	POST	/education/wrong-question/review-session	{ clientSessionId, wrongQuestionIds[] }	practice session	Server validates ownership.
Favorites	GET	/education/favorite/page	pageNo, pageSize, optional targetType	page result	Current student only.
Favorite create	POST	/education/favorite/create	{ targetType: 'QUESTION', targetId }	favorite item	Idempotent.
Favorite delete	DELETE	/education/favorite/delete	{ id? or targetType, targetId? }	boolean	Logical/idempotent removal.
Favorite status	POST	/education/favorite/status	{ questionIds[] }	{ questionIds }	Batch status probe.

Envelope and failures

The project convention is a common result envelope. Successful payloads are expected under data; page payloads generally contain list and total. Errors should remain errors rather than becoming empty success data. Capture the server-provided request/trace ID for local investigation, but never record authorization headers or full sensitive response bodies.

The route prefix is intentionally /app-api, not a direct Scalar URL. If the local server uses another deployment prefix, adapt the reverse proxy rather than changing the harness to call Scalar.