Spaces:
Sleeping
Sleeping
File size: 33,361 Bytes
3a16beb 9d3d881 3a16beb 9d3d881 3a16beb | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | # API Inventory
## Phạm vi
Nguồn audit: AutoCode Video `codex/hf-prod-sync` tại `595ccdfaf45ff83473f2da8fd2c71d491828e5f5`. Xác định **82 endpoint HTTP**. Đây là inventory count, không phải bằng chứng completeness:
- 78 endpoint thuộc Node app: 77 router declaration cộng Node `/health`.
- Hai font route nằm trong 77 declaration được đếm nhưng có implementation status `UNREACHABLE` vì router không được mount.
- Bốn endpoint thuộc Modal gateway; Modal `/health` là endpoint riêng, không phải Node `/health` bị đếm hai lần.
- Dynamic API nội bộ do HyperFrames preview cung cấp không được đếm vì surface phụ thuộc package runtime.
Cột `Status / evidence` mô tả implementation status/reachability trong source. `Active` trong bảng cũ phải được đọc là `SOURCE_VERIFIED` ở mức source, không phải xác minh runtime. Mọi endpoint là `NOT_RUNTIME_VERIFIED` trong Phase 0; không endpoint nào được gán `RUNTIME_VERIFIED` hoặc `PARTIAL_RUNTIME_EVIDENCE`.
Auth mặc định cho các route `/api/**` ngoài auth là “session nếu `AUTOCODE_AUTH_ENABLED=true`; mở/local-admin nếu false”. Evidence mount: `server.js`. Không sao chép implementation route.
## Health và authentication (16)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Frontend consumer | Status / evidence |
| ------ | --------------------------- | -------------------------------- | -------------------------------- | ------------------------------- | ---------------------------------------------- | ---------------------------------------- | --------------------------- | ----------------------------------------------- |
| GET | `/health` | Public hoặc optional Basic Auth | Không | Service/render/delivery summary | Không | Env | Ops | Active; `server.js` |
| POST | `/api/auth/test-login` | Internal bearer + feature flag | Test token context | Session + test user | Tạo/upsert test admin/session | SQLite | Test/smoke | Test-only; `auth.js` |
| POST | `/api/auth/waitlist` | Public | name, email | success | Tạo/update pending user | SQLite | Landing | Active; `auth.js`, `public/landing.js` |
| POST | `/api/auth/register` | Public nhưng flag local-password | name, email, password | user + session | Tạo user/session | SQLite | Không thấy consumer hosted | Legacy/local; `auth.js` |
| POST | `/api/auth/login` | Public nhưng flag local-password | email, password | user + session | Cập nhật login/session | SQLite | Không thấy form chính | Legacy/local; `auth.js` |
| POST | `/api/auth/logout` | Session optional | Cookie | success | Xóa session/cookie | SQLite | Account menu | Active; `auth.js`, `public/app.js` |
| GET | `/api/auth/me` | Cookie optional | Không | authenticated + user | Có thể làm mới lookup cache | SQLite/cache | Bootstrap | Active; `auth.js` |
| GET | `/api/auth/status` | Cookie/internal token optional | Không | auth mode + user | Không | SQLite/env/cache | Landing/dashboard, CF smoke | Active; `auth.js` |
| GET | `/api/auth/admin/users` | Admin session | Không | users | Không | SQLite | Admin | Active; `auth.js`, `public/app.js` |
| PATCH | `/api/auth/admin/users/:id` | Admin session | role/status/name/email | updated user | Update user, approval fields | SQLite | Admin editor | Active; `auth.js`, `public/app.js` |
| DELETE | `/api/auth/admin/users/:id` | Admin session | user ID | deleted ID | Xóa user/session có guard last/protected admin | SQLite transaction | Admin editor | Active, destructive; `auth.js`, `public/app.js` |
| GET | `/api/auth/admin/stats` | Admin session | Không | user/job/activity aggregates | Không | SQLite + activity DB + disk-derived data | Admin overview | Active/partial; `auth.js`, `public/app.js` |
| GET | `/api/auth/google` | Public | optional login_hint/state cookie | Redirect Google | Set OAuth state cookie | Cookie/env | Landing | Active; `auth.js` |
| GET | `/api/auth/google/callback` | OAuth state | code, state | Redirect dashboard/error | Upsert user, session, last login | SQLite | Google redirect | Active; `auth.js` |
| GET | `/api/auth/github` | Public | State cookie | Redirect GitHub | Set state cookie | Cookie/env | Không thấy CTA chính | Unclear; `auth.js` |
| GET | `/api/auth/github/callback` | OAuth state | code, state | Redirect/error | Upsert user/session | SQLite | GitHub redirect | Unclear; `auth.js` |
## Admin operations (4)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | --------------------- | -------------- | -------------------------------- | -------------------------- | ----------------------------------------------------- | --------------------------- | ------------- | --------------------------------- |
| GET | `/api/admin/pricing` | Admin | Không | pricing | Có thể refresh Modal price projection | AppSetting/web price | Admin pricing | Active/partial; `routes/admin.js` |
| PATCH | `/api/admin/pricing` | Admin | pricing | normalized pricing | Lưu token/provider prices; Modal portion auto-derived | AppSetting | Admin pricing | Active; `routes/admin.js` |
| GET | `/api/admin/jobs` | Admin | userId/status/query/limit/offset | paged jobs + costs/summary | Không | SQLite + project files | Admin jobs | Active/partial; `routes/admin.js` |
| GET | `/api/admin/jobs/:id` | Admin | job ID | detail + cost | Không | SQLite + project files/logs | Job detail | Active/partial; `routes/admin.js` |
## Asset library và BGM (12)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | -------------------------------------- | -------------------------------------------- | --------------------------------------- | ------------------------ | ---------------------------------- | --------------------------------- | ----------------- | --------------------------------------------- |
| GET | `/api/assets/library` | Conditional session | Không | Sanitized asset catalog | Warm/read cache | Shared files/sidecars | DAM/asset lock | Active; `routes/assets.js` |
| GET | `/api/assets/scan-duplicates` | Admin hosted | Không | Exact duplicate groups | Đọc/hash | Shared files | DAM scanner | Active; `routes/assets.js` |
| GET | `/api/assets/scan-semantic-duplicates` | Admin hosted | threshold | Similarity groups | Không | Sidecar embeddings | DAM scanner | Active/partial; `routes/assets.js` |
| POST | `/api/assets/update-metadata` | Admin hosted | filename/type + patch | updated metadata | Ghi sidecar, invalidate cache | Shared files | DAM metadata/bulk | Active; `routes/assets.js` |
| POST | `/api/assets/delete-library` | Admin hosted | filename, type | success | Xóa media + sidecar | Shared files | DAM | Active, permanent; `routes/assets.js` |
| POST | `/api/assets/use-asset` | Conditional session | projectId, filename, type | project-relative path | Copy asset/sidecar vào project | Shared + project files | Asset lock/detail | Active; `routes/assets.js` |
| POST | `/api/assets/upload-library` | Admin hosted | Raw bytes; filename/type/config headers | metadata | Lưu file/sidecar, enqueue analysis | Shared files + RAM analysis queue | DAM upload | Active/partial; `routes/assets.js` |
| POST | `/api/assets/analyze-library` | Admin hosted | filename/type/guidance/config | pending/current metadata | Enqueue AI analysis | Shared sidecar + RAM queue | Re-analyze | Active/partial; `routes/assets.js` |
| GET | `/api/assets/bgm` | Conditional session | Không | Tracks | Đọc metadata | Shared audio | BGM modal | Active; `routes/bgm.js` |
| POST | `/api/assets/upload-music` | Conditional session, không admin guard riêng | Raw audio + headers | metadata | Ghi shared BGM + enqueue analysis | Shared files | BGM upload | Active nhưng permission lệch; `routes/bgm.js` |
| POST | `/api/assets/delete-music` | Conditional session, không admin guard riêng | filename | success | Xóa shared BGM | Shared files | BGM modal | Active, destructive; `routes/bgm.js` |
| POST | `/api/assets/select-bgm` | Conditional session | projectId, filename/none | project path/success | Copy/xóa project BGM | Shared + project files | Create/Studio | Active; `routes/bgm.js` |
## Composition, generation, TTS và direct render (9)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | ------------------------------- | ----------------------------------- | --------------------------------- | ------------------------------- | ------------------------------------------- | ------------------------ | ----------------------------- | -------------------------------------------------------- |
| GET | `/api/composition/document` | Conditional session + project scope | projectId | HTML, revision, project info | Không | Project `index.html` | Studio editor | Active; `routes/composition.js`, `src/studio-editor.jsx` |
| PUT | `/api/composition/document` | Conditional session + scope | projectId, HTML, revision | new revision | Sanitize/write HTML/checkpoint/job preview | Project files/meta | Studio editor | Active; `routes/composition.js` |
| POST | `/api/composition/upload-image` | Conditional session + scope | Raw image + headers/project | URL | Write project asset | Project files | Dashboard/editor | Active; `routes/composition.js`, `public/app.js` |
| POST | `/api/composition/upload-media` | Conditional session + scope | Raw media + headers/project | URL/type | Write project asset | Project files | Studio editor | Active; `routes/composition.js`, `src/studio-editor.jsx` |
| POST | `/api/composition/update-scene` | Conditional session + scope | sceneId, narration, innerHTML | success | Mutate/sanitize HTML/checkpoint/job preview | Project files/meta | Quick scene edit | Active/partial; `routes/composition.js`, `public/app.js` |
| POST | `/api/generate` | Conditional session | prompt/url/openai config | composition result/assets | Capture/scrape/write project | Project/shared files | Không thấy dashboard consumer | Legacy/duplicate; `routes/generate.js` |
| POST | `/api/compile` | Conditional session | narration/duration/caption/config | timed words/compiled result | Transcribe/inject/write composition assets | Project files | Không thấy dashboard consumer | Legacy/duplicate; `routes/compile.js` |
| POST | `/api/tts/create` | Conditional session | text/Omnivoice config | external job ID | Tạo TTS job | Provider | Không thấy dashboard consumer | Legacy/duplicate; `routes/tts.js` |
| GET | `/api/tts/status/:jobId` | Conditional session | baseUrl/token/target LUFS | status/progress hoặc audio path | Poll/download/normalize narration | Provider + project files | Không thấy dashboard consumer | Legacy, token in query; `routes/tts.js` |
## Direct render và Forge lifecycle (10)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | -------------------------- | ------------------------------------- | ------------------------------- | -------------------------- | ---------------------------------------- | ---------------------------- | ----------------------------- | ----------------------------------------------- |
| GET | `/api/render` | Conditional session + project context | projectId qua context/referer | SSE log + video URL/error | Materialize registry, render MP4 | Project files, local/Modal | Không thấy dashboard consumer | Legacy/duplicate; `routes/render.js` |
| POST | `/api/forge/start` | Conditional session + scope | prompt/project/config/assets | 202 project/job/queue info | Tạo project nếu cần, checkpoint, enqueue | RAM + SQLite + project files | Main Create | Active core; `routes/forge.js`, `public/app.js` |
| POST | `/api/forge/edit` | Conditional session + scope | prompt/renderOnly/config/assets | accepted job | Enqueue edit/rerender | RAM + SQLite + project files | Studio AI edit/quick rerender | Active; `routes/forge.js` |
| GET | `/api/forge/events` | Conditional session + scope | projectId | SSE status/log/stats | Add/remove event listener | RAM job events | Studio progress | Active; `routes/forge.js` |
| GET | `/api/forge/status` | Conditional session + scope | projectId, summary/mode | live/persisted status | Có thể load job from disk | RAM/meta/log/DB | Poll fallback/render dock | Active; `routes/forge.js` |
| GET | `/api/forge/report` | Conditional session + scope | projectId, section | report section | Đọc/parse artifacts | Project files | Report modal | Active; `routes/forge.js` |
| POST | `/api/forge/cancel` | Conditional session + scope | projectId | success | Remove queued/abort/kill, mark failed | RAM + meta/DB/log | Studio | Active; `routes/forge.js` |
| POST | `/api/forge/resume` | Conditional session + scope | projectId + provider configs | accepted/resume info | Enqueue from checkpoint | RAM + meta/DB/files | Studio retry | Active; `routes/forge.js` |
| POST | `/api/forge/pause` | Conditional session + scope | projectId | success | Mark paused/kill process | RAM + meta/DB/log | Studio | Active/partial; `routes/forge.js` |
| POST | `/api/forge/resume-paused` | Conditional session + scope | projectId | success/conflict | Re-enqueue paused job | RAM + meta/DB | Studio | Active/partial; `routes/forge.js` |
## Projects (11)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | ------------------------------- | ---------------------------------- | ------------------------------------- | ----------------------------- | ---------------------------------------- | ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| GET | `/api/projects` | Conditional session + owner filter | paging/search/status/tags/model/ratio | paged projects + totals | Disk fallback/sync read | SQLite + disk | Projects/render dock | Active; `routes/projects.js` |
| GET | `/api/projects/:id` | Conditional session + ownership | ID | project detail | Load disk/job state | SQLite + disk + RAM | Select Studio | Active; `routes/projects.js` |
| GET | `/api/projects/:id/diagnostics` | Conditional session + ownership | ID | lint/animation/error markdown | Có thể generate diagnostics | Project files/subprocess | Error/report UI | Active/partial; `routes/projects.js` |
| POST | `/api/projects` | Conditional session | name, description | projectId/name | Tạo folders/config/meta + DB record | Filesystem + SQLite | Không thấy current dashboard call; CF smoke mong contract khác | Alternate/legacy; `routes/projects.js` |
| POST | `/api/projects/select` | Conditional session + ownership | projectId | resolved IDs | Không | Filesystem | Project selection | Active; `routes/projects.js` |
| POST | `/api/projects/bulk-delete` | Conditional session + ownership | IDs | deleted + errors | DB delete + recursive delete | SQLite + filesystem | Project manage | Active, critical destructive risk; `routes/projects.js` |
| DELETE | `/api/projects/:id` | Conditional session + ownership | ID | success | DB delete + recursive delete | SQLite + filesystem | Không thấy direct UI consumer | Active alternate/destructive; `routes/projects.js` |
| POST | `/api/projects/clone` | Conditional session + ownership | source ID | new project | Copy tree/reset meta/history + DB create | Filesystem + SQLite | Project quick menu | Active; `routes/projects.js` |
| POST | `/api/projects/toggle-favorite` | Conditional session + ownership | ID | favorite | Write meta + sync DB | Filesystem + SQLite | Project quick menu | Active; `routes/projects.js` |
| POST | `/api/projects/toggle-posted` | Conditional session + ownership | ID | posted | Write meta + sync DB | Filesystem + SQLite | Project quick menu | `SOURCE_VERIFIED`, legacy semantics; không thuộc Oloka MVP; `routes/projects.js` |
| GET | `/api/projects/:id/thumbnail` | Conditional session + ownership | ID | PNG or generated SVG | Có thể enqueue/generate thumbnail | Project files/process | Project cards | Active/partial; `routes/projects.js` |
## Status, media và settings (7)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | ------------------------------- | --------------------------- | ------------------- | ------------------------------------ | --------------------- | -------------------------- | --------------------- | ------------------------------------------- |
| GET | `/api/status` | Conditional session + scope | projectId | composition/video flags, URL/version | Disk fallback | SQLite + files | Studio selection | Active; `routes/status.js` |
| GET | `/api/status/modal-render` | Conditional session | Không | provider config + gateway health | Gọi Modal health | Env/provider | Settings | Active; `routes/status.js`, `public/app.js` |
| GET | `/api/media/video` | Conditional session + scope | projectId, renderId | 307 redirect | Sinh/cache signed URL | Env + expected object path | Video player/download | Active; `routes/media.js` |
| GET | `/api/settings/shared` | Conditional session | Không | masked config + edit capability | Không | AppSetting | Settings/bootstrap | Active; `routes/settings.js` |
| PATCH | `/api/settings/shared` | Admin hosted | config | masked saved config | Upsert config/secrets | AppSetting SQLite | Settings save | Active; `routes/settings.js` |
| POST | `/api/settings/list-models` | Admin hosted | baseUrl, apiKey | models/capabilities | External request | Provider | Model selector | Active/partial; `routes/settings.js` |
| POST | `/api/settings/test-connection` | Admin hosted | type, config | success/error | External probe | Provider | Settings | Active/partial; `routes/settings.js` |
## Quality và social (7)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | -------------------------- | --------------------------- | ----------------------------------------------- | -------------------- | ---------------------------------------- | ------------------------ | --------------------------- | -------------------------------------------- |
| GET | `/api/quality/report` | Conditional session + scope | projectId | report | Không | Project JSON | Report UI | Active; `routes/quality.js` |
| GET | `/api/quality/memory` | Conditional session | aspectRatio | verified rules | Không | `quality-memory/**` | Không thấy main consumer rõ | Active/unclear; `routes/quality.js` |
| GET | `/api/quality/codex-brief` | Conditional session + scope | projectId | markdown/path/scan | Ghi repair brief | Project files | Error copy/report | Active; `routes/quality.js`, `public/app.js` |
| POST | `/api/quality/config` | Conditional session | recognition configs | configured flags | Ghi config vào RAM process | RAM | Settings sync | Active/ephemeral; `routes/quality.js` |
| POST | `/api/quality/analyze` | Conditional session + scope | projectId + vision configs | quality report | Sample/analyze video, persist job/report | Project files/meta | Manual QA | Active/partial; `routes/quality.js` |
| POST | `/api/quality/feedback` | Conditional session + scope | finding | updated report | Ghi feedback/memory/report | Project + quality memory | Report UI/ops | Active/partial; `routes/quality.js` |
| POST | `/api/social/publish` | Conditional session + scope | projectId, platforms, config, title/description | per-platform results | Upload external video | Project file + platform | Publish modal | Active/partial; `routes/socialPublish.js` |
## Font routes chưa được mount (2)
| Method | Intended path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | --------------------- | ------------------------------ | ------- | -------------- | ----------- | ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/fonts` | Nếu mount: conditional session | Không | font inventory | Scan files | Font inputs/assets | Caption font selector | **Unreachable/unclear:** router tồn tại, frontend gọi, `server.js` không mount; `routes/fonts.js`, `public/app.js` |
| GET | `/api/fonts/file/:id` | Nếu mount: conditional session | Font ID | font bytes | Không | Font files | Browser font loader | **Unreachable/unclear**; `routes/fonts.js`, `services/fontInventoryService.js` |
## Modal gateway (4)
| Method | Path | Authentication | Request | Response | Side effect | Storage | Consumer | Status / evidence |
| ------ | ----------------------- | ---------------------------- | ------------------------------- | --------------------------- | ----------------------- | ---------------- | -------------------------- | -------------------------------------- |
| GET | `/health` | Public trong gateway | Không | HyperFrames version/timeout | Không | Runtime | Node health route/operator | Active; `deploy/modal-renderer/app.py` |
| POST | `/api/render` | Bearer nếu secret configured | projectId, preset, base64 files | call_id | Spawn Modal function | Modal job/volume | Node Modal provider | Active; `deploy/modal-renderer/app.py` |
| GET | `/api/render/{call_id}` | Bearer nếu configured | call ID | running/done/failed | Poll function | Modal call | Node Modal provider | Active; `deploy/modal-renderer/app.py` |
| GET | `/renders/{name}` | Bearer nếu configured | Safe filename | MP4 | Reload volume/read file | Modal Volume | Node download step | Active; `deploy/modal-renderer/app.py` |
## API conclusions cho Oloka
- Giữ một command API cho generation/edit/render, không duy trì direct pipeline endpoints trùng Forge.
- Tách command acceptance (`202`) khỏi durable job/read model/events.
- Mọi resource dùng opaque ID và tenant scope; không để filename/path làm identity.
- Upload/download dùng object storage URL có checksum/quota, không raw body qua app cho file lớn.
- Sinh OpenAPI/typed contracts và route reachability tests để tránh router tồn tại nhưng không mount.
- Admin/provider/social APIs cần authorization policy thống nhất và idempotency/audit.
|