Codex first iteration

2026-07-12 02:56:51 +08:00
parent 16c626fbd7
commit 7cb409f5a6
20 changed files with 1771 additions and 0 deletions
@@ -0,0 +1,46 @@
+# Preface Tools
+
+Preface Tools is a database-free classroom utility server. Its first tool,
+Comic Animator, lets a student upload a comic page, create and edit a
+multimodal OpenRouter prompt, obtain instructor approval, and generate a video.
+
+## Run locally
+
+Requires Go 1.26 or later. Copy `.env.example` to `.env`, replace every secret
+and model placeholder, export the variables, then run:
+
+```sh
+go run ./cmd/preface-tools
+```
+
+The process fails at startup when required configuration is missing. In
+production, use HTTPS and set `APP_ENV=production` so the session cookie is
+marked Secure. `PUBLIC_BASE_URL` must be an HTTPS address reachable by
+OpenRouter because it fetches a short-lived, signed source-image URL.
+
+## Storage and restart behavior
+
+Uploads and runtime generation records are held in process-specific registries.
+Completed videos are streamed immediately and atomically into
+`data/comic-animator/outputs` (or the configured output directory). The
+instructor page scans that directory, so downloaded videos remain recoverable
+after restart.
+
+OpenRouter does not document an endpoint for listing all historical video jobs.
+Consequently, queued and in-progress jobs and rich metadata cannot be recovered
+after a restart. The downloaded-file view is a recovery aid, not an audit log.
+Uploads and outputs are not automatically removed; operators must monitor disk
+usage and introduce a retention policy appropriate to their deployment.
+
+## Verification
+
+```sh
+gofmt -w .
+go test ./...
+go test -race ./...
+go vet ./...
+go build ./...
+```
+
+No database, Node.js, npm, frontend build, or live OpenRouter call is required
+by the automated test suite.