alla-allaos-fullstack/docs/setup/verification-matrix.md

Setup Verification Matrix

Verification checks return PASS, WARNING, or FAIL.

Check ID	Area	Check Name	Purpose	Required For	Method	Pass Condition	Warning Condition	Fail Condition	Suggested Fix	API / Service
ENV_AUTH_SECRET	Environment	Auth secret present	Ensure Auth.js can sign sessions.	first login	Read server env.	AUTH_SECRET exists and length is acceptable.	Weak-looking local/dev secret.	Missing secret.	Set AUTH_SECRET in .env.local or deployment secrets.	setup/readiness.service.ts
ENV_DATABASE_URL	Environment	Database URL present	Ensure app can connect to PostgreSQL.	all setup	Read server env.	DATABASE_URL exists.	Host appears local in non-local environment.	Missing value.	Set DATABASE_URL.	setup/readiness.service.ts
DB_CONNECTIVITY	Database	Database connectivity	Prove DB is reachable.	all setup	Open DB connection and select 1.	Query succeeds.	High latency.	Connection/query fails.	Verify database host, network, credentials.	src/lib/db.ts
DB_MIGRATIONS	Database	Migration status	Prevent setup against stale schema.	all setup	Check Drizzle migration metadata/schema tables where available.	Schema matches expected tables.	Migration metadata unavailable but required tables exist.	Required tables missing.	Run npm run db:migrate.	setup readiness + Drizzle
STORAGE_PROVIDER	Storage	Storage provider smoke test	Prove seed/document storage can write.	document library/PDF	Write/read/delete test object under setup prefix.	All operations succeed.	Delete cleanup fails but object tracked.	Write/read fails.	Fix local directory/S3 credentials.	src/features/foundation/storage/**
UPLOAD_DIRECTORY	Storage	Upload directory readiness	Prove local provider path is writable.	local storage	Check directory exists/create/write/delete.	Directory writable.	Directory created during check.	Not writable.	Create/fix permissions.	storage provider
PDF_TEMPLATE_ASSET	PDF	PDF template assets exist	Ensure quotation PDF can render.	quotation	Check active template version/file/schema.	Active version and schema exist.	Template exists but preview asset missing.	No active template version.	Run foundation/PDF template seed.	document-template/pdf foundations
PDF_MAPPING_COVERAGE	PDF	PDF mappings exist	Ensure placeholders can resolve.	quotation	Count required mappings for active version.	Required mappings present.	Optional mappings missing.	Required mapping missing.	Run PDF mapping seed/audit.	PDF audit services/scripts
EMAIL_CONFIG	Email	Email configuration	Confirm optional email readiness.	optional notifications	Read env/provider config; optional dry-run.	Provider configured and dry-run succeeds.	Email not configured but in-app notifications are available.	Provider configured but dry-run fails.	Fix SMTP/provider settings.	future notification/email service
ADMIN_USER	Auth	First administrator exists	Ensure first login actor exists.	first login	Query users by setup admin email.	User exists.	User exists but inactive semantics added later.	Missing user.	Create administrator step.	user/auth service
ADMIN_MEMBERSHIP	Auth	Administrator membership exists	Ensure admin can enter organization.	first login	Query memberships.	Membership exists with admin role.	Membership role is user but CRM assignment admin.	Missing membership.	Create membership.	organization/session helpers
ADMIN_CRM_ASSIGNMENT	Authorization	Administrator CRM assignment resolves	Ensure CRM admin permissions resolve.	CRM	Resolve CRM access.	crm_admin or equivalent permissions resolve.	Compatibility business role only, no assignment.	No CRM access.	Seed role profiles and assignment.	resolveCrmAccess()
ORG_ACTIVE	Organization	Organization active/resolvable	Ensure active org context works.	all setup	Resolve organization and active org for admin.	Organization exists and admin active org set.	Organization exists but active org missing.	Organization missing.	Update users.active_organization_id.	requireOrganizationAccess()
BRANCH_OPTION	Scope	Branch option exists	Ensure branch scope can resolve.	CRM/quotation	Query ms_options category crm_branch.	At least one active branch.	Branch exists but no default convention.	No active branch.	Configure branch step.	master-options foundation
PRODUCT_TYPE_OPTION	Scope	Product type option exists	Ensure product scope can resolve.	CRM/quotation	Query ms_options category crm_product_type.	At least one active product type.	Product type exists but no document prefix metadata.	No active product type.	Configure product types.	master-options foundation
SEQUENCE_CUSTOMER	Document sequence	Customer sequence preview	Ensure customer codes can generate.	CRM	Call sequence preview for customer.	Preview returns code.	Generic branch/product scope only.	Preview fails.	Configure document sequence.	document-sequence foundation
SEQUENCE_LEAD	Document sequence	Lead sequence preview	Ensure lead codes can generate.	CRM	Call sequence preview for crm_lead.	Preview returns code.	Generic scope only.	Preview fails.	Configure lead sequence.	document-sequence foundation
SEQUENCE_OPPORTUNITY	Document sequence	Opportunity sequence preview	Ensure opportunity codes can generate.	CRM	Call sequence preview for crm_opportunity.	Preview returns code.	Generic scope only.	Preview fails.	Configure opportunity sequence.	document-sequence foundation
SEQUENCE_QUOTATION	Document sequence	Quotation sequence preview	Ensure quotation codes can generate.	quotation	Preview by branch/product type.	Preview returns code for each configured product type.	Missing some branch/product combinations.	No quotation sequence works.	Configure quotation sequences.	document-sequence foundation
APPROVAL_WORKFLOW	Approval	Quotation workflow resolves	Ensure quotation approval can start.	quotation	Query active workflow for quotation.	Active workflow exists.	Multiple active candidates.	Missing workflow.	Configure approval workflow.	approval foundation
APPROVAL_MATRIX	Approval	Approval matrix resolves	Ensure quotation can select workflow by scope/amount.	quotation	Resolve matrix for sample quotation amount.	Matrix resolves.	Default-only fallback.	No matrix resolves.	Configure approval matrix.	approval foundation
NOTIFICATION_TEMPLATES	Notifications	Approval notification templates exist	Ensure in-app approval notifications can render.	CRM/quotation	Query app_notification_templates.	Required approval templates active.	Some optional templates missing.	Required templates missing.	Run foundation seed.	notification foundation
REPORT_DEFINITIONS	Reports	Report definitions exist	Ensure report catalog works.	CRM reports	Query crm_report_definitions.	Required definitions active.	Definitions exist but categories missing.	No definitions.	Run report foundation seed.	report foundation
CSV_PREVIEW	Import	CSV preview integrity	Ensure uploaded files were validated before commit.	CSV import	Check latest preview hash/status.	Preview exists and matches commit input hash.	Preview stale after dependency change.	Missing preview for commit.	Re-run CSV preview.	setup import service
SETUP_MANIFEST	Setup	Seed manifest recorded	Ensure lifecycle tracking exists.	setup completion	Query proposed manifest tables once implemented.	Manifest recorded with checksums.	Manifest not implemented in early slice.	Manifest required but missing.	Implement D.7.8.	setup manifest service

Required Completion Rule

Setup can complete only when all required checks for selected setup mode pass:

• Production foundation mode: all first-login, CRM, quotation, storage/PDF required checks must pass except optional email may warn.
• Demo/UAT mode: production required checks plus UAT user/data checks must pass.
• Dry-run mode: failures do not write setup completion, but report can be exported.