howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/02-database/01-schema-design.md

@@ -1,16 +1,19 @@
-# Database Architecture Design
+# Database Schema Design
 
-Use this reference when designing or changing HowOne backend entity schemas. It summarizes
-the contract in `docs/dynamic-entity-architecture.zh.md` for app-building agents.
+Use this reference when designing or changing HowOne backend entity schemas. It condenses the
+runtime contract from `docs/dynamic-entity-architecture.zh.md` into instructions an AI agent can
+actually apply.
 
-This reference is for **backend entity design**. For schema tool flow, read
-`02-database/02-schema-operations.md`. For frontend read/write calls, read
-`02-database/03-data-access-patterns.md` and `03-sdk/02-entity-operations.md` after schema
-artifacts have been synced.
+This file answers: **what should the schema be?** For how to apply changes, read
+`02-schema-operations.md`. For frontend calls, read `03-data-access-patterns.md` and
+`03-sdk/02-entity-operations.md`.
 
-## Core Model
+## Mental Model
 
-An entity is a versioned database contract, not a loose JSON form. Design all relevant parts:
+A HowOne Entity is a versioned app-level database contract. It is not a MongoDB collection exposed
+directly and not a loose JSON form.
+
+Design the whole contract:
 
 ```ts
 type EntityContract = {
@@ -21,8 +24,8 @@ type EntityContract = {
   properties: Record<string, EntityField>
   required?: string[]
   access: {
-    authenticated?: AuthenticatedAccess
-    public?: PublicAccess
+    authenticated: AuthenticatedAccess
+    public: PublicAccess
   }
   indexes?: EntityIndex[]
   relations?: Record<string, EntityRelation>
@@ -32,70 +35,250 @@ type EntityContract = {
 }
 ```
 
-Every schema change should preserve this mental split:
+Each section has a different job:
+
+| Section | Purpose | AI design question |
+|---|---|---|
+| `properties` | Business fields and primitive validation | What data is persisted? |
+| `required` | Create-time required fields | What must exist before first save? |
+| `access.authenticated` | Logged-in/private API access | Who can read/write after auth? |
+| `access.public` | Anonymous/public API access | Can a public page read or write it? |
+| `indexes` | Query performance and uniqueness | What lists/details will be queried often? |
+| `relations` | Valid include names | What can be joined/expanded? |
+| `presentation` | Admin/generator hints | What fields identify the record in UI? |
+| `lifecycle` | Audit/delete policy hints | Is this append-only, soft-deletable, audited? |
+| `performance` | SDK/admin pagination/sort hints | What limits and sorts are safe? |
+
+## Storage Reality
+
+HowOne uses shared runtime collections:
+
+| Collection | Meaning |
+|---|---|
+| `entityshares` | Current active entity definitions. |
+| `entitydatashares` | Real business records. |
+| `entityschemaversions` | Historical schema snapshots. |
+| `entityschemastates` | Current schema version pointer per app. |
+| `usershares` | App user mapping used for ownership. |
+
+Schema restore changes definitions only. It does **not** roll back existing business records.
+
+Every data row may carry:
+
+```ts
+{
+  id: string
+  created_date: string
+  updated_date: string
+  created_by_id: string
+  schema_version_id?: string
+  schema_version_number?: number
+  is_sample?: boolean
+  ...businessFields
+}
+```
+
+Do not create business fields that collide with system fields.
+
+## Field Design
+
+### Naming
+
+Entity and field names must match:
+
+```text
+^[a-zA-Z_][a-zA-Z0-9_]*$
+```
+
+Conventions:
+
+- Entity names: PascalCase, singular, domain noun: `Todo`, `Article`, `QrProfile`.
+- Field names: camelCase: `qrImageUrl`, `publishedAt`, `moodScore`.
+- Avoid ambiguous names like `data`, `info`, `value`, `result` unless the product really stores opaque blobs.
+
+Forbidden business field names:
+
+```text
+id
+_id
+created_date
+updated_date
+created_by_id
+createdById
+ownerId
+is_sample
+schema_version_id
+schema_version_number
+```
+
+`created_by_user_id` is special: use it only when a public write/share flow explicitly needs a
+project-user identifier. Do not use it as the owner field for normal authenticated private data;
+the backend derives owner from JWT.
+
+### Supported Types
+
+```text
+string
+number
+boolean
+date
+array
+object
+integer
+null
+```
+
+Nullable:
+
+```json
+{ "type": ["string", "null"], "default": null }
+```
+
+Backend runtime currently enforces:
 
-- `properties` and `required` define payload validation.
-- `access` defines who can read/write and how ownership is derived.
-- `indexes` and `performance` define expected query paths.
-- `relations` defines valid `include` names.
-- `presentation` helps admin UI and SDK generation.
-- schema versions track the contract applied when future records are written.
+- unknown field rejection;
+- create required fields;
+- basic primitive type checks;
+- non-null required fields unless the type includes `null`;
+- defaults and `autoGenerate`.
 
-## Access Contract
+Do not assume full JSON Schema enforcement for every nested constraint. Use Zod/frontend validation
+for stronger UX validation:
 
-Every entity should explicitly define both authenticated and public access. Choose the data posture
-in `02-database/03-data-access-patterns.md`, then encode it in the `access` block here.
+- `enum`
+- `minimum` / `maximum`
+- `minLength` / `maxLength`
+- `pattern`
+- nested `items` / `properties`
 
-## Field Design Rules
+### Defaults and Generated Fields
 
-- Entity and field names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
-- Do not define system fields as business fields: `id`, `_id`, `created_date`, `updated_date`,
-  `created_by_id`, `schema_version_id`, `schema_version_number`, `is_sample`.
-- Required fields must be supplied on create unless the field has `default`, `defaultValue`, or
-  `autoGenerate`.
-- Use explicit enum fields for UI status values instead of free-form strings when choices are known.
-- Use ISO strings for date/datetime fields at the SDK boundary.
-- Complex JSON Schema validation may need frontend validation too; do not assume every nested
-  constraint is fully enforced by backend runtime.
+Use `default` when a field has an obvious value at creation:
 
-## Index and Performance Rules
+```json
+{ "completed": { "type": "boolean", "default": false } }
+```
 
-Add indexes for the query paths the UI will actually use:
+Use nullable defaults for optional dates:
+
+```json
+{ "publishedAt": { "type": ["date", "null"], "default": null } }
+```
+
+Use server generation for public IDs:
 
 ```json
 {
-  "indexes": [
-    {
-      "name": "owner_status_updated",
-      "fields": ["status", "updatedDate"],
-      "scope": "owner",
-      "order": { "updatedDate": "desc" }
-    }
-  ],
-  "performance": {
-    "defaultLimit": 20,
-    "maxLimit": 100,
-    "allowedSorts": ["createdDate", "updatedDate"]
+  "publicId": {
+    "type": "string",
+    "autoGenerate": { "strategy": "uuid" }
   }
 }
 ```
 
-Guidelines:
+Current `autoGenerate.strategy` support:
+
+```text
+uuid
+```
+
+AI rule: Create input may omit fields with `default` or `autoGenerate`; response types should include
+them as present/possible.
+
+## Access Design
+
+Always write both `authenticated` and `public`. Do not rely on `visibility` defaults for new schema.
+
+Authenticated channel:
+
+```text
+/api/entities/apps/:appId/data/:entityName
+```
+
+Public channel:
+
+```text
+/api/entities/public/apps/:appId/data/:entityName
+```
+
+These channels are independent.
+
+### Authenticated Access
+
+Each action accepts `own`, `all`, or `none`:
+
+```json
+"authenticated": {
+  "read": "own",
+  "create": "own",
+  "update": "own",
+  "delete": "own"
+}
+```
+
+| Value | Meaning |
+|---|---|
+| `own` | Backend scopes to current `usershares._id`; create assigns current owner. |
+| `all` | Logged-in users can access all records for that operation. |
+| `none` | Operation forbidden. |
+
+Rules:
+
+- For private user data, use all `own`.
+- For authenticated shared dashboards/CMS, use `read: "all"` and be conservative on update/delete.
+- Do not pass owner fields in authenticated payloads or filters. Backend derives owner from auth.
+- `query.mine()` is the SDK shorthand for authenticated own lists.
+
+### Public Access
+
+Public read values:
+
+| Value | Use for |
+|---|---|
+| `none` | Not visible without login. |
+| `list` | Public feeds/catalogs/lists. |
+| `scoped` | Public share/detail pages that require scope keys. |
+
+Public write values:
+
+| Value | Use for |
+|---|---|
+| `none` | No anonymous write. |
+| `scoped` | Anonymous write only with required scope values. |
+| `any` | Fully public write; use rarely. |
+
+Guardrail fields:
+
+```json
+"public": {
+  "read": "scoped",
+  "create": "none",
+  "update": "none",
+  "requiredScopes": ["ownerId", "slug"],
+  "allowedFilters": ["slug", "active"],
+  "allowedSorts": ["updatedDate"],
+  "defaultLimit": 1,
+  "maxLimit": 10
+}
+```
+
+Rules:
 
-- Private user lists usually need owner-scoped indexes.
-- Public list pages need `access.public.allowedFilters` and `access.public.allowedSorts`.
-- `performance.allowedSorts` informs SDK/admin generation; public sort enforcement comes from
-  `access.public.allowedSorts`.
+- `scoped` requires every `requiredScopes` value in query/body.
+- `list` must define `allowedFilters`, `allowedSorts`, `defaultLimit`, and `maxLimit`.
+- Public create requires a clear ownership/scoping story. If it needs `created_by_user_id`, document where that value comes from.
+- Never expose broad public write unless the product explicitly needs anonymous submissions.
 
-## Todo Example
+## Standard Patterns
 
-For a personal Todo app:
+### A. User Private Data
+
+Use for todos, notes, journals, saved generations, personal settings.
 
 ```json
 {
   "name": "Todo",
   "type": "object",
-  "description": "User-owned todo item",
   "visibility": "private",
   "properties": {
     "text": { "type": "string" },
@@ -103,24 +286,14 @@ For a personal Todo app:
   },
   "required": ["text"],
   "access": {
-    "authenticated": {
-      "read": "own",
-      "create": "own",
-      "update": "own",
-      "delete": "own"
-    },
-    "public": {
-      "read": "none",
-      "create": "none",
-      "update": "none",
-      "delete": "none"
-    }
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
   },
   "indexes": [
     {
-      "name": "owner_updated",
-      "fields": ["updatedDate"],
+      "name": "owner_completed_updated",
       "scope": "owner",
+      "fields": ["completed", "updatedDate"],
       "order": { "updatedDate": "desc" }
     }
   ],
@@ -137,11 +310,232 @@ For a personal Todo app:
 }
 ```
 
-Corresponding frontend read:
+SDK list:
 
 ```ts
-const result = await howone.entities.Todo.query.mine({
+await howone.entities.Todo.query.mine({
   page: { number: 1, size: 50 },
   orderBy: { updatedDate: 'desc' },
 })
 ```
+
+### B. Public Read-Only Catalog
+
+Use for articles, templates, listings, published galleries.
+
+```json
+{
+  "name": "Article",
+  "type": "object",
+  "visibility": "public",
+  "properties": {
+    "title": { "type": "string" },
+    "slug": { "type": "string" },
+    "status": { "type": "string", "enum": ["draft", "published"], "default": "draft" },
+    "publishedAt": { "type": ["date", "null"], "default": null }
+  },
+  "required": ["title", "slug"],
+  "access": {
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+    "public": {
+      "read": "list",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "allowedFilters": ["slug", "status"],
+      "allowedSorts": ["publishedAt", "updatedDate"],
+      "defaultLimit": 20,
+      "maxLimit": 100
+    }
+  },
+  "indexes": [
+    { "name": "slug_unique", "scope": "global", "fields": ["slug"], "unique": true },
+    {
+      "name": "status_published",
+      "scope": "global",
+      "fields": ["status", "publishedAt"],
+      "order": { "publishedAt": "desc" }
+    }
+  ]
+}
+```
+
+SDK public list:
+
+```ts
+await howone.public.entities.Article.query({
+  where: { status: 'published' },
+  orderBy: { publishedAt: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+### C. Public Scoped Share Page
+
+Use for QR profile, public invoice, public resume, shared report.
+
+```json
+{
+  "name": "QrProfile",
+  "type": "object",
+  "visibility": "public",
+  "properties": {
+    "slug": { "type": "string" },
+    "title": { "type": "string" },
+    "qrImageUrl": { "type": "string" },
+    "active": { "type": "boolean", "default": true }
+  },
+  "required": ["slug", "title", "qrImageUrl"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": {
+      "read": "scoped",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["ownerId", "slug"],
+      "allowedFilters": ["slug", "active"],
+      "allowedSorts": ["updatedDate"],
+      "defaultLimit": 1,
+      "maxLimit": 10
+    }
+  },
+  "indexes": [
+    { "name": "owner_slug_unique", "scope": "owner", "fields": ["slug"], "unique": true }
+  ]
+}
+```
+
+SDK public scoped read:
+
+```ts
+await howone.public.entities.QrProfile.queryScoped({
+  where: { ownerId, slug, active: true },
+  page: { number: 1, size: 1 },
+})
+```
+
+### D. Workflow Output History
+
+Use for AI generation/analyze/report flows that need persisted history.
+
+```json
+{
+  "name": "Generation",
+  "type": "object",
+  "visibility": "private",
+  "properties": {
+    "prompt": { "type": "string" },
+    "status": { "type": "string", "enum": ["pending", "completed", "failed"], "default": "pending" },
+    "resultUrl": { "type": ["string", "null"], "default": null },
+    "errorMessage": { "type": ["string", "null"], "default": null },
+    "completedAt": { "type": ["date", "null"], "default": null }
+  },
+  "required": ["prompt", "status"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  },
+  "indexes": [
+    {
+      "name": "owner_status_updated",
+      "scope": "owner",
+      "fields": ["status", "updatedDate"],
+      "order": { "updatedDate": "desc" }
+    }
+  ]
+}
+```
+
+Rules:
+
+- Persist pending before long-running workflow when product needs history/resume.
+- Persist completed output only into fields declared here.
+- Persist failed state and error message if history must show failures.
+- Do not persist raw workflow envelopes unless schema declares an object field for them.
+
+## Index Design
+
+Every list/detail path should map to an index.
+
+| Query shape | Index recommendation |
+|---|---|
+| private user list by updated time | `scope: "owner"`, `fields: ["updatedDate"]` |
+| private user list filtered by status | `scope: "owner"`, `fields: ["status", "updatedDate"]` |
+| owner unique slug | `scope: "owner"`, `fields: ["slug"]`, `unique: true` |
+| public slug detail | `scope: "global"`, `fields: ["slug"]`, `unique: true` |
+| public feed by status/date | `scope: "global"`, `fields: ["status", "publishedAt"]` |
+
+Index rules:
+
+- Index fields should match real UI queries, not every field.
+- Owner-scoped unique means unique per owner, not globally unique.
+- Public filters/sorts must also be listed in `access.public.allowedFilters/allowedSorts`.
+- Avoid designing public queries that require unbounded scans.
+
+## Relations
+
+Use `relations` only when frontend/admin needs `include`.
+
+```json
+"relations": {
+  "author": {
+    "type": "entity",
+    "entity": "Author",
+    "localField": "authorId",
+    "foreignField": "id",
+    "as": "author"
+  }
+}
+```
+
+Rules:
+
+- Keep relation names stable; SDK/UI may use them in `include`.
+- Do not use relations to hide missing denormalized fields required by list pages.
+- Public include should be conservative; ensure related data is safe to expose.
+
+## Presentation and Lifecycle
+
+`presentation` is not API validation. It teaches admin UI, codegen, and agents how to display a record:
+
+```json
+"presentation": {
+  "titleField": "title",
+  "imageField": "coverImageUrl",
+  "defaultSort": { "field": "updatedDate", "order": "desc" },
+  "listFields": ["title", "status", "updatedDate"]
+}
+```
+
+`lifecycle` is policy metadata:
+
+```json
+"lifecycle": {
+  "audit": true,
+  "softDelete": false
+}
+```
+
+Use it to document intent, but do not assume every lifecycle policy is fully enforced unless backend
+source confirms it.
+
+## Schema Review Checklist
+
+Before applying a schema:
+
+- Entity name and field names pass naming rules.
+- No business field collides with system fields.
+- Every required field exists in `properties`.
+- Every optional nullable field has a deliberate `null` type/default.
+- Defaults exist for fields that should not block create.
+- Access has both `authenticated` and `public`.
+- Public list/scoped flows have filters, sorts, scopes, and limits.
+- Private owned data does not require app code to pass owner fields.
+- Indexes match real list/detail queries.
+- Presentation tells UI/admin which fields to show.
+- Workflow output fields are explicitly declared before persistence.
+- Dangerous public write is avoided or explicitly justified.
+
+If any item cannot be answered from requirements, stop and ask for the missing contract instead of
+inventing hidden fields or public exposure.