Files
persionalBrand/packages/api-client/src/resources/template.ts
T

427 lines
15 KiB
TypeScript

import type { BrandTemplateKey, RuntimeWorkspace } from "@personal-brand/types";
import type { RequestFn } from "../client/request.js";
import {
adminCapabilityListSchema,
adminTemplateOperationFailuresSchema,
adminTemplatePackageAuditListSchema,
adminTemplatePackageListSchema,
} from "../schemas/admin-collections.js";
import type { BrandPageSchemeOptions, BrandProfile } from "../types/brand.js";
import type { CapabilityWithMetadata } from "../types/capability.js";
import type { BrandFieldDefinition } from "../types/field.js";
import type { Offering } from "../types/offering.js";
import type { AdminTemplateContent } from "../types/template.js";
import type { BrandTemplateDefinition } from "../types/template-definition.js";
export interface TemplateMethods {
getAdminPageSchemeOptions(): Promise<BrandPageSchemeOptions>;
listAdminTemplatePackages(params?: {
page?: number;
pageSize?: number;
}): Promise<TemplatePackageList>;
importAdminTemplatePackage(body: unknown): Promise<TemplatePackageImportResult>;
publishAdminTemplatePackage(id: string): Promise<TemplatePackageActionResult>;
retireAdminTemplatePackage(id: string): Promise<TemplatePackageActionResult>;
listAdminTemplatePackageAudit(id: string): Promise<TemplatePackageAuditEntry[]>;
previewAdminTemplatePackage(
id: string,
industry: string,
session?: string,
): Promise<TemplatePackagePreview>;
getPublicTemplate(key: BrandTemplateKey): Promise<BrandTemplateDefinition>;
listPublicTemplates(): Promise<{
industries: BrandTemplateDefinition[];
visuals: Array<{
key: string;
version: string;
name: string;
description: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
theme: { colors: Record<string, string> };
}>;
}>;
previewPublicTemplateCombination(
industry: string,
visual: string,
): Promise<{
industry: BrandTemplateDefinition;
visual: {
key: string;
version: string;
name: string;
description: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
theme: { colors: Record<string, string> };
};
runtime: {
schemaVersion: string;
capabilities: Array<{ key: string; version: string }>;
theme: unknown;
};
}>;
getAdminWorkspace(): Promise<{
brand: BrandProfile;
visualTemplate?: {
key: string;
version: string;
name: string;
supportedIndustryTemplates: BrandTemplateKey[];
variants: Record<string, string>;
} | null;
installations: Array<{
id: string;
templateKey: BrandTemplateKey;
templateVersion: string;
visualTemplateKey: string;
templatePackageVersionId: string;
contentChecksum: string;
}>;
fields: BrandFieldDefinition[];
offerings: Offering[];
forms: unknown[];
templateContent: AdminTemplateContent | null;
capabilities?: CapabilityWithMetadata[];
}>;
getAdminPreviewWorkspace(): Promise<RuntimeWorkspace>;
installAdminTemplate(
templateKey: BrandTemplateKey,
templatePackageVersionId: string,
): Promise<unknown>;
selectAdminTemplateVersion(input: {
templatePackageVersionId: string;
expectedCurrentPackageVersionId?: string | null;
confirm: true;
}): Promise<unknown>;
listAdminCapabilities(): Promise<CapabilityWithMetadata[]>;
updateAdminCapability(
key: string,
body: {
status: CapabilityWithMetadata["status"];
config?: Record<string, unknown>;
},
): Promise<CapabilityWithMetadata>;
previewAdminSampleContent(params?: {
templatePackageVersionId?: string;
strategy?: "missing_only";
}): Promise<{
templateKey: string;
visualTemplateKey: string;
source: {
kind: "package_version";
packageKey: string;
version: string;
contentChecksum: string;
templatePackageVersionId: string;
};
alreadyImported: boolean;
counts: Record<
"brandConfig" | "offerings" | "trustContent" | "fields" | "inquiryForms",
number
>;
skipped: Record<
"brandConfig" | "offerings" | "trustContent" | "fields" | "inquiryForms",
number
>;
willCreateInquiryForm: boolean;
missingConfigKeys: string[];
plan: Array<{ type: string; key: string; action: "create" | "skip" }>;
}>;
importAdminSampleContent(body: {
templatePackageVersionId?: string;
strategy: "missing_only";
confirm: true;
}): Promise<{
imported: boolean;
alreadyImported: boolean;
source: {
kind: "package_version";
packageKey: string;
version: string;
contentChecksum: string;
templatePackageVersionId: string;
};
counts: Record<string, number>;
}>;
getAdminTemplateUpgradePreview(): Promise<{
templateKey: BrandTemplateKey;
currentVersion: string;
latestVersion: string;
canUpgrade: boolean;
canRollback: boolean;
currentPackageVersionId: string | null;
currentContentChecksum: string | null;
targetPackageVersionId: string | null;
targetContentChecksum: string | null;
changes: {
brandFields: { available: false; reason: string };
templateBindings: { added: unknown[]; changed: unknown[]; removed: unknown[] };
pages: { added: unknown[]; changed: unknown[]; removed: unknown[] };
modules: {
available: boolean;
source: "platform_visual_manifest";
packageUpgradeChangesRenderer: false;
pages: Array<{ key: string; renderer: string | null; modules?: unknown[] }>;
};
assets: {
slots: { added: unknown[]; changed: unknown[]; removed: unknown[] };
files: {
available: boolean;
added?: unknown[];
changed?: unknown[];
removed?: unknown[];
reason?: string;
};
};
capabilities: { added: string[]; removed: string[] };
renderer: {
available: boolean;
source: "platform_visual_manifest";
packageUpgradeChangesRenderer: false;
pages: Array<{ key: string; renderer: string | null }>;
};
package: {
currentContentChecksum: string | null;
targetContentChecksum: string | null;
runtimeContract: { current: unknown; target: unknown };
};
};
conflicts: Array<{ key: string; binding: string; reason: string }>;
}>;
upgradeAdminTemplate(input: {
templatePackageVersionId: string;
expectedContentChecksum: string;
expectedCurrentVersion: string;
expectedCurrentPackageVersionId: string | null;
confirm: true;
preservedBindings: Array<{ key: string; binding: string; action: "preserve" }>;
}): Promise<unknown>;
rollbackAdminTemplate(input: { expectedCurrentVersion: string; confirm: true }): Promise<unknown>;
getAdminTemplateOperationFailures(params?: { days?: number }): Promise<{
since: string;
until: string;
days: number;
backfilled: false;
failures: Array<{ action: string; count: number }>;
}>;
}
export interface TemplatePackageVersion {
id: string;
templatePackageId: string;
packageKey: string;
version: string;
displayName: string;
status: "imported" | "published" | "retired" | "disabled";
contentChecksum: string;
archiveChecksum: string;
validationReport: Record<string, unknown>;
importedAt: string;
updatedAt: string;
importedBy: { id: string; username: string; displayName: string };
manifestSummary?: {
runtimeContract: string;
supportedIndustryTemplates: string[];
requiredCapabilities: string[];
};
}
export interface TemplatePackagePreview {
template: Pick<
TemplatePackageVersion,
"id" | "packageKey" | "version" | "displayName" | "status" | "contentChecksum"
> & {
visualTemplateKey: string;
navigation: Array<{ key: string; label: string; page: string }>;
pages: string[];
};
industry: { key: string; version: string; name: string };
compatibility: {
runtimeContract: string;
renderer: { key: string; version: string; trusted: boolean };
requiredCapabilities: string[];
missingSampleSlots: string[];
};
workspace: RuntimeWorkspace;
preview: {
assetFiles: Record<string, { sha256: string; dataUrl: string }>;
fixtureSource: "previewFixture";
safety: { submissions: "disabled"; customerRecords: "disabled"; contactActions: "disabled" };
session: { token: string; expiresAt: string };
diagnostics: Array<{ code: string; severity: "warning"; message: string }>;
pages: Array<{
key: string;
modules: Array<{ key: string; title: string; bindings: string[] }>;
}>;
assets: Array<{
key: string;
label: string;
binding: string;
required: boolean;
populated: number;
total: number;
status: "missing" | "unverified" | "ready";
}>;
};
}
export interface TemplatePackageList {
items: TemplatePackageVersion[];
page: number;
pageSize: number;
total: number;
}
export interface TemplatePackageActionResult {
changed: boolean;
version: Pick<
TemplatePackageVersion,
| "id"
| "packageKey"
| "version"
| "displayName"
| "status"
| "contentChecksum"
| "archiveChecksum"
| "importedAt"
>;
}
export interface TemplatePackageAuditEntry {
id: string;
action: string;
fromStatus: TemplatePackageVersion["status"] | null;
toStatus: TemplatePackageVersion["status"] | null;
requestId: string | null;
metadata: Record<string, unknown> | null;
createdAt: string;
actor: { id: string; username: string; displayName: string };
}
export interface TemplatePackageImportResult {
imported: boolean;
idempotent: boolean;
version: Pick<
TemplatePackageVersion,
| "id"
| "packageKey"
| "version"
| "displayName"
| "status"
| "contentChecksum"
| "archiveChecksum"
| "importedAt"
>;
}
export function templateMethods({ request }: { request: RequestFn }): TemplateMethods {
return {
getAdminPageSchemeOptions: () => request("/admin/workspace/template/options"),
listAdminTemplatePackages: (params = {}) => {
const query = [
params.page === undefined ? null : `page=${encodeURIComponent(String(params.page))}`,
params.pageSize === undefined
? null
: `pageSize=${encodeURIComponent(String(params.pageSize))}`,
].filter((item): item is string => item !== null);
return request(`/admin/templates${query.length ? `?${query.join("&")}` : ""}`, {
expect: adminTemplatePackageListSchema,
});
},
importAdminTemplatePackage: (body) =>
request("/admin/templates/import", { method: "POST", rawBody: body }),
publishAdminTemplatePackage: (id) =>
request(`/admin/templates/${encodeURIComponent(id)}/publish`, { method: "POST" }),
retireAdminTemplatePackage: (id) =>
request(`/admin/templates/${encodeURIComponent(id)}/retire`, { method: "POST" }),
listAdminTemplatePackageAudit: (id) =>
request(`/admin/templates/${encodeURIComponent(id)}/audit`, {
expect: adminTemplatePackageAuditListSchema,
}),
previewAdminTemplatePackage: (id, industry, session) =>
request(
`/admin/templates/${encodeURIComponent(id)}/preview?industry=${encodeURIComponent(industry)}${session ? `&session=${encodeURIComponent(session)}` : ""}`,
),
getPublicTemplate: (key) => request(`/public/templates/${key}`),
listPublicTemplates: () =>
request<{
industries: BrandTemplateDefinition[];
visuals: Array<{
key: string;
version: string;
name: string;
description: string;
supportedIndustryTemplates?: unknown;
variants?: unknown;
theme?: unknown;
}>;
}>("/public/templates").then((catalog) => ({
industries: Array.isArray(catalog.industries) ? catalog.industries : [],
visuals: Array.isArray(catalog.visuals)
? catalog.visuals.map((visual) => ({
key: String(visual.key ?? ""),
version: String(visual.version ?? ""),
name: String(visual.name ?? "未命名视觉模板"),
description: String(visual.description ?? ""),
supportedIndustryTemplates: Array.isArray(visual.supportedIndustryTemplates)
? visual.supportedIndustryTemplates.filter(
(item): item is BrandTemplateKey => typeof item === "string",
)
: [],
variants:
visual.variants && typeof visual.variants === "object"
? (visual.variants as Record<string, string>)
: {},
theme:
visual.theme && typeof visual.theme === "object"
? (visual.theme as { colors: Record<string, string> })
: { colors: {} },
}))
: [],
})),
previewPublicTemplateCombination: (industry, visual) =>
request(
`/public/templates/preview?industry=${encodeURIComponent(industry)}&visual=${encodeURIComponent(visual)}`,
),
getAdminWorkspace: () => request("/admin/workspace"),
getAdminPreviewWorkspace: () => request("/admin/workspace/preview"),
installAdminTemplate: (templateKey, templatePackageVersionId) =>
request("/admin/workspace/install", {
method: "POST",
body: { templateKey, templatePackageVersionId },
}),
selectAdminTemplateVersion: (input) =>
request("/admin/workspace/template/select-version", { method: "POST", body: input }),
listAdminCapabilities: () =>
request("/admin/workspace/capabilities", { expect: adminCapabilityListSchema }),
updateAdminCapability: (key, body) =>
request(`/admin/workspace/capabilities/${encodeURIComponent(key)}`, {
method: "PATCH",
body,
}),
previewAdminSampleContent: (params) => {
const query = [
params?.templatePackageVersionId
? `templatePackageVersionId=${encodeURIComponent(params.templatePackageVersionId)}`
: "",
params?.strategy ? `strategy=${encodeURIComponent(params.strategy)}` : "",
].filter(Boolean);
const suffix = query.length ? `?${query.join("&")}` : "";
return request(`/admin/workspace/sample-content/preview${suffix}`);
},
importAdminSampleContent: (body) =>
request("/admin/workspace/sample-content/import", { method: "POST", body }),
getAdminTemplateUpgradePreview: () => request("/admin/workspace/template/preview"),
upgradeAdminTemplate: (input) =>
request("/admin/workspace/template/upgrade", { method: "POST", body: input }),
rollbackAdminTemplate: (input) =>
request("/admin/workspace/template/rollback", { method: "POST", body: input }),
getAdminTemplateOperationFailures: (params = {}) =>
request(
`/admin/template-operations/failures${params.days === undefined ? "" : `?days=${encodeURIComponent(String(params.days))}`}`,
{ expect: adminTemplateOperationFailuresSchema },
),
};
}