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

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