# 首页快捷方式自定义 + 应用库 + 频度追踪 设计规格

- 日期：2026-09-21
- 状态：待用户审查
- 涉及模块：`cfc-backend`（后端）+ `cfc-frontend`（微信小程序）

---

## 1. 背景与目标

首页（`pages/index-home/index.vue`）在"开通会员"卡片下方有一排 **6 个硬编码快捷入口**：任务、互动、天盘、成员、圈子、商城。

当前问题：
- 6 个入口写死在模板里，用户无法自定义。
- 平台有大量"可直接进入"的功能页面（健康报告、饮食推荐、AI 管家、成长记录、心愿、测评、小游戏、活动、会员中心、财富等），散落在各分包，用户找不到。
- 没有记录用户对每个功能的使用频度，无法做个性化推荐。

目标：
1. 把这 6 个快捷入口改造成**用户可自定义**（从应用库选择放哪些）。
2. 为每个可直接进入的功能设计**图标**，形成**应用库**。
3. 记录用户进入每个应用的**次数**。
4. 根据**使用频度**自动调整首页快捷方式（锁定应用优先 + 频度填充）。
5. 已在首页有显著入口的功能，**不进快捷配置列表**（避免重复）。

---

## 2. 需求澄清结论（已与用户确认）

| 问题 | 结论 |
|------|------|
| 频度调整机制 | **自动排序但可手动覆盖**：系统按频度排序，但用户手动锁定后以锁定为准 |
| 配置与频度存储 | **服务端存储**（换设备同步、频度累计准确） |
| 适用人群 | **所有登录用户**（非会员与会员一致） |
| 首页重复功能 | **已在首页显著位置的功能，从配置列表中排除** |
| 应用库范围 | **全部候选功能都入库** |
| 锁定的语义 | **锁定 = 置顶**，不会被点击次数挤掉；但用户仍可手动移除 |
| 锁定操作入口 | **只在应用库配置页管理**，首页不显示锁图标 |
| 自动填充逻辑 | **锁定占位 + 频度填满剩余** |
| 锁定应用内部排序 | **支持**手动调整锁定应用之间的顺序 |
| 频度计数触发 | **任意入口进入都计数**（含 TabBar 页） |

---

## 3. 架构方案

采用 **混合方案**：

- **应用库 = 前端常量文件** `utils/app-library.js`，图标用 **emoji**（与现有 6 个快捷入口一致，零静态资源成本）。
- **后端建 2 张表**：`user_shortcut_config`（用户快捷配置）+ `user_app_usage`（使用频度）。

理由：
- 应用库本质是静态配置（key/名称/图标/路由/是否可快捷），前端维护最灵活，迭代快。
- 新增应用需发版（可接受，功能迭代本就发版）。
- 符合 YAGNI：应用库无"运营后台动态增删"需求，不做成后端表。

---

## 4. 数据模型

### 4.1 `user_shortcut_config`（用户快捷配置）

记录"用户把某个应用放到快捷区"的配置，**每应用一条记录**，`locked` 决定是否锁定。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO | 主键 |
| user_id | BIGINT NOT NULL | 用户 ID |
| app_key | VARCHAR(64) NOT NULL | 应用 key（对应 app-library.js） |
| locked | TINYINT DEFAULT 0 | 是否锁定（1=锁定/置顶，0=普通） |
| sort_order | INT DEFAULT 0 | 手动排序序号（锁定的应用之间排序用） |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

- **唯一索引**：`(user_id, app_key)`

> 语义：`locked=1` 的应用在首页快捷区**始终保留**（不被频度排序挤掉），按 `sort_order` 升序排在最前；`locked=0` 的应用参与频度填充。

### 4.2 `user_app_usage`（应用使用频度）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO | 主键 |
| user_id | BIGINT NOT NULL | 用户 ID |
| app_key | VARCHAR(64) NOT NULL | 应用 key |
| enter_count | INT DEFAULT 0 | 累计进入次数 |
| last_enter_at | DATETIME | 最近进入时间 |

- **唯一索引**：`(user_id, app_key)`

---

## 5. 应用库清单（前端常量 `utils/app-library.js`）

每个应用字段：`key`、`name`、`icon`（emoji）、`route`、`canShortcut`（是否可放首页快捷区）。

| key | 名称 | 图标 | 路由 | canShortcut |
|-----|------|------|------|:---:|
| task | 任务 | 📋 | /pages/tasks/tasks | ✅ |
| interaction | 互动 | 💬 | /pages/action-detail/interaction-log | ✅ |
| tiandi | 天盘 | 🏠 | /pages/mind-detail/family-dashboard | ✅ |
| members | 成员 | 👨‍👩‍👧‍👦 | /pages/profile-extra/family-members | ✅ |
| circle | 圈子 | 🤝 | /pages/discover/circles | ✅ |
| shop | 商城 | 🛒 | /pages/shop/index/index | ✅ |
| diet | 饮食推荐 | 🥗 | /pages/diet/index | ✅ |
| ai | AI管家 | 🤖 | /pages/ai/chat | ✅ |
| growth | 成长记录 | 📈 | /pages/growth-main/index | ✅ |
| wish | 心愿 | ⭐ | /pages/wishes/index | ✅ |
| medal | 勋章 | 🏅 | /pages/rewards/rewards | ✅ |
| game | 小游戏 | 🎮 | /pages/games/list | ✅ |
| assess | 测评 | 🧪 | /pages/assessment/apply | ✅ |
| activity | 活动 | 🎪 | /pages/activity/index | ✅ |
| membership | 会员中心 | 👑 | /pages/membership/index | ✅ |
| wealth | 财富 | 💰 | /pages/wealth/index | ✅ |
| report | 健康报告 | 🩺 | /pages/health/report-upload | ❌ 已在首页 |
| article | 文章中心 | 📖 | /pages/article-center/index | ❌ 已在首页(推荐阅读) |

> `canShortcut=false` 的应用在应用库页面可见但**置灰 + 标注"已在首页"**，用户无法选入 6 格。

**默认 6 格**（新用户 / 无配置时）= 当前硬编码的 6 个：task、interaction、tiandi、members、circle、shop。

---

## 6. API 设计（统一 `@PostMapping` + `Result<T>`，JWT 认证）

### 6.1 `POST /api/home/app-library`
返回应用库 + 我的快捷配置 + 频度，**合并为一次请求**（避免 N+1）。

- 请求：无 body（从 JWT 取 user_id）
- 响应 `data`：
  ```json
  {
    "apps": [
      { "key": "task", "name": "任务", "icon": "📋", "route": "/pages/tasks/tasks", "canShortcut": true }
    ],
    "myShortcuts": [
      { "appKey": "task", "locked": true, "sortOrder": 0 }
    ],
    "usage": { "task": 12, "shop": 8 }
  }
  ```

### 6.2 `POST /api/home/shortcut/save`
保存用户配置（全量覆盖用户对该用户的快捷配置）。

- 请求 body：`{ "items": [ { "appKey": "task", "locked": true, "sortOrder": 0 } ] }`
- 语义：删除该用户旧的 `user_shortcut_config` 记录，批量插入新的 `items`（每个 item 一条记录）。
- 响应：`Result<Void>`

### 6.3 `POST /api/home/app/enter`
记录进入次数。

- 请求 body：`{ "appKey": "task" }`
- 语义：`user_app_usage` 的 `enter_count` +1，更新 `last_enter_at`（不存在则插入）。
- 响应：`Result<Void>`

### 6.4 `POST /api/home/shortcut/reset`
重置为默认（清除锁定，回到系统按频度排序）。

- 请求：无 body
- 语义：删除该用户的 `user_shortcut_config` 记录。
- 响应：`Result<Void>`

---

## 7. 前端改造

### 7.1 首页快捷区（`pages/index-home/index.vue`）

- 将 6 个硬编码 `<view class="quick-item">` 改为 `v-for` 动态渲染，数据来自 `POST /api/home/app-library`。
- 快捷区右上角加"编辑"小图标 → 跳转应用库配置页 `/pages/home/app-library`。
- 快捷区点击某个应用 → 先 `navTo(route)`，再调用 `POST /api/home/app/enter` 记录频度（注意：频度计数是"任意入口"，故记录逻辑放在各应用入口页 onLoad，而非仅首页点击处，见 7.4）。

### 7.2 应用库配置页（新增 `pages/home/app-library`）

- 在 `pages.json` 注册（复用或新建分包 `pages/home`）。
- 页面结构：
  1. 顶部：**当前首页快捷区**（6 格预览），支持：
     - 添加/移除应用（点击应用库里的应用切换选中态）
     - 拖动/上移下移调整锁定应用顺序（小程序用「长按排序」或「上移/下移」按钮，避免复杂拖拽）
     - 每个锁定应用显示"🔒 已锁定"标识
  2. 中部：**应用库网格**，展示所有应用（图标 + 名称 + 进入次数），`canShortcut=false` 的置灰标注"已在首页"。
  3. 底部按钮：
     - **保存** → `POST /api/home/shortcut/save`
     - **一键按频度排序** → 清除锁定，回到系统自动排序（调 `POST /api/home/shortcut/reset`）

### 7.3 前端 API 封装（`utils/api.js`）

按 AGENTS.md 规则 2（同 URL 唯一入口）新增：
```js
export const getAppLibrary = () => request('/api/home/app-library', 'POST', {})
export const saveShortcutConfig = (items) => request('/api/home/shortcut/save', 'POST', { items })
export const reportAppEnter = (appKey) => request('/api/home/app/enter', 'POST', { appKey })
export const resetShortcutConfig = () => request('/api/home/shortcut/reset', 'POST', {})
```

### 7.4 频度计数埋点（"任意入口进入都计数"）

在每个应用入口页的 `onLoad`（非 onShow，避免 Tab 切换重复计数）中调用 `reportAppEnter(appKey)`。

- 复用 `_onLoadFired` 模式：`onLoad` 只触发一次，天然适合计数。
- 埋点页面 = 应用库清单中所有 `canShortcut=true` 应用的入口页（约 16 个页面），在各自 `onLoad` 里加一行 `reportAppEnter('xxx')`（静默失败，不阻塞页面）。

---

## 8. 首页快捷区排序算法（核心逻辑）

**输入**：`myShortcuts`（含 locked 标记）+ `usage`（频度）。

**输出**：6 个应用 key（有序）。

```
1. lockedApps = myShortcuts 中 locked=1 的应用，按 sort_order 升序
2. if lockedApps.length >= 6:
       取前 6 个
   else:
       remaining = 6 - lockedApps.length
       candidates = app-library 中 canShortcut=true 且 不在 lockedApps 里的应用
       fill = candidates 按 usage[appKey] 降序排序，取前 remaining 个
       若候选不足 remaining，用默认顺序补齐（不足 6 格就少显示）
   结果 = lockedApps + fill
```

> 说明：`myShortcuts` 里 `locked=0` 的应用本质上是"用户主动加入但未锁定"的，在填充阶段它们会被纳入 `candidates` 一起按频度排序，因此仍有机会显示（频度高时），也可能被更高频应用挤掉。

---

## 9. 后端实现要点

### 9.1 文件

| 文件 | 说明 |
|------|------|
| `entity/UserShortcutConfig.java` | 实体，`@TableName("user_shortcut_config")` |
| `entity/UserAppUsage.java` | 实体，`@TableName("user_app_usage")` |
| `mapper/UserShortcutConfigMapper.java` | MyBatis-Plus Mapper |
| `mapper/UserAppUsageMapper.java` | MyBatis-Plus Mapper |
| `controller/HomeController.java` | 4 个接口 |
| `service/HomeShortcutService.java`（或并入 controller） | 业务逻辑 |

### 9.2 迁移（`DatabaseInitializer.runMigrations()`）

新增迁移编号 **327**，建两张表（幂等，`CREATE TABLE IF NOT EXISTS`），并同步 `schema.sql`：

```sql
CREATE TABLE IF NOT EXISTS user_shortcut_config (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT NOT NULL,
  app_key VARCHAR(64) NOT NULL,
  locked TINYINT DEFAULT 0,
  sort_order INT DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_user_app (user_id, app_key)
);

CREATE TABLE IF NOT EXISTS user_app_usage (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT NOT NULL,
  app_key VARCHAR(64) NOT NULL,
  enter_count INT DEFAULT 0,
  last_enter_at DATETIME,
  UNIQUE KEY uk_user_app (user_id, app_key)
);
```

### 9.3 规范遵循

- `@PostMapping`、`Result<T>`、`@Resource` DI、JWT 认证（拦截 `/api/**`）。
- Controller 内手动校验 `@RequestAttribute("role")`（所有登录角色可用，无需角色限制）。
- Bean 命名无冲突（`HomeController` 需确认不与现有类重名）。

---

## 10. 边界情况

1. **锁定数 > 6**：取 `sort_order` 前 6 个锁定应用。
2. **候选应用不足 6 个**：少显示即可（不报错）。
3. **频度全为 0**：用默认 6 个顺序。
4. **并发计数**：`app/enter` 用 `UPDATE ... SET enter_count = enter_count + 1` 原子更新，避免覆盖。
5. **重复上报**：`onLoad` 只触发一次，天然去重；后端对同 key 同用户做 upsert。
6. **换设备**：配置与频度都在服务端，登录后同步。

---

## 11. 测试

- **后端单测**：`HomeShortcutService` 排序算法（锁定占位 + 频度填充、锁定>6、候选不足）。
- **前端**：`utils/app-library.js` 导出结构校验；首页快捷区 `v-for` 渲染（含空态）。
- **CI 门禁**：`node scripts/audit-duplicate-api-calls.js` 通过（新页面 onLoad 埋点不重复打同一 URL）。

---

## 12. 交付范围

- 后端：2 张表迁移 + 2 实体 + 2 Mapper + 1 Controller + 排序逻辑。
- 前端：`utils/app-library.js` + `utils/api.js` 4 个封装 + 首页改造 + 应用库配置页 + 16 个入口页埋点。
- 不涉及：运营后台动态维护应用库（YAGNI，后续有需求再扩展）。