From e4adfc6b13dfc0a52d6a01216453467e8ee000e3 Mon Sep 17 00:00:00 2001 From: que01 Date: Sun, 20 Sep 2026 11:59:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E5=B0=8F=E7=A8=8B?= =?UTF-8?q?=E5=BA=8F=E8=AE=BE=E8=AE=A1=E4=B8=8E=E6=A8=A1=E6=9D=BF=E6=B8=B2?= =?UTF-8?q?=E6=9F=93=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/miniapp-design-system.md | 56 +++++++++++++++++++++++ docs/miniapp-information-architecture.md | 50 +++++++++++++++++++++ docs/miniapp-template-rendering.md | 57 ++++++++++++++++++++++++ 3 files changed, 163 insertions(+) create mode 100644 docs/miniapp-design-system.md create mode 100644 docs/miniapp-information-architecture.md create mode 100644 docs/miniapp-template-rendering.md diff --git a/docs/miniapp-design-system.md b/docs/miniapp-design-system.md new file mode 100644 index 0000000..705f02e --- /dev/null +++ b/docs/miniapp-design-system.md @@ -0,0 +1,56 @@ +# 小程序 Design System + +## 目标 + +小程序通过个人品牌表达建立信任,并将信任转化为咨询、合作或预约。组件库只提供稳定交互能力,最终视觉由品牌层统一控制。 + +## 视觉 Token + +基础 Token 统一维护在 `apps/miniapp/styles/tokens.wxss`: + +- 背景:暖白 `#FBF7F1`、米黄 `#F4EBD9`; +- 主色:砖红 `#B54A2C`,交互按下态使用更深砖红; +- 文字:深炭黑 `#2B2B2B`,辅助文字使用深棕 `#7A4A2B`; +- 强调色:浅橙 `#E8A75F`; +- 页面左右安全边距:`32rpx`; +- 卡片圆角:`16rpx`;控件圆角:`12rpx`。 + +行业模板不得覆盖基础 Token。未来如需品牌换肤,应通过版本化 Token 配置实现,不在页面中写死行业颜色。 + +## 组件分层 + +### 基础能力层 + +`tdesign-miniprogram` 负责输入、选择、弹层、Loading 和无障碍行为。 + +### 品牌组件层 + +页面只能依赖以下项目组件: + +- `BrandButton` +- `BrandField` +- `BrandSelect` +- `BrandDatePicker` +- `BrandDialog` +- `BrandCard` +- `BrandLoading` +- `BrandEmpty` +- `BrandError` + +品牌组件必须封装 TDesign 的视觉变量,禁止页面直接使用 `t-*` 组件完成业务布局。 + +## 状态规范 + +所有远程数据页面必须显式处理:加载中、空数据、请求失败、提交中、提交成功和提交失败。失败状态必须保留用户输入,并提供可操作的重试或返回路径。 + +## 表单规范 + +- 标签、必填标记、帮助文本和错误文本由 `BrandField` 统一渲染; +- 表单字段来自后端 `InquiryForm`,页面不得按行业写死字段; +- 提交按钮只在成功响应后结束提交状态; +- 字段校验错误显示在对应字段附近,网络错误显示在表单级别; +- 表单提交保存版本和字段快照,历史记录不受后续配置修改影响。 + +## 验收要求 + +组件必须在模拟器和真机验证,覆盖正常、禁用、加载、错误和空数据状态;新增组件必须通过格式检查和小程序类型检查。 diff --git a/docs/miniapp-information-architecture.md b/docs/miniapp-information-architecture.md new file mode 100644 index 0000000..560a0e4 --- /dev/null +++ b/docs/miniapp-information-architecture.md @@ -0,0 +1,50 @@ +# 小程序页面信息架构 + +## 产品主线 + +小程序不是餐饮商城,而是个人品牌信任与业务承接入口。固定流程是: + +```text +认识品牌 → 理解价值 → 查看信任证据 → 选择业务 → 咨询/预约 → 查看后续状态 +``` + +## 底部导航 + +固定保留三个 Tab:`首页`、`服务`、`我的`。预约不是独立 Tab,而是 Offering 详情后的业务动作。 + +### 首页 + +按以下层级表达品牌: + +1. 品牌名和一句话定位; +2. 服务对象与核心价值; +3. 资历、案例、作品或其他信任证据; +4. 代表性 Offering; +5. 合作、咨询或联系入口。 + +### 服务 + +展示后端启用的 Offering,支持 `service`、`product`、`package`、`subscription` 等通用类型。列表只展示摘要,详情页展示完整分区、媒体和 CTA。 + +### 我的 + +展示当前用户的咨询和预约记录,明确状态、下一步动作和联系路径。没有记录时使用品牌化空状态,而不是空白页面。 + +## 业务动作 + +Offering 的 CTA 由后端配置决定: + +- `inquiry`:打开动态咨询表单; +- `booking`:打开预约流程; +- `contact`:拨打电话或复制联系方式; +- `external-link`:打开配置的外部链接。 + +页面不得根据行业名称判断动作,也不得将餐饮流程作为默认业务模型。 + +## 页面状态与导航 + +每个页面都必须支持加载、空数据、错误和重试。Tab 页面使用 `wx.switchTab`,详情和表单使用 `wx.navigateTo`。返回路径必须符合用户当前业务上下文。 + +## 视觉验收 + +个人品牌模板必须优先验证首页、Offering 详情、咨询表单和我的记录四个关键页面;行业模板只能替换内容模块和字段,不能破坏页面层级和品牌信任表达。 diff --git a/docs/miniapp-template-rendering.md b/docs/miniapp-template-rendering.md new file mode 100644 index 0000000..d410a3d --- /dev/null +++ b/docs/miniapp-template-rendering.md @@ -0,0 +1,57 @@ +# 小程序模板渲染边界 + +## 模板定位 + +模板是初始化品牌工作空间的业务表达方案,不是运行时继承体系。安装模板时复制模块、字段和默认内容;运行时以 `BrandWorkspace` 为最终事实来源。 + +`personal` 是默认基准模板,`food` 是行业示例。未来模板可以覆盖咨询、设计、摄影、教育等行业,但不能改变核心品牌模型。 + +## 数据来源 + +小程序只读取公开接口: + +- `/public/brand` +- `/public/workspace` +- `/public/offerings` +- `/public/offerings/:id` +- `/public/inquiry-forms/:id` + +小程序不得直接读取管理接口,也不得自行推断隐藏字段或品牌标识。 + +## 三层字段模型 + +### 核心字段 + +所有品牌都可使用:`name`、`tagline`、`audience`、`valueProposition`、`trustProof`。 + +### 模板字段 + +由模板初始化,例如餐饮的取送方式、摄影的拍摄类型。模板字段必须遵守后端字段类型白名单。 + +### 自定义字段 + +品牌方可以在管理后台增加,用于表达未被模板预见的业务需求。前端根据字段类型渲染,不为单个行业新增页面分支。 + +## Offering 渲染 + +Offering 的统一响应包含基础信息、`sections`、`media` 和 `cta`。分区支持 `text`、`image-list`、`timeline`、`faq`,未知分区必须安全降级,不得导致页面崩溃。 + +## 表单渲染 + +动态咨询表单必须使用后端返回的字段顺序、标签、类型、选项、必填状态和可见条件。提交请求必须携带字段值,服务端负责最终校验;客户端校验只用于即时反馈。 + +## 禁止事项 + +- 禁止 `if (templateKey === "food")` 形式的页面业务分支; +- 禁止把餐饮字段加入共享品牌模型; +- 禁止在小程序配置服务、Offering 或表单; +- 禁止引入购物车、库存、优惠券、会员积分和支付流程; +- 禁止将 TDesign 组件名暴露为行业模板协议。 + +## 演进策略 + +模板升级必须先生成差异预览,再由品牌方选择应用。新增字段和模块采用 additive 方式;删除或重命名必须保留迁移策略,不能破坏已有提交记录。 + +## 验收要求 + +使用 `personal` 和 `food` 两套数据验证同一套页面组件;再使用至少一个自定义字段验证动态表单。三种场景均不得修改页面代码,且接口、字段快照和错误状态测试必须通过。