feat: 建立视觉模板包契约与林境映射
This commit is contained in:
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,最终收口
|
||||
|
@@ -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 和截图测试作为发布门禁。
|
||||
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user