qualia-framework 2.6.0 → 3.1.0

package/framework/skills/sakani-conventions/references/entities.md

@@ -1,365 +0,0 @@
-# Sakani Entity Reference
-
-Complete entity definitions from SRS V1.14. This is the source of truth for schema design, API contracts, and type generation.
-
-## Conventions
-
-- All IDs are UUIDs
-- All tables have `id`, `created_at` (timestamptz, UTC), `updated_at` (timestamptz, UTC)
-- Monetary fields: `{ amount: numeric, currency: text }` (ISO 4217)
-- All timestamps stored UTC, presented Asia/Amman
-- `request_id` correlation on every write operation
-
----
-
-## Identity Domain
-
-### building
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_key_v1 | text | Canonical key for deterministic matching. UNIQUE. Never expose. |
-| name_ar | text | Arabic building name |
-| name_en | text | English building name |
-| building_type | enum | RESIDENTIAL, COMMERCIAL, MIXED |
-| address | jsonb | Structured address object |
-| unit_count | integer | Number of units |
-| subscription_status | enum | TRIAL, ACTIVE, INACTIVE |
-| trial_expires_at | timestamptz | 30-day trial expiry |
-
-### building_contact
-| Field | Type | Notes |
-|-------|------|-------|
-| building_id | uuid | FK → building |
-| contact_type | enum | PHONE, EMAIL, ADDRESS |
-| value | text | |
-
-### building_setup_request
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| requested_by | uuid | FK → auth.users |
-| status | enum | PENDING, APPROVED, REJECTED, RETURNED_FOR_FIX |
-| building_data | jsonb | Submitted building details |
-| occupation_permit_document_id | uuid | FK → document |
-| reviewed_by | uuid | FK → auth.users (staff) |
-| review_notes | text | |
-| rejection_reason_code | text | Stable identifier |
-
-### unit
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| unit_key_v1 | text | Canonical key. UNIQUE per building. Never expose. |
-| unit_number | text | Display number |
-| floor | integer | |
-| unit_type | enum | APARTMENT, OFFICE, SHOP, OTHER |
-| status | enum | DRAFT, ACTIVE |
-
-### unit_claim_request
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| unit_id | uuid | FK → unit |
-| claimed_by | uuid | FK → auth.users |
-| status | enum | PENDING, APPROVED, REJECTED, RETURNED_FOR_FIX |
-| goshan_document_id | uuid | FK → document |
-| match_outcome | enum | ZERO_MATCH, ONE_MATCH, MULTI_MATCH |
-| reviewed_by | uuid | FK → auth.users (staff) |
-
-### unit_membership
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| unit_id | uuid | FK → unit |
-| user_id | uuid | FK → auth.users |
-| role | enum | OWNER_VERIFIED, TENANT |
-| status | enum | ACTIVE, INACTIVE |
-| invited_by | uuid | FK → auth.users |
-
-One OWNER_VERIFIED per unit (no co-ownership in Phase 1).
-
-### building_role_assignment
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| user_id | uuid | FK → auth.users |
-| role | enum | BM_CANDIDATE, BM_VERIFIED, GUARD, DEV_ADMIN |
-| status | enum | ACTIVE, INACTIVE |
-| assigned_by | uuid | FK → auth.users |
-
-### document
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| owner_entity_type | enum | BUILDING, UNIT, USER, TICKET, CREDIT_TOPUP_REQUEST, CONTRACT, NOTICE, TASK_TEMPLATE, TASK_INSTANCE |
-| owner_entity_id | uuid | Polymorphic FK |
-| document_type | text | Classification |
-| storage_path | text | Object storage path |
-| signed_url_ttl | integer | Seconds |
-| uploaded_by | uuid | FK → auth.users |
-| approval_status | enum | PENDING, APPROVED, REJECTED |
-| visibility | enum | PUBLIC, BUILDING_MEMBERS, UNIT_MEMBERS, PRIVATE |
-
----
-
-## Finance Domain
-
-### dues_config
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| amount | numeric | Monthly amount |
-| currency | text | ISO 4217 (JOD) |
-| collection_day | integer | Day of month (1-28 recommended) |
-| effective_from | date | |
-
-### dues_cycle
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| cycle_ym | text | Format: YYYY-MM |
-| status | enum | OPEN, CLOSED |
-
-### dues_obligation
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| cycle_id | uuid | FK → dues_cycle |
-| unit_id | uuid | FK → unit |
-| amount | numeric | |
-| currency | text | JOD |
-| status | enum | UNPAID, PAID, LATE |
-| due_date | date | |
-
-UNPAID → LATE at cycle boundary. UNPAID/LATE → PAID via settlement.
-
-### ledger_entry
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| unit_id | uuid | FK → unit (nullable for building-level) |
-| entry_type | enum | CREDIT_TOPUP, MANUAL_UNIT_INCOME, OPENING_BALANCE, EXPENSE, SUBSCRIPTION_FEE, AUTOSETTLEMENT_APPLIED, REVERSAL |
-| amount | numeric | Positive = credit, negative = debit |
-| currency | text | JOD |
-| reference_id | uuid | FK to source entity |
-| reference_type | text | Source entity type |
-| idempotency_key | text | UNIQUE. Prevents duplicate writes. |
-| request_id | uuid | Audit correlation |
-| created_by | uuid | FK → auth.users |
-
-**APPEND-ONLY.** Never UPDATE or DELETE. Corrections via REVERSAL entries only.
-
-### credit_topup_request
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| unit_id | uuid | FK → unit |
-| requested_by | uuid | FK → auth.users (owner only) |
-| amount | numeric | |
-| currency | text | JOD |
-| evidence_document_id | uuid | FK → document (CliQ/bank screenshot) |
-| status | enum | PENDING, APPROVED, REJECTED |
-| reviewed_by | uuid | FK → auth.users (BM) |
-| idempotency_key | text | UNIQUE |
-
-### settlement_entry
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| obligation_id | uuid | FK → dues_obligation |
-| ledger_entry_id | uuid | FK → ledger_entry |
-| amount | numeric | |
-| settled_at | timestamptz | |
-
-FIFO: oldest obligation settled first. No partial settlement.
-
-### expense
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| amount | numeric | |
-| currency | text | JOD |
-| description | text | |
-| category | text | |
-| evidence_document_id | uuid | FK → document |
-| recorded_by | uuid | FK → auth.users (BM) |
-| approval_status | enum | PENDING, APPROVED |
-
----
-
-## Subscription Domain
-
-### subscription_entitlement
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building. ONE per building. |
-| status | enum | TRIAL, ACTIVE, INACTIVE |
-| current_period_start | timestamptz | |
-| current_period_end | timestamptz | |
-| provider | text | stripe, hyperpay |
-| provider_subscription_id | text | External ID |
-
-### subscription_plan
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| name | text | |
-| building_type | enum | RESIDENTIAL, COMMERCIAL, MIXED |
-| unit_count_min | integer | |
-| unit_count_max | integer | |
-| price | numeric | |
-| currency | text | JOD |
-| billing_interval | text | monthly, yearly |
-
-### subscription_price_quote
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| plan_id | uuid | FK → subscription_plan |
-| quoted_price | numeric | Snapshot at quote time |
-| inputs_snapshot | jsonb | building_type, unit_count at quote time |
-| expires_at | timestamptz | Quote expiry |
-| status | enum | ACTIVE, EXPIRED, CONSUMED |
-
-### subscription_checkout_session
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| quote_id | uuid | FK → subscription_price_quote |
-| provider | text | stripe, hyperpay |
-| provider_session_id | text | |
-| status | enum | PENDING, COMPLETED, FAILED |
-| promo_redemption_id | uuid | FK → promo_redemption (nullable) |
-
-### subscription_event
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| provider | text | |
-| provider_event_id | text | UNIQUE (idempotency) |
-| canonical_event_type | text | Normalized event type |
-| raw_payload | jsonb | |
-| processed_at | timestamptz | |
-| signature_valid | boolean | |
-
-### promo_code
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| code | text | UNIQUE |
-| discount_type | enum | PERCENTAGE, FIXED |
-| discount_value | numeric | |
-| max_redemptions | integer | |
-| current_redemptions | integer | |
-| valid_from | timestamptz | |
-| valid_until | timestamptz | |
-| status | enum | ACTIVE, EXHAUSTED, EXPIRED |
-
-### promo_redemption
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| promo_code_id | uuid | FK → promo_code |
-| building_id | uuid | FK → building |
-| status | enum | RESERVED, CONSUMED |
-
-RESERVED on checkout start, CONSUMED on payment success. Atomic.
-
-### reimbursement_obligation
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| checkout_session_id | uuid | FK → subscription_checkout_session |
-| amount | numeric | |
-| currency | text | JOD |
-| settlement_method | enum | DUES_OFFSET, MANUAL |
-| status | enum | PENDING, SETTLED |
-| idempotency_key | text | UNIQUE |
-
----
-
-## Operations Domain
-
-### guard_invite
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| invited_by | uuid | FK → auth.users (BM) |
-| phone_number | text | |
-| status | enum | PENDING, ACCEPTED, EXPIRED, REVOKED |
-| expires_at | timestamptz | 7-day expiry |
-| token | text | Single-use invite token |
-
-One ACTIVE guard per building.
-
-### guard_task
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| template_id | uuid | FK → task_template (nullable) |
-| assigned_to | uuid | FK → auth.users (guard) |
-| title | text | |
-| description | text | |
-| scheduled_at | timestamptz | |
-| reminder_at | timestamptz | T-15m before scheduled_at |
-| status | enum | PENDING, IN_PROGRESS, COMPLETED, MISSED |
-| visibility | enum | BUILDING_PUBLIC, UNIT_PRIVATE |
-
-BUILDING_PUBLIC: all building members see details. UNIT_PRIVATE: others see "Busy/Private" only.
-
-### ticket
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| unit_id | uuid | FK → unit (nullable) |
-| reported_by | uuid | FK → auth.users |
-| assigned_to | uuid | FK → auth.users (guard, nullable) |
-| title | text | |
-| description | text | |
-| category | text | Optional |
-| status | enum | NEW, IN_PROGRESS, DONE, CLOSED, CANCELLED |
-| priority | enum | LOW, MEDIUM, HIGH |
-
-Status flow: NEW → IN_PROGRESS → DONE → CLOSED. Optional CANCELLED from any state.
-
----
-
-## Audit Domain
-
-### audit_log
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| event_type | text | e.g., permit_submitted, credit_topup_approved |
-| actor_user_id | uuid | FK → auth.users |
-| building_id | uuid | Nullable |
-| unit_id | uuid | Nullable |
-| request_id | uuid | Correlation |
-| payload | jsonb | Event-specific data (no PII) |
-| created_at | timestamptz | |
-
-**IMMUTABLE.** 7-year retention. Filterable by building_id, unit_id, actor_user_id, event_type, date range.
-
-### statement_version
-| Field | Type | Notes |
-|-------|------|-------|
-| id | uuid | PK |
-| building_id | uuid | FK → building |
-| cycle_ym | text | |
-| version_token | text | UNIQUE |
-| pdf_storage_path | text | |
-| hash | text | Immutable content hash |
-| generated_at | timestamptz | |

package/framework/skills/sakani-conventions/references/error-codes.md

@@ -1,95 +0,0 @@
-# Sakani Error Codes
-
-All 44 error codes from SRS V1.14 (EH-6.02 through EH-6.44). Every API endpoint must use these exact codes.
-
-## Error Response Shape
-
-```typescript
-interface ApiError {
-  http_status: number;
-  error_code: string;
-  message_key: string;      // i18n lookup key
-  request_id: string;        // UUID, always present
-  details?: Record<string, unknown>;  // safe details only
-}
-```
-
-## Safe-Details Rule
-
-NEVER include in `details` or error messages:
-- `building_key_v1` or `unit_key_v1` values
-- National ID numbers or extracted document text
-- Internal entity IDs that enable enumeration
-- Stack traces or internal paths
-
-## Error Code Table
-
-| Code | error_code | HTTP | message_key | Context |
-|------|-----------|------|-------------|---------|
-| EH-6.02 | UNAUTHENTICATED | 401 | error.auth.unauthenticated | No valid token |
-| EH-6.03 | TOKEN_EXPIRED | 401 | error.auth.token_expired | Access token expired |
-| EH-6.04 | INSUFFICIENT_PERMISSIONS | 403 | error.auth.insufficient_permissions | Role/scope insufficient |
-| EH-6.05 | BUILDING_NOT_FOUND | 404 | error.building.not_found | Building lookup 0-match |
-| EH-6.06 | BUILDING_AMBIGUOUS | 409 | error.building.ambiguous | Building lookup >1-match |
-| EH-6.07 | UNIT_NOT_FOUND | 404 | error.unit.not_found | Unit lookup 0-match |
-| EH-6.08 | UNIT_AMBIGUOUS | 409 | error.unit.ambiguous | Unit lookup >1-match |
-| EH-6.09 | UNIT_ALREADY_CLAIMED | 409 | error.unit.already_claimed | OWNER_VERIFIED exists |
-| EH-6.10 | CLAIM_ALREADY_PENDING | 409 | error.claim.already_pending | Duplicate claim request |
-| EH-6.11 | PERMIT_ALREADY_SUBMITTED | 409 | error.permit.already_submitted | Duplicate permit submission |
-| EH-6.12 | SETUP_REQUEST_ALREADY_PENDING | 409 | error.setup.already_pending | Duplicate setup request |
-| EH-6.13 | DOCUMENT_NOT_FOUND | 404 | error.document.not_found | Document ID invalid |
-| EH-6.14 | DOCUMENT_ACCESS_DENIED | 403 | error.document.access_denied | Visibility check failed |
-| EH-6.15 | INVALID_DOCUMENT_TYPE | 422 | error.document.invalid_type | Wrong document classification |
-| EH-6.16 | DUES_CONFIG_NOT_FOUND | 404 | error.dues.config_not_found | No dues config for building |
-| EH-6.17 | DUES_CYCLE_NOT_FOUND | 404 | error.dues.cycle_not_found | Invalid cycle_ym |
-| EH-6.18 | OBLIGATION_NOT_FOUND | 404 | error.dues.obligation_not_found | Invalid obligation |
-| EH-6.19 | INSUFFICIENT_CREDIT | 422 | error.credit.insufficient | Credit doesn't cover obligation |
-| EH-6.20 | DUPLICATE_TOPUP_REQUEST | 409 | error.credit.duplicate_topup | Idempotency key collision |
-| EH-6.21 | TOPUP_ALREADY_REVIEWED | 409 | error.credit.already_reviewed | Re-reviewing decided request |
-| EH-6.22 | OPENING_BALANCE_EXISTS | 409 | error.ledger.opening_balance_exists | One per unit |
-| EH-6.23 | OPENING_BALANCE_WINDOW_CLOSED | 422 | error.ledger.opening_balance_window | Past controlled window |
-| EH-6.24 | LEDGER_IDEMPOTENCY_CONFLICT | 409 | error.ledger.idempotency_conflict | Duplicate financial write |
-| EH-6.25 | SUBSCRIPTION_NOT_FOUND | 404 | error.subscription.not_found | No entitlement for building |
-| EH-6.26 | SUBSCRIPTION_INACTIVE | 403 | error.subscription.inactive | Paywall gate |
-| EH-6.27 | TRIAL_EXPIRED | 403 | error.subscription.trial_expired | 30-day trial over |
-| EH-6.28 | QUOTE_EXPIRED | 422 | error.subscription.quote_expired | Price quote past expiry |
-| EH-6.29 | QUOTE_ALREADY_CONSUMED | 409 | error.subscription.quote_consumed | Quote used in checkout |
-| EH-6.30 | PROMO_CODE_INVALID | 422 | error.promo.invalid | Code not found or inactive |
-| EH-6.31 | PROMO_CODE_EXHAUSTED | 422 | error.promo.exhausted | Max redemptions reached |
-| EH-6.32 | PROMO_ALREADY_RESERVED | 409 | error.promo.already_reserved | Duplicate reservation |
-| EH-6.33 | CHECKOUT_SESSION_INVALID | 422 | error.checkout.invalid | Bad session state |
-| EH-6.34 | WEBHOOK_SIGNATURE_INVALID | 401 | error.webhook.signature_invalid | Provider signature failed |
-| EH-6.35 | GUARD_INVITE_EXPIRED | 422 | error.guard.invite_expired | Past 7-day window |
-| EH-6.36 | GUARD_INVITE_REVOKED | 422 | error.guard.invite_revoked | Invite was revoked |
-| EH-6.37 | GUARD_ALREADY_ACTIVE | 409 | error.guard.already_active | One active guard per building |
-| EH-6.38 | TICKET_NOT_FOUND | 404 | error.ticket.not_found | Invalid ticket |
-| EH-6.39 | TICKET_INVALID_TRANSITION | 422 | error.ticket.invalid_transition | Status flow violated |
-| EH-6.40 | TASK_NOT_FOUND | 404 | error.task.not_found | Invalid task |
-| EH-6.41 | VALIDATION_ERROR | 422 | error.validation.failed | Zod/input validation |
-| EH-6.42 | RATE_LIMITED | 429 | error.rate_limit.exceeded | Too many requests |
-| EH-6.43 | INTERNAL_ERROR | 500 | error.internal | Unexpected server error |
-| EH-6.44 | SERVICE_UNAVAILABLE | 503 | error.service.unavailable | Downstream service down |
-
-## Usage in NestJS
-
-```typescript
-// In @sakani/shared/src/constants/errors.ts
-export const SAKANI_ERRORS = {
-  UNAUTHENTICATED: { code: 'UNAUTHENTICATED', status: 401, messageKey: 'error.auth.unauthenticated' },
-  BUILDING_NOT_FOUND: { code: 'BUILDING_NOT_FOUND', status: 404, messageKey: 'error.building.not_found' },
-  // ... all 44
-} as const;
-
-// In NestJS exception filter
-throw new SakaniException(SAKANI_ERRORS.BUILDING_NOT_FOUND, { requestId });
-```
-
-## Deterministic Lookup Semantics
-
-These error codes have precise semantic meanings for building/unit lookup:
-- `BUILDING_NOT_FOUND` = exactly 0-match (not "maybe not found")
-- `BUILDING_AMBIGUOUS` = exactly >1-match
-- `UNIT_NOT_FOUND` = exactly 0-match
-- `UNIT_AMBIGUOUS` = exactly >1-match
-
-The lookup algorithm must be deterministic: same input always produces the same match outcome.