165 lines
5.5 KiB
Markdown
165 lines
5.5 KiB
Markdown
# 灵镜 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`
|