528 lines
12 KiB
Markdown
528 lines
12 KiB
Markdown
# 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()"` 打开联系方式弹窗
|
||
|
||
现有结构大致如下：
|
||
|
||
```html
|
||
<div class="hero-actions">
|
||
<button onclick="showContactModal()" class="btn btn-primary">
|
||
...
|
||
联系我
|
||
</button>
|
||
</div>
|
||
```
|
||
|
||
这说明：
|
||
- Hero 操作区已经预留了多按钮容器 `hero-actions`
|
||
- 新增 GitHub 按钮不需要重构整体布局，只需扩展现有按钮组
|
||
|
||
### 2. 前台联系方式数据来源
|
||
|
||
当前联系方式弹窗内容来自：
|
||
- `content.contact.email`
|
||
|
||
现有弹窗只渲染邮箱：
|
||
|
||
```html
|
||
<span class="email-text" id="emailText">{{ content.contact.email }}</span>
|
||
```
|
||
|
||
说明当前 `contact` 数据结构只被用于邮箱展示，没有 GitHub 相关字段。
|
||
|
||
### 3. 后台编辑页当前只支持邮箱
|
||
|
||
后台模板位于：
|
||
- `home/templates/admin/index.html`
|
||
|
||
当前“联系方式”区块只有一个字段：
|
||
|
||
```html
|
||
<input type="email" class="form-input" id="contact_email" value="{{ content.contact.email }}">
|
||
```
|
||
|
||
前端提交草稿 / 发布时，`collectFormData()` 也只收集邮箱：
|
||
|
||
```js
|
||
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 结构：
|
||
|
||
```python
|
||
"contact": {
|
||
"email": ""
|
||
}
|
||
```
|
||
|
||
示例内容文件位于：
|
||
- `home/data/home_content.json`
|
||
|
||
当前 contact 示例也仅有：
|
||
|
||
```json
|
||
"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 字段。
|
||
|
||
建议结构：
|
||
|
||
```json
|
||
"contact": {
|
||
"email": "ephron_ren@163.com",
|
||
"github_url": "https://github.com/ephron-ren"
|
||
}
|
||
```
|
||
|
||
### 可选增强方案
|
||
|
||
如果希望按钮文案也可配置，可以进一步扩展为：
|
||
|
||
```json
|
||
"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）
|
||
|
||
建议形式：
|
||
|
||
```html
|
||
<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 按钮文案
|
||
|
||
```html
|
||
<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()` 必须同步扩展。
|
||
|
||
最低改法：
|
||
|
||
```js
|
||
contact: {
|
||
email: document.getElementById('contact_email').value,
|
||
github_url: document.getElementById('contact_github_url').value
|
||
}
|
||
```
|
||
|
||
若支持按钮文案：
|
||
|
||
```js
|
||
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
|
||
|
||
### 建议实现
|
||
|
||
保留现有“联系我”按钮不变，在右侧新增一个锚点按钮：
|
||
|
||
```html
|
||
<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>
|
||
```
|
||
|
||
### 为什么建议条件渲染
|
||
|
||
使用：
|
||
|
||
```jinja2
|
||
{% 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` 只有：
|
||
|
||
```json
|
||
{ "email": "..." }
|
||
```
|
||
|
||
那么模板若直接访问 `content.contact.github_url`，可能出现以下问题：
|
||
- Jinja 取不到字段导致空值
|
||
- 管理页输入框初始值异常
|
||
- 前台逻辑不统一
|
||
|
||
### 建议
|
||
|
||
在内容读取或默认值合并处做轻量兼容，保证旧数据自动补默认字段。
|
||
|
||
建议方向二选一：
|
||
|
||
#### 方案 A：服务层补默认值（推荐）
|
||
在 `get_published_content()` / `get_draft_content()` / `get_content_for_edit()` 返回前，对 `contact` 做 schema normalize。
|
||
|
||
例如确保返回结构至少包含：
|
||
|
||
```python
|
||
content.setdefault("contact", {})
|
||
content["contact"].setdefault("email", "")
|
||
content["contact"].setdefault("github_url", "")
|
||
```
|
||
|
||
若采用增强方案，再补：
|
||
|
||
```python
|
||
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
|
||
- 后台表单
|
||
- 提交收集逻辑
|
||
- 前台模板
|
||
- 旧数据兼容
|
||
|
||
否则会出现“按钮显示了但后台不能改”或“后台能填但前台不渲染”的半更新状态。
|