Saas-voc-server/docs/parse-rest-schema.md

Parse REST VOC schema

The Parse REST storage driver uses isolated Voc* classes so it can coexist with unrelated applications in a shared Parse development environment. Every class is configured for master-key-only find, get, count, create, update, delete, and field changes. Browser clients never receive the master key and access data through saas-voc-server.

Class	Purpose	Stable identity
VocWorkspace	Tenant/case workspace	publicId
VocWorkspaceMember	Workspace role and status	workspaceId + userId in naturalKey
VocSourceConnection	Company relay configuration metadata	workspace/platform/kind in naturalKey
VocImportBatch	Import provenance, totals, daily aggregates, and quality report	publicId
VocProduct	Domestic product catalog plus derived summary/trend	workspace/platform/product in naturalKey
VocDailyMetric	Canonical daily operating metrics	workspace/platform/product/date/source in naturalKey
VocProductRelation	Denormalized own-product to competitor mapping	workspace/platform/relation in naturalKey
VocReview	Review evidence and source payload	workspace/platform/review in naturalKey
VocSyncJob	Idempotent collection queue record	publicId and idempotencyKey
VocSyncJobEvent	Sync progress and failure events	publicId
VocAnalysisRun	Truthful pending/completed analysis lifecycle	publicId
VocInsightDecision	Append-only human decision versions for an AI insight	publicId; source tuple plus version
VocActionItem	Operational action workflow with decision provenance and retry idempotency	publicId; workspace plus creationKey
VocAlert	Risk/data-quality alert workflow	publicId
VocAuditLog	Workspace-scoped write audit trail	publicId
VocPromptConfig	Workspace-scoped AI prompt, model, output-style, and revision metadata	workspaceId + promptKey in naturalKey
VocProductKnowledge	Featured state, tags, notes, and ownership metadata kept separate from imported product facts	workspaceId + productKey in naturalKey

Parse does not provide the same relational constraints as the PostgreSQL voc schema. The application therefore validates enums and permissions with Zod/RBAC, uses deterministic natural keys for idempotency, denormalizes relation identities, and restricts the current Parse worker to a single process because claim-by-update is not a SQL row lock. VocInsightDecision content is append-only; creating a new version marks the prior version non-current. VocActionItem.creationKey is checked before create, but Parse indexes are non-unique, so concurrent writers still require deployment-level serialization.

The current Demashi acceptance totals before product-knowledge curation are:

VocWorkspace           1
VocWorkspaceMember     1
VocSourceConnection    1
VocImportBatch         1
VocProduct          2854
VocDailyMetric      9717
VocProductRelation    40
VocReview            355
VocPromptConfig       13
VocProductKnowledge    0+

Run npm run verify:parse-rest -- demashi jd after schema changes or imports.

Current boundary

The 17 managed Voc* classes are the deployable minimum for the current product, not the final generic SaaS model. The current revision includes query-driven indexes, non-destructive natural-key imports, workspace-scoped AI prompt configuration, independently maintained product knowledge metadata, insight decision history, and action creation keys. Before adding more tenants or sustained collection volume, the next schema revision should cover:

1. Immutable prompt revision history, analysis evidence, follow-up messages, model parameters, latency, and usage metadata.
2. Store/channel-account and listing identities so a generic domestic SaaS can distinguish a product definition from the same listing sold by different stores or channels.
3. Database-enforced uniqueness. Parse indexes in this deployment are non-unique, so deterministic naturalKey values and application-side upserts remain mandatory.
4. Transactional imports and concurrent worker claims when sustained collection volume requires stronger guarantees than a single Parse worker.

All 17 managed classes have query-driven indexes for their current list and lookup routes. The managed Parse deployment does not consistently preserve field-level required flags, so application validation remains mandatory. PostgreSQL migration 005_insight_decision_action_idempotency.sql supplies database-enforced current-decision and action-creation-key uniqueness for concurrent production writers.