# 灵镜 H5 验证版 - 需求与开发文档

> 最后更新：2026-02-23

---

## 项目概述

灵镜是一个AI灵魂测试器，通过30题深度对话发现用户的性格特点、潜能、天赋和发展路线，生成专属洞察报告。

**访问地址**：https://lingjing.darkerilclaw.com
**服务器**：103.201.130.54，端口3200，PM2进程：lingjing-api
**项目路径**：/root/Projects/lingjing/

---

## 技术栈

- 前端：Next.js + Tailwind CSS（app router）
- 后端：Node.js + Express（server.js）
- AI模型：GPT-5.3-Codex（ycapis API）
- 部署：PM2 + Caddy反代

---

## 设计原则（范总确认）

1. **沉浸感第一** — 黑色背景星空飞驰，全屏无边栏，像飞船在宇宙前行
2. **仪式感** — 开场动画：灵镜淡入淡出 → 副标题 → 开始探索按钮
3. **未知感** — 不显示进度（已删除1/30进度条），用户不知道什么时候结束
4. **一问一答沉浸** — 每个问题淡入，回答后问答一起淡出消失，不可回看
5. **按钮风格** — 纯白文字+下划线，不用边框按钮

---

## 页面结构

```
/ → 重定向到 /chat
/chat → 主对话页（开场动画 + 沉浸问答）
/waiting → 等待生成报告
/report-preview → 免费版预览报告
/report-full → 完整报告（暂时不接支付）
```

---

## 开场动画流程（/chat页面）

1. 星空飞驰背景全程运行（Canvas动画）
2. 0.6s后：「灵镜」字样淡入（font-light, tracking-[0.3em]）
3. 2.2s后：「灵镜」淡出
4. 3.0s后：「一场温柔但有穿透力的对话」淡入
5. 4.8s后：副标题淡出
6. 5.6s后：「开始探索」按钮出现
7. 用户点击后：请求API → 进入沉浸问答

---

## 沉浸问答流程

- 每题全屏居中展示，问题文字淡入
- 用户在textarea输入回答
- 点击「继续 →」或回车：问答淡出 → 下一题淡入
- 没有进度显示，没有历史记录
- 完成后跳转 /waiting

---

## 当前已知Bug（需要修复）

### 🔴 Bug1：「继续 →」按钮颜色不是白色

**现象**：`app/chat/page.jsx` 里的「继续 →」按钮，设计要求纯白色文字+下划线，但实际显示不是白色。

**已尝试但无效的方案**：
- Tailwind class: `text-white`
- 内联style: `color: 'white'` / `color: '#fff'`
- globals.css加 `button { color: inherit }`
- globals.css加 `.continue-btn { color: #fff !important; -webkit-text-fill-color: #fff !important; }`
- 多次 `rm -rf .next && npm run build`

**怀疑原因**：可能是某个父容器、Tailwind preflight或CSS层叠顺序在覆盖button颜色，具体原因未定位。

**需要小周**：用开发者工具或直接审查CSS层叠，找到是谁覆盖了颜色，给出根治方案。

---

## AI配置

```
API: https://ycapis.com/v1/chat/completions
Model: gpt-5.3-codex
API Key: 在 .env 文件中 YCAPIS_API_KEY
```

System Prompt完整版：`/root/Projects/dochub-next/content-private/project-lingjing/system-prompt-v1.md`

---

## 已完成的改动记录

| 时间 | 改动内容 |
|------|---------|
| 今日 | 项目初始化（Next.js + Express） |
| 今日 | 暗黑主题（#0a0a0a背景，白色文字） |
| 今日 | 星空飞驰Canvas动画 |
| 今日 | 开场淡入淡出动画序列 |
| 今日 | 沉浸式单题问答界面 |
| 今日 | PWA manifest + 图标（可添加到主屏幕） |
| 今日 | 首页改为直接重定向到/chat（去掉多余入口） |
| 今日 | 删除进度条（1/30） |
| 今日 | 按钮从边框样式改为文字+下划线样式 |
| 今日 | 模型从DeepSeek改为GPT-5.3-Codex（ycapis） |
| 今日 | 「继续 →」按钮白色问题（未解决，待修复）|

---

## 下一步计划

1. 修复「继续 →」按钮颜色问题
2. 接入真实AI对话（目前后端有fallback逻辑）
3. 报告页UI优化
4. 测试完整对话+报告生成流程

---

## v0.1 封版说明（2026-02-23）

### 已完成功能
- 沉浸式暗黑UI：星空Canvas动画贯穿全程
- 开场Intro序列（灵镜→副标题→开始探索）
- 单题全屏沉浸问答模式（QuestionView）
- 首页直接redirect到/chat，无多余按钮
- 按钮风格：纯白文字+下划线，有输入才变白（交互设计保留）
- AI动态提问（ycapis GPT-5.3-Codex，/v1/responses端点）
- 提交回答后显示"探索中……"呼吸闪烁loading
- 性别问题改为口语化："你是男生还是女生呀？"
- session/new返回total:30
- Gitea仓库：https://git.darkerilclaw.com/lulu/lingjing

### 已知问题/下一版待解决
1. **报告页太潦草**（最高优先级）
   - 现状：硬编码模板，与对话内容完全无关，全是空话
   - 目标：AI根据完整对话记录生成报告，每个结论引用用户原话
   - 待定方案：
     - 🅰️ 30题完成后，一次性调AI生成（等待10-20秒，质量高）
     - 🅱️ 每5题生成一次小结，最后合并（等待分散，体验流畅）
   - **范总下次继续时先选方案再开发**

2. **报告页UI**
   - 现状：纯文字堆砌，没有层次感
   - 目标：暗黑风格卡片展示，与整体沉浸感一致

3. **30题题数控制**
   - 现状：done条件是index>=30，但AI动态生成不严格控制题数
   - 待优化：让AI感知当前题号，合理推进节奏

4. **waiting/report页面暗黑风格适配**
   - 现状：跳转到waiting页后风格不统一

### 下次开发入口
- 从报告生成逻辑开始：`server.js` 的 `/api/report` 接口
- 报告页：`app/report-preview/page.jsx` + `app/report-full/page.jsx`