@rytass/bpm-core-nestjs-module 0.20.0 → 0.21.0

package/src/lib/workflow-engine/workflow-engine.service.js

@@ -18,6 +18,7 @@ const form_definition_version_entity_1 = require("../form/form-definition-versio
 const form_enums_1 = require("../form/form.enums");
 const form_data_source_errors_1 = require("../form-data-source/form-data-source.errors");
 const form_member_value_validator_1 = require("../form/form-member-value.validator");
+const form_data_issue_1 = require("../form/form-data-issue");
 const form_org_unit_value_validator_1 = require("../form/form-org-unit-value.validator");
 const form_data_source_types_1 = require("../form-data-source/form-data-source.types");
 const sla_schedule_service_1 = require("../calendar/sla-schedule.service");
@@ -39,6 +40,8 @@ const activity_log_entity_1 = require("./activity-log.entity");
 const adhoc_directive_entity_1 = require("./adhoc-directive.entity");
 const adhoc_enums_1 = require("./adhoc.enums");
 const approval_instance_entity_1 = require("./approval-instance.entity");
+const approval_instance_field_filter_compiler_1 = require("./approval-instance-field-filter.compiler");
+const approval_instance_filterable_field_policy_1 = require("./approval-instance-filterable-field.policy");
 const text_field_pattern_test_1 = require("./text-field-pattern-test");
 const form_data_fingerprint_1 = require("./form-data-fingerprint");
 const instance_submitter_1 = require("./instance-submitter");
@@ -47,6 +50,7 @@ const task_candidate_entity_1 = require("./task-candidate.entity");
 const task_entity_1 = require("./task.entity");
 const workflow_engine_enums_1 = require("./workflow-engine.enums");
 const workflow_condition_evaluator_1 = require("./workflow-condition-evaluator");
+const workflow_form_value_1 = require("./workflow-form-value");
 const workflow_dry_run_object_1 = require("./workflow-dry-run.object");
 const time_budget_1 = require("./time-budget");
 const expression_budget_1 = require("../condition/expression-budget");
@@ -194,6 +198,8 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         this.formDataSourceValueResolver = formDataSourceValueResolver;
         this.webhookDeliveryService = webhookDeliveryService;
         this.logger = new common_1.Logger(WorkflowEngineService_1.name);
+        this.approvalInstanceFieldFilterCompiler = new approval_instance_field_filter_compiler_1.ApprovalInstanceFieldFilterCompiler();
+        this.approvalInstanceFilterableFieldPolicy = new approval_instance_filterable_field_policy_1.ApprovalInstanceFilterableFieldPolicy();
         /** Webhooks each open engine transaction will send once it has committed. */
         this.deferredWebhookDispatches = new WeakMap();
         // A binding under the token wins: that is either the host's own provider
@@ -307,6 +313,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         validateSubmittedFormData(formDefinitionVersion.schema, formData, {
             deferredFieldKeys,
         });
+        // Checked against the bound version's schema before any data source is
+        // called, so a bad value is refused cheaply. The transaction below
+        // confirms under the template lock that this version is still current
+        // (ADR 25 §15), which is what makes this schema the one in force.
+        assertFilterableFormDataValues(formDefinitionVersion.schema, formData);
         const formDataOptionSnapshot = await this.resolveFormDataOptionSnapshots({
             authContext: authContext ?? createWorkflowAuthContext(input.initiatorMemberId),
             formData,
@@ -333,6 +344,26 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             throw new common_1.BadRequestException('Published workflow does not include a startEvent');
         }
         return this.runEngineTransaction(async (manager) => {
+            // ADR 25 §6 and §15: take FOR SHARE on the template row, so a publish,
+            // deactivation or edit cannot commit between this point and the
+            // insert, then re-check under the lock what was read before it. The
+            // filterable check above used the version read then; it holds only
+            // while that version is still the current one.
+            const lockedTemplate = await manager
+                .getRepository(approval_template_entity_1.ApprovalTemplateEntity)
+                .findOne({
+                lock: { mode: 'pessimistic_read' },
+                where: { deletedAt: (0, typeorm_2.IsNull)(), id: template.id },
+            });
+            if (!lockedTemplate) {
+                throw new common_1.NotFoundException(`Approval template ${template.id} was not found`);
+            }
+            if (!lockedTemplate.isActive) {
+                throw new common_1.ConflictException('Approval template is deactivated');
+            }
+            if (lockedTemplate.currentVersionId !== templateVersion.id) {
+                throw new common_1.ConflictException('範本在送出期間發布了新版本，這次申請沒有送出；請重新整理頁面後再送出');
+            }
             const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
             const tokenRepository = manager.getRepository(workflow_token_entity_1.WorkflowTokenEntity);
             const activityRepository = manager.getRepository(activity_log_entity_1.ActivityLogEntity);
@@ -459,6 +490,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             ? (0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferredFieldKeys)
             : submittedFormData;
         validateSubmittedFormData(schema, formData, { deferredFieldKeys });
+        await this.assertCurrentFilterableFormDataValues(instance.templateId, formData);
         const formDataOptionSnapshot = await this.resolveFormDataOptionSnapshots({
             authContext,
             formData,
@@ -672,6 +704,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 }
             }
             if (filledFormData !== null && changedFieldKeys.length > 0) {
+                await this.assertCurrentFilterableFormDataValues(instance.templateId, mergedFormData, manager);
                 // Merged into the shared `instance` before it is signed and before
                 // the token moves on: the signature must cover the filled values, a
                 // gateway after this node must route on them, and an end node saves
@@ -993,6 +1026,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             validateSubmittedFormData(resubmitSchema, formData, {
                 deferredFieldKeys,
             });
+            await this.assertCurrentFilterableFormDataValues(instance.templateId, formData, manager);
             if (!preparation) {
                 assertNoUnresolvableDynamicValues(resubmitSchema, formData);
             }
@@ -1950,14 +1984,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         };
     }
     evaluateDryRunEdge(input, edge, lastDecision) {
-        const expression = edge.data.condition?.trim();
-        if (expression && !isListValuedStructuredCondition(edge, input.formData)) {
-            return this.conditionService.evaluateBoolean(expression, buildDryRunExpressionContext(input, lastDecision), `workflow.edges.${edge.id}.data.condition`, {
-                allowedRootIdentifiers: DRY_RUN_EDGE_ROOT_IDENTIFIERS,
-                dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(input.workflowDefinition),
-            });
+        const expression = readEvaluableEdgeExpression(edge, input.formData);
+        if (!expression) {
+            return (0, workflow_condition_evaluator_1.evaluateWorkflowEdgeCondition)(edge, { formData: input.formData });
         }
-        return (0, workflow_condition_evaluator_1.evaluateWorkflowEdgeCondition)(edge, { formData: input.formData });
+        return evaluateWithStructuredFallback(edge, input.formData, (message) => this.logger.warn(`dry-run ${message}`), () => this.conditionService.evaluateBoolean(expression, buildDryRunExpressionContext(input, lastDecision), `workflow.edges.${edge.id}.data.condition`, {
+            allowedRootIdentifiers: DRY_RUN_EDGE_ROOT_IDENTIFIERS,
+            dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(input.workflowDefinition),
+        }));
     }
     /**
      * The dry-run assignee of a user task. Only resolvers whose dry run yields
@@ -2084,22 +2118,76 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         return instance;
     }
+    /**
+     * ADR 25 §6: a value written to a filterable field must fit its type, on
+     * every path that writes form data. The fields checked are the ones the
+     * template's *current* version marks filterable, not the instance's own
+     * snapshot: an older instance can be re-filled, resubmitted or written by a
+     * service task after a newer version enabled filtering on a field, and the
+     * enable check (ADR 25 §5.4) guarantees the type is the same in every version
+     * that holds instances, so the current definition judges the old value too.
+     */
+    async assertCurrentFilterableFormDataValues(templateId, formData, manager, serviceNodeLabel) {
+        const schema = await this.readCurrentFormSchema(templateId, manager);
+        assertFilterableFormDataValues(schema, formData, serviceNodeLabel);
+    }
+    /** The form schema of the template's current version, or `null` when there is none. */
+    async readCurrentFormSchema(templateId, manager) {
+        // Inside a write transaction the template row is taken FOR SHARE (ADR 25
+        // §15): a publish, compose or rollback needs FOR UPDATE on the same row, so
+        // the current version read here cannot change before the write commits.
+        const template = manager
+            ? await manager.getRepository(approval_template_entity_1.ApprovalTemplateEntity).findOne({
+                lock: { mode: 'pessimistic_read' },
+                where: { id: templateId },
+            })
+            : await this.approvalTemplateRepository.findOne({
+                where: { id: templateId },
+            });
+        if (!template?.currentVersionId) {
+            return null;
+        }
+        const versions = manager
+            ? manager.getRepository(approval_template_version_entity_1.ApprovalTemplateVersionEntity)
+            : this.approvalTemplateVersionRepository;
+        const version = await versions.findOne({
+            where: { id: template.currentVersionId },
+        });
+        if (!version?.formDefinitionVersionId) {
+            return null;
+        }
+        const formVersions = manager
+            ? manager.getRepository(form_definition_version_entity_1.FormDefinitionVersionEntity)
+            : this.formDefinitionVersionRepository;
+        const formVersion = await formVersions.findOne({
+            where: { id: version.formDefinitionVersionId },
+        });
+        return formVersion?.schema ?? null;
+    }
     async listApprovalInstances(scope, options = {}) {
-        const queryBuilder = await this.createFilteredApprovalInstanceQueryBuilder(scope, options);
-        if (!queryBuilder) {
+        const query = await this.createFilteredApprovalInstanceQuery(scope, options);
+        if (!query) {
             return [];
         }
-        queryBuilder.orderBy('"approvalInstance"."created_at"', 'DESC');
+        const { orderBy, queryBuilder } = query;
+        orderBy.forEach((order, index) => {
+            if (index === 0) {
+                queryBuilder.orderBy(order.sql, order.direction);
+            }
+            else {
+                queryBuilder.addOrderBy(order.sql, order.direction);
+            }
+        });
         if (shouldPaginateList(options)) {
             queryBuilder
-                .skip(readPageOffset(options.page, options.pageSize))
-                .take(normalizePageSize(options.pageSize));
+                .offset(readPageOffset(options.page, options.pageSize))
+                .limit(normalizePageSize(options.pageSize));
         }
         return queryBuilder.getMany();
     }
     async countApprovalInstances(scope, options = {}) {
-        const queryBuilder = await this.createFilteredApprovalInstanceQueryBuilder(scope, options);
-        return queryBuilder ? queryBuilder.getCount() : 0;
+        const query = await this.createFilteredApprovalInstanceQuery(scope, options);
+        return query ? query.queryBuilder.getCount() : 0;
     }
     async readApprovalInstancePageInfo(scope, options = {}) {
         const totalCount = await this.countApprovalInstances(scope, options);
@@ -2115,7 +2203,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             totalPages,
         };
     }
-    async createFilteredApprovalInstanceQueryBuilder(scope, options = {}) {
+    async createFilteredApprovalInstanceQuery(scope, options = {}) {
         const queryBuilder = this.approvalInstanceRepository.createQueryBuilder('approvalInstance');
         const hasReadableInstances = this.applyReadableInstanceFilter(queryBuilder, scope, options);
         if (!hasReadableInstances) {
@@ -2133,7 +2221,72 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             });
         }
         applyApprovalInstanceSearchFilter(queryBuilder, options.searchText);
-        return queryBuilder;
+        const compiled = await this.compileApprovalInstanceFieldQuery(scope, templateId, options);
+        compiled.conditions.forEach((condition) => {
+            queryBuilder.andWhere(condition.sql, condition.parameters);
+        });
+        queryBuilder.setParameters(compiled.orderBy.reduce((all, order) => ({ ...all, ...order.parameters }), {}));
+        return { orderBy: compiled.orderBy, queryBuilder };
+    }
+    /**
+     * The WHERE conditions and sort keys of the field filters and sort on the
+     * approval-instance list (ADR 25 §7). The template's current schema is read,
+     * and the static option lists of every version holding instances, only when
+     * a condition or a non-time sort key needs them.
+     */
+    async compileApprovalInstanceFieldQuery(scope, templateId, options) {
+        const fieldFilters = options.fieldFilters ?? [];
+        const sort = options.sort ?? [];
+        const needsSchema = fieldFilters.length > 0 ||
+            sort.some((item) => !(0, bpm_core_shared_1.isApprovalInstanceSortTimeField)(item.field));
+        if (needsSchema && !templateId) {
+            throw new common_1.BadRequestException('篩選或排序表單欄位時需要指定簽核範本');
+        }
+        const schema = needsSchema && templateId
+            ? await this.readCurrentFormSchema(templateId)
+            : null;
+        // Only a name search (CONTAINS) reads option names; other conditions and
+        // sort keys need the current schema alone.
+        const needsOptionNames = fieldFilters.some((filter) => filter.operator === 'CONTAINS');
+        const staticOptionsByPath = needsOptionNames && templateId
+            ? await this.readStaticOptionsByPathForTemplate(templateId, schema)
+            : (0, approval_instance_field_filter_compiler_1.readStaticOptionsByPath)([]);
+        return this.approvalInstanceFieldFilterCompiler.compile({
+            alias: 'approvalInstance',
+            fieldFilters,
+            paths: this.approvalInstanceFilterableFieldPolicy.readFilterableFieldPaths(scope, schema),
+            sort,
+            staticOptionsByPath,
+        });
+    }
+    /**
+     * Static option lists by field path, across the current schema and the form
+     * version of every template version that holds instances (ADR 25 §7.3): a
+     * CONTAINS on a retired option still matches its name.
+     */
+    async readStaticOptionsByPathForTemplate(templateId, currentSchema) {
+        const held = await this.approvalInstanceRepository
+            .createQueryBuilder('approvalInstance')
+            .select('DISTINCT "approvalInstance"."template_version_id"', 'id')
+            .where('"approvalInstance"."template_id" = :templateId', { templateId })
+            .getRawMany();
+        const templateVersions = held.length === 0
+            ? []
+            : await this.approvalTemplateVersionRepository.find({
+                where: { id: (0, typeorm_2.In)(held.map((row) => row.id)) },
+            });
+        const formVersionIds = templateVersions
+            .map((version) => version.formDefinitionVersionId)
+            .filter((id) => id !== null);
+        const formVersions = formVersionIds.length === 0
+            ? []
+            : await this.formDefinitionVersionRepository.find({
+                where: { id: (0, typeorm_2.In)(formVersionIds) },
+            });
+        return (0, approval_instance_field_filter_compiler_1.readStaticOptionsByPath)([
+            currentSchema,
+            ...formVersions.map((version) => version.schema),
+        ]);
     }
     applyReadableInstanceFilter(queryBuilder, scope, options) {
         if (!scope) {
@@ -2802,15 +2955,17 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         throw new common_1.ConflictException(`Workflow node ${node.id} has no matching outgoing edge`);
     }
     async evaluateWorkflowEdge(manager, instance, node, edge) {
-        const expression = edge.data.condition?.trim();
-        if (expression &&
-            !isListValuedStructuredCondition(edge, instance.formData)) {
-            return this.conditionService.evaluateBoolean(expression, {
-                ...buildWorkflowExpressionContext(instance),
-                lastDecision: await this.readLastDecisionContext(manager, instance.id, node.id),
-            }, `workflow.edges.${edge.id}.data.condition`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) });
+        const expression = readEvaluableEdgeExpression(edge, instance.formData);
+        if (!expression) {
+            return (0, workflow_condition_evaluator_1.evaluateWorkflowEdgeCondition)(edge, {
+                formData: instance.formData,
+            });
         }
-        return (0, workflow_condition_evaluator_1.evaluateWorkflowEdgeCondition)(edge, { formData: instance.formData });
+        const context = {
+            ...buildWorkflowExpressionContext(instance),
+            lastDecision: await this.readLastDecisionContext(manager, instance.id, node.id),
+        };
+        return evaluateWithStructuredFallback(edge, instance.formData, (message) => this.logger.warn(`instance=${instance.id} ${message}`), () => this.conditionService.evaluateBoolean(expression, context, `workflow.edges.${edge.id}.data.condition`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }));
     }
     async readLastDecisionContext(manager, instanceId, nodeId) {
         const tasks = await manager.getRepository(task_entity_1.TaskEntity).find({
@@ -4646,6 +4801,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             const value = this.conditionService.evaluateValue(action.value, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.action.value`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) });
             assertServiceTaskTextValue(instance.formDefinitionSnapshot, action.fieldPath, value, node.data.label);
             const updatedFormData = writeValueAtPath(instance.formData, action.fieldPath, value);
+            await this.assertCurrentFilterableFormDataValues(instance.templateId, updatedFormData, manager, node.data.label);
             // A service task runs inside this transaction, so it cannot call a host
             // provider to re-resolve the label. Rather than leave the previous
             // option snapshot describing a value that no longer exists, drop it: the
@@ -5104,6 +5260,52 @@ function readDataSourceFieldKeyAtPath(snapshot, fieldPath) {
     const field = schema.fields.find((candidate) => isRecord(candidate) && candidate.fieldKey === fieldKey);
     return field && (0, form_1.isFormDataSourceFieldDefinition)(field) ? field.fieldKey : null;
 }
+/**
+ * Refuses form data whose filterable fields hold a value of the wrong type
+ * (ADR 25 §6). The list query reads these values with type guards, so a wrong
+ * value would silently fall out of every filter; refusing the write is what
+ * keeps filter results trustworthy.
+ */
+function assertFilterableFormDataValues(schema, formData, serviceNodeLabel) {
+    const problems = (0, bpm_core_shared_1.readFilterableValueProblems)((0, bpm_core_shared_1.readFilterableFieldPaths)(schema), formData);
+    if (problems.length === 0) {
+        return;
+    }
+    const issues = problems.map((problem) => (0, form_data_issue_1.createFormDataIssue)(readFilterableProblemLocation(schema, problem), 'TYPE', `必須是${problem.expected}`));
+    const details = (0, form_data_issue_1.readFormDataIssueMessage)(issues);
+    throw (0, form_data_issue_1.createFormDataBadRequest)(serviceNodeLabel
+        ? `系統節點「${serviceNodeLabel}」要寫入的表單值不符合可篩選欄位的型別（${details}），這次操作沒有生效；請聯絡流程管理者修正此節點的寫入值`
+        : `可篩選欄位的值型別不正確：${details}`, issues);
+}
+/** Where a filterable problem sits: a field, a table row, or one cell of a row. */
+function readFilterableProblemLocation(schema, problem) {
+    const [tableKey, columnKey] = problem.path.split('.');
+    const table = schema?.fields.find((field) => field.fieldKey === tableKey && (0, form_1.isTableFieldDefinition)(field));
+    const column = table && (0, form_1.isTableFieldDefinition)(table) && columnKey !== undefined
+        ? table.columns.find((candidate) => candidate.fieldKey === columnKey)
+        : undefined;
+    if (table && (0, form_1.isTableFieldDefinition)(table)) {
+        if (problem.rowIndex === null) {
+            return (0, form_data_issue_1.readFieldIssueLocation)(table);
+        }
+        const rowLocation = (0, form_data_issue_1.readRowIssueLocation)(table, problem.rowIndex);
+        return column ? (0, form_data_issue_1.readCellIssueLocation)(rowLocation, column) : rowLocation;
+    }
+    const field = schema?.fields.find((candidate) => candidate.fieldKey === problem.path);
+    if (field) {
+        return (0, form_data_issue_1.readFieldIssueLocation)(field);
+    }
+    // Not in the schema (the check and this lookup read the same schema, so
+    // this is defensive): still address it the way FormDataIssue.path promises,
+    // `table[i].col` for a row value rather than the dotted filter path.
+    const row = `${tableKey}[${problem.rowIndex}]`;
+    const path = problem.rowIndex === null
+        ? problem.path
+        : columnKey === undefined
+            ? row
+            : `${row}.${columnKey}`;
+    return { path, ref: `欄位「${path}」` };
+}
 /**
  * Holds a `SET_FORM_FIELD` write to the length and format rules the form
  * applies to a filler, so a service task cannot store text the field would
@@ -5129,8 +5331,8 @@ function assertServiceTaskTextValue(snapshot, fieldPath, value, nodeLabel) {
     if (!field || errors.length === 0) {
         return;
     }
-    throw new common_1.BadRequestException(`系統節點「${nodeLabel}」要寫入欄位「${field.label || field.fieldKey}」的值不符合該欄位的規則` +
-        `（${errors.join('; ')}），這次操作沒有生效；請聯絡流程管理者修正此節點的寫入值`);
+    throw new common_1.BadRequestException(`系統節點「${nodeLabel}」要寫入的值不符合欄位規則（${(0, form_data_issue_1.readFormDataIssueMessage)(errors)}），` +
+        `這次操作沒有生效；請聯絡流程管理者修正此節點的寫入值`);
 }
 function readSnapshotWithoutField(snapshots, fieldKey) {
     return Object.fromEntries(Object.entries(snapshots ?? {}).filter(([key]) => key !== fieldKey));
@@ -5445,22 +5647,67 @@ function readNodeEntryCondition(node) {
     return null;
 }
 /**
- * A designer-built condition on a multiple-selection field (checkbox, or a
- * select / autocomplete in `multiple` mode), whose submitted value is a list.
- * Definitions saved before the designer compiled such fields with list
- * semantics carry a single-value CEL (`form.tags == "A"`), which is false for
- * `["A"]` — `!=` is always true and `!= ""` counts `[]` as filled — so those
- * edges never routed as designed. The structured fields the designer stores
- * beside the CEL are evaluated instead: `evaluateWorkflowEdgeCondition`
- * already reads a list as contains / does not contain and an empty list as
- * empty, the meaning the current designer compiles too. A hand-written CEL
- * carries no structured fields and is never overridden.
+ * The stored CEL an edge is evaluated by, or `null` when its structured fields
+ * answer directly: no CEL, or a designer-built edge whose value is a list
+ * (`evaluateWorkflowEdgeCondition` reads a list as contains / does not contain
+ * and an empty list as empty, which the stored CEL of older definitions did
+ * not).
  */
-function isListValuedStructuredCondition(edge, formData) {
+function readEvaluableEdgeExpression(edge, formData) {
+    const expression = edge.data.condition?.trim();
     const fieldKey = edge.data.conditionFieldKey;
-    return Boolean(fieldKey &&
+    const listValued = Boolean(fieldKey &&
         edge.data.conditionOperator &&
-        Array.isArray(formData[fieldKey]));
+        Array.isArray((0, workflow_form_value_1.readOwnFormValue)(formData, fieldKey)));
+    return expression && !listValued ? expression : null;
+}
+/**
+ * Evaluates an edge's stored CEL and, only when it fails because the edge's
+ * own field is unfilled, answers from the structured fields instead. The one
+ * place both the actual run and the designer dry run decide that, so the two
+ * cannot drift apart.
+ *
+ * Published definitions and in-flight instances keep the CEL they were
+ * stored with, and that CEL throws for an optional field left untouched: the
+ * key is absent (`Identifier "agent" not found`), or an ordered comparison
+ * meets `null` or `""` (`null > 5`, `"" > 5`). Only then does the structured
+ * evaluator answer, reading the value as unfilled (`EQUALS` and the ordered
+ * comparisons false, `NOT_EQUALS` and `IS_EMPTY` true, `IS_FILLED` false).
+ *
+ * - `EXPRESSION_MISSING_KEY` falls back only when the missing key *is* the
+ *   edge's field. A CEL edited by hand to also read another key
+ *   (`form.agent != null && initiator.department == "X"`) fails as written
+ *   when that other key is missing, even if the edge's field is unfilled.
+ * - `EXPRESSION_TYPE_ERROR` carries no key, so it falls back whenever the
+ *   edge's field is unfilled, and each such fallback is logged (`warn`, no
+ *   values) so an unrelated type error answered this way stays traceable.
+ * - Everything else is rethrown: a stored CEL that evaluates keeps its
+ *   result, so no route that worked before changes; an error while the
+ *   edge's field is filled points at the CEL itself; a hand-written CEL has
+ *   no structured fields; a budget overrun or a function failure is never
+ *   absorbed.
+ */
+function evaluateWithStructuredFallback(edge, formData, warn, evaluate) {
+    try {
+        return evaluate();
+    }
+    catch (error) {
+        const fieldKey = edge.data.conditionFieldKey;
+        if (!fieldKey ||
+            !edge.data.conditionOperator ||
+            !(error instanceof expression_errors_1.ExpressionRuntimeError) ||
+            !(0, workflow_form_value_1.isEmptyWorkflowValue)((0, workflow_form_value_1.readOwnFormValue)(formData, fieldKey))) {
+            throw error;
+        }
+        if (error.code === 'EXPRESSION_MISSING_KEY' && error.keyName === fieldKey) {
+            return (0, workflow_condition_evaluator_1.evaluateWorkflowEdgeCondition)(edge, { formData });
+        }
+        if (error.code === 'EXPRESSION_TYPE_ERROR') {
+            warn(`code=EDGE_STRUCTURED_FALLBACK edge=${edge.id} field=${fieldKey} reason=EXPRESSION_TYPE_ERROR`);
+            return (0, workflow_condition_evaluator_1.evaluateWorkflowEdgeCondition)(edge, { formData });
+        }
+        throw error;
+    }
 }
 function edgeHasCondition(edge) {
     return Boolean(edge.data.condition?.trim() ||
@@ -6160,29 +6407,28 @@ function validateFilledFormFields(schema, formData, fieldKeys, requiredFieldKeys
  * field wins over a text value breaking its length or format rule, which wins
  * over a malformed member value, which wins over a malformed org unit value,
  * which wins over a table problem, and the later checks are only evaluated
- * when the earlier ones pass.
+ * when the earlier ones pass. The refusal carries every issue of the winning
+ * check. Its message is those issues' sentences joined, except for missing
+ * required fields, which keep the one-line summary `缺少必填欄位：A, B` that
+ * submitters read; each issue there still says `欄位「A」為必填`. A client
+ * that places errors on fields reads the issues, not the message.
  */
 function throwFirstFormDataFieldError({ missingFields, readMemberErrors, readOrgUnitErrors, readTableErrors, readTextErrors, }) {
     if (missingFields.length > 0) {
-        throw new common_1.BadRequestException(`Form data is missing required fields: ${missingFields
+        throw (0, form_data_issue_1.createFormDataBadRequest)(`缺少必填欄位：${missingFields
             .map((field) => field.label || field.fieldKey)
-            .join(', ')}`);
-    }
-    const textErrors = readTextErrors();
-    if (textErrors.length > 0) {
-        throw new common_1.BadRequestException(textErrors.join('; '));
-    }
-    const memberErrors = readMemberErrors();
-    if (memberErrors.length > 0) {
-        throw new common_1.BadRequestException(memberErrors.join('; '));
+            .join(', ')}`, missingFields.map((field) => (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readFieldIssueLocation)(field), 'REQUIRED', '為必填')));
     }
-    const orgUnitErrors = readOrgUnitErrors();
-    if (orgUnitErrors.length > 0) {
-        throw new common_1.BadRequestException(orgUnitErrors.join('; '));
-    }
-    const tableErrors = readTableErrors();
-    if (tableErrors.length > 0) {
-        throw new common_1.BadRequestException(tableErrors.join('; '));
+    // Each check runs only when every earlier one passed, so a later check's
+    // work is never done for a request that is already refused.
+    const winning = [
+        readTextErrors,
+        readMemberErrors,
+        readOrgUnitErrors,
+        readTableErrors,
+    ].reduce((found, check) => (found.length > 0 ? found : check()), []);
+    if (winning.length > 0) {
+        throw (0, form_data_issue_1.createFormDataBadRequest)((0, form_data_issue_1.readFormDataIssueMessage)(winning), winning);
     }
 }
 /**
@@ -6191,64 +6437,73 @@ function throwFirstFormDataFieldError({ missingFields, readMemberErrors, readOrg
  * the flat text fields share. `minimum` / `maximum` stay a frontend hint.
  */
 function validateSubmittedTableValue(field, value, required, testPattern, shapeOnly = false) {
-    const path = `formData.${field.fieldKey}`;
+    const location = (0, form_data_issue_1.readFieldIssueLocation)(field);
     if (typeof value === 'undefined' || value === null) {
-        return shapeOnly
-            ? []
-            : required || readTableMinRows(field) > 0
-                ? [`${path} must include at least ${readTableRequiredRowCount(field)} row(s)`]
-                : [];
+        if (shapeOnly) {
+            return [];
+        }
+        if (required || readTableMinRows(field) > 0) {
+            const rows = readTableRequiredRowCount(field);
+            return [
+                (0, form_data_issue_1.createFormDataIssue)(location, 'MIN_ROWS', `至少需要 ${rows} 列`, rows),
+            ];
+        }
+        return [];
     }
     if (!Array.isArray(value)) {
-        return [`${path} must be an array of rows`];
+        return [(0, form_data_issue_1.createFormDataIssue)(location, 'TYPE', '必須是表格列的清單')];
     }
     // Too many rows is refused before any row is checked: the rows a submitter
     // sends would otherwise decide how many cells the text patterns run on.
     const maxRows = readTableMaxRows(field);
     if (value.length > maxRows) {
-        return [`${path} must include at most ${maxRows} row(s)`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MAX_ROWS', `最多 ${maxRows} 列`, maxRows),
+        ];
     }
-    const rowErrors = value.flatMap((row, index) => validateSubmittedTableRow(field, row, `${path}[${index}]`, testPattern, shapeOnly));
+    const rowErrors = value.flatMap((row, index) => validateSubmittedTableRow(field, row, (0, form_data_issue_1.readRowIssueLocation)(field, index), testPattern, shapeOnly));
     // A malformed row cannot be counted against the minimum meaningfully; report
     // the shape problem first so the submitter fixes the real cause.
     if (rowErrors.length > 0) {
         return rowErrors;
     }
-    return validateSubmittedTableRowCount(field, value.length, required, path, shapeOnly);
+    return validateSubmittedTableRowCount(field, value.length, required, location, shapeOnly);
 }
 /** The minimum only: the maximum is refused before any row is checked. */
-function validateSubmittedTableRowCount(field, rowCount, required, path, shapeOnly = false) {
+function validateSubmittedTableRowCount(field, rowCount, required, location, shapeOnly = false) {
     const minRows = shapeOnly
         ? 0
         : required
             ? Math.max(readTableMinRows(field), 1)
             : readTableMinRows(field);
     return rowCount < minRows
-        ? [`${path} must include at least ${minRows} row(s)`]
+        ? [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MIN_ROWS', `至少需要 ${minRows} 列`, minRows),
+        ]
         : [];
 }
-function validateSubmittedTableRow(field, row, path, testPattern, shapeOnly = false) {
+function validateSubmittedTableRow(field, row, location, testPattern, shapeOnly = false) {
     if (!isRecord(row)) {
-        return [`${path} must be an object`];
+        return [(0, form_data_issue_1.createFormDataIssue)(location, 'TYPE', '必須是物件')];
     }
     const columnsByKey = new Map(field.columns.map((column) => [column.fieldKey, column]));
     const unknownKeyErrors = Object.keys(row)
         .filter((columnKey) => !columnsByKey.has(columnKey))
-        .map((columnKey) => `${path}.${columnKey} is not a table column`);
+        .map((columnKey) => (0, form_data_issue_1.createFormDataIssue)(location, 'UNKNOWN_COLUMN', `含有不屬於此表格的欄位「${columnKey}」`));
     const cellErrors = Object.entries(row)
         .filter(([columnKey, cellValue]) => columnsByKey.has(columnKey) && !(0, form_1.isFormTableCellValue)(cellValue))
-        .map(([columnKey]) => `${path}.${columnKey} is not a valid cell value`);
+        .map(([columnKey]) => (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readCellIssueLocation)(location, columnsByKey.get(columnKey) ?? { fieldKey: columnKey }), 'TYPE', '不是有效的值'));
     const requiredErrors = shapeOnly
         ? []
         : field.columns
             .filter((column) => isSubmittedTableColumnRequired(column) &&
             !isSubmittedFieldValuePresent(readRowCellValue(row, column.fieldKey)))
-            .map((column) => `${path}.${column.fieldKey} is required`);
+            .map((column) => (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readCellIssueLocation)(location, column), 'REQUIRED', '為必填'));
     // A shape-only pass covers a table nobody fills in, so the filler-facing
     // rules do not apply to it, the same as the required check above; only a
     // cell of the wrong type is still refused.
     const textErrors = field.columns.flatMap((column) => readSubmittedTextValueErrors(column, readRowCellValue(row, column.fieldKey), {
-        path: `${path}.${column.fieldKey}`,
+        location: (0, form_data_issue_1.readCellIssueLocation)(location, column),
         shapeOnly,
         testPattern,
     }));
@@ -6265,7 +6520,7 @@ function validateSubmittedTableRow(field, row, path, testPattern, shapeOnly = fa
  * budget is spent, a value is reported as not checked rather than as a
  * format error.
  */
-function readSubmittedTextValueErrors(field, value, { path = `formData.${field.fieldKey}`, shapeOnly = false, testPattern, }) {
+function readSubmittedTextValueErrors(field, value, { location = (0, form_data_issue_1.readFieldIssueLocation)(field), shapeOnly = false, testPattern, }) {
     if (field.type !== 'text' && field.type !== 'textarea') {
         return [];
     }
@@ -6284,21 +6539,27 @@ function readSubmittedTextValueErrors(field, value, { path = `formData.${field.f
     };
     const issue = readIssue();
     if (issue === 'timeout') {
-        return [`${path} could not be checked against the required format in time`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'PATTERN_TIMEOUT', '無法在時限內完成格式檢查'),
+        ];
     }
     if (!issue || (shapeOnly && issue.kind !== 'type')) {
         return [];
     }
     if (issue.kind === 'type') {
-        return [`${path} must be text`];
+        return [(0, form_data_issue_1.createFormDataIssue)(location, 'TYPE', '必須是文字')];
     }
     if (issue.kind === 'minLength') {
-        return [`${path} must be at least ${issue.limit} characters`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MIN_LENGTH', `至少需要 ${issue.limit} 個字`, issue.limit),
+        ];
     }
     if (issue.kind === 'maxLength') {
-        return [`${path} must be at most ${issue.limit} characters`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MAX_LENGTH', `最多 ${issue.limit} 個字`, issue.limit),
+        ];
     }
-    return [`${path} does not match the required format`];
+    return [(0, form_data_issue_1.createFormDataIssue)(location, 'PATTERN', '格式不正確')];
 }
 /**
  * Own-property read. `constructor`, `toString` and friends all satisfy the