docs: 地址联系人回填真实姓名设计（自检修正+文档索引同步）

docs/superpowers/PROJECT-OVERVIEW.md

@@ -378,6 +378,7 @@
 | `2026-09-10-key-person-expansion-octopus-design.md` | 🟡 设计规格已确认（成效对象=会员客户 + 类型bitmask + 关键人画像 + 四步法 + 高频词≤8方向；3表/10接口/三层画布；替换旧章鱼图） | 关键人拓展章鱼图替换设计（关系三图重构） |
 | `2026-09-19-article-reading-quiz-design.md` | 🟢 已实施（补全现有阅读答题：article_quiz_records 表 + LangGraph article_quiz_graph 出题 + AiGateway 接入 + 提交答题落库 + CF值/五维能量双奖励 + profile_snapshot.quiz_summary 认知雷达） | 文章阅读后答题奖励 + 认知雷达记录设计 |
 | `2026-09-22-guide-popup-config-design.md` | ✅ 已实施（4表/guide_popup+step+trigger+log，9接口，ConfigurableGuide.vue组件+管理端2页；旧 sys_config 方案保留并行） | 弹窗引导页配置化管理设计 |
+| `2026-10-10-address-contact-backfill-realname-design.md` | 🟡 设计稿（后端统一回填方案：`RealNameBackfillService` 独立组件 + `UserAddressService.create/update` + `ConsigneeService.save` 两入口回填，realName 为空才回填，幂等） | 地址联系人回填真实姓名设计 |
 
 ### 实施计划（plans/）
 

docs/superpowers/specs/2026-10-10-address-contact-backfill-realname-design.md

@@ -22,14 +22,15 @@
 | 收货人管理 `/api/consignee/save`（新增 + 编辑） | `name` | `ConsigneeService.save()` |
 
 - 家庭地址页（`pages/family/address-edit`）无联系人字段，不涉及。
-- 回填目标始终为**当前登录用户**的 `realName`（userId 已是两个 Service 的方法参数）。
+- 回填目标始终为**当前登录用户**的 `realName`。userId 来源：`UserAddressService.create/update` 由方法参数传入；`ConsigneeService.save` 在新增分支取 `consignee.getUserId()`、编辑分支取 `existing.getUserId()`。
 
 ## 实现要点
 
-1. 新增私有方法 `backfillRealNameIfEmpty(Long userId, String contactName)`：
+1. 新增独立组件 `RealNameBackfillService`（`@Service`，依赖 `UserMapper`），提供方法 `backfill(Long userId, String contactName)`：
    - `contactName` 空白 → 直接返回（不回填）
    - 查询用户，`realName == null || trim().isEmpty()` → `setRealName(contactName.trim())` + `updateById`
-2. `UserAddressService.create/update`、`ConsigneeService.save`（新增与编辑两支）在保存成功后调用。
+   - 用独立组件而非私有方法：`UserAddressService` 与 `ConsigneeService` 两个类都要调用，且避免 `UserService` 双向依赖
+2. `UserAddressService.create/update`、`ConsigneeService.save`（新增与编辑两支）在保存成功后注入并调用 `RealNameBackfillService#backfill`。
 3. 风格参照现有 `ConsigneeService.syncUserRegion()`：回填失败 try-catch 静默，**不阻塞地址保存主流程**。
 4. 零 schema 变更（`users.real_name` 列已存在）；零前端改动；无新接口（不新增路由，无需更新 API_REFERENCE）。