cfc/docs/superpowers/specs/2026-06-14-action-page-relationship-design.md

行远页 · 重要关系维护设计

Status: Draft Date: 2026-06-14 Scope: 行远（行动）TabBar 页新增「重要关系」区块 + 后端 Contact CRUD + 通讯录导入

---

1. 五行匹配

维度	五行	属性	对应关系维护
行远（行动）	木	生发·仁爱	关系践行、社群连接 → 人脉根系

关系网络的本质是人际联结的"根系"，如同树木根系交错滋养生命，天然对应行远·木属性。

---

2. 数据模型

Contact 实体

/**
 * 通讯录关系
 * 记录用户维护的重要人际关系
 */
public class Contact {
    private Long id;
    private Long userId;            // 关系拥有者
    private String name;            // 姓名
    private String phone;           // 手机号
    private String avatar;          // 头像URL（通讯录导入或手动上传）

    /**
     * 关系类型:
     * family(家人) / friend(朋友) / partner(伴侣)
     * / colleague(同事) / other(其他)
     */
    private String relationshipType;

    private Date knownSince;        // 认识时间
    private String bio;             // 个人介绍/备注
    private Date birthday;          // 生日
    private Integer intimacyLevel;  // 亲密度 0-100
    private String contactSource;   // 来源: phone(通讯录导入) / manual(手动添加)
    private String tags;            // 标签 JSON: ["老友","同事"]
    private Date lastContactAt;     // 最近联系时间
    private Integer contactCount;   // 累计联系次数
    private String notes;           // 备注
    private Date createdAt;
    private Date updatedAt;
}

亲密度计算规则

基础分 = min(contactCount * 5, 60)          // 联系次数，上限60
活跃分 = 0
  if lastContactAt 在7天内: +20
  if lastContactAt 在30天内: +10
  if lastContactAt 在90天内: +5
  if lastContactAt 超过1年: -10
手动调整 = 用户可 ±20
intimacyLevel = clamp(基础分 + 活跃分 + 手动调整, 0, 100)

---

3. 通讯录导入流程

行远页 → [📱 导入通讯录] 按钮
     ↓
wx.chooseContact()  // 微信小程序API，选择手机通讯录联系人
     ↓
用户选择联系人 → 获取 name + phone
     ↓
POST /api/contact/import-phone  { name, phone, userId }
     ↓
后端查重: SELECT FROM contacts WHERE userId=? AND phone=?
     ↓
┌─ 已存在 ──────────────────────────────────────┐
│  提示："张三"已在您的关系列表中                    │
│  [查看详情] [取消]                               │
└───────────────────────────────────────────────┘
     ↓
┌─ 新建 ────────────────────────────────────────┐
│  弹出补充信息浮层 ContactImport.vue              │
│  ┌─────────────────────────────────────────┐   │
│  │  👤 张三                                │   │
│  │  关系类型: [▼ 朋友]                      │   │
│  │  认识时间: [2021-06-01]                 │   │
│  │  生日: [03/15]                          │   │
│  │  个人介绍: [大学同学...]                 │   │
│  │  [确认添加]  [取消]                      │   │
│  └─────────────────────────────────────────┘   │
└───────────────────────────────────────────────┘
     ↓
联系人列表更新

---

4. 行远页变更（登录后）

┌─ 行远品牌头 + 能量值 ────────────────────────┐
├─ 功能入口 Grid ──────────────────────────────┤
├─ ✅ 今日待办 ────────────────────────────────┤
│  ...                                         │
├─ 🔥 重要关系 ──────────────── [?] [📱导入] ─┤
│  ┌──────────────────────────────────────┐    │
│  │ 👤 张三     [朋友] 认识5年  ❤️85     │    │  ← 横向滚动卡片
│  │   📞 138xxxx  🎂 06/15               │    │
│  ├──────────────────────────────────────┤    │
│  │ 👤 李四     [家人]  ❤️95             │    │
│  │   📞 139xxxx  🎂 03/20               │    │
│  └──────────────────────────────────────┘    │
│  [👁 查看全部 N人 →]                         │
├─ 🎉 热门活动 ───────────────────────────────┤
├─ 📈 行远能量周报 ────────────────────────────┤
└─ 🛍️ 推荐商品 ───────────────────────────────┘

关系卡片（ContactCard.vue）

每个卡片展示字段：

字段	渲染方式
头像	首字圆形渐变底色（按 relationshipType 分色）或通讯录头像
姓名	18rpx 加粗
关系类型	彩色标签：家人 #10B981 绿 / 朋友 #F59E0B 黄 / 伴侣 #FF6B35 橙 / 同事 #3B82F6 蓝 / 其他 #94A3B8 灰
认识时间	"认识 X 年"
亲密度	❤️ + 数值（颜色随值渐变：低#94A3B8 中#F59E0B 高#FF6B35）
手机号	小字显示
生日	🎂 MM/DD（距30天内显示 "还有N天"）

空状态

<view class="empty-state">
  <text class="empty-icon">📇</text>
  <text class="empty-title">还没有记录重要关系</text>
  <text class="empty-desc">导入手机通讯录或手动添加重要的人</text>
  <view class="empty-actions">
    <button class="btn-import">📱 导入通讯录</button>
    <button class="btn-manual">➕ 手动添加</button>
  </view>
</view>

游客模式

游客看不到「重要关系」区块 — 区块直接 v-if="isLoggedIn" 控制。

---

5. 关系详情页（contact-detail.vue）

┌─ 返回 ── 关系详情 ──────── [编辑] ────────┐
│                                            │
│           👤 张                             │
│           张三                              │
│           朋友 · 认识5年                    │
│           ❤️ 亲密度 85                      │
│                                            │
├─ 基本信息 ─────────────────────────────────┤
│  📞 138xxxx1234                            │
│  🎂 06月15日                               │
│  📝 大学同学，现在同一城市                   │
│  🏷️ #老友 #同事                             │
│                                            │
├─ 互动记录 ─────────────────────────────────┤
│  2026-06-10  浏览了资料                     │
│  2026-05-20  更新了生日                     │
│  2026-04-01  导入了通讯录                   │
│  [📞 标记联系]                              │
└────────────────────────────────────────────┘

---

6. API 清单

接口	Method	说明
POST /api/contact/list	需登录	获取当前用户所有联系人
POST /api/contact/create	需登录	手动创建联系人
POST /api/contact/update	需登录	编辑联系人
POST /api/contact/delete	需登录	删除联系人
POST /api/contact/detail	需登录	联系人详情
POST /api/contact/import-phone	需登录	从通讯录导入（接收 name + phone）
POST /api/contact/interaction	需登录	标记一次互动

---

7. 文件变更清单

操作	文件	说明
✨	cfc-backend/.../entity/Contact.java	通讯录关系实体
✨	cfc-backend/.../dto/ContactDTO.java	关系传输对象
✨	cfc-backend/.../mapper/ContactMapper.java	MyBatis Mapper
✨	cfc-backend/.../service/ContactService.java	关系业务逻辑
✨	cfc-backend/.../controller/ContactController.java	关系 API
✨	cfc-frontend/components/ContactCard.vue	关系卡片组件
✨	cfc-frontend/components/ContactImport.vue	通讯录导入浮层
✨	cfc-frontend/pages/action/contact-detail.vue	关系详情页
🔄	cfc-frontend/pages/action/index.vue	插入「重要关系」区块
🔄	cfc-frontend/pages.json	注册 contact-detail 页面
🔄	cfc-frontend/utils/api.js	新增 contact API 封装
🔄	cfc-backend/.../resources/mapper/ContactMapper.xml	SQL 映射