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

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

---

## 1. 五行匹配

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

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

---

## 2. 数据模型

### Contact 实体

```java
/**
 * 通讯录关系
 * 记录用户维护的重要人际关系
 */
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天"）|

### 空状态

```html
<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 映射 |