refactor: 重构模板叠加式编译产物
This commit is contained in:
1 parent
c46297b13b
commit
25d1fe983c
93 files changed
+870
-2467
No files matched your search
@@ -1,3 +1,13 @@
|
||||
# Template Contract
|
||||
|
||||
模板包是构建期输入。模板必须声明 runtime contract、页面入口、导航、行业兼容性和能力依赖;不得在模板包中实现数据库访问、鉴权或业务状态机。
|
||||
|
||||
## 新增模板
|
||||
|
||||
1. 在 `packages/template-<key>/` 创建 `template.json` 和 `miniapp/`。
|
||||
2. 在 manifest 中声明 `entrypoints`、`pages`、`navigation`、`requiredCapabilities`、数据槽位、媒体槽位和面向管理员的 `admin.sections`。
|
||||
3. 将模板自己的页面、组件、tab 图标和 `miniapp/app.json` 放入模板包。页面必须提供 `.js`、`.json`、`.wxml`、`.wxss` 四个文件。
|
||||
4. 如果需要替换运行时或能力包页面,必须在 `overrides` 中声明目录;未声明的同路径文件会被 compiler 拒绝。
|
||||
5. 执行 `pnpm generate:template-catalog --write`、`pnpm validate:templates` 和 `pnpm test:template-compiler`。
|
||||
|
||||
使用 `pnpm template:dev <key> --brand <slug>` 生成微信开发者工具项目。生产构建还必须提供 `--appid` 和 HTTPS `--api`。模板在构建时选择,运行时不会下载或解释模板代码。
|
||||
@@ -3,9 +3,13 @@ export const TEMPLATE_RUNTIME_CONTRACT = "1.0" as const;
|
||||
export type TemplatePageKey =
|
||||
"home" | "offerings" | "detail" | "inquiry" | "success" | "records" | "profile" | (string & {});
|
||||
|
||||
export type TemplateRenderers = Partial<Record<"home" | "offerings" | "profile", string>>;
|
||||
/** 运行时(apps/miniapp)提供的核心能力,不需要能力包。 */
|
||||
export const CORE_CAPABILITIES = ["offerings", "inquiry"] as const;
|
||||
|
||||
export type TemplateRuntimeOwnedPage = "detail" | "inquiry" | "success" | "records";
|
||||
/** 小程序页面路径,例如 `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。
|
||||
@@ -83,9 +87,12 @@ export type TemplatePackageManifest = {
|
||||
selectedIconPath?: string;
|
||||
}>;
|
||||
requiredCapabilities: string[];
|
||||
renderers?: TemplateRenderers;
|
||||
runtimeOwnedPages?: TemplateRuntimeOwnedPage[];
|
||||
ownedPaths?: string[];
|
||||
/** 模板包自己提供的页面;编译器据此生成 app.json。 */
|
||||
pages: string[];
|
||||
/** 模板替换运行时或能力包中的页面/组件目录;未声明的同名文件视为冲突。 */
|
||||
overrides?: string[];
|
||||
/** 开发时的默认品牌;构建参数 `--brand` 优先。 */
|
||||
defaultBrandSlug?: string;
|
||||
dataSlots: TemplateDataSlot[];
|
||||
assetSlots: TemplateAssetSlot[];
|
||||
admin: TemplateAdminManifest;
|
||||
@@ -139,13 +146,25 @@ export function validateTemplatePackageManifest(value: unknown): string[] {
|
||||
}
|
||||
}
|
||||
}
|
||||
if (manifest.ownedPaths !== undefined && !Array.isArray(manifest.ownedPaths))
|
||||
errors.push("ownedPaths must be an array when provided");
|
||||
if (
|
||||
manifest.renderers !== undefined &&
|
||||
(typeof manifest.renderers !== "object" || Array.isArray(manifest.renderers))
|
||||
)
|
||||
errors.push("renderers must be an object when provided");
|
||||
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",
|
||||
@@ -158,6 +177,10 @@ export function validateTemplatePackageManifest(value: unknown): string[] {
|
||||
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))
|
||||
@@ -180,3 +203,33 @@ export function validateTemplatePackageManifest(value: unknown): string[] {
|
||||
}
|
||||
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;
|
||||
}
|
||||
Reference in new issue
Block a user