Files
persionalBrand/packages/template-contract/src/index.ts
T
que01 3017e3eb49 fix: 收口依赖兼容与会话撤销
为 miniprogram-ci 和 Jimp 依赖增加兼容 patch 与 smoke test;修复平台模板管理员路由漏配;收紧模板契约校验;为 admin/customer 增加 token 撤销和集中会话存储;同步品牌切换角色、doctor source hash、多屏宽截图证据和 CI 构建门禁。
2026-10-18 23:43:25 +08:00

460 lines
18 KiB
TypeScript

import { validateTemplatePreviewFixtures } from "@personal-brand/validation";
export const TEMPLATE_RUNTIME_CONTRACT = "1.0" as const;
export type TemplatePageKey =
"home" | "offerings" | "detail" | "inquiry" | "success" | "records" | "profile" | (string & {});
/** 运行时(apps/miniapp)提供的核心能力,不需要能力包。 */
export const CORE_CAPABILITIES = ["offerings", "inquiry"] as const;
/** 小程序页面路径,例如 `pages/index/index`,不带扩展名。 */
const PAGE_PATH_PATTERN = /^pages\/[a-z0-9-]+(\/[a-z0-9-]+)*$/;
/** 叠加路径:页面目录或组件目录,例如 `pages/inquiry`、`components/templates/acheng-home`。 */
const LAYER_PATH_PATTERN = /^(pages|components)\/[a-z0-9-]+(\/[a-z0-9-]+)*$/;
/**
* 模板向平台声明的内容来源。它只描述稳定的业务事实,不描述页面结构或 renderer。
*/
export type TemplateContentSource = "brand" | "offering" | "trust" | "inquiry" | "records";
/** 模板需要的小程序数据集合,用于 Runtime 投影和发布前校验。 */
export type TemplateDataSlot = {
key: string;
source: TemplateContentSource;
required: boolean;
description: string;
};
/** 图片、标志等媒体需求;label/help 是给品牌管理员看到的业务语言。 */
export type TemplateAssetSlot = {
key: string;
binding: string;
target: "brand" | "offering" | "trust";
label: string;
help: string;
required: boolean;
kind: "image" | "logo" | "portrait" | "texture";
aspectRatio?: string;
};
/**
* 一个可由普通品牌管理员编辑的字段。
* key 是稳定语义标识,binding 是平台内部的存储映射;两者均不直接展示给用户。
*/
export type TemplateAdminField = {
key: string;
binding: string;
label: string;
help?: string;
input:
| "text"
| "textarea"
| "phone"
| "image"
| "number"
| "boolean"
| "select"
| "multi-select"
| "list";
itemFields?: Array<{
key: string;
label: string;
input?: "text" | "textarea";
required?: boolean;
}>;
itemValueKey?: string;
required?: boolean;
maxLength?: number;
placeholder?: string;
options?: Array<{ value: string; label: string }>;
/** Stable visual-region identifier declared by the owning Admin section. */
previewTarget?: string;
};
/** 模板自己的浅层品牌字段,值存于 BrandProfile.config.templateData。 */
export type TemplateField = Omit<TemplateAdminField, "binding"> & {
key: string;
page?: TemplatePageKey;
binding?: `brand.config.templateData.${string}`;
};
/** 一个面向业务用户的编辑分组,而不是技术 schema 或 JSON 编辑器。 */
export type TemplateAdminSection = {
key: string;
title: string;
description: string;
/** Exact Mini Program page that displays this section's content. */
page: TemplatePageKey;
target: "brand" | "offering" | "trust" | "inquiry";
/** Visual regions rendered by this section's page. */
previewTargets?: Array<{
key: string;
label: string;
/** 组合区域只负责承载和导航,不重复声明可编辑字段。 */
composite?: boolean;
children?: string[];
}>;
fields: TemplateAdminField[];
};
export type TemplateAdminManifest = {
sections: TemplateAdminSection[];
};
export type TemplateTrustContentType = {
type: "schedule" | "coverage" | "process" | "credential" | "case" | "promise" | (string & {});
label: string;
/** Labels for the persisted TrustContent columns edited in Admin. */
adminFields: {
title: string;
summary: string;
content: string;
summaryHelp?: string;
summaryPlaceholder?: string;
};
pages?: TemplatePageKey[];
help?: string;
placeholder?: string;
required?: boolean;
configFields?: TemplateAdminField[];
previewTargets?: Array<{ key: string; label: string; page?: string }>;
maxPublishedItems?: number;
hideStandardFields?: Array<"summary" | "content">;
};
export type TemplateSampleContent = {
brandConfig?: Record<string, unknown>;
templateKey: string;
inquiryFormName: string;
offerings: Array<Record<string, unknown> & { priceAmount?: number }>;
trustContent: Array<Record<string, unknown>>;
fields: Array<Record<string, unknown>>;
capabilityKey: string;
};
export type TemplateVisualPresentation = {
description: string;
variants: Record<string, string>;
theme: { colors: Record<string, string>; radius: Record<string, string> };
layout?: {
home: string[];
offerings: string[];
detail: string[];
profile: string[];
};
};
export type TemplatePackageManifest = {
packageKey: string;
version: string;
displayName: string;
visualTemplateKey: string;
visualPresentation: TemplateVisualPresentation;
runtimeContract: typeof TEMPLATE_RUNTIME_CONTRACT;
supportedIndustryTemplates: string[];
entrypoints: Record<string, string>;
navigation: Array<{
key: string;
label: string;
page: TemplatePageKey;
iconPath?: string;
selectedIconPath?: string;
}>;
requiredCapabilities: string[];
/** 模板包自己提供的页面;编译器据此生成 app.json。 */
pages: string[];
/** 模板替换运行时或能力包中的页面/组件目录;未声明的同名文件视为冲突。 */
overrides?: string[];
/** 开发时的默认品牌;构建参数 `--brand` 优先。 */
defaultBrandSlug?: string;
dataSlots: TemplateDataSlot[];
templateFields?: TemplateField[];
assetSlots: TemplateAssetSlot[];
admin: TemplateAdminManifest;
trustContentTypes?: TemplateTrustContentType[];
sampleContent?: Record<string, TemplateSampleContent>;
previewFixture: Record<string, unknown>;
};
export function validateTemplatePackageManifest(value: unknown): string[] {
const errors: string[] = [];
if (!value || typeof value !== "object") return ["manifest must be an object"];
const manifest = value as Partial<TemplatePackageManifest>;
for (const issue of validateTemplatePreviewFixtures(
manifest.previewFixture,
manifest.supportedIndustryTemplates ?? [],
))
errors.push(`previewFixture.${issue.path}: ${issue.message}`);
if (!manifest.packageKey?.trim()) errors.push("packageKey is required");
if (!manifest.version?.trim()) errors.push("version is required");
if (!manifest.visualTemplateKey?.trim()) errors.push("visualTemplateKey is required");
if (manifest.packageKey !== manifest.visualTemplateKey)
errors.push("visualTemplateKey must match packageKey");
if (manifest.runtimeContract !== TEMPLATE_RUNTIME_CONTRACT)
errors.push(`runtimeContract must be ${TEMPLATE_RUNTIME_CONTRACT}`);
if (!manifest.displayName?.trim()) errors.push("displayName is required");
const presentation = manifest.visualPresentation;
const validPresentation =
presentation &&
typeof presentation === "object" &&
presentation.description?.trim() &&
presentation.variants &&
typeof presentation.variants === "object" &&
!Array.isArray(presentation.variants) &&
presentation.theme &&
typeof presentation.theme === "object" &&
presentation.theme.colors &&
typeof presentation.theme.colors === "object" &&
presentation.theme.radius &&
typeof presentation.theme.radius === "object";
if (!validPresentation) {
errors.push("visualPresentation requires description, variants, theme.colors and theme.radius");
} else {
const requiredVariant = (key: string) =>
typeof presentation.variants[key] === "string" && presentation.variants[key].trim();
if (!(["hero", "offeringList", "detail"] as const).every(requiredVariant))
errors.push("visualPresentation.variants requires hero, offeringList and detail");
const requiredColor = (key: string) =>
typeof presentation.theme.colors[key] === "string" && presentation.theme.colors[key].trim();
if (!(["background", "foreground", "accent", "dark"] as const).every(requiredColor))
errors.push(
"visualPresentation.theme.colors requires background, foreground, accent and dark",
);
if (
typeof presentation.theme.radius.card !== "string" ||
!presentation.theme.radius.card.trim()
)
errors.push("visualPresentation.theme.radius requires card");
if (presentation.layout) {
const layout = presentation.layout;
if (
!(["home", "offerings", "detail", "profile"] as const).every(
(page) =>
Array.isArray(layout[page]) &&
layout[page].length > 0 &&
layout[page].every((item) => typeof item === "string" && item.trim()),
)
) {
errors.push("visualPresentation.layout must contain non-empty page module arrays");
}
}
}
if (
!Array.isArray(manifest.supportedIndustryTemplates) ||
!manifest.supportedIndustryTemplates.length
)
errors.push("supportedIndustryTemplates must not be empty");
if (!Array.isArray(manifest.navigation) || !manifest.navigation.length)
errors.push("navigation must not be empty");
if (!Array.isArray(manifest.dataSlots) || !manifest.dataSlots.length)
errors.push("dataSlots must not be empty");
else {
for (const slot of manifest.dataSlots) {
if (!slot?.key?.trim() || !slot.description?.trim())
errors.push("every data slot requires key and description");
if (!(["brand", "offering", "trust", "inquiry", "records"] as string[]).includes(slot.source))
errors.push("data slot source is invalid");
}
}
for (const [index, field] of (manifest.templateFields ?? []).entries()) {
if (!field?.key?.trim() || !field?.label?.trim())
errors.push(`templateFields.${index} requires key and label`);
if (field.binding && !field.binding.startsWith("brand.config.templateData."))
errors.push(`templateFields.${index}.binding must target templateData`);
if (field.input === "list" && !field.itemFields?.length)
errors.push(`templateFields.${index}.list requires itemFields`);
}
if (manifest.trustContentTypes !== undefined) {
if (!Array.isArray(manifest.trustContentTypes))
errors.push("trustContentTypes must be an array");
else {
for (const [index, item] of manifest.trustContentTypes.entries()) {
if (!item || typeof item !== "object") {
errors.push(`trustContentTypes.${index} must be an object`);
continue;
}
if (typeof item.type !== "string" || !item.type.trim())
errors.push(`trustContentTypes.${index}.type is required`);
if (typeof item.label !== "string" || !item.label.trim())
errors.push(`trustContentTypes.${index}.label is required`);
for (const key of ["title", "summary", "content"] as const) {
if (typeof item.adminFields?.[key] !== "string" || !item.adminFields[key].trim())
errors.push(`trustContentTypes.${index}.adminFields.${key} is required`);
}
for (const page of item.pages ?? []) {
if (!manifest.entrypoints?.[page])
errors.push(`trustContentTypes.${index}.pages contains an undeclared entrypoint`);
}
if (
item.maxPublishedItems !== undefined &&
(!Number.isInteger(item.maxPublishedItems) || item.maxPublishedItems < 1)
)
errors.push(`trustContentTypes.${index}.maxPublishedItems must be a positive integer`);
for (const field of item.configFields ?? []) {
if (!field.key?.trim() || !field.binding?.startsWith("trust.config."))
errors.push(`trustContentTypes.${index}.configFields binding is invalid`);
if (field.input === "list" && !field.itemFields?.length)
errors.push(`trustContentTypes.${index}.configFields list requires itemFields`);
}
}
}
}
if (manifest.sampleContent && typeof manifest.sampleContent === "object") {
for (const [industry, sample] of Object.entries(manifest.sampleContent)) {
if (!sample.inquiryFormName?.trim())
errors.push(`sampleContent.${industry}.inquiryFormName is required`);
for (const [index, item] of (sample.trustContent ?? []).entries()) {
if (!manifest.trustContentTypes?.some((type) => type.type === item.type))
errors.push(
`sampleContent.${industry}.trustContent.${index} uses an undeclared trust content type`,
);
}
for (const [index, field] of (sample.fields ?? []).entries()) {
if (
typeof field.key !== "string" ||
!field.key.trim() ||
typeof field.label !== "string" ||
!field.label.trim()
)
errors.push(`sampleContent.${industry}.fields.${index} requires key and label`);
if (
![
"text",
"tel",
"phone",
"number",
"select",
"radio",
"multi-select",
"textarea",
"date",
].includes(String(field.type))
)
errors.push(`sampleContent.${industry}.fields.${index} has an unsupported Runtime type`);
}
}
}
if (!Array.isArray(manifest.assetSlots)) errors.push("assetSlots must be an array");
else {
for (const slot of manifest.assetSlots) {
if (!slot?.key?.trim() || !slot.binding?.trim() || !slot.label?.trim() || !slot.help?.trim())
errors.push("every asset slot requires key, binding, label and help");
}
}
if (!manifest.admin || !Array.isArray(manifest.admin.sections) || !manifest.admin.sections.length)
errors.push("admin.sections must not be empty");
else {
for (const section of manifest.admin.sections) {
if (!section?.key?.trim() || !section.title?.trim() || !section.description?.trim())
errors.push("every admin section requires key, title and description");
if (!section?.page?.trim() || !manifest.entrypoints?.[section.page])
errors.push(
`admin section ${section?.key ?? "<unknown>"} must target a declared entrypoint`,
);
if (!Array.isArray(section.fields) || !section.fields.length)
errors.push("every admin section must contain fields");
for (const field of section.fields ?? []) {
if (!field?.key?.trim() || !field.binding?.trim() || !field.label?.trim())
errors.push("every admin field requires key, binding and label");
if (field.input === "list" && !field.itemFields?.length)
errors.push("list admin fields require itemFields");
if (
field.itemValueKey &&
!field.itemFields?.some((item) => item.key === field.itemValueKey)
)
errors.push("list itemValueKey must match an itemField");
}
}
}
if (!Array.isArray(manifest.requiredCapabilities))
errors.push("requiredCapabilities must be an array");
if (!Array.isArray(manifest.pages) || !manifest.pages.length)
errors.push("pages must not be empty");
else if (manifest.pages.some((page) => typeof page !== "string" || !PAGE_PATH_PATTERN.test(page)))
errors.push("pages must contain mini program page paths such as pages/index/index");
if (manifest.overrides !== undefined) {
if (
!Array.isArray(manifest.overrides) ||
manifest.overrides.some((item) => typeof item !== "string" || !LAYER_PATH_PATTERN.test(item))
)
errors.push("overrides must contain pages/... or components/... directories");
}
for (const item of manifest.navigation ?? []) {
if (!item?.key?.trim() || !item.label?.trim())
errors.push("navigation items require key and label");
if (typeof item?.page !== "string" || typeof manifest.entrypoints?.[item.page] !== "string")
errors.push(`navigation page is not a declared entrypoint: ${String(item?.key)}`);
}
for (const page of [
"home",
"offerings",
"detail",
"inquiry",
"success",
"records",
"profile",
] as const) {
if (!manifest.entrypoints || typeof manifest.entrypoints[page] !== "string")
errors.push(`entrypoints.${page} is required`);
}
for (const [key, page] of Object.entries(manifest.entrypoints ?? {})) {
if (typeof page !== "string" || !PAGE_PATH_PATTERN.test(page))
errors.push(`entrypoints.${key} must be a mini program page path`);
}
if (manifest.sampleContent !== undefined) {
for (const [industryKey, sample] of Object.entries(manifest.sampleContent)) {
if (!manifest.supportedIndustryTemplates?.includes(industryKey))
errors.push(`sampleContent.${industryKey} is not a supported industry template`);
if (sample.templateKey !== industryKey)
errors.push(`sampleContent.${industryKey}.templateKey must match its key`);
if (!Array.isArray(sample.offerings) || !Array.isArray(sample.trustContent))
errors.push(`sampleContent.${industryKey} requires offerings and trustContent arrays`);
if (!Array.isArray(sample.fields) || !sample.fields.length)
errors.push(`sampleContent.${industryKey} requires fields`);
for (const field of sample.fields ?? []) {
if (typeof field.key !== "string" || typeof field.label !== "string")
errors.push(`sampleContent.${industryKey} fields require key and label`);
if (["select", "radio", "multi-select"].includes(String(field.type))) {
if (!Array.isArray(field.options) || !field.options.length)
errors.push(`sampleContent.${industryKey}.${String(field.key)} requires options`);
}
}
}
}
return errors;
}
/**
* 能力包清单(packages/capability-<key>/capability.json)。
* 能力包为需要独立业务流程的能力提供小程序页面,由模板的 requiredCapabilities 引入。
*/
export type CapabilityPackageManifest = {
key: string;
version: string;
runtimeContract: typeof TEMPLATE_RUNTIME_CONTRACT;
description: string;
pages: string[];
};
export function validateCapabilityPackageManifest(value: unknown): string[] {
const errors: string[] = [];
if (!value || typeof value !== "object") return ["capability manifest must be an object"];
const manifest = value as Partial<CapabilityPackageManifest>;
if (!manifest.key?.trim()) errors.push("key is required");
if ((CORE_CAPABILITIES as readonly string[]).includes(manifest.key ?? ""))
errors.push(`${manifest.key} is a core capability provided by the runtime`);
if (!manifest.version?.trim()) errors.push("version is required");
if (manifest.runtimeContract !== TEMPLATE_RUNTIME_CONTRACT)
errors.push(`runtimeContract must be ${TEMPLATE_RUNTIME_CONTRACT}`);
if (!manifest.description?.trim()) errors.push("description is required");
if (!Array.isArray(manifest.pages) || !manifest.pages.length)
errors.push("pages must not be empty");
else if (manifest.pages.some((page) => typeof page !== "string" || !PAGE_PATH_PATTERN.test(page)))
errors.push("pages must contain mini program page paths");
return errors;
}