feat: 建立视觉模板包契约与林境映射

This commit is contained in:
que01 committed 2026-09-23 14:18:28 +08:00
1 parent 241c19812f
commit 031c81a7c1
9 files changed
+427

No files matched your search

@@ -0,0 +1,26 @@
# 小程序视觉模板包体系
## 目标
将当前仅包含主题颜色和少量变体的视觉配置,升级为可安装、可验证、可快照、可演进的小程序视觉模板包。视觉模板负责页面结构、模块变体、设计令牌和资源槽位;行业模板负责业务表达;能力插件负责咨询、预约、报价和状态流转。个人品牌身份、信任证明和转化路径始终是所有模板的共同主线。
## 交付边界
- 第一阶段定义 `VisualTemplateManifest` 和 `TemplatePackage` 契约,并完成林境模板映射,供用户验收。
- 第二阶段再改造小程序渲染器,使页面按 manifest 和 variant 组合渲染。
- 第三阶段补齐模板安装、初始数据导入、快照、升级和回滚。
- 第四阶段建立接口、构建、fixture 和截图回归门禁。
## 设计约束
- Stitch 产物只能作为设计输入,不能直接作为生产运行时。
- 视觉模板不可写入行业术语和业务字段;行业字段通过数据槽位和能力配置注入。
- 模板默认内容可编辑,模板结构约束和必需模块由安装器维护。
- 所有公共内容必须通过品牌上下文隔离;模板包不能携带跨品牌数据。
## 完成标准
- 所有子任务均为 `DONE`;
- manifest 类型可被 config、API 和 Miniapp 共享使用;
- 林境模板覆盖核心页面、模块顺序、资源槽位、数据槽位和能力依赖;
- 通过格式、config typecheck、API typecheck、API integration、Miniapp fixture 和 visual fixture 门禁。
@@ -0,0 +1,15 @@
# 进度
- 任务:小程序视觉模板包体系
- 形态:epic
- 进度:2/5
- 当前:子任务 1、2 已完成,等待用户验收视觉模板契约;子任务 3 暂不开始
- 真相文件:`SUBTASKS.csv`
## 恢复信息
- 多品牌隔离、品牌上下文和运行时 seed 数据已完成并提交。
- 已新增 `VisualTemplateManifest`、`TemplatePackage`、页面/模块/资源/数据槽位和设计 token 类型。
- 已将林境模板登记为 7 个核心页面的正式 manifest,并保留个人品牌主线、行业解耦和能力依赖。
- `pnpm format:check`、`pnpm --filter @personal-brand/config typecheck`、`git diff --check` 已通过。
- 当前等待用户验收契约和林境映射;确认后才能进入渲染器、安装器和快照实现。
@@ -0,0 +1,6 @@
id,title,task_type,depends_on,status,task_dir,acceptance_criteria,validation_command,notes
1,定义视觉模板包契约,single-full,,DONE,tasks/contract,VisualTemplateManifest 和 TemplatePackage 类型及契约说明完成,pnpm format:check && pnpm --filter @personal-brand/config typecheck,共享契约和 ADR 已完成
2,将林境静态设计映射为正式视觉模板,single-full,1,DONE,tasks/linjing-mapping,林境核心页面和资源数据映射到 manifest,pnpm --filter @personal-brand/config typecheck,7 个页面、模块变体、资源槽位、数据槽位和能力依赖已登记
3,改造小程序按 manifest 和 variant 渲染,single-full,1;2,TODO,tasks/miniapp-renderer,小程序不再依赖行业硬编码页面结构,pnpm --filter @personal-brand/miniapp test:fixture && pnpm --filter @personal-brand/miniapp test:visual-fixture,依赖前两项及用户验收
4,初始数据导入与模板安装快照,single-full,1;2,TODO,tasks/installation,新品牌可安装模板并导入初始内容且生成快照,pnpm --filter @personal-brand/api test:integration,与安装器和品牌隔离联动
5,视觉与全量回归,single-full,1;2;3;4,TODO,tasks/regression,接口、构建、fixture 和视觉回归全部通过,pnpm format:check && pnpm lint && pnpm typecheck && pnpm --filter @personal-brand/api test:integration,最终收口
1 id title task_type depends_on status task_dir acceptance_criteria validation_command notes
2 1 定义视觉模板包契约 single-full DONE tasks/contract VisualTemplateManifest 和 TemplatePackage 类型及契约说明完成 pnpm format:check && pnpm --filter @personal-brand/config typecheck 共享契约和 ADR 已完成
3 2 将林境静态设计映射为正式视觉模板 single-full 1 DONE tasks/linjing-mapping 林境核心页面和资源数据映射到 manifest pnpm --filter @personal-brand/config typecheck 7 个页面、模块变体、资源槽位、数据槽位和能力依赖已登记
4 3 改造小程序按 manifest 和 variant 渲染 single-full 1;2 TODO tasks/miniapp-renderer 小程序不再依赖行业硬编码页面结构 pnpm --filter @personal-brand/miniapp test:fixture && pnpm --filter @personal-brand/miniapp test:visual-fixture 依赖前两项及用户验收
5 4 初始数据导入与模板安装快照 single-full 1;2 TODO tasks/installation 新品牌可安装模板并导入初始内容且生成快照 pnpm --filter @personal-brand/api test:integration 与安装器和品牌隔离联动
6 5 视觉与全量回归 single-full 1;2;3;4 TODO tasks/regression 接口、构建、fixture 和视觉回归全部通过 pnpm format:check && pnpm lint && pnpm typecheck && pnpm --filter @personal-brand/api test:integration 最终收口
@@ -0,0 +1,6 @@
# 视觉模板包契约
- 状态:DONE
- 范围:共享类型、注册表和 ADR
- 完成条件:config typecheck 与格式检查通过,并由用户验收契约方向
- 验证:`pnpm --filter @personal-brand/config typecheck`、`pnpm format:check`
@@ -0,0 +1,6 @@
# 林境模板映射
- 状态:DONE
- 依赖:视觉模板包契约
- 结果:登记首页、业务列表、详情、咨询、成功、记录、主理人 7 个页面,以及模块变体、资源槽位、数据槽位和能力依赖。
- 验证:`pnpm --filter @personal-brand/config typecheck`
@@ -0,0 +1,4 @@
# 小程序渲染器
- 状态:TODO
- 依赖:视觉模板包契约、林境模板映射和用户验收
@@ -0,0 +1,4 @@
# 回归验证
- 状态:TODO
- 依赖:前置实现全部完成
@@ -0,0 +1,31 @@
# ADR 0008:小程序视觉模板包契约
## 背景
现有视觉模板只有颜色、圆角和少量页面变体,无法忠实承载 Stitch 设计中的页面结构、模块顺序、图片资源和数据依赖。继续在页面代码中增加行业分支会让视觉和业务耦合,且新品牌无法可靠导入初始内容。
## 决策
引入共享的 `VisualTemplateManifest` 和 `TemplatePackage` 契约。视觉 manifest 明确页面、模块、variant、设计 tokens、资源槽位、数据槽位和能力依赖;模板包在此基础上携带可导入的内容、表单、能力和 fixture。视觉模板只描述呈现结构,不写死行业字段;行业模板和能力插件通过数据槽位与能力 key 连接。
模板安装必须以 manifest 为边界,完成结构校验、数据导入和快照生成。Stitch HTML 仅作为映射输入,不能直接作为小程序运行时。
## 备选方案
- 继续扩展 `VisualTemplateDefinition`:无法表达资源、数据和安装边界,且容易继续堆叠可选字段。
- 每个行业复制一套 Miniapp 页面:视觉还原快,但品牌主线和跨行业复用失败,后续维护成本不可控。
- 直接运行 Stitch HTML:与小程序组件、接口、无障碍和测试体系不一致,不可作为生产方案。
## 后果
- 需要先建立 manifest 和映射,再改造 Miniapp 渲染器;短期类型和配置增加,长期可避免页面硬编码。
- 模板安装、升级、快照和回滚可以共享同一份契约;模板默认内容仍可被品牌编辑。
- 视觉回归需要固定 fixture 和截图基线,模板交付周期会增加,但能够在用户验收前发现明显偏差。
## 迁移计划
1. 定义共享类型并登记林境 manifest;
2. 将现有 `VisualTemplateDefinition` 兼容映射到新 manifest;
3. 改造 Miniapp 页面按页面 schema 和模块 registry 渲染;
4. 增加模板安装、初始数据导入和快照;
5. 以接口、构建、fixture 和截图测试作为发布门禁。
+329
View File
@@ -98,6 +98,335 @@ export interface VisualTemplateDefinition {
layout?: { home: string[]; offerings: string[]; detail: string[]; profile: string[] };
}
export type VisualPageKey =
"home" | "offerings" | "detail" | "inquiry" | "success" | "records" | "profile";
export type VisualModuleType =
| "brand-identity"
| "hero"
| "trust"
| "offering-list"
| "offering-detail"
| "inquiry-form"
| "success-summary"
| "records-list"
| "contact";
export interface VisualTokenSet {
colors: Record<string, string>;
spacing: Record<string, string>;
typography: Record<string, string>;
radius: Record<string, string>;
shadows?: Record<string, string>;
}
export interface VisualAssetSlot {
key: string;
label: string;
required: boolean;
kind: "image" | "icon" | "logo" | "texture";
aspectRatio?: string;
fallback?: string;
}
export interface VisualDataSlot {
key: string;
source: "brand" | "trust" | "offering" | "inquiry" | "records" | "profile";
required: boolean;
description: string;
}
export interface VisualModuleDefinition {
key: string;
type: VisualModuleType;
variant: string;
required: boolean;
dataSlots?: string[];
assetSlots?: string[];
capability?: CapabilityKey;
}
export interface VisualPageDefinition {
key: VisualPageKey;
title: string;
modules: VisualModuleDefinition[];
}
export interface VisualTemplateManifest {
schemaVersion: "1.0";
key: VisualTemplateKey;
version: string;
name: string;
description: string;
brandFirst: true;
tokens: VisualTokenSet;
pages: VisualPageDefinition[];
assets: VisualAssetSlot[];
dataSlots: VisualDataSlot[];
capabilities: CapabilityKey[];
}
export interface TemplatePackage {
manifest: VisualTemplateManifest;
industryTemplateKey: BrandTemplateKey;
content: Record<string, unknown>;
forms: Record<string, unknown>[];
capabilityConfig: Record<string, unknown>;
fixtures: {
runtime: Record<string, unknown>;
visual: Record<string, unknown>;
};
}
const linjingEditorialManifest: VisualTemplateManifest = {
schemaVersion: "1.0",
key: "linjing-editorial",
version: "1.0.0",
name: "林境建筑画册",
description: "以个人品牌信任为主线、以高端项目作品为表达重点的编辑式视觉模板。",
brandFirst: true,
tokens: {
colors: {
background: "#F7F5F1",
surface: "#FFFFFF",
foreground: "#252525",
muted: "#77736C",
accent: "#8A6846",
dark: "#202221",
},
spacing: { page: "32rpx", section: "56rpx", module: "24rpx" },
typography: { display: "56rpx", heading: "36rpx", body: "28rpx", caption: "22rpx" },
radius: { card: "16rpx", button: "999rpx", media: "12rpx" },
shadows: { card: "0 8rpx 32rpx rgba(32,34,33,0.08)" },
},
assets: [
{ key: "brand.logo", label: "品牌标志", required: false, kind: "logo" },
{
key: "home.hero",
label: "首页首屏图",
required: true,
kind: "image",
aspectRatio: "16:9",
},
{
key: "offering.cover",
label: "业务提供项封面",
required: true,
kind: "image",
aspectRatio: "1:1",
},
{
key: "profile.portrait",
label: "主理人肖像",
required: false,
kind: "image",
aspectRatio: "1:1",
},
{ key: "brand.texture", label: "品牌底纹", required: false, kind: "texture" },
],
dataSlots: [
{
key: "brand.identity",
source: "brand",
required: true,
description: "品牌名、定位和主理人身份",
},
{ key: "brand.hero", source: "brand", required: true, description: "品牌首屏表达和行动入口" },
{ key: "trust.proof", source: "trust", required: true, description: "经历、资质、案例和方法" },
{
key: "offerings.list",
source: "offering",
required: true,
description: "可展示的业务提供项",
},
{
key: "offering.detail",
source: "offering",
required: true,
description: "单个提供项的详情内容",
},
{ key: "inquiry.form", source: "inquiry", required: true, description: "品牌咨询或预约表单" },
{
key: "records.items",
source: "records",
required: true,
description: "用户提交后的跟进记录",
},
{
key: "profile.contact",
source: "profile",
required: true,
description: "联系方式和合作预期",
},
],
pages: [
{
key: "home",
title: "首页",
modules: [
{
key: "identity",
type: "brand-identity",
variant: "editorial-card",
required: true,
dataSlots: ["brand.identity"],
assetSlots: ["brand.logo"],
},
{
key: "hero",
type: "hero",
variant: "architectural",
required: true,
dataSlots: ["brand.hero"],
assetSlots: ["home.hero"],
},
{
key: "proof",
type: "trust",
variant: "proof-strip",
required: true,
dataSlots: ["trust.proof"],
},
{
key: "offerings",
type: "offering-list",
variant: "editorial-list",
required: true,
dataSlots: ["offerings.list"],
assetSlots: ["offering.cover"],
capability: "offerings",
},
{
key: "contact",
type: "contact",
variant: "quiet-footer",
required: true,
dataSlots: ["profile.contact"],
},
],
},
{
key: "offerings",
title: "业务提供项",
modules: [
{
key: "offerings",
type: "offering-list",
variant: "editorial-grid",
required: true,
dataSlots: ["offerings.list"],
assetSlots: ["offering.cover"],
capability: "offerings",
},
],
},
{
key: "detail",
title: "提供项详情",
modules: [
{
key: "detail",
type: "offering-detail",
variant: "project-case",
required: true,
dataSlots: ["offering.detail"],
assetSlots: ["offering.cover"],
capability: "offerings",
},
],
},
{
key: "inquiry",
title: "咨询与预约",
modules: [
{
key: "inquiry",
type: "inquiry-form",
variant: "editorial-form",
required: true,
dataSlots: ["inquiry.form"],
capability: "inquiry",
},
],
},
{
key: "success",
title: "提交成功",
modules: [
{
key: "success",
type: "success-summary",
variant: "editorial-confirmation",
required: true,
dataSlots: ["brand.identity"],
},
],
},
{
key: "records",
title: "我的记录",
modules: [
{
key: "records",
type: "records-list",
variant: "timeline",
required: true,
dataSlots: ["records.items"],
},
],
},
{
key: "profile",
title: "主理人与我",
modules: [
{
key: "identity",
type: "brand-identity",
variant: "profile-editorial",
required: true,
dataSlots: ["brand.identity"],
assetSlots: ["profile.portrait"],
},
{
key: "contact",
type: "contact",
variant: "contact-sheet",
required: true,
dataSlots: ["profile.contact"],
},
],
},
],
capabilities: ["offerings", "inquiry"],
};
export const visualTemplateManifests: Record<VisualTemplateKey, VisualTemplateManifest> = {
"linjing-editorial": linjingEditorialManifest,
"minimal-neutral": {
...linjingEditorialManifest,
key: "minimal-neutral",
version: "1.0.0",
name: "极简留白",
description: "适合咨询、设计和专业服务型个人品牌的中性视觉模板。",
tokens: {
...linjingEditorialManifest.tokens,
colors: {
background: "#FAFAF8",
surface: "#FFFFFF",
foreground: "#202221",
muted: "#6B7280",
accent: "#4B5563",
dark: "#202221",
},
radius: { card: "8rpx", button: "8rpx", media: "8rpx" },
},
},
};
export function getVisualTemplateManifest(key: string): VisualTemplateManifest | undefined {
return visualTemplateManifests[key as VisualTemplateKey];
}
export const visualTemplates: Record<VisualTemplateKey, VisualTemplateDefinition> = {
"linjing-editorial": {
key: "linjing-editorial",