ephron-ren-prd/prd-home-add-github-button.md

Home 页新增 GitHub 按钮与后台可编辑支持 PRD

背景

当前 www.ephron.ren 的 home 页 Hero 区只有一个“联系我”按钮，点击后弹出联系方式弹窗，仅展示邮箱。用户希望：

1. 在首页 Hero 区中，在“联系我”右侧新增一个“GitHub”按钮。
2. 后台管理页也必须支持维护这个 GitHub 按钮对应的内容，不能写死在模板里。
3. 该变更需要纳入现有 home 服务的草稿 / 发布工作流。

本 PRD 基于 origin/main 源码分析，不基于当前本地工作树。

---

现状分析

1. 前台首页按钮结构

Home 页模板位于：

• home/templates/index.html

当前 Hero 区按钮只有一个：

• 联系我
• 通过 onclick="showContactModal()" 打开联系方式弹窗

现有结构大致如下：

<div class="hero-actions">
    <button onclick="showContactModal()" class="btn btn-primary">
        ...
        联系我
    </button>
</div>

这说明：

• Hero 操作区已经预留了多按钮容器 hero-actions
• 新增 GitHub 按钮不需要重构整体布局，只需扩展现有按钮组

2. 前台联系方式数据来源

当前联系方式弹窗内容来自：

• content.contact.email

现有弹窗只渲染邮箱：

<span class="email-text" id="emailText">{{ content.contact.email }}</span>

说明当前 contact 数据结构只被用于邮箱展示，没有 GitHub 相关字段。

3. 后台编辑页当前只支持邮箱

后台模板位于：

• home/templates/admin/index.html

当前“联系方式”区块只有一个字段：

<input type="email" class="form-input" id="contact_email" value="{{ content.contact.email }}">

前端提交草稿 / 发布时，collectFormData() 也只收集邮箱：

contact: {
    email: document.getElementById('contact_email').value
}

说明：

• 即使只改前台模板，也无法通过后台维护 GitHub 按钮内容
• 必须同步修改 admin 表单 + JS 收集逻辑

4. Home 服务确实有独立草稿 / 发布机制

关键文件：

• home/src/routes/admin.py
• home/src/services/content.py

已确认 Home 服务支持：

• GET /admin
• POST /admin/save
• POST /admin/publish
• POST /admin/discard

内容通过 content_json 整体提交，并存入 home_content 表中的 content_json 字段。

这意味着 GitHub 字段必须进入 Home content schema，才能被草稿保存和发布机制完整承载。

5. 当前默认内容 schema 不包含 GitHub

默认空内容定义位于：

• home/src/services/content.py → _get_empty_content()

当前 contact 结构：

"contact": {
    "email": ""
}

示例内容文件位于：

• home/data/home_content.json

当前 contact 示例也仅有：

"contact": {
  "email": "ephron_ren@163.com"
}

说明 schema 目前不支持 GitHub。

---

问题定义

当前实现存在以下缺口：

1. 首页缺少 GitHub 快捷入口

   • Hero 区只有“联系我”，没有直达 GitHub 的显式按钮。

2. 后台无法维护 GitHub 按钮内容

   • 联系方式仅支持邮箱，不支持 GitHub 文案 / URL。

3. 内容 schema 不完整

   • contact 结构没有 GitHub 字段，草稿与发布链路无法承载该信息。

4. 如果只改模板会造成配置写死

   • 不符合现有 home 服务“后台可编辑 + 草稿发布”的设计模式。

---

目标

产品目标

在首页 Hero 区实现双按钮：

• 左侧保留“联系我”
• 右侧新增“GitHub”

并且后台支持修改 GitHub 按钮对应的数据，确保：

• 可保存草稿
• 可发布
• 可回显
• 无需改代码即可调整 GitHub 链接

技术目标

将 GitHub 按钮数据纳入 Home content 的统一 JSON schema，而不是写死在模板中。

---

方案设计

一、数据结构调整

方案建议

扩展 contact 对象，至少新增 GitHub URL 字段。

建议结构：

"contact": {
  "email": "ephron_ren@163.com",
  "github_url": "https://github.com/ephron-ren"
}

可选增强方案

如果希望按钮文案也可配置，可以进一步扩展为：

"contact": {
  "email": "ephron_ren@163.com",
  "github_label": "GitHub",
  "github_url": "https://github.com/ephron-ren"
}

本次建议

建议本次至少落 github_url，github_label 可选。

理由：

• 用户明确要新增名为“GitHub”的按钮，文案固定即可满足需求
• 如果后续想支持“GitHub / 开源主页 / 代码仓库”等不同文案，再加 github_label 也不晚
• 本次最小闭环是“后台可改 GitHub 链接”

必改位置

1. home/src/services/content.py

   • 更新 HomeContent 对应的 contact 结构说明
   • 更新 _get_empty_content() 默认值

2. home/data/home_content.json

   • 为现有示例数据补上 github_url

---

二、后台管理页改造

目标

在后台“联系方式”区块中新增 GitHub 配置项。

建议 UI

当前仅有邮箱输入框，新增一项：

• GitHub 链接（URL）

建议形式：

<div class="form-group">
    <label class="form-label">GitHub 链接</label>
    <input type="url" class="form-input" id="contact_github_url" value="{{ content.contact.github_url }}">
</div>

如果采用增强方案，也可再加：

• GitHub 按钮文案

<div class="form-group">
    <label class="form-label">GitHub 按钮文案</label>
    <input type="text" class="form-input" id="contact_github_label" value="{{ content.contact.github_label or 'GitHub' }}">
</div>

提交逻辑改造

home/templates/admin/index.html 中的 collectFormData() 必须同步扩展。

最低改法：

contact: {
    email: document.getElementById('contact_email').value,
    github_url: document.getElementById('contact_github_url').value
}

若支持按钮文案：

contact: {
    email: document.getElementById('contact_email').value,
    github_label: document.getElementById('contact_github_label').value,
    github_url: document.getElementById('contact_github_url').value
}

兼容性要求

为避免旧数据缺字段导致后台渲染异常：

• 模板取值要允许字段不存在
• 推荐用兼容写法，例如：
  • content.contact.github_url or ''
  • content.contact.github_label or 'GitHub'

不要假设线上已有数据一定已经补齐。

---

三、前台首页 Hero 区改造

目标

在 Hero 区 .hero-actions 中，把单按钮扩展为双按钮布局：

• 联系我
• GitHub

建议实现

保留现有“联系我”按钮不变，在右侧新增一个锚点按钮：

<div class="hero-actions">
    <button onclick="showContactModal()" class="btn btn-primary">
        ...
        联系我
    </button>

    {% if content.contact.github_url %}
    <a href="{{ content.contact.github_url }}" target="_blank" rel="noopener noreferrer" class="btn btn-secondary">
        ...
        GitHub
    </a>
    {% endif %}
</div>

为什么建议条件渲染

使用：

{% if content.contact.github_url %}

原因：

• 避免后台未配置 GitHub 时渲染空链接按钮
• 保持发布内容的容错性
• 符合配置驱动模式

样式建议

优先复用现有按钮体系：

• btn btn-primary 给“联系我”
• btn btn-secondary 给“GitHub”

这样改动最小，也能保持视觉一致性。

位置要求

GitHub 按钮必须出现在“联系我”右侧，与用户需求一致。

---

四、联系方式弹窗是否需要改

本次建议

不强制把 GitHub 塞进联系弹窗。

原因：

• 用户明确需求是“在联系我右边新增一个按钮 GitHub”
• GitHub 是独立入口，放在 Hero 区直接跳转比塞进弹窗更合理
• 当前弹窗职责单一：展示邮箱并支持复制，继续保持简单更好

允许的增强项

如果开发时认为一致性更强，也可以在弹窗底部附加一行 GitHub 链接，但这不是本次必需项。

---

五、后端服务层与兼容策略

现状

home/src/services/content.py 当前直接把 JSON 读出后返回，没有做 schema migration。

风险

如果线上数据库里已有历史 content_json，其中 contact 只有：

{ "email": "..." }

那么模板若直接访问 content.contact.github_url，可能出现以下问题：

• Jinja 取不到字段导致空值
• 管理页输入框初始值异常
• 前台逻辑不统一

建议

在内容读取或默认值合并处做轻量兼容，保证旧数据自动补默认字段。

建议方向二选一：

方案 A：服务层补默认值（推荐）

在 get_published_content() / get_draft_content() / get_content_for_edit() 返回前，对 contact 做 schema normalize。

例如确保返回结构至少包含：

content.setdefault("contact", {})
content["contact"].setdefault("email", "")
content["contact"].setdefault("github_url", "")

若采用增强方案，再补：

content["contact"].setdefault("github_label", "GitHub")

方案 B：模板层全靠 or ''

这种能跑，但会把兼容逻辑分散到多个模板，不推荐。

结论

推荐在服务层统一做 schema 补齐。

---

修改范围

必改文件

1. home/templates/index.html

   • Hero 区新增 GitHub 按钮
   • 按配置条件渲染

2. home/templates/admin/index.html

   • 联系方式区块新增 GitHub 输入项
   • collectFormData() 增加 GitHub 字段收集

3. home/src/services/content.py

   • 扩展默认 schema
   • 增加旧数据兼容补齐逻辑

4. home/data/home_content.json

   • 补充 GitHub 示例字段

可选修改文件

5. home/tests/...
   • 为 admin 渲染 / 发布内容链路补测试

---

验收标准

前台验收

1. 首页 Hero 区显示两个按钮：

   • 联系我
   • GitHub

2. GitHub 按钮位于“联系我”右侧。

3. GitHub 按钮点击后：

   • 新标签页打开 GitHub 页面
   • 带 rel="noopener noreferrer"

4. 当后台未填写 GitHub 链接时：

   • 不显示 GitHub 按钮
   • 页面不报错

后台验收

1. 管理页“联系方式”区块新增 GitHub 链接输入框。
2. 修改 GitHub 链接后点击“保存草稿”：
   • 草稿保存成功
   • 刷新管理页能回显草稿值
3. 点击“发布”后：
   • 首页 GitHub 按钮更新为最新链接
4. 点击“丢弃草稿”后：
   • 未发布的 GitHub 修改被撤销

兼容性验收

1. 对已有旧数据（无 github_url 字段）可正常打开首页。
2. 对已有旧数据可正常打开后台管理页。
3. 不要求手工清洗历史 content_json 才能运行。

---

测试建议

手工测试路径

1. 打开 /admin
2. 在“联系方式”中填写 GitHub 链接
3. 点击“保存草稿”
4. 刷新 /admin，确认值仍在
5. 点击“发布”
6. 打开首页 /
7. 检查“联系我”右侧是否出现 GitHub 按钮
8. 点击按钮，确认跳转正确
9. 清空 GitHub 链接后重新发布
10. 首页应隐藏 GitHub 按钮

自动化测试建议

至少补以下测试：

1. 内容兼容测试

   • 旧 schema 无 github_url 时，服务层返回结果应自动补空值

2. 后台表单渲染测试

   • /admin 页面应包含 contact_github_url

3. 前台渲染测试

   • 有 github_url 时显示按钮
   • 无 github_url 时不显示按钮

---

非目标

本次 PRD 不包含以下内容：

1. 不改“联系我”弹窗的交互模式
2. 不新增多社交平台矩阵（如 X、LinkedIn、掘金、知乎）
3. 不重构 Hero 区整体布局
4. 不引入单独的 Home Service API

---

实施建议

建议按以下顺序开发：

1. 先改 content.py 默认 schema 和兼容补齐
2. 再改 admin 表单与 collectFormData()
3. 最后改首页 Hero 模板渲染
4. 补回归测试

这样能最大限度降低“模板先引用新字段、但后端旧数据没补齐”导致的线上报错风险。

---

结论

这不是一个单纯的模板文案调整，而是一个 Home 内容模型扩展 + 后台编辑支持 + 前台配置驱动渲染 的小型功能改造。

最小闭环必须同时覆盖：

• 数据 schema
• 后台表单
• 提交收集逻辑
• 前台模板
• 旧数据兼容

否则会出现“按钮显示了但后台不能改”或“后台能填但前台不渲染”的半更新状态。