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 & { 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; templateKey: string; inquiryFormName: string; offerings: Array & { priceAmount?: number }>; trustContent: Array>; fields: Array>; capabilityKey: string; }; export type TemplateVisualPresentation = { description: string; variants: Record; theme: { colors: Record; radius: Record }; 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; 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; previewFixture: Record; }; 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; 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 ?? ""} 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-/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; 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; }