Files
canina/specs/corporate-backend/api.md
T

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.