AI Classification Apply Live Gateway Smoke

Purpose

make test-question-classification-apply-live is an opt-in write smoke for the non-default native AI classification apply gateway route. It verifies that PATCH /api/questions/ai-classify/apply reaches question-bank-service as question-classification-apply with native_write, while sibling AI classification routes continue to fall through to the broad legacy questions proxy.

The smoke is not part of normal validation because it mutates a real native question row.

Run make test-question-classification-apply-routes before this live smoke to statically prove the default route table stays legacy-only and the non-default native apply examples carve out only exact PATCH /api/questions/ai-classify/apply.

Prerequisites

• API Gateway is running with deploy/gateway/routes.question-classification-apply-native-localhost-example.json or the equivalent deployed route table.
• question-bank-service is running and owns the target native question row.
• The caller has a legacy access token or cookie for an ADMIN or TEACHER in the target organization.
• The selected question can safely receive the supplied classification field.

Command

cd go-platform
QUESTION_CLASSIFICATION_APPLY_CONFIRM=apply-native \
QUESTION_CLASSIFICATION_APPLY_QUESTION_ID=<native-question-id> \
QUESTION_CLASSIFICATION_APPLY_AUTHORIZATION='Bearer <token>' \
QUESTION_CLASSIFICATION_APPLY_ORGANIZATION_ID=<org-id> \
make test-question-classification-apply-live

By default the smoke applies type=ESSAY. Override the generated body with:

QUESTION_CLASSIFICATION_APPLY_FIELD=difficultyLevelId \
QUESTION_CLASSIFICATION_APPLY_VALUE=<stored-difficulty-id-or-name>

For exact control, pass QUESTION_CLASSIFICATION_APPLY_BODY_JSON or QUESTION_CLASSIFICATION_APPLY_BODY_FILE.

Assertions

• GET /v1/routes exposes question-classification-apply with:
  • prefix /api/questions/ai-classify/apply
  • method PATCH
  • exact: true
  • state: native_write
  • target prefix /v1/questions/ai-classify/apply
  • auth, organization, and ADMIN/TEACHER role enforcement
• Broad route questions remains legacy_proxy.
• GET /api/questions/ai-classify/jobs?limit=1 observes gateway headers for broad questions legacy routing.
• Apply response headers include:
  • X-Hoctapaz-Gateway-Route: question-classification-apply
  • X-Hoctapaz-Gateway-Route-State: native_write
• The response is the legacy-shaped success envelope with:
  • success: true
  • message: AI classification suggestions applied
  • positive data.requested
  • positive data.applied
  • zero data.failed
  • a successful result for the requested question id

Self-Test

The hermetic self-test validates the shell/Python assertions without a running gateway:

QUESTION_CLASSIFICATION_APPLY_SELF_TEST=1 make test-question-classification-apply-live

Artifacts

Set QUESTION_CLASSIFICATION_APPLY_ARTIFACT_DIR=<dir> to copy the route table, headers, request body, and response body for debugging.

Rollback

No route table changes are made by the smoke. Stop using the non-default native route table or return GATEWAY_ROUTE_TABLE to deploy/gateway/routes.json to route AI classification apply back to legacy.