文档中心 | 芭乐派

ARCHITECTURE.md · 2026-09-06

OpenFlow 架构规范

本文档定义「每个功能唯一实现位置」，防止同功能多实现累积噪声。

新增功能前，先查本文档 + grep 现有 lib/，能复用就不新建。

一、前端资产（唯一实现清单）

| 用途 | 唯一文件 | 说明 |

|------|----------|------|

| 设计 token（配色/间距/圆角） | assets/tokens.css | Open Design 统一，全站唯一 token 源 |

| 组件样式（卡片/按钮/表单等） | assets/modules.css | Open Design 统一组件库 |

| 主页面视觉 | 各 .php 内联 <style> | index/product/capability/courses/about 各自内联 |

| 次级页面样式 | assets/tailwind-build.css | academy/community/docs 等 35 个次级页 |

| 独立页样式 | assets/standalone.css | 问卷/感谢页等 7 个独立页 |

| 次级页面外壳/导航 | assets/site-shell.js | 26 个次级页共用 |

| 首页角色化 | assets/role-content.js + assets/role-switch.js | 仅首页 |

| 埋点注入 | assets/inject.js | 全站 |

| SEO 注入 | assets/seo-inject.js | 主页面 |

| 埋点 SDK | assets/cdp-track.js | 全站 |

探索期的未引用主题变体已经移除；不要恢复未进入当前资产管线的样式和脚本。

二、Markdown 转换（唯一实现）

唯一实现：lib/Markdown.php（Markdown::toHtml / Markdown::extractFrontMatter）

现状存在 4 处重复，需逐步收敛：

✅ lib/Markdown.php — 完整实现（标题/加粗/代码块/链接/图片/列表/引用/表格），目前仅 api/ingest.php 使用
❌ docs.php::md_render — 简化版，应改为调用 Markdown::toHtml
❌ bin/import.php::md_to_html — 简化版，同上
❌ bin/import-drafts.php::md_to_html — 简化版，同上

三、导航系统（现状 3 套 → 目标 1 套）

| 页面 | 现状 | 目标 |

|------|------|------|

| 首页 index.php | SSR 静态导航（Open Design 重构） | 保留 SSR |

| product/capability/courses/about | 内联 NAV 数组 + renderTabs/renderSidebar | 迁到 site-shell.js |

| 次级页面 26 个 | site-shell.js | 唯一实现 |

四、缓存（唯一实现）

唯一实现：lib/Cache.php（Cache::remember / FileCache / RedisCache）

lib/PageCache.php 是页面级缓存封装，内部已用 FileCache，保留但不再另起炉灶。

五、数据存储（两套分工明确）

| 存储 | 用途 | 文件 |

|------|------|------|

| JSON 文件 | 内容型数据（文章/课程/社区/配置） | data/*.json |

| SQLite | 关系型/高频写（会员/订单/日志） | data/db/openflow.db |

规则：内容读多写少用 JSON，事务/关系用 SQLite，不混用。

六、站点配置（唯一入口）

唯一入口：lib/SiteConfig.php（site_config_get()）

品牌名/标语/联系方式等一律走 site_config_get('key')
不要在页面里硬编码品牌名（历史遗留的硬编码已清理）

七、新增功能规范

先查表：本文档 + grep -rn "关键词" lib/，确认没有现成实现

单一实现：同一功能只在一处实现，其他地方 require 复用

命名一致：模块名 = 功能名，不造同义词（如 GrowthDriver vs GrowthEngine 二选一）

品牌单一：产品文案、字段名、注释和资源只使用当前 OpenFlow 品牌与增长业务语义，不保留历史品牌资产

不留备份：工具产生的 .bak* 文件不入库（已在 .gitignore 排除）

不留死代码：删除旧实现后，跑 qa-check.sh 确认无 0 引用残留

八、历史遗留债务（处理进度）

| 债务 | 位置 | 状态 |

|------|------|------|

| flow-community 旧页面名 | config.php、admin/*、data/pages/ | ✅ 已处理：前台按钮改指向 /community，后台页面类型删除 |

| GrowthDriver vs GrowthEngine 命名歧义 | lib/ | ✅ 已处理：GrowthDriver → GrowthFlywheel |

| CdpSystem / CdpInsight / CdpSync 边界 | lib/ | ✅ 已处理：三文件加了三层架构边界注释 |

| FlowSystem / CanvasSystem / AutomationSystem 关系 | lib/ | ✅ 已处理：三文件加了「流程编排三件套」边界注释 |

九、后台页面组件规范（对齐设计稿 openflow-admin.html）

后台视觉契约源：/Users/seveno/Downloads/openflow-admin.html（Open Design 运营台原型）。

后台公共样式全部集中在 admin/config.php 的 <style>，页面内不写零散样式。

| 组件 | class | 说明 |

|------|-------|------|

| 页面头 | .v-head + .v-sub + .v-actions | 页面标题区 |

| KPI 网格 | .kpi-grid + .kpi（.k-label/.k-val/.k-sub） | 指标卡 |

| 面板 | .panels + .panel（.p-head/.p-body） | 双栏/两栏面板 |

| 引擎卡 | .eng + .param-grid + .param | 增长引擎状态 |

| 待办 | .todo-row（.t-ic/.t-b/.t-t/.t-d） | 待办队列 |

| 时间线 | .tl + .tl-item（.ok/.accent/.warn） | 事件流 |

| 状态徽标 | .st + .st-ok/.st-warn/.st-danger/.st-faint/.st-accent | 状态 |

| 筛选 tabs | .ftabs + .ftab.on | 表格筛选 |

| 工具栏 | .toolbar + .tbar-search + .tbar-meta | 搜索/计数 |

| 表格 | .tbl-wrap + .tbl（.t-main/.t-sub/.mono/.num/.r） | 数据表 |

| 批量条 | .batch | 批量操作 |

| 面包屑 | .f-crumb | 功能页头部 |

| 功能 hero | .f-hero（.f-ic/.f-desc/.f-meta/.f-chip） | 功能说明 |

| 同组入口 | .f-kpis + .f-grid + .f-feats + .f-feat | 功能关联 |

| 标签 | .tag / .chips + .chip | 标签 |

| 按钮 | .btn-p（实心）/ .btn-s（描边）/ .btn-ghost / .btn-danger / .btn-sm | 按钮 |

规范：新增/改后台页面时，用上表 class，不在页面内写硬编码 hex 或零散内联样式；表格页面优先用 .tbl-wrap + .tbl。

模板库

拿来就用的模板

线索转化

预约诊断表单

姓名/企业/职位/联系方式/问题 → CRM 线索自动建档

表单提交 /api/form-submit（form_slug=appointment）

内容订阅

Newsletter 订阅框

邮箱订阅，自动写入订阅列表并触发欢迎邮件

POST /api/newsletter {email}

线索转化

资料下载门禁

白皮书/报告门禁，填表后返回下载链接

downloads.php 卡片 + POST /api/download

全局组件

顶部通知条

全站置顶通知，可关闭，可埋点

后台「转化组件」启用 top_bar

全局组件

底部 CTA 区块

页面底部转化区块，标题+描述+按钮

后台「转化组件」启用 bottom_cta

全局组件

弹窗（含内嵌表单）

定时/滚动/离开触发弹窗，可关联表单

后台「转化组件」启用 popup

开放 API

统一 JSON 接口

统一 JSON 接口，均支持跨域（Access-Control-Allow-Origin: *），可用于对接 CRM、数据分析工具等。

POST

/api/form-submit

统一表单提交：线索入库 + CRM + 通知 + 数据流

form_slug + 字段（或 slug + data JSON）

GET/POST

/api/community

论坛：topics / posts 拉取，create_post / vote 操作

action, topic, title, content

GET

/api/articles

文章列表：type=list 按分类/标签筛选

type, category, tag, limit

POST

/api/member

会员：注册 / 登录 / 登出 / 申请讲师

action, account, password

POST

/api/track

统一行为埋点：page_view / button_click / form_submit 等

event, props, label

POST

/api/newsletter

Newsletter 订阅

email, source

POST

/api/download

资料下载门禁：验证后返回下载链接

download_id, name, email, company

GET

/api/conversion

转化组件配置：top_bar / bottom_cta / popup

—

GET

/api/site-structure

站点结构：全局导航 / 页脚 / 自定义页面

—

GET

/api/landing

聚合页数据：slug → 页面 + 聚合文章

slug

GET

/api/search

站内搜索：文章 / 课程 / 资料

q

调用示例

// 提交预约线索
fetch('/api/form-submit', {
  method: 'POST',
  body: new URLSearchParams({
    form_slug: 'appointment',
    name: '张三', company: '示例公司',
    contact: '13800000000', note: '想了解增长诊断'
  })
});

文档中心
查得到、看得懂

OpenFlow 架构规范

一、前端资产（唯一实现清单）

二、Markdown 转换（唯一实现）

三、导航系统（现状 3 套 → 目标 1 套）

四、缓存（唯一实现）

五、数据存储（两套分工明确）

六、站点配置（唯一入口）

七、新增功能规范

八、历史遗留债务（处理进度）

九、后台页面组件规范（对齐设计稿 openflow-admin.html）

拿来就用的模板

预约诊断表单

Newsletter 订阅框

资料下载门禁

顶部通知条

底部 CTA 区块

弹窗（含内嵌表单）

统一 JSON 接口

调用示例

文档看懂了，系统该动手设计了

文档中心查得到、看得懂

OpenFlow 架构规范

一、前端资产（唯一实现清单）

二、Markdown 转换（唯一实现）

三、导航系统（现状 3 套 → 目标 1 套）

四、缓存（唯一实现）

五、数据存储（两套分工明确）

六、站点配置（唯一入口）

七、新增功能规范

八、历史遗留债务（处理进度）

九、后台页面组件规范（对齐设计稿 openflow-admin.html）

拿来就用的模板

预约诊断表单

Newsletter 订阅框

资料下载门禁

顶部通知条

底部 CTA 区块

弹窗（含内嵌表单）

统一 JSON 接口

调用示例

文档看懂了，系统该动手设计了

文档中心
查得到、看得懂