Skip to content

Commit e69f640

Browse files
Spectualclaude
Spectual
and
claude
committed
docs: 添加 CLAUDE.md 项目文档
记录项目架构、技术栈、部署配置、历次优化改动和待办事项， 供新对话快速上手使用。 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 7685310 commit e69f640

File tree

1 file changed

+205
-0
lines changed

1 file changed

+205
-0
lines changed

‎CLAUDE.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# CLAUDE.md — 项目文档
2+
3+
> 供 Claude Code 在新对话中快速上手使用。
4+
5+
---
6+
7+
## 项目概览
8+
9+
这是 **spectual.ai** 的个人主页，一个终端风格的 AI 个人简历/助手网站。访客可以与 AI 助手对话了解作者信息，也可以浏览项目、简历页面。
10+
11+
**线上地址**：https://www.spectual.ai
12+
13+
**核心特色**：
14+
- 终端 / 黑客风格 UI，Matrix 雨动画背景
15+
- 内嵌 AI 聊天助手（基于 RAG，了解作者个人信息）
16+
- GitHub 动态展示、项目技术栈筛选
17+
- Boot 启动动画 → 主界面过渡
18+
19+
---
20+
21+
## 技术栈
22+
23+
### 前端
24+
| 技术 | 版本 | 用途 |
25+
|------|------|------|
26+
| React | 18.2 | UI 框架 |
27+
| TypeScript | 5.3 | 类型安全（已开启 strictNullChecks） |
28+
| Vite | 5.0 | 构建工具 |
29+
| Tailwind CSS | 3.4 | 样式 |
30+
| React Router DOM | 6.20 | 路由（BrowserRouter） |
31+
| TanStack Query | 5.17 | 服务端状态管理 |
32+
| Radix UI | 多个 | 无障碍 UI 组件 |
33+
| react-markdown + remark-gfm | 最新 | Markdown 渲染 |
34+
35+
### 后端
36+
| 技术 | 用途 |
37+
|------|------|
38+
| Flask + flask-cors | HTTP 服务 |
39+
| OpenAI API | LLM 对话 |
40+
| ChromaDB | 向量数据库（RAG） |
41+
| python-dotenv | 环境变量 |
42+
43+
后端入口：`backend/app.py`，RAG 系统：`backend/rag_system.py`，个人数据：`backend/personal_data.json`
44+
45+
---
46+
47+
## 目录结构
48+
49+
```
50+
/
51+
├── src/
52+
│ ├── App.tsx # 路由配置、ErrorBoundary、懒加载
53+
│ ├── main.tsx
54+
│ ├── components/
55+
│ │ ├── BootSequence.tsx # 启动动画，完成后触发 onComplete
56+
│ │ ├── ChatSection.tsx # AI 聊天区，含历史命令 ↑↓
57+
│ │ ├── MatrixRain.tsx # Canvas Matrix 雨动画（isMobile 响应式）
58+
│ │ ├── MessageBubble.tsx # 聊天气泡，含 scrollIntoView
59+
│ │ ├── TerminalHeader.tsx # 终端顶部栏（独立组件）
60+
│ │ ├── TerminalFooter.tsx # 底部
61+
│ │ ├── ProfileSection.tsx # 个人信息
62+
│ │ ├── GetInTouchSection.tsx # 联系方式（集中管理联系信息）
63+
│ │ └── ui/ # shadcn/ui 组件
64+
│ ├── pages/
65+
│ │ ├── Index.tsx # 主页（Boot → 主界面）
66+
│ │ ├── Projects.tsx # 项目页（含技术栈筛选器）
67+
│ │ ├── Resume.tsx # 简历页（懒加载）
68+
│ │ └── NotFound.tsx # 404 页
69+
│ ├── hooks/
70+
│ │ ├── useTypewriter.ts # 打字机效果（setTimeout 递归实现）
71+
│ │ ├── use-mobile.tsx # 移动端检测
72+
│ │ └── use-toast.ts # Toast 通知
73+
│ ├── types/
74+
│ │ └── chat.ts # Message 接口统一定义
75+
│ ├── data/ # 静态数据
76+
│ ├── lib/ # 工具函数
77+
│ └── utils/
78+
├── public/
79+
│ ├── CNAME # www.spectual.ai（GitHub Pages 自定义域名）
80+
│ └── 404.html # BrowserRouter SPA 重定向脚本
81+
├── backend/
82+
│ ├── app.py # Flask 主服务
83+
│ ├── rag_system.py # ChromaDB RAG 系统
84+
│ ├── personal_data.json # 个人信息数据源
85+
│ └── requirements.txt
86+
├── vite.config.ts # base: '/'
87+
└── tsconfig.app.json # strictNullChecks: true
88+
```
89+
90+
---
91+
92+
## 部署配置
93+
94+
### 前端：GitHub Pages + Cloudflare
95+
96+
- **构建**：`npm run build` → `dist/`
97+
- **部署分支**：`gh-pages`（通过 `npm run deploy` 或手动推送）
98+
- **自定义域名**：`public/CNAME` 内容为 `www.spectual.ai`
99+
100+
**Cloudflare DNS 配置**：
101+
| 类型 | 名称 | 内容 | 代理状态 |
102+
|------|------|------|---------|
103+
| A | spectual.ai | 185.199.108.153 | Proxied（橙云） |
104+
| A | spectual.ai | 185.199.109.153 | Proxied |
105+
| A | spectual.ai | 185.199.110.153 | Proxied |
106+
| A | spectual.ai | 185.199.111.153 | Proxied |
107+
| CNAME | www | spectual.github.io | DNS only（灰云）|
108+
109+
**Cloudflare 重定向规则**（Rules → Redirect Rules）：
110+
- 匹配：`spectual.ai/*`（或 hostname = spectual.ai）
111+
- 动作：301 永久重定向 → `https://www.spectual.ai/`
112+
- 目的：裸域自动跳转到 www 子域
113+
114+
**关键说明**：CNAME 文件必须是 `www.spectual.ai` 而非 `spectual.ai`，否则 Cloudflare Proxied 模式下裸域重定向会失败。
115+
116+
### 后端：Railway
117+
118+
- 服务名：`ai-assistant`
119+
- 启动命令：`python app.py`
120+
- 目录：`backend/`
121+
- 环境变量：`OPENAI_API_KEY`、`PORT`（Railway 自动注入）
122+
- 前端通过环境变量 `VITE_API_URL` 指向 Railway 服务地址
123+
124+
### BrowserRouter SPA 路由支持
125+
126+
GitHub Pages 不支持客户端路由，通过两个机制解决：
127+
1. `public/404.html`：将所有 404 请求重定向回 `index.html`，保留路径信息
128+
2. `index.html` 中有对应的解析脚本恢复路径
129+
130+
---
131+
132+
## 已完成的优化记录
133+
134+
### 第一轮：高优先级重构
135+
136+
1. **提取 TerminalHeader 组件** — 从 Index.tsx 抽出独立组件 `src/components/TerminalHeader.tsx`
137+
2. **统一 Message 接口** — 创建 `src/types/chat.ts`，所有消息类型从这里导入
138+
3. **联系信息集中管理** — `GetInTouchSection.tsx` 中集中定义，避免多处散落
139+
4. **JS hover 改 CSS** — 移除 onMouseEnter/Leave，改用 Tailwind hover: 类
140+
5. **无障碍修复** — `<label htmlFor>` 关联输入框，聊天区加 `aria-live="polite"`
141+
6. **MessageBubble scrollIntoView** — 新消息自动滚动到可见区域
142+
7. **MatrixRain isMobile resize 修复** — 窗口 resize 时正确更新移动端状态
143+
8. **OG 图片改绝对路径** — `og:image` 使用完整 URL 而非相对路径
144+
145+
### 第二轮：中低优先级优化
146+
147+
1. **useTypewriter 改 setTimeout 递归** — 避免 setInterval 闭包陷阱，更精确控制打字速度
148+
2. **路由懒加载** — `Resume`、`Projects` 页面用 `React.lazy + Suspense` 包裹，减少首屏 bundle
149+
3. **SkillBar IntersectionObserver 合并** — 多个技能条共享单个 Observer 实例
150+
4. **消息 ID 改 `crypto.randomUUID()`** — 替代 `Date.now()` 避免碰撞
151+
5. **列表 key 改 `project.name`** — 使用稳定唯一标识符
152+
6. **字体预加载** — `index.html` 中加 `<link rel="preload">` 提升 LCP
153+
7. **BootSequence 过渡优化** — 动画结束时平滑淡出
154+
8. **聊天历史命令** — 输入框支持 ↑/↓ 键切换历史记录
155+
156+
### 第三轮：功能增强
157+
158+
1. **strictNullChecks 开启** — `tsconfig.app.json` 中启用，修复了所有相关类型错误
159+
2. **HashRouter 改 BrowserRouter** — 更干净的 URL（去掉 `#`），配合 `public/404.html` 重定向
160+
3. **GitHub 动态展示组件** — 调用 GitHub API 展示最近 commits/contributions
161+
4. **Projects 技术栈筛选器** — 标签筛选功能，支持多选
162+
163+
### Bug 修复
164+
165+
- **CLI 动画换行布局偏移**：BootSequence 中打字机动画文字换行导致页面抖动，修复方案：设置容器 `height: 3.6em; overflow: hidden`，固定高度防止回流
166+
- **CNAME 域名修复**：CNAME 从 `spectual.ai` 改为 `www.spectual.ai`，配合 Cloudflare 重定向规则
167+
168+
---
169+
170+
## 待办 / 可改进项
171+
172+
- [ ] **中英双语支持** — i18n 国际化，切换语言
173+
- [ ] **浏览器内 ML demo** — 使用 Transformers.js 在前端跑轻量模型
174+
- [ ] **后端改 SSE 流式响应** — AI 回复逐字流式输出，提升体验
175+
- [ ] **聊天记录导出** — 支持导出对话为 Markdown / JSON
176+
- [ ] **深色/浅色主题切换**（当前只有深色）
177+
178+
---
179+
180+
## 常用命令
181+
182+
```bash
183+
# 前端开发
184+
npm run dev # 本地开发服务器
185+
npm run build # 构建生产版本
186+
npm run lint # ESLint 检查
187+
188+
# 后端开发
189+
cd backend
190+
pip install -r requirements.txt
191+
python app.py # 本地启动 Flask（默认 5000 端口）
192+
193+
# 部署
194+
git push origin main # 触发 CI 或手动构建
195+
# gh-pages 分支通过构建产物推送
196+
```
197+
198+
---
199+
200+
## 注意事项
201+
202+
- `public/CNAME` 内容必须是 `www.spectual.ai`（带 www），不能是裸域
203+
- 前端 `vite.config.ts` 中 `base: '/'` 与自定义域名配合（不是子路径部署）
204+
- 后端 CORS 已全局启用（`CORS(app)`），生产环境可按需收紧为特定 origin
205+
- `backend/personal_data.json` 包含个人信息，不提交到公开仓库（已在 .gitignore）

0 commit comments

Comments
 (0)