ephron-ren-prd/prd-home-icp-link-icp-url-followup.md

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

"footer": {
  "copyright": "...",
  "icp": "...",
  "icp_link": "https://beian.miit.gov.cn/"
}

当前代码 / 后台使用

• home/src/services/content.py
• home/templates/admin/index.html
• 后台 collectFormData()

这些位置使用的是：

footer["icp_url"]

或：

icp_url: document.getElementById('footer_icp_url').value

---

风险

这个问题当前风险不高，但会带来以下长期问题：

1. 示例数据误导

   • 后续维护者会误以为正式字段名是 icp_link

2. 手工编辑数据容易写错

   • 如果有人参考 home_content.json 或旧数据手工写入 JSON，可能继续写 icp_link
   • 结果后台和前台读取不到，表现为备案链接丢失

3. schema 漂移扩大

   • 如果不收敛，后续可能继续出现：
     • 模板用一套名
     • 示例数据一套名
     • 测试再补一套名

4. 增加兼容负担

   • 当前是小问题，越晚统一，越容易变成必须长期兼容两套字段

---

目标

统一 Home 内容中 ICP 备案链接字段命名，明确唯一正式字段为：

footer.icp_url

并确保：

• 示例数据一致
• 服务层兼容旧字段
• 后台编辑读写一致
• 前台渲染一致

---

建议方案

一、正式字段名定为 icp_url

理由：

• 当前服务层默认 schema 已经使用 icp_url
• 后台表单和 collectFormData() 也已经使用 icp_url
• 继续沿用现代码主线改动最小

因此本次 follow-up 不建议反向改回 icp_link。

---

二、修正示例数据文件

必改文件

• home/data/home_content.json

修改内容

将：

"icp_link": "https://beian.miit.gov.cn/"

改为：

"icp_url": "https://beian.miit.gov.cn/"

目的

让示例数据与实际 schema 对齐，避免继续误导维护者。

---

三、服务层补旧字段兼容迁移

必改文件

• home/src/services/content.py

现状

当前 _normalize_content() 已补：

• footer.icp_url
• footer.beian_url

但若旧数据里已有：

"footer": {
  "icp_link": "https://..."
}

而没有 icp_url，那么当前 normalize 若只 setdefault("icp_url", "")，会导致：

• 旧值不会自动迁移到 icp_url
• 后台打开后看起来像空值
• 再次保存时会把旧字段信息“洗掉”

建议兼容逻辑

在 _normalize_content() 中增加迁移规则：

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 相关测试中增加一个兼容场景：

用例

当旧内容使用：

"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 数据
• 避免后台再次保存时无意丢失旧值

这是一个典型的小修正，不应扩成大改动。