Ship Novya PWA with backend for deployable production use.

Fix production TypeScript builds and add DEPLOY.md so the app can be hosted from this repo.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
ar.badiei
2026-09-03 21:01:52 +03:30
co-authored by Cursor
parent aa9236fb92
commit 370ac15471
193 changed files with 25997 additions and 1991 deletions
+66
View File
@@ -0,0 +1,66 @@
/**
* PCQ-24 Dimension Configuration
*
* Maps each PCQ-24 question ID to its psychological capital dimension.
*
* Dimension assignment (as specified):
* - Self-Efficacy: Questions 1-6 → pcq_01 – pcq_06
* - Hope: Questions 7-12 → pcq_07 – pcq_12
* - Resilience: Questions 13-18 → pcq_13 – pcq_18
* - Optimism: Questions 19-24 → pcq_19 – pcq_24
*
* Scale: 1–6 for all items (reverse-scored items use 7 − value)
*/
export const DIMENSION_NAMES = ['efficacy', 'hope', 'resilience', 'optimism'] as const;
export type DimensionName = (typeof DIMENSION_NAMES)[number];
export const DIMENSION_ITEM_COUNT = 6;
export const DIMENSION_SCORE_MIN = 6; // 6 items × 1
export const DIMENSION_SCORE_MAX = 36; // 6 items × 6
export const TOTAL_SCORE_MIN = 24; // 24 items × 1
export const TOTAL_SCORE_MAX = 144; // 24 items × 6
/** Question ID → Dimension mapping */
export const QUESTION_DIMENSION_MAP: Record<string, DimensionName> = {
pcq_01: 'efficacy',
pcq_02: 'efficacy',
pcq_03: 'efficacy',
pcq_04: 'efficacy',
pcq_05: 'efficacy',
pcq_06: 'efficacy',
pcq_07: 'hope',
pcq_08: 'hope',
pcq_09: 'hope',
pcq_10: 'hope',
pcq_11: 'hope',
pcq_12: 'hope',
pcq_13: 'resilience',
pcq_14: 'resilience',
pcq_15: 'resilience',
pcq_16: 'resilience',
pcq_17: 'resilience',
pcq_18: 'resilience',
pcq_19: 'optimism',
pcq_20: 'optimism',
pcq_21: 'optimism',
pcq_22: 'optimism',
pcq_23: 'optimism',
pcq_24: 'optimism',
};
/** All 24 PCQ-24 question IDs in survey order */
export const PCQ_QUESTION_IDS: string[] = Array.from({ length: 24 }, (_, i) =>
`pcq_${String(i + 1).padStart(2, '0')}`
);
/** Build reverse lookup: dimension → ordered list of question IDs */
export const DIMENSION_QUESTIONS: Record<DimensionName, string[]> = {
efficacy: ['pcq_01', 'pcq_02', 'pcq_03', 'pcq_04', 'pcq_05', 'pcq_06'],
hope: ['pcq_07', 'pcq_08', 'pcq_09', 'pcq_10', 'pcq_11', 'pcq_12'],
resilience: ['pcq_13', 'pcq_14', 'pcq_15', 'pcq_16', 'pcq_17', 'pcq_18'],
optimism: ['pcq_19', 'pcq_20', 'pcq_21', 'pcq_22', 'pcq_23', 'pcq_24'],
};
+49
View File
@@ -0,0 +1,49 @@
/**
* PCQ-24 Scoring Engine — Public API
*/
// Scoring engine
export {
scoreAssessment,
scoreAnswer,
computeDimensionTotals,
computeTotalScore,
validateAnswers,
parseLikertValue,
type RawAnswer,
type ScoredAnswer,
type DimensionScores,
type ScoringResult,
type ValidationResult,
type ScoringError,
type ValidationError,
} from './scoringEngine';
// Configuration
export {
DIMENSION_NAMES,
DIMENSION_ITEM_COUNT,
DIMENSION_SCORE_MIN,
DIMENSION_SCORE_MAX,
TOTAL_SCORE_MIN,
TOTAL_SCORE_MAX,
QUESTION_DIMENSION_MAP,
PCQ_QUESTION_IDS,
DIMENSION_QUESTIONS,
type DimensionName,
} from './dimensions';
export {
REVERSE_SCORED_QUESTIONS,
isReverseScored,
applyReverseScoring,
} from './reverseScoring';
// Utility helpers
export {
getDimensionQuestionIds,
getDimensionItemCount,
getDimensionScoreRange,
getTotalScoreRange,
getReverseScoredQuestionIds,
} from './scoringEngine';
@@ -0,0 +1,34 @@
/**
* PCQ-24 Reverse Scoring Configuration
*
* Reverse scoring formula: 7 - rawValue
* After reversal, a value of 1 becomes 6, 2 becomes 5, 3 becomes 4, etc.
*
* Reverse-scored questions (as specified):
* - pcq_13 (Question 13 — Resilience dimension)
* - pcq_20 (Question 20 — Optimism dimension)
* - pcq_23 (Question 23 — Optimism dimension)
*
* Scale: 1–6
* Reversed: 1→6, 2→5, 3→4, 4→3, 5→2, 6→1
*/
import type { PcqLikertValue } from '@/config/pcq24';
/** Set of question IDs that must be reverse-scored */
export const REVERSE_SCORED_QUESTIONS = new Set<string>(['pcq_13', 'pcq_20', 'pcq_23']);
/** Returns true if the given question ID is reverse-scored */
export function isReverseScored(questionId: string): boolean {
return REVERSE_SCORED_QUESTIONS.has(questionId);
}
/**
* Apply the PCQ-24 reverse scoring formula: 7 − rawValue
*
* @param rawValue - Likert value as string or number (expected 1–6)
* @returns reversed score (6→1, 5→2, 4→3, 3→4, 2→5, 1→6)
*/
export function applyReverseScoring(rawValue: PcqLikertValue | string): number {
return 7 - Number(rawValue);
}
+274
View File
@@ -0,0 +1,274 @@
/**
* PCQ-24 Scoring Engine
*
* Pure computation module — no React, no storage, no Supabase.
* Works identically on frontend or backend.
*/
import type { PcqLikertValue } from '@/config/pcq24';
import type { AttemptPhase } from '@/services/assessmentService';
import {
DIMENSION_NAMES,
DIMENSION_ITEM_COUNT,
DIMENSION_SCORE_MIN,
DIMENSION_SCORE_MAX,
TOTAL_SCORE_MIN,
TOTAL_SCORE_MAX,
QUESTION_DIMENSION_MAP,
PCQ_QUESTION_IDS,
DIMENSION_QUESTIONS,
type DimensionName,
} from './dimensions';
import {
isReverseScored,
applyReverseScoring,
REVERSE_SCORED_QUESTIONS,
} from './reverseScoring';
// ─────────────────────────────────────────────────────────────────────────────
// Input / Output Types
// ─────────────────────────────────────────────────────────────────────────────
export type RawAnswer = {
questionId: string;
selectedValue: PcqLikertValue | string;
};
export type ScoredAnswer = {
questionId: string;
selectedValue: number;
dimension: DimensionName;
isReverseScored: boolean;
rawScore: number;
dimensionScore: number;
};
export type DimensionScores = Record<DimensionName, number>;
export type ScoringResult = {
assessmentType: AttemptPhase;
totalScore: number;
dimensions: DimensionScores;
answers: ScoredAnswer[];
completedAt: Date;
validation: ValidationResult;
};
export type ValidationResult = {
isValid: boolean;
errorCount: number;
warnings: string[];
};
// ─────────────────────────────────────────────────────────────────────────────
// Errors
// ─────────────────────────────────────────────────────────────────────────────
export class ScoringError extends Error {
constructor(message: string) {
super(message);
this.name = 'ScoringError';
}
}
export class ValidationError extends Error {
public readonly issues: string[];
constructor(issues: string[]) {
super(issues.join('; '));
this.name = 'ValidationError';
this.issues = issues;
}
}
// ─────────────────────────────────────────────────────────────────────────────
// Score Calculation
// ─────────────────────────────────────────────────────────────────────────────
/**
* Convert a raw string Likert value to a validated number.
* Returns null if the value is not a valid Likert integer (1–6).
*/
export function parseLikertValue(value: PcqLikertValue | string): number | null {
const n = Number(value);
if (!Number.isFinite(n)) return null;
const rounded = Math.round(n);
if (rounded < 1 || rounded > 6) return null;
return rounded;
}
/**
* Score a single answer: apply reverse scoring if needed, then return the
* dimension score (same as raw score — scoring is per-question, aggregation
* happens in dimensionTotals).
*/
export function scoreAnswer(
questionId: string,
selectedValue: PcqLikertValue | string
): { rawScore: number; dimension: DimensionName; isReverseScored: boolean } | null {
const numeric = parseLikertValue(selectedValue);
if (numeric === null) return null;
const dimension = QUESTION_DIMENSION_MAP[questionId];
if (!dimension) return null;
const reverse = isReverseScored(questionId);
const rawScore = reverse ? applyReverseScoring(selectedValue as PcqLikertValue) : numeric;
return { rawScore, dimension, isReverseScored: reverse };
}
/**
* Aggregate per-question raw scores into per-dimension totals.
* Each dimension sums exactly 6 items (questions assigned to it).
*/
export function computeDimensionTotals(answers: ScoredAnswer[]): DimensionScores {
const totals: DimensionScores = Object.fromEntries(DIMENSION_NAMES.map((d) => [d, 0])) as DimensionScores;
for (const answer of answers) {
totals[answer.dimension] += answer.dimensionScore;
}
return totals;
}
/**
* Sum all dimension scores to produce the total PCQ-24 psychological capital score.
*/
export function computeTotalScore(dimensions: DimensionScores): number {
return DIMENSION_NAMES.reduce((sum, dim) => sum + dimensions[dim], 0);
}
// ─────────────────────────────────────────────────────────────────────────────
// Validation
// ─────────────────────────────────────────────────────────────────────────────
/**
* Validate that exactly 24 answers are present, one per PCQ-24 item,
* and that every answer value is in the range 1–6.
*/
export function validateAnswers(answers: RawAnswer[]): ValidationResult {
if (answers.length !== PCQ_QUESTION_IDS.length) {
return {
isValid: false,
errorCount: 1,
warnings: [
`Expected ${PCQ_QUESTION_IDS.length} answers but received ${answers.length}.`,
],
};
}
const providedIds = new Set(answers.map((a) => a.questionId));
const missing = PCQ_QUESTION_IDS.filter((id) => !providedIds.has(id));
if (missing.length > 0) {
return {
isValid: false,
errorCount: missing.length,
warnings: [`Missing questions: ${missing.join(', ')}`],
};
}
const invalid: string[] = [];
for (const answer of answers) {
const parsed = parseLikertValue(answer.selectedValue);
if (parsed === null) {
invalid.push(
`${answer.questionId}=${String(answer.selectedValue)}`
);
}
}
if (invalid.length > 0) {
return {
isValid: false,
errorCount: invalid.length,
warnings: [`Invalid answer values: ${invalid.join(', ')}`],
};
}
return { isValid: true, errorCount: 0, warnings: [] };
}
// ─────────────────────────────────────────────────────────────────────────────
// Main Entry Point
// ─────────────────────────────────────────────────────────────────────────────
/**
* Score a complete PCQ-24 assessment.
*
* Steps:
* 1. Validate answer count and values
* 2. Score each answer (with reverse scoring applied where needed)
* 3. Aggregate into 4 dimension scores
* 4. Sum dimension scores for total psychological capital score
*
* @throws ValidationError — if the answer set is invalid
*/
export function scoreAssessment(
assessmentType: AttemptPhase,
answers: RawAnswer[]
): ScoringResult {
const validation = validateAnswers(answers);
if (!validation.isValid) {
throw new ValidationError(validation.warnings);
}
const scoredAnswers: ScoredAnswer[] = [];
for (const answer of answers) {
const scored = scoreAnswer(answer.questionId, answer.selectedValue);
if (!scored) {
// Should not happen after validation, but defensive
throw new ScoringError(`Failed to score question: ${answer.questionId}`);
}
scoredAnswers.push({
questionId: answer.questionId,
selectedValue: scored.rawScore,
dimension: scored.dimension,
isReverseScored: scored.isReverseScored,
rawScore: scored.rawScore,
dimensionScore: scored.rawScore,
});
}
const dimensions = computeDimensionTotals(scoredAnswers);
const totalScore = computeTotalScore(dimensions);
return {
assessmentType,
totalScore,
dimensions,
answers: scoredAnswers,
completedAt: new Date(),
validation: { isValid: true, errorCount: 0, warnings: [] },
};
}
// ─────────────────────────────────────────────────────────────────────────────
// Utility helpers (exported for testing / reporting)
// ─────────────────────────────────────────────────────────────────────────────
/** Return the full list of question IDs for a given dimension */
export function getDimensionQuestionIds(dimension: DimensionName): string[] {
return DIMENSION_QUESTIONS[dimension];
}
/** Return the number of items per dimension */
export function getDimensionItemCount(): number {
return DIMENSION_ITEM_COUNT;
}
/** Return the valid score range for a single dimension */
export function getDimensionScoreRange(): { min: number; max: number } {
return { min: DIMENSION_SCORE_MIN, max: DIMENSION_SCORE_MAX };
}
/** Return the valid total score range */
export function getTotalScoreRange(): { min: number; max: number } {
return { min: TOTAL_SCORE_MIN, max: TOTAL_SCORE_MAX };
}
/** List all reverse-scored question IDs */
export function getReverseScoredQuestionIds(): string[] {
return Array.from(REVERSE_SCORED_QUESTIONS);
}