@viengut/vgq-sdk 0.1.1 → 0.3.0

package/dist/client.d.ts

@@ -30,6 +30,12 @@ export declare class VgqClient {
     /** Tải một Form Version bất biến (Response luôn gắn đúng version đã bắt đầu). */
     getFormVersion(id: string): Promise<FormVersion>;
     createResponse(publicationKey: string, options?: StartResponseOptions): Promise<ResponseDto>;
+    /**
+     * Bắt đầu Response xem thử trên bản Draft của Form (trang demo cổng bệnh
+     * nhân). Server chụp Draft vào shadow snapshot version và XOÁ Response
+     * preview cũ của Form — mỗi Form chỉ giữ một bản thử.
+     */
+    createPreviewResponse(formId: string, options?: StartResponseOptions): Promise<ResponseDto>;
     getInvitation(id: string): Promise<InvitationDto>;
     /** Bắt đầu (hoặc mở lại) Response duy nhất của một Invitation. */
     startInvitationResponse(invitationId: string): Promise<ResponseDto>;

package/dist/client.js

@@ -40,6 +40,18 @@ export class VgqClient {
             care_context_ref: options.careContextRef ?? null,
         }, headers);
     }
+    /**
+     * Bắt đầu Response xem thử trên bản Draft của Form (trang demo cổng bệnh
+     * nhân). Server chụp Draft vào shadow snapshot version và XOÁ Response
+     * preview cũ của Form — mỗi Form chỉ giữ một bản thử.
+     */
+    createPreviewResponse(formId, options = {}) {
+        return this.request('POST', `/api/forms/${encodeURIComponent(formId)}/preview-responses`, {
+            subject_ref: options.subjectRef ?? null,
+            respondent_ref: options.respondentRef ?? null,
+            care_context_ref: options.careContextRef ?? null,
+        });
+    }
     getInvitation(id) {
         return this.request('GET', `/api/invitations/${encodeURIComponent(id)}`);
     }

package/dist/engine.d.ts

@@ -11,12 +11,15 @@ export declare function topoOrder(def: FormDefinition): {
 export interface ActiveState {
     /** Id các Question đang hoạt động. */
     activeIds: Set<string>;
+    /** Id các Category đang hiện (điều kiện của chính nó và mọi tổ tiên đều đúng). */
+    activeCategoryIds: Set<string>;
     /** Giá trị hiệu lực theo slug: chỉ gồm giá trị của Question đang hoạt động. */
     effectiveValues: ResponseValues;
 }
 /**
  * Đánh giá Enable Condition toàn Form theo thứ tự topo. Giá trị của Question
  * không hoạt động bị loại khỏi giá trị hiệu lực nên chuỗi phụ thuộc tắt theo.
+ * Question trong Category tắt cũng không hoạt động.
  */
 export declare function computeActive(def: FormDefinition, values: ResponseValues): ActiveState;
 export declare function isAnswered(value: JsonValue | undefined): boolean;

package/dist/engine.js

@@ -12,8 +12,27 @@ export function allQuestions(def) {
     walk(def.categories);
     return out;
 }
-function conditionRefs(question) {
-    return (question.enable_condition?.any ?? []).flatMap((group) => group.all.map((condition) => condition.question_id));
+function conditionRefs(cond) {
+    return (cond?.any ?? []).flatMap((group) => group.all.map((condition) => condition.question_id));
+}
+/**
+ * Phụ thuộc Enable Condition của từng Question: refs của chính nó cộng refs
+ * điều kiện của mọi Category tổ tiên (Category tắt kéo Question tắt theo,
+ * nên thứ tự topo và phát hiện chu trình phủ luôn điều kiện cấp Category).
+ */
+function dependencyMap(def) {
+    const out = new Map();
+    const walk = (categories, inherited) => {
+        for (const category of categories) {
+            const refs = [...inherited, ...conditionRefs(category.enable_condition)];
+            for (const q of category.questions) {
+                out.set(q.id, [...refs, ...conditionRefs(q.enable_condition)]);
+            }
+            walk(category.children ?? [], refs);
+        }
+    };
+    walk(def.categories, []);
+    return out;
 }
 /**
  * Sắp xếp topo theo phụ thuộc Enable Condition (Kahn).
@@ -22,10 +41,11 @@ function conditionRefs(question) {
 export function topoOrder(def) {
     const questions = allQuestions(def);
     const known = new Set(questions.map((q) => q.id));
+    const deps = dependencyMap(def);
     const inDegree = new Map();
     const dependents = new Map();
     for (const q of questions) {
-        const valid = conditionRefs(q).filter((ref) => known.has(ref));
+        const valid = (deps.get(q.id) ?? []).filter((ref) => known.has(ref));
         inDegree.set(q.id, valid.length);
         for (const ref of valid) {
             const list = dependents.get(ref) ?? [];
@@ -49,13 +69,35 @@ export function topoOrder(def) {
     const stuck = [...known].filter((id) => !done.has(id)).sort();
     return { order, stuck };
 }
+function indexCategories(def) {
+    const idx = {
+        condition: new Map(),
+        parent: new Map(),
+        categoryOf: new Map(),
+        ordered: [],
+    };
+    const walk = (categories, parent) => {
+        for (const c of categories) {
+            idx.condition.set(c.id, c.enable_condition);
+            idx.parent.set(c.id, parent);
+            idx.ordered.push(c.id);
+            for (const q of c.questions)
+                idx.categoryOf.set(q.id, c.id);
+            walk(c.children ?? [], c.id);
+        }
+    };
+    walk(def.categories, null);
+    return idx;
+}
 /**
  * Đánh giá Enable Condition toàn Form theo thứ tự topo. Giá trị của Question
  * không hoạt động bị loại khỏi giá trị hiệu lực nên chuỗi phụ thuộc tắt theo.
+ * Question trong Category tắt cũng không hoạt động.
  */
 export function computeActive(def, values) {
     const questions = allQuestions(def);
     const byId = new Map(questions.map((q) => [q.id, q]));
+    const idx = indexCategories(def);
     const { order, stuck } = topoOrder(def);
     const evaluationOrder = stuck.length === 0 ? order : questions.map((q) => q.id);
     const effectiveValues = {};
@@ -64,16 +106,37 @@ export function computeActive(def, values) {
         if (v !== undefined && v !== null)
             effectiveValues[q.slug] = v;
     }
+    // Category hiện khi điều kiện của nó và mọi tổ tiên đều đúng. Memo an toàn
+    // vì thứ tự topo bảo đảm các Question được tham chiếu đã chốt giá trị
+    // trước khi bất kỳ Question nào bên trong Category được đánh giá.
+    const catMemo = new Map();
+    const categoryActive = (id) => {
+        const memoized = catMemo.get(id);
+        if (memoized !== undefined)
+            return memoized;
+        const parent = idx.parent.get(id) ?? null;
+        const cond = idx.condition.get(id);
+        const active = (parent === null || categoryActive(parent)) &&
+            (!cond || evalCondition(cond, effectiveValues, byId));
+        catMemo.set(id, active);
+        return active;
+    };
     const activeIds = new Set();
     for (const id of evaluationOrder) {
         const q = byId.get(id);
-        const active = !q.enable_condition || evalCondition(q.enable_condition, effectiveValues, byId);
+        const cat = idx.categoryOf.get(id);
+        const active = (cat === undefined || categoryActive(cat)) &&
+            (!q.enable_condition ||
+                evalCondition(q.enable_condition, effectiveValues, byId));
         if (active)
             activeIds.add(id);
         else
             delete effectiveValues[q.slug];
     }
-    return { activeIds, effectiveValues };
+    // Category không chứa Question nào chưa được đánh giá trong vòng trên;
+    // giá trị hiệu lực đã chốt nên đánh giá nốt tại đây.
+    const activeCategoryIds = new Set(idx.ordered.filter(categoryActive));
+    return { activeIds, activeCategoryIds, effectiveValues };
 }
 function evalCondition(condition, effective, byId) {
     return condition.any.some((group) => group.all.every((c) => evalSingle(c, effective, byId)));

package/dist/session.d.ts

@@ -2,7 +2,7 @@ import type { VgqClient } from './client.js';
 import type { ActiveState, CompletionResult } from './engine.js';
 import type { FormDefinition, JsonValue, ResponseDto, ResponseValues } from './types.js';
 /** Phần VgqClient mà ResponseSession cần — thu hẹp để test dễ stub. */
-export type SessionClient = Pick<VgqClient, 'getFormVersion' | 'createResponse' | 'startInvitationResponse' | 'getResponse' | 'updateValues' | 'completeResponse'>;
+export type SessionClient = Pick<VgqClient, 'getFormVersion' | 'createResponse' | 'createPreviewResponse' | 'startInvitationResponse' | 'getResponse' | 'updateValues' | 'completeResponse'>;
 export interface SessionOptions {
     /** Thời gian gom thay đổi trước khi đồng bộ lên server (ms). Mặc định 800. */
     debounceMs?: number;
@@ -14,8 +14,13 @@ export interface SessionOptions {
 export interface StartSessionOptions {
     /** Bắt đầu qua Publication key... */
     publicationKey?: string;
-    /** ...hoặc qua Invitation đã được tạo sẵn. */
+    /** ...hoặc qua Invitation đã được tạo sẵn... */
     invitationId?: string;
+    /**
+     * ...hoặc xem thử bản Draft của một Form (chưa phát hành). Server chụp
+     * Draft thành snapshot và thay thế Response preview cũ của Form đó.
+     */
+    previewFormId?: string;
     subjectRef?: string;
     respondentRef?: string;
     careContextRef?: string;

package/dist/session.js

@@ -41,8 +41,15 @@ export class ResponseSession {
                 idempotencyKey: start.idempotencyKey,
             });
         }
+        else if (start.previewFormId) {
+            response = await client.createPreviewResponse(start.previewFormId, {
+                subjectRef: start.subjectRef,
+                respondentRef: start.respondentRef,
+                careContextRef: start.careContextRef,
+            });
+        }
         else {
-            throw new Error('Cần publicationKey hoặc invitationId để bắt đầu Response');
+            throw new Error('Cần publicationKey, invitationId hoặc previewFormId để bắt đầu Response');
         }
         // Định nghĩa lấy theo đúng Form Version mà Response đã ghim, không phải
         // version mới nhất của Publication (Draft không đổi Form giữa chừng).

package/dist/types.d.ts

@@ -54,12 +54,39 @@ export interface BodyMapSpot {
     /** Metadata lâm sàng tuỳ ý; VGQ không diễn giải. */
     metadata?: JsonValue;
 }
+/**
+ * Hướng dẫn bằng audio/video kèm lời dẫn, đặt ở Form, Category hoặc dùng làm
+ * audio phát khi chọn Option. Ứng dụng phát media (nếu có) và/hoặc đọc `text`.
+ */
+export interface Guidance {
+    /** Media Asset dạng audio hoặc video; vắng mặt nghĩa là chỉ có lời dẫn. */
+    media_asset_id?: string;
+    text?: string;
+}
+/** Thang đau VAS: các khoảng điểm liên tiếp kèm mô tả để tự đối chiếu. */
+export interface PainScale {
+    enabled: boolean;
+    ranges: PainRange[];
+}
+export interface PainRange {
+    start: number;
+    end: number;
+    label?: string;
+}
 export interface OptionDef {
     id: string;
     slug: string;
     label: string;
     /** Chỉ có mặt khi Question có data type body_map. */
     body_map?: BodyMapSpot | null;
+    /**
+     * Option cha trong cùng Question, theo id nội bộ. Body Map nhiều tầng: vùng
+     * lớn là Option cha, điểm chi tiết là Option con. Response Value vẫn phẳng.
+     */
+    parent_id?: string | null;
+    /** Audio phát khi Respondent chọn Option. */
+    audio?: Guidance | null;
+    pain_scale?: PainScale | null;
 }
 export interface MediaAssetDto {
     id: string;
@@ -88,11 +115,21 @@ export interface CategoryDef {
     label: string;
     children?: CategoryDef[];
     questions: QuestionDef[];
+    /** Hướng dẫn mở đầu cho riêng Category này. */
+    guidance?: Guidance | null;
+    /**
+     * Điều kiện hiện cả Category (ví dụ tab bệnh hiện theo lý do đến khám).
+     * Category tắt thì mọi Question bên trong — kể cả trong Category con —
+     * tắt theo và giá trị của chúng bị loại khỏi official values.
+     */
+    enable_condition?: EnableCondition | null;
 }
 export interface FormDefinition {
     title: string;
     form_type: FormType;
     categories: CategoryDef[];
+    /** Hướng dẫn mở đầu cho cả Form. */
+    guidance?: Guidance | null;
 }
 export interface ValidationIssue {
     path: string;
@@ -114,6 +151,8 @@ export interface ResponseDto {
     updated_at: string;
     completed_at: string | null;
     completed_by: string | null;
+    /** Response xem thử từ trang demo cổng bệnh nhân (server < 0.3.0 không trả). */
+    is_preview?: boolean;
 }
 export interface PublicationForm {
     publication_key: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viengut/vgq-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Headless TypeScript SDK for the VGQ clinical form platform: load published Forms, manage Response state, evaluate Enable Conditions and validate Response Values without any UI components.",
   "repository": {
     "type": "git",