5.0 KiB
Corporate API contract
Base /api/admin/hermes (application global /api prefix). All routes use existing JwtAuthGuard + RolesGuard, Admin/SUPER_ADMIN; API keys require explicit admin scope. Actor comes from authenticated user/key ID. Never accepts executor/reviewer identity in request bodies.
- GET
runtime:{mode: MANUAL_DORMANT, schedulesEnabled:false, externalExecutionEnabled:false}. - GET
tasks:{data,meta:{total,page,limit,totalPages,hasNextPage,hasPrevPage}}. page default 1; limit default 20, valid 1..100. Filters department, priority, status, goalId. Search only normalized title/taskCode (Persian/Arabic letters, digits, zero-width spaces, parentheses). Sort allowlist createdAt/updatedAt/title/taskCode/priority/status; sortOrder asc/desc. Deterministic id tie break, repeatable-read count/page snapshot. - GET
tasks/:id: raw persisted task with logs/evidence/reviews/effects/children; 404 absent, 400 malformed UUID. - POST
tasks:{title,department,description,priority?='CEO_EXPEDITE',parentId?,goalId?,actionType?,dueCycle?}. Raw persisted task, 201. Strict allowlist. actionType CEO_DIRECTIVE/BLOG_NEW/BLOG_UPDATE/CATALOG_ENRICH/RESEARCH/ENGINEERING. BLOG_NEW separate from needs-driven BLOG_UPDATE, no quota ratio. - POST
claims:{department?,leaseSeconds?=300}valid lease 30..900 seconds. Returns{task:null|task}. Priority enum order CEO_EXPEDITE..LOW, oldest updated first. Actual row lock SKIP LOCKED. Expired IN_PROGRESS leases reclaimable with new UUID token. Pending children exclude parent; rejected child QA sets parent BLOCKED; corrected children eventually make parent reclaimable. - POST
tasks/:id/evidence:{claimToken,artifactUri,sha256,summary,tool,result}. Current owner + unexpired lease required. Stores receipt, transitions to TEST. HTTPS or content-addressed urn:sha256 locator; digest 64 lowercase hex. No network access performed. - POST
tasks/:id/reviews:{evidenceId,passed:boolean,findings,verification:{artifactUri,sha256,method,result}}. Exact current artifact required. Reviewer must differ from executor authenticated subject. Pass -> DONE only if every child DONE. Fail -> TODO for a new execution/QA attempt; parent BLOCKED. No retry cap or approval modules. - GET
market-insights:{data,meta}, pagination, optional category. Fields match existing UI: title/category/source/opportunity/impact/recommendedAction/status/createdAt plus sources/provenance/cadence. - POST
market-insights: title/category/source/opportunity/impact/recommendedAction, cadence MONTHLY|EVENT, provenance{method,collector,context}, sources (1..30){url:https,title,excerpt,retrievedAt,sha256}. - GET
monthly-roadmap:{data,meta}, pagination, optional month. Existing UI fields retained: cycleName/month/seasonalTheme/strategicGoals/plannedArticlesCount/plannedRefreshesCount/plannedCatalogEnrichments/isActive/createdAt plus goals. - POST
monthly-roadmap: researchId + above UI fields + goals[ {title,department,acceptanceCriteria,metric,target?} ]. Requires persisted source-backed research. Creates goals atomically; connect tasks through returned goal IDs. Active is declarative, not schedule activation. - POST
tasks/:id/effects:{metric,availability:MEASURED|UNAVAILABLE|UNINSTRUMENTED|BUSINESS_DISABLED,baseline?,observed?,source,observedAt}. DONE required. MEASURED requires numeric observed; other states prohibit numeric values (missing != zero). - GET
reports:{data,meta}. - POST
reports:{day:YYYY-MM-DD,summary}creates unique daily UTC snapshot of persisted tasks/events/effects. Summary is attributed user-supplied text, not generated or independently verified analytics.
All POST operations accept Idempotency-Key, mandatory except task creation for compatibility with existing UI. Without the optional create key, retry creates a new task. Keys scoped to authenticated actor and operation; canonical payload digest mismatch ->409; transaction advisory lock serializes duplicate requests; immutable response saved in same transaction. Use fresh key for a new claim attempt; replaying a past claim returns original (possibly now expired) lease, never renews it. Claim token never authorizes other actors.
Limitations / explicit boundaries
This is a persisted manual orchestration ledger and guarded lifecycle, not an autonomous executor. No scheduler, commands, URL fetching, LLM calls, publishing or deployment adapters. Evidence/provenance and QA verification are authenticated attestations, not server-side fetched content proof. Independent credentials do not prove independent humans. No arbitrary status PATCH, cancellation UI, lease heartbeat, research update, roadmap auto fan-out, provider metric ingestion, or push notifications. Daily publisher remains unchanged; roadmap consumption requires parent integration. Daily snapshots use UTC, not Tehran business-day boundaries. Roadmap activity need not be unique per month. GET collection sorts by createdAt descending; task list is sortable. No frontend/storefront changes or Stage deployment in this branch.