| name | hw-seed-lesson-pending-review |
| description | Seed a lesson-import draft on a deployed Happyword API (Preview or prod) and optionally run the extract-pending cron so it reaches `pending` (待复核). Uses tools starting with `hw_`. Invoke when the user wants to upload a textbook photo for review against a specific Vercel URL, mirror E2E `test_lesson_import_cron_e2e`, or smoke-test lesson import + cron on a branch deployment. |
hw-seed-lesson-pending-review
Canonical entrypoints
From repository root:
bash tools/hw_seed_lesson_pending_review.sh \
--base-url https://happyword-xxxx-terrymas-projects.vercel.app \
--family-id fam-01234567
--base-url — Deployment origin (scheme optional; trailing slash stripped).--family-id — Path segment for /api/v1/family/{family_id}/… lesson routes (default _ when omitted). Server-side draft rows are not filtered by this value yet; keep it aligned with a bound device when debugging.--image — Optional path to JPEG/PNG/WebP (defaults to server/tests/e2e/_fixtures/lesson_import_fixture.jpg).--skip-cron — Only POST /api/v1/family/{family_id}/lessons/import (draft stays extracting until Vercel cron or a manual cron trigger).
Direct Python (same behaviour):
uv run --project server python tools/hw_seed_lesson_pending_review.py --help
Secrets (~/.env)
The shell wrapper sources ~/.env when readable (like other operator scripts). Do not print secrets.
| Purpose | Env vars tried (first wins) |
|---|
| Vercel Deployment Protection bypass | HW_VERCEL_BYPASS, E2E_VERCEL_PROTECTION_BYPASS, VERCEL_AUTOMATION_BYPASS_SECRET |
Cron Authorization for POST /api/v1/admin/cron/extract-pending | HW_CRON_SECRET, E2E_CRON_SECRET, VERCEL_CRON_SECRET, CRON_SECRET |
Preview deployments without a bypass header typically return 401 HTML from Vercel — match production/staging CRON_SECRET on the target deployment when invoking cron.
Behaviour (matches E2E)
Aligned with server/tests/e2e/test_lesson_import_cron_e2e.py:
POST /api/v1/family/{family_id}/lessons/import → 201, draft extracting.- Unless
--skip-cron: POST /api/v1/admin/cron/extract-pending with Authorization: Bearer ….
GET /api/v1/family/{family_id}/lesson-drafts/{id} → expect pending (success) or extract_failed (LLM/config failure on server).
Exit 0 only when final draft status is pending. Mongo queue cleanup (deleting other extracting rows) is not performed — if multiple drafts are extracting, cron may claim another row first; see E2E test for deterministic DB cleanup when needed.
Related
- Cron manual trigger: skill
vercel-trigger-cron (bash tools/vercel/trigger-cron.sh).
- Vercel Root Directory for this repo:
.cursor/rules/vercel-root-directory.mdc (server/).
