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

25 lines
5.0 KiB
Markdown

# 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.