feat: harden public OpenAI API contracts

Makefile

@@ -6,9 +6,10 @@
 # 容器内执行 psql 的固定前缀(postgres/postgres/postgres,见 docker-compose.yaml)
 PSQL = docker compose exec -T postgres psql -U postgres -d postgres
 UV = UV_CACHE_DIR=/private/tmp/ai-video-uv-cache uv run --with-requirements requirements.txt
+BACKEND_PYTHON = $(if $(wildcard backend/.venv/bin/python),.venv/bin/python,$(UV) python)
 
 .DEFAULT_GOAL := help
-.PHONY: help up down restart logs api-logs db db-list db-up db-migrate db-revision db-current db-sync-interface-definitions db-init db-seed db-seed-model-resources db-seed-assistants db-clear db-reset db-drop-schema db-reset-hard
+.PHONY: help up down restart logs api-logs test test-backend test-frontend contract-snapshots contract-check db db-list db-up db-migrate db-revision db-current db-sync-interface-definitions db-init db-seed db-seed-model-resources db-seed-assistants db-clear db-reset db-drop-schema db-reset-hard
 
 help: ## 列出所有可用目标
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
@@ -30,6 +31,21 @@ logs: ## 跟随全部服务日志
 api-logs: ## 只看后端日志
 	docker compose logs -f api
 
+# ---- 质量与契约 ----
+test: test-backend test-frontend contract-check ## 运行本地提交前质量门禁
+
+test-backend: ## 运行全部后端测试（已内置 NLTK 本地环境兼容项）
+	cd backend && $(BACKEND_PYTHON) -m scripts.run_tests
+
+test-frontend: ## 运行前端 lint、契约测试和 production build
+	cd frontend && npm run lint && npm run test:contracts && npm run build
+
+contract-snapshots: ## 重新生成 OpenAPI 与 Realtime JSON Schema 快照
+	cd backend && $(BACKEND_PYTHON) -m scripts.export_contracts
+
+contract-check: ## 检查已提交契约快照是否与运行时代码一致
+	cd backend && $(BACKEND_PYTHON) -m unittest tests.test_public_contract_snapshots
+
 # ---- 数据库 ----
 db: ## 进入交互式 psql
 	docker compose exec postgres psql -U postgres -d postgres