From 031c81a7c1b8f0e3b1312c1e9cd7383d750e7752 Mon Sep 17 00:00:00 2001 From: que01 Date: Wed, 23 Sep 2026 14:18:28 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=BB=BA=E7=AB=8B=E8=A7=86=E8=A7=89?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF=E5=8C=85=E5=A5=91=E7=BA=A6=E4=B8=8E=E6=9E=97?= =?UTF-8?q?=E5=A2=83=E6=98=A0=E5=B0=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../visual-template-package-epic/EPIC.md | 26 ++ .../visual-template-package-epic/PROGRESS.md | 15 + .../visual-template-package-epic/SUBTASKS.csv | 6 + .../tasks/contract/PROGRESS.md | 6 + .../tasks/linjing-mapping/PROGRESS.md | 6 + .../tasks/miniapp-renderer/PROGRESS.md | 4 + .../tasks/regression/PROGRESS.md | 4 + .../0008-visual-template-package-contract.md | 31 ++ packages/config/src/index.ts | 329 ++++++++++++++++++ 9 files changed, 427 insertions(+) create mode 100644 .codex-tasks/visual-template-package-epic/EPIC.md create mode 100644 .codex-tasks/visual-template-package-epic/PROGRESS.md create mode 100644 .codex-tasks/visual-template-package-epic/SUBTASKS.csv create mode 100644 .codex-tasks/visual-template-package-epic/tasks/contract/PROGRESS.md create mode 100644 .codex-tasks/visual-template-package-epic/tasks/linjing-mapping/PROGRESS.md create mode 100644 .codex-tasks/visual-template-package-epic/tasks/miniapp-renderer/PROGRESS.md create mode 100644 .codex-tasks/visual-template-package-epic/tasks/regression/PROGRESS.md create mode 100644 docs/adr/0008-visual-template-package-contract.md diff --git a/.codex-tasks/visual-template-package-epic/EPIC.md b/.codex-tasks/visual-template-package-epic/EPIC.md new file mode 100644 index 0000000..d315e90 --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/EPIC.md @@ -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 门禁。 diff --git a/.codex-tasks/visual-template-package-epic/PROGRESS.md b/.codex-tasks/visual-template-package-epic/PROGRESS.md new file mode 100644 index 0000000..9925d4d --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/PROGRESS.md @@ -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` 已通过。 +- 当前等待用户验收契约和林境映射;确认后才能进入渲染器、安装器和快照实现。 diff --git a/.codex-tasks/visual-template-package-epic/SUBTASKS.csv b/.codex-tasks/visual-template-package-epic/SUBTASKS.csv new file mode 100644 index 0000000..898b324 --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/SUBTASKS.csv @@ -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,最终收口 diff --git a/.codex-tasks/visual-template-package-epic/tasks/contract/PROGRESS.md b/.codex-tasks/visual-template-package-epic/tasks/contract/PROGRESS.md new file mode 100644 index 0000000..40b141c --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/tasks/contract/PROGRESS.md @@ -0,0 +1,6 @@ +# 视觉模板包契约 + +- 状态:DONE +- 范围:共享类型、注册表和 ADR +- 完成条件:config typecheck 与格式检查通过,并由用户验收契约方向 +- 验证:`pnpm --filter @personal-brand/config typecheck`、`pnpm format:check` diff --git a/.codex-tasks/visual-template-package-epic/tasks/linjing-mapping/PROGRESS.md b/.codex-tasks/visual-template-package-epic/tasks/linjing-mapping/PROGRESS.md new file mode 100644 index 0000000..affebe3 --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/tasks/linjing-mapping/PROGRESS.md @@ -0,0 +1,6 @@ +# 林境模板映射 + +- 状态:DONE +- 依赖:视觉模板包契约 +- 结果:登记首页、业务列表、详情、咨询、成功、记录、主理人 7 个页面,以及模块变体、资源槽位、数据槽位和能力依赖。 +- 验证:`pnpm --filter @personal-brand/config typecheck` diff --git a/.codex-tasks/visual-template-package-epic/tasks/miniapp-renderer/PROGRESS.md b/.codex-tasks/visual-template-package-epic/tasks/miniapp-renderer/PROGRESS.md new file mode 100644 index 0000000..72e0d24 --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/tasks/miniapp-renderer/PROGRESS.md @@ -0,0 +1,4 @@ +# 小程序渲染器 + +- 状态:TODO +- 依赖:视觉模板包契约、林境模板映射和用户验收 diff --git a/.codex-tasks/visual-template-package-epic/tasks/regression/PROGRESS.md b/.codex-tasks/visual-template-package-epic/tasks/regression/PROGRESS.md new file mode 100644 index 0000000..5e9b6c0 --- /dev/null +++ b/.codex-tasks/visual-template-package-epic/tasks/regression/PROGRESS.md @@ -0,0 +1,4 @@ +# 回归验证 + +- 状态:TODO +- 依赖:前置实现全部完成 diff --git a/docs/adr/0008-visual-template-package-contract.md b/docs/adr/0008-visual-template-package-contract.md new file mode 100644 index 0000000..ebe8bbe --- /dev/null +++ b/docs/adr/0008-visual-template-package-contract.md @@ -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 和截图测试作为发布门禁。 diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts index 09f072e..0551df8 100644 --- a/packages/config/src/index.ts +++ b/packages/config/src/index.ts @@ -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; + spacing: Record; + typography: Record; + radius: Record; + shadows?: Record; +} + +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; + forms: Record[]; + capabilityConfig: Record; + fixtures: { + runtime: Record; + visual: Record; + }; +} + +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 = { + "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 = { "linjing-editorial": { key: "linjing-editorial",