From e86f0113bdff8b1d828467f94e287cce70d387ad Mon Sep 17 00:00:00 2001
From: Ubuntu <ubuntu@localhost.localdomain>
Date: Mon, 18 May 2026 10:33:51 +0800
Subject: [PATCH] docs: add home icp field follow-up PRD

---
 prd-home-icp-link-icp-url-followup.md | 242 ++++++++++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 prd-home-icp-link-icp-url-followup.md

diff --git a/prd-home-icp-link-icp-url-followup.md b/prd-home-icp-link-icp-url-followup.md
new file mode 100644
index 0000000..d7f4a66
--- /dev/null
+++ b/prd-home-icp-link-icp-url-followup.md
@@ -0,0 +1,242 @@
+# Follow-up PRD：统一 Home 内容中的 `icp_link` / `icp_url` 字段命名
+
+## 背景
+
+在验收 `home` 页新增 GitHub 按钮功能时，发现 Home 内容示例数据与当前服务 schema 之间仍存在一个遗留字段漂移问题：
+
+- `home/data/home_content.json` 中使用的是：`footer.icp_link`
+- 但当前 Home 服务代码和后台表单使用的是：`footer.icp_url`
+
+这不是本次 GitHub 功能的阻塞项，但属于会持续制造误导的命名不一致，应尽快收敛。
+
+---
+
+## 问题定义
+
+当前 Home 内容相关实现中，ICP 链接字段存在双命名：
+
+### 示例数据
+`home/data/home_content.json`
+
+```json
+"footer": {
+  "copyright": "...",
+  "icp": "...",
+  "icp_link": "https://beian.miit.gov.cn/"
+}
+```
+
+### 当前代码 / 后台使用
+- `home/src/services/content.py`
+- `home/templates/admin/index.html`
+- 后台 `collectFormData()`
+
+这些位置使用的是：
+
+```python
+footer["icp_url"]
+```
+
+或：
+
+```js
+icp_url: document.getElementById('footer_icp_url').value
+```
+
+---
+
+## 风险
+
+这个问题当前风险不高，但会带来以下长期问题：
+
+1. **示例数据误导**
+   - 后续维护者会误以为正式字段名是 `icp_link`
+
+2. **手工编辑数据容易写错**
+   - 如果有人参考 `home_content.json` 或旧数据手工写入 JSON，可能继续写 `icp_link`
+   - 结果后台和前台读取不到，表现为备案链接丢失
+
+3. **schema 漂移扩大**
+   - 如果不收敛，后续可能继续出现：
+     - 模板用一套名
+     - 示例数据一套名
+     - 测试再补一套名
+
+4. **增加兼容负担**
+   - 当前是小问题，越晚统一，越容易变成必须长期兼容两套字段
+
+---
+
+## 目标
+
+统一 Home 内容中 ICP 备案链接字段命名，明确唯一正式字段为：
+
+```json
+footer.icp_url
+```
+
+并确保：
+- 示例数据一致
+- 服务层兼容旧字段
+- 后台编辑读写一致
+- 前台渲染一致
+
+---
+
+## 建议方案
+
+## 一、正式字段名定为 `icp_url`
+
+理由：
+- 当前服务层默认 schema 已经使用 `icp_url`
+- 后台表单和 `collectFormData()` 也已经使用 `icp_url`
+- 继续沿用现代码主线改动最小
+
+因此本次 follow-up 不建议反向改回 `icp_link`。
+
+---
+
+## 二、修正示例数据文件
+
+### 必改文件
+- `home/data/home_content.json`
+
+### 修改内容
+将：
+
+```json
+"icp_link": "https://beian.miit.gov.cn/"
+```
+
+改为：
+
+```json
+"icp_url": "https://beian.miit.gov.cn/"
+```
+
+### 目的
+让示例数据与实际 schema 对齐，避免继续误导维护者。
+
+---
+
+## 三、服务层补旧字段兼容迁移
+
+### 必改文件
+- `home/src/services/content.py`
+
+### 现状
+当前 `_normalize_content()` 已补：
+- `footer.icp_url`
+- `footer.beian_url`
+
+但若旧数据里已有：
+
+```json
+"footer": {
+  "icp_link": "https://..."
+}
+```
+
+而没有 `icp_url`，那么当前 normalize 若只 `setdefault("icp_url", "")`，会导致：
+- 旧值不会自动迁移到 `icp_url`
+- 后台打开后看起来像空值
+- 再次保存时会把旧字段信息“洗掉”
+
+### 建议兼容逻辑
+在 `_normalize_content()` 中增加迁移规则：
+
+```python
+footer = content.setdefault("footer", {})
+legacy_icp_link = footer.get("icp_link")
+if not footer.get("icp_url") and legacy_icp_link:
+    footer["icp_url"] = legacy_icp_link
+footer.setdefault("icp_url", "")
+```
+
+### 是否删除旧字段
+本次建议：
+- **运行时兼容旧字段即可**
+- 不要求在 normalize 时强制删除 `icp_link`
+
+原因：
+- 当前目标是安全兼容，不是激进清洗
+- 避免无必要扩大改动面
+
+---
+
+## 四、测试补充
+
+### 建议新增测试
+在 Home 相关测试中增加一个兼容场景：
+
+#### 用例
+当旧内容使用：
+
+```json
+"footer": {
+  "icp": "...",
+  "icp_link": "https://beian.miit.gov.cn/"
+}
+```
+
+而没有 `icp_url` 时：
+- 服务层应自动补出 `icp_url`
+- 后台渲染时 `footer_icp_url` 输入框应能看到该值
+- 不应丢失原备案链接
+
+### 目标
+避免未来再次改坏这个兼容逻辑。
+
+---
+
+## 修改范围
+
+### 必改
+1. `home/data/home_content.json`
+   - `icp_link` → `icp_url`
+
+2. `home/src/services/content.py`
+   - `_normalize_content()` 增加旧字段兼容迁移逻辑
+
+### 建议补充
+3. `home/tests/...`
+   - 新增 `icp_link` → `icp_url` 兼容测试
+
+---
+
+## 验收标准
+
+### 数据一致性
+1. `home/data/home_content.json` 中不再出现 `icp_link`
+2. 示例数据统一使用 `icp_url`
+
+### 兼容性
+1. 若历史内容只有 `footer.icp_link`，页面仍可正常读取备案链接
+2. 后台打开旧内容时，ICP 链接输入框能正确回显
+3. 保存草稿 / 发布后，不会因为字段名变化丢失备案链接
+
+### 回归安全
+1. 现有使用 `icp_url` 的内容不受影响
+2. GitHub 按钮相关改动不受影响
+
+---
+
+## 非目标
+
+本次 follow-up 不处理：
+- `beian_link` / `beian_url` 是否也存在历史漂移（除非源码已确认存在）
+- Footer 区块整体重构
+- Home 内容 schema 的全面版本化
+
+---
+
+## 结论
+
+这是一个低优先级但值得尽快收口的 schema 一致性问题。
+
+本次 follow-up 应聚焦：
+- **统一命名为 `icp_url`**
+- **兼容历史 `icp_link` 数据**
+- **避免后台再次保存时无意丢失旧值**
+
+这是一个典型的小修正，不应扩成大改动。