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

```text
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.