@voplus/morpho-csp 11.2.8 → 11.3.0-dev.0

package/es/modules/corporate/legal-generation/form/legalGenerationSubmit.js

@@ -0,0 +1,840 @@
+import { ApiError, RequestBuilder } from "@voplus/api";
+import { CAPTURED_FIELD_LABEL } from "@voplus/morpho-compliance/es/data/identityShape/constants";
+import { utcdayjs } from "@voplus/morpho-ui/es/controls/UTCDatePicker/state";
+import { message } from "antd";
+// spec:3850 — CSP: 法律文书生成表单提交时把组合后的载荷送交转换
+/** The route a legal-generation form's composed payload is posted to (spec:3850). */
+export const LEGAL_GENERATION_SUBMIT_ROUTE = "/api/document-assistants/legal-generation/submit";
+/** The existing gallery templates support exactly these appointment positions. */
+export const SUPPORTED_OFFICER_POSITIONS = ["Director", "Secretary"];
+/** Reports whether an input position is supported by the existing gallery templates. */
+export function isSupportedOfficerPosition(position) {
+    return SUPPORTED_OFFICER_POSITIONS.includes(position);
+}
+/** 检查服务端副本的显示类型，允许 legacy 缺项与明确空值。 */
+function readParentCompanyDetails(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const data = value;
+    for (const key of ["name", "address", "email", "phone"])
+        if (data[key] != null && typeof data[key] !== "string")
+            return undefined;
+    if (data.identity != null && (typeof data.identity !== "object" || Array.isArray(data.identity)))
+        return undefined;
+    const identity = data.identity;
+    if (identity?.number != null && typeof identity.number !== "string")
+        return undefined;
+    return { name: data.name, address: data.address,
+        email: data.email, phone: data.phone,
+        number: identity?.number };
+}
+/** The CLDA meta key every legal-generation submission persists under (contract §1). */
+export const LEGAL_GENERATION_META_KEY = "CHO";
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * The frozen snapshot of `shape` as the payload carries it (spec:3848): a copy of the members a
+ * snapshot owns, taken from the capture's own shape and never resolved against the shared catalog.
+ *
+ * @param shape the capture's frozen shape.
+ * @returns the snapshot the submit body and the form-content JSON column carry.
+ */
+export function toIdentityShapeSnapshot(shape) {
+    return {
+        sourceNumber: shape.source,
+        name: shape.name,
+        family: shape.family,
+        subject: shape.subject,
+        aliasPolicy: shape.policies.alias,
+        issuingCountryPolicy: shape.policies.issuingCountry,
+        expiryPolicy: shape.policies.expiryDate,
+    };
+}
+/**
+ * The identity values of one manual branch. The captured alias / issuing country / expiry date
+ * travel only where the captured shape's policy does not omit them (spec:3713), so a field the
+ * shape hides can never reach the payload even if its control once held a value.
+ */
+function toSubmitIdentity(branch, name) {
+    const capture = branch.Identity;
+    const policies = capture?.shape.policies;
+    return {
+        fullName: name,
+        number: branch.IdentityNumber === undefined ? undefined : String(branch.IdentityNumber),
+        country: branch.Country,
+        ...(policies?.alias !== "omitted" ? { alias: capture?.values.alias } : {}),
+        ...(policies?.issuingCountry !== "omitted"
+            ? { issuingCountry: capture?.values.issuingCountry }
+            : {}),
+        ...(policies?.expiryDate !== "omitted" ? { expiryDate: capture?.values.expiryDate } : {}),
+    };
+}
+/**
+ * The manual branch's person. The full name is typed as `FullName` by the AppointOfficer branch and
+ * as `IdentityName` by the CorporateRepresentative branch; both name the same person field.
+ */
+function toSubmitPerson(branch, documentName) {
+    const name = branch.FullName ?? branch.IdentityName;
+    const capture = branch.Identity;
+    return {
+        name,
+        ...(documentName === "Corporate Representative"
+            ? {
+                representative: name,
+                representativePassport: branch.IdentityNumber === undefined ? undefined : String(branch.IdentityNumber),
+            }
+            : {}),
+        email: branch.Email,
+        phone: branch.Contact,
+        type: "Person",
+        types: branch.OfficerType ? [branch.OfficerType] : undefined,
+        address: branch.Address,
+        identity: toSubmitIdentity(branch, name),
+        identityShape: capture ? toIdentityShapeSnapshot(capture.shape) : undefined,
+    };
+}
+// spec:1930 — CSP: 使用“Select existing”模式时，表单发送所选实体的 id；手动模式发送用户键入的字段
+/**
+ * The `YYYY-MM-DD` date a submit body carries, or `null` when its control held no formattable date
+ * (spec:1928). The forms normalise their controls with `dayjs(value).format("YYYY-MM-DD")`, which
+ * answers the literal `"Invalid Date"` for an empty one, and the endpoint's `DateTime?` binding
+ * rejects that value with an opaque 400 — so an absent date is what the body must carry instead.
+ *
+ * @param date the date a form normalised.
+ * @returns the date the body carries, or null when there is none.
+ */
+function toSubmitDate(date) {
+    return date && /^\d{4}-\d{2}-\d{2}$/.test(date) ? date : null;
+}
+/**
+ * Builds the submit request body from one form's composed submission (spec:1930): select-existing
+ * carries the picked entity's id and omits every typed person field, manual carries the typed
+ * person with its captured snapshot and omits the id.
+ *
+ * @param submission the document name plus the branch the form composed.
+ * @returns the body the conversion endpoint reads.
+ */
+export function buildLegalGenerationSubmitBody(submission) {
+    const { documentName, mode, branch, company, parentCompany, parentCompanyCountry, parentCompanyDetails, documentDate, effectiveDate, } = submission;
+    const entityId = branch.OfficerId ?? branch.IdentityId;
+    return {
+        documentName,
+        mode,
+        entityId: mode === "select-existing" ? entityId ?? null : null,
+        // The Company picker hands over the corporate's own camelCase read model, while a reopened
+        // document's restore seeds the PascalCase pair; both are read so the body never carries the
+        // empty id a PascalCase-only extraction produced.
+        company: company
+            ? { id: company.id ?? company.Id ?? "", name: company.name ?? company.Name ?? "" }
+            : undefined,
+        ...(documentName === "Corporate Representative"
+            ? {
+                parentCompany: parentCompany
+                    ? {
+                        id: parentCompany.id ?? parentCompany.Id ?? "",
+                        name: parentCompany.name ?? parentCompany.Name ?? "",
+                    }
+                    : undefined,
+                parentCompanyCountry,
+                ...(parentCompanyDetails !== undefined ? { parentCompanyDetails } : {}),
+            }
+            : {}),
+        documentDate: toSubmitDate(documentDate),
+        effectiveDate: toSubmitDate(effectiveDate),
+        person: mode === "manual" ? toSubmitPerson(branch, documentName) : undefined,
+    };
+}
+/**
+ * The message a failed submit carries (spec:3850). `ApiEndPoint` rejects with
+ * `` `${status} - ${bodyText}` `` and the conversion endpoint answers its failure message as a JSON
+ * string literal, so the body is unwrapped and anything else falls back to the raw text.
+ *
+ * @param error the rejection the endpoint raised.
+ * @returns the message the form shows.
+ */
+export function legalGenerationFailureMessage(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    const separator = text.indexOf(" - ");
+    const body = separator < 0 ? text : text.slice(separator + 3);
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed === "string" && parsed.length > 0) {
+            return parsed;
+        }
+    }
+    catch {
+        // The body was not a JSON string literal.
+    }
+    return body || text;
+}
+/** Validate required and omitted values against the immutable policies before create or same-id save. */
+export function validateLegalGenerationCapture(capture) {
+    const errors = {};
+    if (!capture)
+        return errors;
+    for (const field of ["alias", "issuingCountry", "expiryDate"]) {
+        const populated = typeof capture.values[field] === "string" && !!capture.values[field]?.trim();
+        if (capture.shape.policies[field] === "mandatory" && !populated)
+            errors[field] = `${CAPTURED_FIELD_LABEL[field]} is required for ${capture.shape.name}.`;
+        if (capture.shape.policies[field] === "omitted" && populated)
+            errors[field] = `${CAPTURED_FIELD_LABEL[field]} is not captured by ${capture.shape.name}.`;
+    }
+    return errors;
+}
+// spec:3850 — CSP: 法律文书生成表单提交时把组合后的载荷送交转换
+/** Fetch the ZIP with a bearer header and open a short-lived local URL, keeping credentials out of browser URLs. */
+export async function downloadLegalGenerationDocument(document, accessToken, endpoint, open = (url) => {
+    const link = window.document.createElement("a");
+    link.href = url;
+    link.download = `${document.name || document.id}.zip`;
+    link.hidden = true;
+    window.document.body.appendChild(link);
+    try {
+        link.click();
+    }
+    finally {
+        link.remove();
+    }
+}) {
+    const response = await endpoint.get(document.downloadUrl, new RequestBuilder().bearer(accessToken));
+    if (response.headers.get("Content-Type")?.split(";")[0].trim() !== "application/zip")
+        throw new Error("The document download did not return a ZIP archive.");
+    const url = URL.createObjectURL(await response.blob());
+    try {
+        open(url);
+    }
+    finally {
+        window.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+    }
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+// spec:3850 — CSP: 法律文书生成表单提交时把组合后的载荷送交转换
+/** Report delivery failures separately from persistence so the caller can retain the canonical saved id for retry. */
+async function deliverLegalGeneration(result, endpoint, accessToken, open) {
+    try {
+        await downloadLegalGenerationDocument(result.document, accessToken, endpoint, open);
+        return { ok: true, result, document: result.document };
+    }
+    catch (error) {
+        const failure = `The document was saved, but download failed: ${legalGenerationFailureMessage(error)}. Please retry.`;
+        message.error(failure);
+        return { ok: false, message: failure, result, document: result.document };
+    }
+}
+// spec:3850 — CSP: 法律文书生成表单提交时把组合后的载荷送交转换
+/**
+ * Submits a legal-generation form's composed payload to the document conversion and delivers both
+ * continuations (spec:3850): on success the generated document is opened for download, and on
+ * failure the endpoint's message is shown and nothing is downloaded or reset — the caller's entered
+ * values and captured snapshot stay exactly as they were, so the form stays open for a correction
+ * and a retry.
+ *
+ * @param options the endpoint, the caller's access token and the composed submission.
+ * @returns the handoff outcome.
+ */
+export async function submitLegalGeneration(options) {
+    const { endpoint, accessToken, submission, open } = options;
+    let result;
+    try {
+        const response = await endpoint.post(LEGAL_GENERATION_SUBMIT_ROUTE, new RequestBuilder().json(buildLegalGenerationSubmitBody(submission)));
+        const body = await response.json();
+        if (!isSubmitResult(body))
+            throw new Error("The generated document response is invalid. Please retry.");
+        result = body;
+    }
+    catch (error) {
+        const failure = legalGenerationFailureMessage(error);
+        message.error(failure);
+        return { ok: false, message: failure };
+    }
+    return deliverLegalGeneration(result, endpoint, accessToken, open);
+}
+/** The highest `source` the built-in shapes occupy; custom shapes are numbered above it. */
+const LAST_BUILT_IN_SOURCE = 3;
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * Restores the capture a saved form value holds, from the frozen snapshot alone: no catalog lookup
+ * runs, so a source shape later renamed, re-policied or deleted still restores exactly what was
+ * captured (spec:3848). The snapshot omits the catalog's `builtIn` flag and its concurrency token,
+ * so the restored shape marks itself built-in from its `source` — built-ins are 1-3 (spec:3712).
+ *
+ * @param person the form person a load route returned.
+ * @returns the capture the manual-entry block reopens on, or undefined for a legacy value.
+ */
+export function toIdentityCapture(person) {
+    const snapshot = person.identityShape;
+    if (!snapshot) {
+        return undefined;
+    }
+    return {
+        shape: {
+            source: snapshot.sourceNumber,
+            name: snapshot.name,
+            family: snapshot.family,
+            subject: snapshot.subject,
+            builtIn: snapshot.sourceNumber <= LAST_BUILT_IN_SOURCE,
+            policies: {
+                alias: snapshot.aliasPolicy,
+                issuingCountry: snapshot.issuingCountryPolicy,
+                expiryDate: snapshot.expiryPolicy,
+            },
+        },
+        values: {
+            // A save writes `null` for a captured field the frozen shape omits (spec:3713); the
+            // capture itself reads that as "no value", which is what its controls render.
+            alias: person.identity?.alias ?? undefined,
+            issuingCountry: person.identity?.issuingCountry ?? undefined,
+            expiryDate: person.identity?.expiryDate ?? undefined,
+        },
+    };
+}
+/** The route a persisted form document is loaded from and written back to (contract §4). */
+export function legalGenerationFormRoute(id) {
+    return `/api/document-assistants/forms/${id}`;
+}
+/**
+ * The appointed person of an Appoint Officer document: the contact the officer appointments name,
+ * falling back to the composed contact when the appointments name none.
+ */
+function appointedPerson(content, contacts) {
+    const officerIds = (content.newOfficerAppointments?.officers ?? [])
+        .map((officer) => officer.officerId)
+        .filter((id) => !!id);
+    return (officerIds
+        .map((id) => contacts.find((contact) => contact.id === id))
+        .find((contact) => !!contact) ??
+        contacts.find((contact) => contact.idType === "NewId") ??
+        contacts[0]);
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/** Completes a restored address before Ant Form can inject it into the eager Address control. */
+function completeRestoredAddress(address) {
+    return {
+        line1: address?.line1 ?? "",
+        line2: address?.line2 ?? "",
+        city: address?.city ?? "",
+        state: address?.state ?? "",
+        postalCode: address?.postalCode ?? "",
+        country: address?.country ?? "",
+    };
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * Maps a supported named gallery document onto its first relevant captured person (spec:3848).
+ * The frozen snapshot restores its shape and values verbatim without a catalog lookup.
+ * The foreign parent remains separate from the Singapore company and representative identity.
+ *
+ * @param content the camelCase content a loaded Company General document carries.
+ * @returns what the gallery form reopens with, or undefined when no section of this endpoint's two
+ * is populated (a document another surface composed).
+ */
+export function toLegalGenerationRestore(content, documentName) {
+    const contacts = content.contacts ?? [];
+    const company = content.corporate?.id
+        ? { Id: content.corporate.id, Name: content.corporate.name ?? "" }
+        : undefined;
+    // The persisted date is a C# `DateTime?` string, and both forms seed their `UTCDatePicker` with
+    // it, so it is converted here — at the restore boundary — with the same helper the platform's
+    // own company-general form reads the very same member with. An absent date stays undefined
+    // rather than becoming an `Invalid Date` the control would render as a broken value (spec:1928).
+    const date = content.date ? utcdayjs(content.date) : undefined;
+    if (documentName === "Appoint Officer" &&
+        (content.newOfficerAppointments?.officers ?? []).length > 0) {
+        const person = appointedPerson(content, contacts);
+        if (!person) {
+            return undefined;
+        }
+        return {
+            documentName: "Appoint Officer",
+            mode: person.idType === "ExistingContactId" ? "select-existing" : "manual",
+            person,
+            identity: toIdentityCapture(person),
+            values: {
+                FullName: person.name,
+                Country: person.identity?.country,
+                OfficerType: person.types?.[0],
+                Email: person.email,
+                Contact: person.phone,
+                IdentityNumber: person.identity?.number,
+                Address: completeRestoredAddress(person.address),
+                Company: company,
+                DocumentDate: date,
+                EffectiveDate: content.effectiveDate ? utcdayjs(content.effectiveDate) : undefined,
+                Officer: person.selectedEntityId
+                    ? { id: person.selectedEntityId, name: person.name ?? "" }
+                    : undefined,
+            },
+        };
+    }
+    if (documentName !== "Corporate Representative")
+        return undefined;
+    // A representative the endpoint resolved, or a snapshot the composition captured: either is the
+    // Corporate Representative section, the only other section this endpoint composes (contract §1/§3).
+    const person = contacts.find((contact) => !!contact.representative || !!contact.identityShape || !!contact.selectedIdentityId);
+    if (!person) {
+        return undefined;
+    }
+    const parentDetails = readParentCompanyDetails(content.parentCompanyData);
+    return {
+        documentName: "Corporate Representative",
+        parentCompanyBaseline: content.parentCompany?.id && parentDetails ? { parentId: content.parentCompany.id, details: parentDetails } : undefined,
+        mode: person.idType === "ExistingContactId" ? "select-existing" : "manual",
+        person,
+        identity: toIdentityCapture(person),
+        values: {
+            ParentCompany: content.parentCompany?.id
+                ? { Id: content.parentCompany.id, Name: content.parentCompany.name ?? "" }
+                : undefined,
+            // spec:3848 — 代表身份国家与母公司国家分别恢复；签发国家仍由快照字段恢复。
+            Country: content.parentCompanyCountry ?? undefined,
+            RepresentativeCountry: person.identity?.country ?? undefined,
+            IdentityName: person.identity?.fullName ?? person.name,
+            IdentityNumber: person.identity?.number,
+            Company: company,
+            Date: date,
+            LegalContact: person.selectedEntityId || person.selectedIdentityId
+                ? {
+                    id: person.selectedEntityId ?? person.selectedIdentityId,
+                    name: person.name ?? "",
+                }
+                : undefined,
+        },
+    };
+}
+/** Whether a section differs from the empty default CHO payload. */
+function hasPopulatedSection(value) {
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (value && typeof value === "object")
+        return Object.values(value).some(hasPopulatedSection);
+    return value !== null && value !== undefined && value !== "" && value !== false && value !== 0;
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/** 用规范模板识别逻辑类型；未标记旧文书仍需原有名称及独立内容证据。 */
+export function resolveGalleryDocumentKind(document) {
+    if (document.metaKey !== LEGAL_GENERATION_META_KEY || document.country !== "SGP")
+        return undefined;
+    const keys = document.content?.generationTemplateKeys;
+    const kind = keys == null ? document.name : Array.isArray(keys) && keys.length === 1 && keys[0] === "RepresentativeCert" ? "Corporate Representative" : "Appoint Officer";
+    if (kind !== "Appoint Officer" && kind !== "Corporate Representative")
+        return undefined;
+    const content = document.content;
+    if (!content)
+        return undefined;
+    const contacts = content.contacts ?? [];
+    const appointments = content.newOfficerAppointments?.officers ?? [];
+    if (!Array.isArray(contacts) || !Array.isArray(appointments))
+        return undefined;
+    if (contacts.some((contact) => !contact || typeof contact !== "object") ||
+        appointments.some((position) => !position || typeof position !== "object"))
+        return undefined;
+    const people = kind === "Appoint Officer"
+        ? appointments
+            .map((position) => contacts.find((contact) => contact.id === position.officerId))
+            .filter(Boolean)
+        : contacts.filter((contact) => typeof contact.representative === "string" && !!contact.representative.trim());
+    if (!people.length || (kind === "Appoint Officer" && !contacts.some((contact) => contact.id === appointments[0]?.officerId)))
+        return undefined;
+    if (appointments[0]?.positions != null && !Array.isArray(appointments[0].positions))
+        return undefined;
+    const positions = [...new Set(appointments[0]?.positions ?? [])];
+    if (kind === "Appoint Officer" &&
+        (!positions.length ||
+            positions.some((position) => !isSupportedOfficerPosition(position))))
+        return undefined;
+    const expected = kind === "Corporate Representative"
+        ? ["RepresentativeCert"]
+        : [
+            "BoardResolution",
+            ...(positions.includes("Director") ? ["Form45"] : []),
+            ...(positions.includes("Secretary") ? ["Form45B"] : []),
+        ];
+    if (content.generationTemplateKeys != null)
+        return (Array.isArray(content.generationTemplateKeys) &&
+            JSON.stringify(content.generationTemplateKeys) === JSON.stringify(expected)) ? kind : undefined;
+    if (document.parentNode != null ||
+        !!document.parentNodeId ||
+        contacts.length !== 1 ||
+        people.length !== 1)
+        return undefined;
+    const allowed = [
+        "corporate",
+        "date",
+        "effectiveDate",
+        "contacts",
+        "newOfficerAppointments",
+        "generationTemplateKeys",
+        "parentCompany",
+        "parentCompanyCountry",
+        "parentCompanyData",
+    ];
+    return Object.entries(content).every(([key, value]) => allowed.includes(key) || !hasPopulatedSection(value)) ? kind : undefined;
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * The document a legal-generation page was opened on, when the id it carries names a persisted
+ * Company General document this endpoint composed (contract §1/§4). Anything else — another id, a
+ * document family this gallery does not compose, a content whose sections are both empty — answers
+ * undefined; the saved-id load gate treats unsupported responses as a failure.
+ *
+ * @param document the document a load returned, when one was loaded at all.
+ * @returns the reopened document, or undefined when the page composes a new one.
+ */
+export function toReopenedLegalGeneration(document) {
+    if (!document ||
+        document.metaKey !== LEGAL_GENERATION_META_KEY ||
+        !resolveGalleryDocumentKind(document)) {
+        return undefined;
+    }
+    const content = document.content ?? {};
+    const restore = toLegalGenerationRestore(content, resolveGalleryDocumentKind(document));
+    if (!restore) {
+        return undefined;
+    }
+    return { id: document.id, content, ...restore };
+}
+/**
+ * Maps the camelCase address a load route returns onto the PascalCase one the save route reads.
+ */
+function toAddressEdit(address) {
+    return {
+        Line1: address.line1,
+        Line2: address.line2 ?? null,
+        City: address.city ?? null,
+        State: address.state ?? null,
+        PostalCode: address.postalCode ?? null,
+        Country: address.country,
+    };
+}
+/**
+ * Fixture/legacy helper mapping a loaded person onto the generic PascalCase edit contract, copying
+ * every value verbatim — including the captured snapshot, whose frozen `Name` and three policies
+ * are written back exactly as they were read (spec:3848).
+ */
+function toFormPersonEdit(person) {
+    return {
+        Id: person.id ?? "",
+        IdType: person.idType ?? "NewId",
+        // spec:3848 — Preserve selected provenance alongside the frozen values on unchanged save.
+        SelectedEntityId: person.selectedEntityId ?? null,
+        SelectedIdentityId: person.selectedIdentityId ?? null,
+        Name: person.name ?? "",
+        Email: person.email ?? null,
+        Phone: person.phone ?? null,
+        Type: person.type ?? null,
+        Types: person.types ?? null,
+        Representative: person.representative ?? null,
+        RepresentativePassport: person.representativePassport ?? null,
+        Address: person.address ? toAddressEdit(person.address) : null,
+        Identity: person.identity
+            ? {
+                FullName: person.identity.fullName ?? null,
+                Number: person.identity.number ?? null,
+                Country: person.identity.country ?? null,
+                Alias: person.identity.alias ?? null,
+                IssuingCountry: person.identity.issuingCountry ?? null,
+                ExpiryDate: person.identity.expiryDate ?? null,
+            }
+            : null,
+        IdentityShape: person.identityShape
+            ? {
+                SourceNumber: person.identityShape.sourceNumber,
+                Name: person.identityShape.name,
+                Family: person.identityShape.family,
+                Subject: person.identityShape.subject,
+                AliasPolicy: person.identityShape.aliasPolicy,
+                IssuingCountryPolicy: person.identityShape.issuingCountryPolicy,
+                ExpiryPolicy: person.identityShape.expiryPolicy,
+            }
+            : null,
+    };
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * Maps the form content a load route returned onto the PascalCase
+ * `CompanyGeneral.SGP.FormEditOptions` the platform save route reads (contract §4). Every value is
+ * copied unchanged — in particular the frozen `IdentityShape` snapshot — so save → reopen → resubmit
+ * round-trips the snapshot byte-identically, with no catalog resolution and no dependence on the
+ * source shape still existing (spec:3848).
+ *
+ * Two members are deliberately shaped by the route's own semantics: `Corporate` is never sent,
+ * because a company whose id differs from the stored one reads as "the document moved company" and
+ * unions the whole roster into `Contacts`; and `Contacts` carries the **complete** list, because a
+ * sent list replaces the stored one wholesale — omitting an entry would delete it.
+ *
+ * @param content the camelCase content a loaded legal-generation form carries.
+ * @returns the payload the double-encoded save body carries.
+ */
+export function toFormContentEditPayload(content) {
+    const contacts = content.contacts;
+    const officers = content.newOfficerAppointments?.officers;
+    return {
+        Date: content.date ?? null,
+        ...(contacts ? { Contacts: contacts.map(toFormPersonEdit) } : {}),
+        ...(officers && officers.length > 0
+            ? {
+                // The route binds this body with case-SENSITIVE `System.Text.Json`, so the
+                // read model's camelCase members have to be mapped onto the contract's
+                // PascalCase ones — sent verbatim they bind to nothing and wipe the link.
+                NewOfficerAppointments: {
+                    Officers: officers.map((officer) => ({
+                        Positions: officer.positions ?? [],
+                        OfficerId: officer.officerId,
+                    })),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * One captured identity field of a reopened person's save, decided from the **frozen snapshot's own
+ * policy** rather than from what the capture happens to hold (spec:3713): the replacement shape's
+ * `omitted` policy clears the persisted value to `null` — the capture has already dropped the key,
+ * and spreading it would leave the forbidden value in place, where no control can clear it — while a
+ * captured policy emits the value the user left there, or `null` when the capture holds none. A
+ * person with no capture at all has no policy to consult, so the persisted value it carries is kept.
+ *
+ * @param person the loaded person whose persisted identity the save writes back.
+ * @param capture the capture the re-composed branch holds, when it holds one.
+ * @param field the captured identity field to decide.
+ * @returns the value the saved identity carries for that field.
+ */
+function toEditedIdentityValue(person, capture, field) {
+    if (!capture) {
+        return person.identity?.[field];
+    }
+    return capture.shape.policies[field] === "omitted" ? null : capture.values[field] ?? null;
+}
+/**
+ * The person a reopened document's save writes back: the contact the load returned, with the values
+ * the form re-composed folded into it. The contact's own identity — its id, the type the endpoint
+ * resolved and the members this form does not edit — is copied unchanged, so the save can never
+ * drop a value the document carries (contract §4).
+ */
+function toLegalGenerationEditedPerson(person, branch) {
+    const capture = branch.Identity;
+    const name = branch.FullName ?? branch.IdentityName ?? person.name;
+    return {
+        ...person,
+        name,
+        email: branch.Email ?? person.email,
+        phone: branch.Contact ?? person.phone,
+        address: branch.Address ?? person.address,
+        identity: {
+            ...person.identity,
+            fullName: name,
+            number: branch.IdentityNumber === undefined
+                ? person.identity?.number
+                : String(branch.IdentityNumber),
+            country: branch.Country ?? person.identity?.country,
+            // Each captured field is decided by the frozen snapshot's own policy rather than by what
+            // the capture happens to hold, so a field the shape omits can never survive into the
+            // saved document (spec:3713).
+            alias: toEditedIdentityValue(person, capture, "alias"),
+            issuingCountry: toEditedIdentityValue(person, capture, "issuingCountry"),
+            expiryDate: toEditedIdentityValue(person, capture, "expiryDate"),
+        },
+        identityShape: capture ? toIdentityShapeSnapshot(capture.shape) : person.identityShape,
+    };
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * The content a reopened form's save writes back (contract §4): the document's own content with the
+ * branch the user re-composed folded into the section's contact, and every other contact, the officer
+ * appointments and the document date copied unchanged — so the list the save replaces wholesale is
+ * still the complete one (spec:3848).
+ *
+ * Only a manual branch folds. A select-existing save keeps the contact the endpoint resolved when it
+ * composed the document: the id the picker posts is an officer / legal-contact id, and only the
+ * server can resolve it to the contact id the document addresses its people by (contract §3.1).
+ *
+ * @param reopened the document the form was reopened on.
+ * @param branch the branch the form re-composed.
+ * @param documentDate the date the form carries, already normalised to `YYYY-MM-DD`.
+ * @returns the content {@link toFormContentEditPayload} writes back.
+ */
+export function toLegalGenerationSavedContent(reopened, branch, documentDate) {
+    const date = documentDate && /^\d{4}-\d{2}-\d{2}$/.test(documentDate) ? documentDate : reopened.content.date;
+    if (reopened.mode !== "manual") {
+        return { ...reopened.content, date };
+    }
+    const edited = toLegalGenerationEditedPerson(reopened.person, branch);
+    const contacts = (reopened.content.contacts ?? []).map((contact) => contact.id === edited.id ? edited : contact);
+    // An Appoint Officer document records the appointment on its own section, addressed by the
+    // contact's id, so the position follows the officer type the form re-composed (contract §3).
+    const officers = reopened.content.newOfficerAppointments?.officers?.map((officer) => officer.officerId === edited.id && branch.OfficerType
+        ? { ...officer, positions: [branch.OfficerType] }
+        : officer);
+    return {
+        ...reopened.content,
+        date,
+        contacts,
+        ...(officers ? { newOfficerAppointments: { officers } } : {}),
+    };
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/** The message a load failure other than a missing document surfaces (spec:3848). */
+export const LEGAL_GENERATION_LOAD_FAILURE_MESSAGE = "Failed to load the saved document. Please reopen it from the document list and try again.";
+/** Reject malformed or unsupported saved documents before controls can consume them. */
+function isSavedDocument(value, id) {
+    if (!value || typeof value !== "object")
+        return false;
+    const document = value;
+    if (document.id !== id ||
+        document.metaKey !== LEGAL_GENERATION_META_KEY ||
+        document.country !== "SGP" ||
+        !document.content ||
+        typeof document.content !== "object")
+        return false;
+    const content = document.content;
+    const company = content.corporate;
+    if (!company || typeof company.id !== "string" || !company.id || typeof company.name !== "string")
+        return false;
+    if (content.parentCompany != null) {
+        if (typeof content.parentCompany !== "object" || Array.isArray(content.parentCompany))
+            return false;
+        const parent = content.parentCompany;
+        if (typeof parent.id !== "string" || !parent.id || typeof parent.name !== "string")
+            return false;
+    }
+    if (content.parentCompanyCountry != null && typeof content.parentCompanyCountry !== "string")
+        return false;
+    if (content.parentCompanyData != null && !readParentCompanyDetails(content.parentCompanyData))
+        return false;
+    if (!Array.isArray(content.contacts) ||
+        content.contacts.some((person) => !person ||
+            typeof person !== "object" ||
+            typeof person.id !== "string"))
+        return false;
+    for (const person of content.contacts) {
+        if (person.representative != null && typeof person.representative !== "string")
+            return false;
+        if (person.identity &&
+            (typeof person.identity !== "object" ||
+                Array.isArray(person.identity) ||
+                ["fullName", "number", "country", "alias", "issuingCountry", "expiryDate"].some((key) => {
+                    const field = person.identity?.[key];
+                    return field != null && typeof field !== "string";
+                })))
+            return false;
+        const shape = person.identityShape;
+        if (shape &&
+            (typeof shape !== "object" ||
+                !Number.isInteger(shape.sourceNumber) ||
+                shape.sourceNumber < 1 ||
+                typeof shape.name !== "string" ||
+                !["Passport", "NationalIdentity", "BusinessRegistration", "Other"].includes(shape.family) ||
+                !["Person", "Organization", "Both"].includes(shape.subject) ||
+                [shape.aliasPolicy, shape.issuingCountryPolicy, shape.expiryPolicy].some((policy) => !["omitted", "available", "mandatory"].includes(policy))))
+            return false;
+    }
+    if (content.newOfficerAppointments != null) {
+        if (typeof content.newOfficerAppointments !== "object")
+            return false;
+        const officers = content.newOfficerAppointments.officers;
+        if (!Array.isArray(officers) ||
+            officers.some((officer) => !officer ||
+                typeof officer !== "object" ||
+                typeof officer.officerId !== "string" ||
+                !Array.isArray(officer.positions) ||
+                officer.positions.some((position) => typeof position !== "string") ||
+                !content.contacts.some((contact) => contact.id === officer.officerId)))
+            return false;
+    }
+    for (const field of ["date", "effectiveDate"]) {
+        if (content[field] != null &&
+            (typeof content[field] !== "string" || !utcdayjs(content[field]).isValid()))
+            return false;
+    }
+    return !!toReopenedLegalGeneration(value);
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/** Load a saved CHO composition; only 404 is missing, other failures remain failures. */
+export async function loadLegalGenerationForm(options) {
+    try {
+        const builder = new RequestBuilder();
+        builder.FetchRequest({ signal: options.signal });
+        const response = await options.endpoint.get(legalGenerationFormRoute(options.id), builder);
+        const document = await response.json();
+        if (!isSavedDocument(document, options.id))
+            throw new Error(LEGAL_GENERATION_LOAD_FAILURE_MESSAGE);
+        return document;
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 404)
+            return undefined;
+        throw error;
+    }
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+/**
+ * Fixture/legacy generic-save helper writing re-composed content to its existing document
+ * (contract §4): the PascalCase payload of {@link toFormContentEditPayload}, sent as the JSON **text**
+ * the platform save route binds with case-sensitive `System.Text.Json`.
+ *
+ * This generic route remains for fixture/legacy callers. Production gallery editors call
+ * saveLegalGeneration, whose dedicated /save route owns selected composition and regeneration.
+ *
+ * @param options the endpoint, the persisted document's id and the content to write back.
+ * @returns the save outcome; a failure is surfaced through the same channel the submit uses.
+ */
+export async function saveLegalGenerationContent(options) {
+    const { endpoint, id, content } = options;
+    try {
+        // The payload is the JSON TEXT of the edit options, exactly as the platform's own form save
+        // posts it (`new RequestBuilder().json(JSON.stringify(data))`), not the object itself.
+        await endpoint.post(legalGenerationFormRoute(id), new RequestBuilder().json(JSON.stringify(toFormContentEditPayload(content))));
+        return { ok: true };
+    }
+    catch (error) {
+        const failure = legalGenerationFailureMessage(error);
+        message.error(failure);
+        return { ok: false, message: failure };
+    }
+}
+// spec:1930 — CSP: 使用“Select existing”模式时，表单发送所选实体的 id；手动模式发送用户键入的字段
+// spec:3848 — CSP form identities retain their selected shape snapshot
+// spec:3850 — CSP: 法律文书生成表单提交时把组合后的载荷送交转换
+/** Production gallery save: resolve the complete edited branch through the dedicated /save route, then download the regenerated existing ZIP. */
+export async function saveLegalGeneration(options) {
+    let saved;
+    try {
+        const response = await options.endpoint.post(`/api/document-assistants/legal-generation/${encodeURIComponent(options.id)}/save`, new RequestBuilder().json(buildLegalGenerationSubmitBody(options.submission)));
+        const result = await response.json();
+        if (!isSubmitResult(result, options.id))
+            throw new Error("The saved document response is invalid. Please retry.");
+        saved = result;
+    }
+    catch (error) {
+        const failure = legalGenerationFailureMessage(error);
+        message.error(failure);
+        return { ok: false, message: failure };
+    }
+    return deliverLegalGeneration(saved, options.endpoint, options.accessToken, options.open);
+}
+// spec:3848 — CSP form identities retain their selected shape snapshot
+// spec:3850 — CSP: 法律文书生成表单提交时把组合后的载荷送交转换
+/** Validate canonical returned content and the same-id ZIP reference before reseeding or downloading. */
+function isSubmitResult(value, savedId) {
+    if (!value || typeof value !== "object")
+        return false;
+    const result = value;
+    if (typeof result.id !== "string" ||
+        !result.id ||
+        (savedId && result.id !== savedId) ||
+        !["Appoint Officer", "Corporate Representative"].includes(result.documentName) ||
+        !["manual", "select-existing"].includes(result.mode))
+        return false;
+    return (isSavedDocument({
+        id: result.id,
+        metaKey: result.metaKey,
+        country: "SGP",
+        name: result.documentName,
+        content: result.content,
+    }, result.id) &&
+        resolveGalleryDocumentKind({ id: result.id, metaKey: result.metaKey, country: "SGP", name: result.documentName, content: result.content }) === result.documentName &&
+        result.document?.id === result.id &&
+        result.document.contentType === "application/zip" &&
+        result.document.downloadUrl ===
+            `/api/document-assistants/legal-generation/${encodeURIComponent(result.id)}/download`);
+}
+//# sourceMappingURL=legalGenerationSubmit.js.map