Feishu HTML

Feishu HTML · 内容制作与 OSS 部署

必备信息

• Bucket：clawshell-vault
• OSS Endpoint：https://oss-cn-hongkong.aliyuncs.com
• 绑定域名：https://gzzhike.cn
• AccessKey ID：<YOUR_OSS_ACCESS_KEY_ID> — 从 ~/.ossutilconfig 提取（cat ~/.ossutilconfig），见 references/oss-credentials.md
• AccessKey Secret：<YOUR_OSS_ACCESS_KEY_SECRET> — 同上
• 部署目录前缀：web-spa/
• OSS SDK：oss2（pip install oss2）

核心能力

1. 内容理解：深度解析用户提供文档/文本，提取结构、逻辑、核心需求
2. 功能性设计：拆解目标→制定规范→任务规划→逐步交付→校验验收
3. 展示性设计：调用 huashu-design 技能进行页面规划与视觉设计
4. WEB SPA 架构：多 TAB 页面、响应式、移动端+桌面端分别优化
5. 校验：完整性、功能有效性、页面可读性、内容一致性、关键信息呈现
6. 部署：上传至 OSS WEB-SPA 目录，交付访问链接

页面设计与风格规范

风格来源优先级

1. 用户明确指定风格：用户提供了参考网站/品牌规范/设计稿 → 严格遵循用户指定风格
2. 用户提供了品牌内容：用户提供了 Logo/VI/色值/字体规范 → 以用户品牌为核心设计元素
3. 无明确风格说明：默认参考旅游行业风格，融入山河/自然/在地文化元素
4. 贵州之客品牌调性（无明确风格且内容涉及贵州之客时）：
   • 主色调：自然系（山峦青、水碧、石褐）
   • 辅助色：暖米/陶土/木色
   • 字体：中文衬线（思源宋体/Noto Serif SC）用于标题，中文无衬线用于正文
   • 视觉语言：克制、留白、有呼吸感，避免过度装饰

旅游行业通用风格特征

适用于无明确风格说明时的默认参考：

• 色彩：自然色系（森林绿/岩石褐/天空蓝/日出橙），饱和度适中
• 版式：大图留白，信息密度适中，避免信息过载
• 配图：真实风景/在地人文摄影为主，不用通用 stock photo
• 排版：层级清晰，标题突出，正文可快速扫读
• 交互：轻量动效（如 fade-in、slide-up），强化阅读节奏而非炫技

执行流程

阶段零（可选）：设计前澄清

参考 ai-native-workflow Phase ① 澄清 + grill-me 方法论

当用户意图模糊或缺少关键决策信息时，先追问核心问题再进入内容理解：

• 这个页面的受众是谁？他们看完要做什么？
• 核心信息优先级？（Top 3 必须传达的事）
• 有风格参考吗？有无品牌规范？
• 产出是内部用还是对外展示？

跳过条件：用户指令已明确（如"用昨天那个版本做个 web"），直接进入阶段一。

阶段一：内容理解

目的：充分理解原始文档/文本的结构、逻辑、核心需求，形成可执行的内容大纲。

步骤：

1. 获取原始内容

   • ⚠️ 飞书文档优先用 REST API：feishu_doc_read 工具仅在飞书评论上下文（comment context）中可用，普通对话中会报"Feishu client not available"。通用方法是用 Python + urllib 调用飞书 Open API：

     import urllib.request, urllib.parse, json
     # 1. 获取 tenant_access_token
     req = urllib.request.Request(
         'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal',
         data=urllib.parse.urlencode({'app_id': 'cli_aa9ead14c2641cc3', 'app_secret': 'ZUUm7yI7HmfLi42ki8fPTgZzbj2AuTeM'}).encode(),
         headers={'Content-Type': 'application/x-www-form-urlencoded'}
     )
     with urllib.request.urlopen(req) as r:
         token = json.loads(r.read())['tenant_access_token']
     # 2. 读取文档 raw_content
     req2 = urllib.request.Request(
         f'https://open.feishu.cn/open-apis/docx/v1/documents/{doc_token}/raw_content',
         headers={'Authorization': f'Bearer {token}'}
     )
     with urllib.request.urlopen(req2) as r:
         content = json.loads(r.read())['data']['content']
     

   • 飞书消息线程：GET /im/v1/messages?container_id_type=thread&container_id={thread_id}
   • 用户直接提供：直接使用

2. 深度分析内容

   • 梳理内容结构（总论→分论点→案例/数据→结论）
   • 识别核心信息模块（标题、段落、列表、数据、引用、图表）
   • 提取关键词、核心论点、业务逻辑、数据关系
   • 识别隐含需求（用户没明说但内容暗示的功能）

3. 需求具象化

   • 明确最终交付物的使用场景（内部汇报/外部展示/客户演示/持续运营）
   • 确定目标受众（管理层/客户/内部团队/公众）
   • 提取功能需求（查询/筛选/交互/导出/多人协作等）
   • 提取展示需求（信息架构/可视化/导航结构/TAB分类等）

4. 需求确认：将理解后的内容结构和功能规划一次性向用户确认，🛑 等用户回复再往下走

贵州之客例外：用户（杨瑒/月夜，CTO）沟通风格极简直接，发现问题立即纠正。若用户指令已明确（如"用你修改之后的版本做个web展示"），且提供了文档链接，可直接进入阶段二—三，跳过需求确认步骤，以用户已确认的意图为准。

阶段一 B：设计决策澄清（grill-me 方法论）

目的：在进入设计阶段前，用 grill-me 方法论遍历页面设计的关键决策树，确保设计方向有共识后再动手。

方法：

1. 根据页面类型选择 3-4 个最相关的追问维度
2. 逐维度追问，提供推荐答案
3. 将决策记录到阶段二的规划中

追问维度：

跳过条件：

• 用户已明确指定了风格/受众/目标 → 跳过已明确的维度，只追问未明确的
• 贵州之客常规页面 → 使用品牌默认风格，可跳过风格方向追问
• 用户说"直接做" → 跳过此步骤，用默认假设进入阶段二

双轨交付模式（触发：内部方案+对外宣传同时需要）

当用户要求同时产出内部实施方案和对外宣传版本时，两轨并行执行：

执行顺序：先完成飞书文档（内部版固定信息），再基于同一内容框架转化为面向客户的对外版本。两版内容分开——内部版保留预算/KPI/排期等管理信息，对外版聚焦体验场景/价格/报名入口。

参考案例：暑假营销方案（2026-05-26），内部版归档于知识库，对外版部署于 https://gzzhike.cn/web-spa/summer-campaign-2026/index.html，报名表单页 book.html 承接受众报名行为。

配套参考文件：

• references/summer-campaign-template.md — 对外宣传页结构/配色规范
• references/booking-form-template.md — 报名表单页标准字段/样式/链接规范（派生时直接修改项目信息，无需从零构建）
• references/solution-proposal-template.md — B2B方案/系统建设提案的客户演示页结构（双轨交付：飞书文档+HTML）
• references/interactive-demo-template.md — 交互式功能Demo（客户可点击操作的 prototype，含mock数据/模态框CRUD/多步表单）
• references/course-landing-template.md — 课程/培训落地页：3 TAB结构（概览→详解→知识卡片），移动端优先，操作速查卡+公式框+步骤列表
• references/event-poster-pattern.md — 活动海报生成模式：HTML设计→Playwright截图→OSS PNG，含海报布局规范（色板/字体/分区结构）和完整工作流
• references/shared-data-spa.md — 多人共享 SPA 数据层模式：OSS JSON + Python 代理 + SSH 隧道，替代 localStorage 实现跨设备共享数据

阶段二：功能性与展示性设计规划

2.1 页面分类判断

根据内容判断页面类型：

交互式Demo 与静态方案页的区别：交互式Demo 用 JS mock 数据数组 + 运行时 CRUD，客户可真正点击体验系统流程。结构模板见 references/interactive-demo-template.md。

2.2 功能性页面设计（阶段二-A）

核心原则：以终为始，倒推任务路径。

1. 明确最终目标

   • 用户能做什么？（查询XX、配置XX、提交XX、管理XX）
   • 成功的衡量标准是什么？

2. 拆解功能模块

   [最终目标]
       ↓
   [模块A：负责XX]  [模块B：负责XX]  [模块C：负责XX]
       ↓               ↓               ↓
   [子任务A1/A2]   [子任务B1/B2]   [子任务C1/C2]
   

3. 制定每步产出标准

   • 每步完成什么？
   • 如何校验这步是对的？
   • 什么情况下算"完成"？

4. 数据建模（如涉及）

   • 核心数据实体有哪些？
   • 数据关系是什么？
   • 示例数据是什么？（用于展示）

5. 交互流程设计

   • 用户操作路径（主路径+分支路径）
   • 异常情况处理（空状态/加载中/错误/权限不足）
   • 键盘快捷键（桌面端）

2.3 展示性页面设计（阶段二-B）

调用 huashu-design 技能，执行其完整工作流，特别关注：

1. 内容结构化

   • 核心论点提炼（不超过5个关键点）
   • 层级扁平化（≤3级标题）
   • 关键数据突出（数字放大/色彩强调）

2. 可视化图形规划（按需使用）

   图形类型	适用场景	产出
   SVG架构全景图	产品架构/系统组成/组织结构	矢量可缩放图
   时间周期甘特图	项目计划/里程碑/版本规划	横向时间轴
   业务流程结构图	业务流转/决策流程/用户路径	节点+连线图
   分析框架图	SWOT/PEST/波特五力/RFM等	矩阵/象限图
   时间周期趋势图	趋势数据/增长曲线/周期波动	折线/面积图
   地理信息图	地点分布/路线/区域对比	地图+标记
   占比对比图	分类对比/构成分析	饼图/环形图/堆叠柱状
   进度/漏斗图	转化漏斗/流程进度	漏斗/阶梯图

3. TAB 结构设计

   • 按逻辑模块分组（不是按原文顺序罗列）
   • 每个 TAB 有明确主题，命名简洁
   • TAB 之间有逻辑递进或并列关系
   • 典型结构：
     • 概览总览 → 详情/明细 → 分析/趋势
     • 背景 → 方案 → 实施 → 效果
     • 产品 → 运营 → 财务 → 团队

4. 内容呈现范式

   • 标题区：主题 + 核心结论（一句话）
   • 关键指标卡：数字+标签+趋势箭头
   • 内容区：结构化正文 + 可视化辅助
   • 引用区：关键引语/金句独立展示
   • 交互区：可切换的详情面板

阶段三：WEB SPA 制作

3.0 功能性页面的必检规范 ⚠️

在开始写 HTML 之前，先规划以下功能性要素，漏掉任何一项都是交付缺陷：

按钮规范

• 所有「立即预订」类按钮：href 指向报名页面（不得使用 #contact + alert，必须有真实页面承接）
• 「定制咨询」类按钮：href 指向添加客服微信（weixin://contacts/profile/gzzhike2026）或对应 IM 的跳转链接
• HTML 内禁止在行内元素（如 <a>、<button>）内部嵌入 <!-- 注释 -->
• 飞书群/钉钉群等社群跳转链接：href 不得使用占位符（如 code=*** 或 code=XXXXX），不得出现引号残缺。若暂时没有真实 code，先写完整 URL 结构（去除 code 参数），禁止留残缺引号打断 HTML 解析
• 「返回顶部」按钮：必须使用 href="#"（真正返回页面顶部），禁止指向中间锚点（如 #pricing），否则用户从最底部点击会跳到错误位置
• 所有导航/CTA 按钮：在页面交付前必须逐一验证 href 有效性——禁止任何按钮的 href 是 # + JS alert 的空跳转组合

价格卡片等高规范（底部对齐 + 顶部对齐）

/* 父级：横向排列 + 等高 */
.price-grid {
  display: flex;
  align-items: stretch;          /* ← 关键：强制整行卡片等高，取最高那张 */
  gap: 24px;
}
/* 每张卡：flex column 布局 */
.price-card {
  display: flex;
  flex-direction: column;
  flex: 1;                       /* 等宽 */
  min-height: 520px;             /* 统一起跑线，内容不满时自然撑高 */
}
/* 内容区：自动填满剩余空间 → 底部按钮永远在同一高度 */
.price-features {
  flex: 1;
  align-self: stretch;
}

多行价格卡时，每行必须有独立的 flex 容器，不能跨行直接等高（跨行 grid 的 align-items:stretch 只对单行生效）。每行用一个 div.price-grid 包裹该行的所有卡片，确保每行各自顶部对齐、底部对齐。

联系/CTA 区域设计规范（展示性页面均有） 当页面含「联系我们」区块时，需要提供以下社群入口：

微信社群  →  二维码占位图（120×120 SVG placeholder） + weixin:// 协议跳转
飞书群    →  二维码占位图 + applink 跳转链接（飞书开放平台获取 code 参数）
钉钉群    →  二维码占位图 + dingtalk:// 协议跳转

按钮文字统一：非特殊场景，一律「立即预订」；不混用「咨询详情」「定制咨询」

3.1 架构选型

默认：多 TAB 单文件 SPA（所有 TAB 内联，通过 JS 切换）

<!-- SPA 骨架 -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>${页面标题}</title>
  <style>/* 内联全部样式 */</style>
</head>
<body>
  <header class="spa-header">...</header>
  <nav class="spa-tabs" id="tabNav">...</nav>
  <main class="spa-content" id="tabContent">...</main>
  <script>/* 内联全部逻辑 */</script>
</body>
</html>

例外：多文件包（>2000行/多子页面/需独立分享某一页） → index.html + 每页独立 HTML，iframe 聚合

3.2 响应式框架

断点策略：

• Mobile：< 768px（手机竖屏）
• Tablet：768px - 1024px（平板）
• Desktop：> 1024px（桌面）

移动端优化：

• 底部 TAB 导航栏（手机操作拇指区）
• 触控滑动切换 TAB（touch swipe）
• 触控点击切换 TAB
• 大按钮/大触控区域
• 简化信息密度（桌面端信息全量，移动端按需展开）

桌面端优化：

• 顶部/侧边 TAB 导航栏
• 键盘导航：
  • ← → 或 Tab 切换 TAB
  • Enter 确认/进入
  • Escape 退出弹窗/回到概览
• 悬停态（hover）显示更多信息
• 鼠标滚轮/触摸板横向滚动长列表

3.3 交互规范

阶段四：OSS Bucket 权限确认

⚠️ 必做第一步：确认目标 Bucket ACL 为「公共读」，否则 URL 无法公开访问。

import oss2
auth = oss2.Auth('<YOUR_OSS_ACCESS_KEY_ID>', '<YOUR_OSS_ACCESS_KEY_SECRET>')
bucket = oss2.Bucket(auth, 'oss-cn-hongkong.aliyuncs.com', 'clawshell-vault')
acl = bucket.get_bucket_acl()
print('Bucket ACL:', acl.acl)
# private → 无法公开访问，需改 ACL
# 改法：OSS 控制台 → 基础设置 → Bucket 权限管理 → 改为「公共读」

如果 Bucket 是 private：CDP 访问测试会得到 <Error><Code>AccessDenied</Code>... 的 XML 页面，而不是目标 HTML。可选方案：

• 方案A（推荐）：OSS 控制台改 Bucket ACL 为「公共读」
• 方案B：改完 ACL 之前跳过 CDP 验证，改为 curl -I 检查文件是否存在 + 上传成功即视为通过
• 方案C：使用签名 URL（有效期内的临时访问链接）供 CDP 测试

阶段五：页面校验

设计质量门禁（增强层）：部署前调用 hallmark 技能执行 58 道反 AI-slop 关卡检查。另可调用 design-review 思维——视觉层次、美学一致性、组件复用。完整设计审查流程见 ai-native-workflow Phase ⑦。

Hallmark 集成：进入阶段五时，加载 hallmark 技能，对产出 HTML 执行：

1. 视觉反模式检查（V1-V7 关卡）
2. 内容诚信检查（C1-C4 关卡）
3. 移动端硬地板检查（M1-M5 关卡）
4. 六轴预发射自评（P/H/E/S/R/V 各 1-5 分）
5. 输出 Hallmark stamp 到 CSS 顶部：/* Hallmark · pre-emit critique: P? H? E? S? R? V? · gates: N/58 ✓ */

不通过则修复后重新验证，直到所有关卡通过方可部署。

对阶段二、阶段三产出的所有 HTML 页面（功能性页面 + 展示性页面）逐一进行校验，不通过则修复后再继续：

功能性页面交付前必查清单 ⚠️

所有按钮必须通过以下校验方可交付：

验证方法（每次交付前必做）：

# 第一步：Python 正则检查所有链接
import re
with open('output/index.html') as f:
    html = f.read()
links = re.findall(r'<a[^>]+href="([^"]+)"', html)
for href in links:
    assert href != '', f"空 href: {href}"
    assert not (href == '#contact' and 'alert' in html), f"禁止 #contact+alert"
print(f"共 {len(links)} 个链接，全部通过校验")

⚠️ 必须用 Playwright 做真实浏览器 CDP 验证（功能性页面的最后一道关）

执行环境注意：Playwright 只能通过 terminal() 调用（系统级 Python），不能通过 execute_code sandbox（独立 venv 无 playwright 包）。验证脚本必须用 terminal 工具执行。

所有功能性页面在部署后，必须用 Playwright headless 模式验证以下 7 项，有一项不通过则修复后重新验证：

from playwright.sync_api import sync_playwright

def full_verify(url):
    """功能性页面完整验证协议"""
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()

        # ① 页面能加载且有内容
        page.goto(url, timeout=15000)
        assert len(page.content()) > 1000, "页面内容为空"

        # ② 检查 hero::before 没有拦截点击（高频根因）
        hero_before_ptr = page.evaluate(
            "getComputedStyle(document.querySelector('.hero'),'::before').pointerEvents"
        )
        assert hero_before_ptr == 'none', f"hero::before pointer-events={hero_before_ptr}，会拦截按钮点击"

        # ③ 所有 CTA 按钮 href 有效
        ctas = page.query_selector_all('.btn-primary, .nav-cta, .cta-button')
        for btn in ctas:
            href = btn.get_attribute('href')
            assert href and href != '#', f"按钮 href 无效: {href}"
            assert not (href == '#contact'), "禁止 #contact 空跳转"

        # ④ 返回顶部按钮
        back_top = page.query_selector('.back-to-top, [href="#"]')
        assert back_top, "缺少返回顶部按钮"

        # ⑤ 锚点跳转 hash 保留（如果有锚点区块）
        if page.query_selector('#experience, #pricing, #contact'):
            page.click('a[href="#experience"]')
            page.wait_for_timeout(800)
            hash_val = page.evaluate("window.location.hash")
            assert hash_val == '#experience', f"锚点hash丢失，当前: {hash_val}"
            # 验证 scroll-margin-top 生效
            section_top = page.evaluate(
                "document.querySelector('#experience').getBoundingClientRect().top"
            )
            assert 60 <= section_top <= 90, f"#experience 距顶 {section_top}px，应在60-90px（导航栏下方）"

        # ⑥ 控制台零错误
        errors = []
        page.on('console', lambda msg: errors.append(msg.text) if msg.type == 'error' else None)
        page.reload()
        page.wait_for_timeout(1500)
        assert len(errors) == 0, f"控制台错误: {errors}"

        # ⑦ 报名/社群按钮跳转验证（通过 URL 变化判断，不真正跳转）
        if page.query_selector('a[href*="book.html"]'):
            with page.expect_navigation(timeout=5000):
                page.click('a[href*="book.html"]')
            assert 'book.html' in page.url, f"报名页跳转失败: {page.url}"

        browser.close()
        print("✅ Playwright 完整验证通过")
        return True

⚠️ 重要：在没有 Node.js 环境的机器上，可以用 Python subprocess 调用系统 Playwright CLI；也可以用 Python playwright 包（pip install playwright && playwright install chromium）。禁止跳过此验证步骤。

在线页面验证（必须执行）

⚠️ 部署后必须用 Playwright 验证页面可正常加载：

from playwright.sync_api import sync_playwright

def verify_online_page(url):
    """验证在线页面可访问且结构正确"""
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()
        page.goto(url, timeout=15000)
        title = page.title()
        content = page.content()
        print(f'Title: {title}')
        print(f'Content length: {len(content)}')
        # 检查TAB/导航元素
        tabs = page.query_selector_all('.tab-btn, [role=tab], nav a, .spa-tab')
        print(f'Tabs found: {len(tabs)}')
        page.wait_for_timeout(2000)
        browser.close()
        return len(content) > 1000  # 内容非空即通过

Bucket ACL 预检（防止部署后无法访问）：

import oss2
auth = oss2.Auth('<YOUR_OSS_ACCESS_KEY_ID>', '<YOUR_OSS_ACCESS_KEY_SECRET>')
bucket = oss2.Bucket(auth, 'oss-cn-hongkong.aliyuncs.com', 'clawshell-vault')
acl = bucket.get_bucket_acl()
if acl.acl == 'private':
    print('⚠️ Bucket是私有！部署后URL无法公开访问，需先在OSS控制台改为「公共读」')

通用校验（所有页面必须通过）

功能性页面附加校验

展示性页面附加校验

设计质量审查（design-review 方法论）

以上为技术性校验（链接/按钮/渲染/兼容性），以下是设计质量维度的审查——对照设计决策（阶段一 B）检查实现质量：

🆕 增强审查层：本阶段可调用以下独立技能作为质量门禁：

• editorial-review-structure — 使用5种结构模型审查页面TAB结构和信息层级
• edge-case-hunter — 穷举所有交互路径的边界条件（空状态/加载中/错误/权限不足）

审查方法：

• 部署后用 Playwright 截取三断点截图（1280/768/375）
• 对照截图逐项检查上述维度
• 发现问题分级：Must Fix（功能受阻）/ Should Fix（有损体验）/ Could Improve（锦上添花）

检查清单（与上述技术性校验合并执行）：

• 视觉层次清晰
• 间距/色彩一致性
• 风格方向贯彻
• 组件无重复/冲突
• 交互状态完整
• 响应式质量
• 暗色模式（如适用）

阶段六：OSS 上传与部署

Python 部署脚本：

import oss2, os, glob, time, hashlib

auth = oss2.Auth('<YOUR_OSS_ACCESS_KEY_ID>', '<YOUR_OSS_ACCESS_KEY_SECRET>')
bucket = oss2.Bucket(auth, 'https://oss-cn-hongkong.aliyuncs.com', 'clawshell-vault')

def slugify(name):
    """生成 URL 友好的目录名"""
    import re
    s = name.strip()
    s = re.sub(r'[^\w\s-]', '', s)
    s = re.sub(r'[-\s]+', '-', s)
    return s[:40]  # 限制长度

def deploy_spa(local_dir, project_name):
    """
    部署 SPA 应用到 OSS WEB-SPA 目录
    返回: (main_url, all_urls)
    """
    slug = slugify(project_name)
    prefix = f'web-spa/{slug}/'

    # 上传所有文件
    files = glob.glob(os.path.join(local_dir, '**', '*'), recursive=True)
    uploaded = []
    for filepath in files:
        if os.path.isfile(filepath):
            rel = os.path.relpath(filepath, local_dir).replace('', '/')
            oss_key = f'{prefix}{rel}'.lstrip('/')
            bucket.put_object_from_file(oss_key, filepath)
            uploaded.append(oss_key)

    # 找主文件
    main_files = ['index.html', 'main.html', 'default.html']
    main_url = None
    for mf in main_files:
        if mf in [os.path.basename(f) for f in uploaded]:
            main_url = f'https://gzzhike.cn/{prefix}{mf}'
            break

    return main_url, uploaded

def deploy_static_package(local_file, project_name):
    """
    部署单个静态文件（如 PDF、视频直接上传）
    返回: url
    """
    slug = slugify(project_name)
    fname = os.path.basename(local_file)
    oss_key = f'web-spa/{slug}/{fname}'
    bucket.put_object_from_file(oss_key, local_file)
    return f'https://gzzhike.cn/{oss_key}'

目录命名规则：

访问地址格式：

• 主页面：https://gzzhike.cn/web-spa/{slug}/index.html
• 多页包主文件：由部署函数返回的具体 URL

阶段七：交付清单

向用户交付：

1. 访问链接：https://gzzhike.cn/web-spa/{slug}/index.html
2. 功能说明：页面支持哪些交互操作
3. 移动端适配：在手机浏览器打开体验是否正常
4. 如有多 TAB：说明各 TAB 的内容和切换方式
5. 如含嵌入内容：说明 PDF/视频 等的查看方式
6. 如有多页面包：提供主页面链接，各子页面从主页面进入

复盘：暑假营销活动项目（2026-05-26）最佳实践

项目背景

同时交付内部执行手册（飞书文档）和对外宣传页（HTML SPA），双轨并行。

沉淀下来的关键规范

① 功能性页面必须先规划按钮承接，再写 HTML

• 「立即预订」→ 报名表单页（book.html），表单提交后跳转飞书群
• 不能用 #contact + alert('请联系客服') 敷衍，这是用户立刻能发现的功能性缺陷
• 报名页字段：姓名、手机、项目、日期、人数、备注

② hero::before 伪元素会拦截按钮点击

• 症状：按钮视觉正常，但 Playwright 报错 <section> intercepts pointer events
• 根因：hero 背景的 ::before { position:absolute; inset:0; pointer-events:auto } 透明纹理层覆盖在按钮之上
• 修复：在 ::before 末尾加 pointer-events: none

③ 锚点跳转用 scrollIntoView + pushState，不要用 scrollTo

• window.scrollTo({ top: offset }) 在某些浏览器 smooth scroll 完成后会丢失 URL hash
• 正确做法：target.scrollIntoView({ behavior: 'smooth', block: 'start' }) + history.pushState(null, '', href)
• 锚点目标 section 必须加 scroll-margin-top: 72px（导航栏高度 64px，留 8px 缓冲）

④ 价格卡片多行时每行独立 flex 容器

• 跨行 grid 的 align-items: stretch 只对单行生效，多行价格卡每行需单独 div.price-grid
• 卡片内部用 flex-direction: column + flex: 1 让内容区自动填满，底部按钮永远在同一行

⑤ 飞书群链接不能有引号残缺

• href="https://applink.feishu.cn/client/minimalist/h5?code=*** target=" 这种引号残缺会打断整个 DOM
• 没有真实 code 时，先写完整 URL 结构（去除 code 参数），禁止留残缺引号

⑥ 部署后必须用 Playwright 真实浏览器验证

• Python re 检查只能验证链接格式，无法发现 ::before 拦截、hash 丢失等运行时问题
• Playwright CDP 验证 7 项（页面加载、::before 拦截、CTA href、返回顶部、锚点 hash 保留、控制台错误、报名跳转）
• 没有 Node.js 时用 pip install playwright && playwright install chromium 的 Python 版

内容极简原则（用户偏好）

当用户说"太复杂""简化""只保留核心"时，执行以下裁剪规则——不仅在 HTML 页面内生效，飞书文档、PPT 等所有对外/对讲师的产出均适用：

保留项（必须留）：

• 核心结构/框架总览表
• 比例/数值表
• 公式链路（自然语言，不要代码块）
• 一个完整示例（一张表走完）

裁剪项（一律删除）：

• 背景叙事/设计理念/哲学阐述
• "为什么需要这套制度"类问题陈述
• 多场景示例（只保留一个）
• FAQ 问答
• 长段叙述性文字 → 改为表格
• 任何"在算什么/为什么"三段式解释 → 改为单行公式

极简交付标准：读者打开页面/文档，滚动一次看完所有关键信息，无需翻页寻找。表格优先于段落，公式优先于解释。

错误处理

内容产出原则

• 内容 = 结果性信息，不含推导过程
• HTML 自包含：样式和脚本全部内联，单文件即可运行
• 代码即文档：HTML 结构命名语义化（<nav>/<section>/<article>）
• 关键数据视觉化：数字用大字号/对比色突出
• 渐进增强：基础内容在低版本浏览器也能看，交互在支持环境增强