# Feature Spec: 首页（发现与入口）

> Status: `Active` · Map: `§1 首页 [P1]` · Phase: `P1`  
> 规范：[../feature-design.md](../feature-design.md)

---

## 1. 功能定义

| 字段 | 内容 |
|---|---|
| Name | 首页 |
| Purpose | 品牌露出 + 建档/性格探索主 CTA + 功能入口分发 |
| Business Goal | 新用户进入 Step 1–3；品牌第一屏可识别 |

| In | Out |
|---|---|
| 建档生日表单 → 画像；九宫格/入口 | 运势 Feed 主路径 |
| 推荐区静态/轻运营即可 | Dashboard 式状态墙（如「API 已连接」勿对用户展示） |

---

## 2. 用户价值

1. **为何需要：** 知道从哪开始认识自己。  
2. **完成后获得：** 一键进入画像主路径或其它 Tab。  
3. **付费：** N/A。

---

## 3. 用户角色

| Actor | 能力 |
|---|---|
| 新 Visitor | 见品牌 + 建档 CTA |
| 老用户 | 同样入口；可去「我的」看资产 |

---

## 4. 用户流程

```text
打开 /
  ↓
看到品牌 + 主 CTA（生日/探索）
  ↓
提交生日 → 创建档案 → /portrait
  或
点入口 → /explore /relation /ask /membership …
```

设计约束（前端）：品牌英雄级信号；移动优先；文案 lexicon。

---

## 5. 页面设计

| 路由 | 页面 |
|---|---|
| `/` | HomePage |
| 全局 | AppHeader · TabBar |

```text
/
├── 全局顶栏：透明愈心谷 Logo（AppHeader，全站）
├── 「自己」卡片标题展示账号昵称（默认意象词+场景词；档案页可改）
├── 穿衣指数 · 颜色搭配 · 养生推荐
├── 功能入口（4 列固定网格 · 多行换行 · 禁止横向滑动）
└── （可选）推荐内容
```

---

## 6. 页面状态规范

| 状态 | UI |
|---|---|
| Normal | 主路径可见 |
| Error | 建档/跳转失败可感知 |
| Loading | 提交建档时按钮态 |

Empty：首页本身是入口，不因无档案空白死页。

---

## 7. Business Rules

| ID | Rule |
|---|---|
| R1 | 主 CTA 必须通向建档或画像，而非死链 |
| R2 | 不展示内部运维信息（API 连接状态等） |
| R3 | 入口文案符合 lexicon（个人画像/关系理解/成长会员…） |
| R4 | Tab 五名冻结：首页·探索·问答·陪伴·我的 |
| R5 | 「自己」卡片：穿衣指数 / 颜色搭配 / 养生推荐；有 Self 生日时按生日+**本地日历**+**十二时辰**易经种子生成；**每一时辰准点切换**；无档案或 LLM 不可用则本地回退 |
| R6 | 文案禁止占卜/算命恐吓与医疗疗效承诺；卦象仅作节律意象 |
| R7 | 贴士按 `user × 时辰起点` 持久缓存；GET 优先读缓存**即时返回**；缓存未命中时先回退/旧值，后台异步生成写入，禁止每次打开同步等 LLM |
| R8 | 响应含 `shichen` / `shichen_name` / `valid_until`（下一时辰起点）；前端在 `valid_until` 自动静默刷新 |

---

## 8. 数据模型影响

经首页建档时写 `profiles`。`home_daily_tips(user_id, shichen_start, tips jsonb)` 缓存时辰贴士。

---

## 9. API 需求

| Method | Path | 说明 |
|---|---|---|
| GET | `/api/v1/home/tools` | 宫格（已有） |
| GET | `/api/v1/home/daily-tips` | 自己卡片贴士（读缓存；含 valid_until） |
| — | 复用 | `POST /profiles`、`POST /reports/portrait` |

---

## 10. 权限设计

| 能力 | Visitor | User |
|---|---|---|
| 浏览首页 | ✓ | ✓ |
| 建档并生成画像 | 需登录 | ✓ |
| daily-tips（个性化） | 回退文案 | 有 Self 生日则 LLM |

---

## 11. 埋点

| Event | 触发 |
|---|---|
| `home_viewed` | 打开 |
| `home_cta_portrait` | 主 CTA |
| `home_entry_click` | 九宫格项（带 name） |

---

## 12. 测试验收标准

**Given** 新用户  
**When** 打开首页  
**Then** 可见品牌与建档/探索入口  

**Given** 合法生日  
**When** 提交主 CTA  
**Then** 进入画像基础结果路径  

**Given** 已登录且有 Self 生日、该时辰已有缓存  
**When** GET `/home/daily-tips`  
**Then** 立即返回缓存（含 clothing/palette/wellness / valid_until），不阻塞 LLM  

**Given** 时辰切换到点  
**When** 前端到达 `valid_until`  
**Then** 静默刷新；穿衣/颜色/养生随新时辰更新  

**Given** 无档案或无 LLM  
**When** GET `/home/daily-tips`  
**Then** `source=fallback` 且页面不白屏  

---

## 13. AI 开发前检查

- [x] lexicon  
- [x] 不恐吓 / 不算命话术  
- [x] OpenAPI 已登记 `/home/daily-tips`  

- [x] Spec 齐全  

---

## 14. Implementation Notes

| 项 | 内容 |
|---|---|
| Packages | `HomePage` · `App.vue` shell |
| Gaps | 推荐 Feed 运营位可静态；埋点未接 |
| Process Review | 2026-08-02 [P1-PROCESS-REVIEW](P1-PROCESS-REVIEW.md) · 设计闭合 · 实现 PASS · 测试 PARTIAL |