243 lines
5.2 KiB
Markdown
243 lines
5.2 KiB
Markdown
# 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` 数据**
|
||
- **避免后台再次保存时无意丢失旧值**
|
||
|
||
这是一个典型的小修正，不应扩成大改动。
|