Skip to content

Commit 6662f13

Browse files
Kosthiclaude
Kosthi
and
claude
committed
docs: add AI context documentation for project
- Add CLAUDE.md with project architecture overview, module index, development guidelines, and AI usage instructions - Add .claude/index.json for Claude Code integration - Covers i18n system, blog workflow, and coding conventions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 9d225a1 commit 6662f13

2 files changed

Lines changed: 377 additions & 0 deletions

File tree

‎.claude/index.json‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
{
2+
"version": "1.0.0",
3+
"timestamp": "2026-02-04T01:22:23+08:00",
4+
"project": {
5+
"name": "rushdb-lab.github.io",
6+
"description": "RushDB Lab 官方网站 - Astro 5 多语言静态网站",
7+
"type": "static-website",
8+
"framework": "astro",
9+
"language": "typescript"
10+
},
11+
"scan": {
12+
"totalFiles": 27,
13+
"scannedFiles": 27,
14+
"coveragePercent": 100,
15+
"truncated": false,
16+
"lastScanDate": "2026-02-04T01:22:23+08:00"
17+
},
18+
"modules": [
19+
{
20+
"path": "src/pages",
21+
"name": "Pages",
22+
"description": "页面路由和视图",
23+
"entryFiles": [
24+
"src/pages/index.astro",
25+
"src/pages/[lang]/index.astro",
26+
"src/pages/[lang]/blog/index.astro",
27+
"src/pages/[lang]/blog/[slug].astro",
28+
"src/pages/[lang]/rss.xml.ts"
29+
],
30+
"language": "astro",
31+
"hasTests": false
32+
},
33+
{
34+
"path": "src/components/astro",
35+
"name": "Astro Components",
36+
"description": "静态渲染的 Astro 组件",
37+
"entryFiles": [
38+
"src/components/astro/HeroSection.astro",
39+
"src/components/astro/AchievementsSection.astro",
40+
"src/components/astro/ProjectsSection.astro",
41+
"src/components/astro/MembersSection.astro",
42+
"src/components/astro/NewsSection.astro",
43+
"src/components/astro/ContactSection.astro",
44+
"src/components/astro/Footer.astro"
45+
],
46+
"language": "astro",
47+
"hasTests": false
48+
},
49+
{
50+
"path": "src/components/vue",
51+
"name": "Vue Components",
52+
"description": "客户端交互的 Vue 组件",
53+
"entryFiles": [
54+
"src/components/vue/NavBar.vue",
55+
"src/components/vue/BackToTop.vue",
56+
"src/components/vue/AboutSection.vue"
57+
],
58+
"language": "vue",
59+
"hasTests": false
60+
},
61+
{
62+
"path": "src/components/blog",
63+
"name": "Blog Components",
64+
"description": "博客专用组件",
65+
"entryFiles": [
66+
"src/components/blog/PostCard.astro",
67+
"src/components/blog/TableOfContents.astro",
68+
"src/components/blog/RelatedPosts.astro"
69+
],
70+
"language": "astro",
71+
"hasTests": false
72+
},
73+
{
74+
"path": "src/i18n",
75+
"name": "Internationalization",
76+
"description": "国际化翻译系统",
77+
"entryFiles": [
78+
"src/i18n/index.ts",
79+
"src/i18n/ui.ts"
80+
],
81+
"language": "typescript",
82+
"hasTests": false,
83+
"exports": [
84+
"getI18n",
85+
"getLangFromUrl",
86+
"useTranslatedPath",
87+
"getLocalizedUrl",
88+
"languages",
89+
"defaultLang",
90+
"ui",
91+
"Lang"
92+
]
93+
},
94+
{
95+
"path": "src/content",
96+
"name": "Content Collections",
97+
"description": "Astro 内容集合（博客）",
98+
"entryFiles": [
99+
"src/content/config.ts"
100+
],
101+
"language": "typescript",
102+
"hasTests": false,
103+
"collections": ["blog"],
104+
"blogPosts": {
105+
"zh": ["miniob-vector-database.md"],
106+
"en": ["miniob-vector-database.md"],
107+
"ja": ["miniob-vector-database.md"]
108+
}
109+
},
110+
{
111+
"path": "src/layouts",
112+
"name": "Layouts",
113+
"description": "页面布局模板",
114+
"entryFiles": [
115+
"src/layouts/BaseLayout.astro"
116+
],
117+
"language": "astro",
118+
"hasTests": false
119+
},
120+
{
121+
"path": "src/styles",
122+
"name": "Styles",
123+
"description": "全局样式定义",
124+
"entryFiles": [
125+
"src/styles/global.css",
126+
"src/styles/site.css"
127+
],
128+
"language": "css",
129+
"hasTests": false
130+
}
131+
],
132+
"config": {
133+
"astro": "astro.config.mjs",
134+
"typescript": "tsconfig.json",
135+
"eslint": ".eslintrc.cjs",
136+
"package": "package.json"
137+
},
138+
"deployment": {
139+
"platform": "github-pages",
140+
"workflow": ".github/workflows/deploy.yml",
141+
"branch": "main",
142+
"buildCommand": "npm run build",
143+
"outputDir": "dist"
144+
},
145+
"i18n": {
146+
"defaultLocale": "zh",
147+
"locales": ["zh", "en", "ja"],
148+
"routing": {
149+
"prefixDefaultLocale": true,
150+
"redirectToDefaultLocale": false
151+
}
152+
},
153+
"dependencies": {
154+
"runtime": {
155+
"astro": "^5.0.0",
156+
"vue": "^3.5.13",
157+
"@astrojs/vue": "^5.0.0",
158+
"@astrojs/rss": "^4.0.0",
159+
"@astrojs/sitemap": "^3.2.0"
160+
},
161+
"dev": {
162+
"typescript": "^5.5.4",
163+
"@types/node": "^22.10.2"
164+
}
165+
},
166+
"gaps": [],
167+
"nextSteps": []
168+
}

‎CLAUDE.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# CLAUDE.md - RushDB Lab 官方网站
2+
3+
> 本文档由 AI 架构师自动生成，用于帮助 AI 助手理解项目结构和开发规范。
4+
5+
## 项目愿景
6+
7+
RushDB Lab 官方网站是一个展示数据库技术竞赛团队成就、项目和成员的多语言静态网站。基于 Astro 5 构建，支持中文、英文、日文三种语言，提供博客系统和 SEO 优化。
8+
9+
## 架构总览
10+
11+
```
12+
技术栈：Astro 5 + Vue 3 + TypeScript
13+
部署方式：GitHub Pages (静态托管)
14+
构建工具：Vite (Astro 内置)
15+
样式方案：原生 CSS + CSS Variables
16+
国际化：Astro 内置 i18n + 自定义翻译系统
17+
```
18+
19+
### 核心特性
20+
21+
- **多语言支持**：zh（中文，默认）、en（英文）、ja（日文）
22+
- **博客系统**：基于 Astro Content Collections，支持 Markdown
23+
- **SEO 优化**：Sitemap、RSS、Open Graph、JSON-LD 结构化数据
24+
- **响应式设计**：移动端优先，支持桌面端和移动端导航
25+
26+
## 模块结构图
27+
28+
```mermaid
29+
graph TD
30+
A["(根) rushdb-lab.github.io"] --> B["src/"]
31+
B --> C["components/"]
32+
B --> D["pages/"]
33+
B --> E["layouts/"]
34+
B --> F["i18n/"]
35+
B --> G["content/"]
36+
B --> H["styles/"]
37+
38+
C --> C1["astro/ - Astro 组件"]
39+
C --> C2["vue/ - Vue 组件"]
40+
C --> C3["blog/ - 博客组件"]
41+
42+
D --> D1["[lang]/ - 多语言页面"]
43+
D1 --> D2["blog/ - 博客页面"]
44+
45+
G --> G1["blog/ - 博客内容"]
46+
G1 --> G2["zh/ en/ ja/"]
47+
48+
A --> I["public/ - 静态资源"]
49+
A --> J[".github/workflows/ - CI/CD"]
50+
51+
click C1 "./src/components/astro/" "Astro 组件目录"
52+
click C2 "./src/components/vue/" "Vue 组件目录"
53+
click F "./src/i18n/" "国际化模块"
54+
click G "./src/content/" "内容模块"
55+
```
56+
57+
## 模块索引
58+
59+
| 模块路径 | 职责 | 语言 | 入口文件 |
60+
|---------|------|------|----------|
61+
| `src/` | 源代码根目录 | TypeScript/Astro/Vue | - |
62+
| `src/pages/` | 页面路由 | Astro | `[lang]/index.astro` |
63+
| `src/components/astro/` | Astro 静态组件 | Astro | 各 Section 组件 |
64+
| `src/components/vue/` | Vue 交互组件 | Vue 3 | `NavBar.vue`, `BackToTop.vue` |
65+
| `src/components/blog/` | 博客专用组件 | Astro | `PostCard.astro` |
66+
| `src/layouts/` | 页面布局 | Astro | `BaseLayout.astro` |
67+
| `src/i18n/` | 国际化系统 | TypeScript | `index.ts`, `ui.ts` |
68+
| `src/content/` | 内容集合 | Markdown | `config.ts` |
69+
| `src/styles/` | 全局样式 | CSS | `global.css`, `site.css` |
70+
| `public/` | 静态资源 | - | 图片、robots.txt |
71+
72+
## 运行与开发
73+
74+
### 环境要求
75+
76+
- Node.js 20+
77+
- npm
78+
79+
### 常用命令
80+
81+
```bash
82+
# 安装依赖
83+
npm install
84+
85+
# 启动开发服务器
86+
npm run dev
87+
88+
# 构建生产版本
89+
npm run build
90+
91+
# 预览构建结果
92+
npm run preview
93+
```
94+
95+
### 目录结构
96+
97+
```
98+
rushdb-lab.github.io/
99+
├── src/
100+
│ ├── components/
101+
│ │ ├── astro/ # Astro 组件（静态渲染）
102+
│ │ │ ├── HeroSection.astro
103+
│ │ │ ├── AchievementsSection.astro
104+
│ │ │ ├── ProjectsSection.astro
105+
│ │ │ ├── MembersSection.astro
106+
│ │ │ ├── NewsSection.astro
107+
│ │ │ ├── ContactSection.astro
108+
│ │ │ └── Footer.astro
109+
│ │ ├── vue/ # Vue 组件（客户端交互）
110+
│ │ │ ├── NavBar.vue
111+
│ │ │ ├── BackToTop.vue
112+
│ │ │ └── AboutSection.vue
113+
│ │ └── blog/ # 博客组件
114+
│ │ ├── PostCard.astro
115+
│ │ ├── TableOfContents.astro
116+
│ │ └── RelatedPosts.astro
117+
│ ├── content/
118+
│ │ ├── config.ts # 内容集合配置
119+
│ │ └── blog/
120+
│ │ ├── zh/ # 中文博客
121+
│ │ ├── en/ # 英文博客
122+
│ │ └── ja/ # 日文博客
123+
│ ├── i18n/
124+
│ │ ├── index.ts # i18n 工具函数
125+
│ │ └── ui.ts # 翻译文本定义
126+
│ ├── layouts/
127+
│ │ └── BaseLayout.astro
128+
│ ├── pages/
129+
│ │ ├── index.astro # 根路径重定向
130+
│ │ └── [lang]/
131+
│ │ ├── index.astro # 首页
132+
│ │ ├── rss.xml.ts # RSS 订阅
133+
│ │ └── blog/
134+
│ │ ├── index.astro
135+
│ │ └── [slug].astro
136+
│ └── styles/
137+
│ ├── global.css # 全局样式（大型）
138+
│ └── site.css # 站点样式
139+
├── public/ # 静态资源
140+
├── astro.config.mjs # Astro 配置
141+
├── tsconfig.json # TypeScript 配置
142+
├── package.json # 项目依赖
143+
└── .github/workflows/ # GitHub Actions
144+
```
145+
146+
## 测试策略
147+
148+
当前项目**未配置自动化测试**。建议未来考虑：
149+
150+
- 使用 Playwright 进行 E2E 测试
151+
- 使用 Vitest 进行单元测试（i18n 函数等）
152+
153+
## 编码规范
154+
155+
### TypeScript
156+
157+
- 使用严格模式（`astro/tsconfigs/strict`）
158+
- 路径别名：`@/*` 映射到 `src/*`
159+
160+
### ESLint 配置
161+
162+
- 继承：`eslint:recommended`, `plugin:vue/vue3-essential`, `plugin:@typescript-eslint/recommended`
163+
- 解析器：`vue-eslint-parser` + `@typescript-eslint/parser`
164+
165+
### 样式规范
166+
167+
- 使用 CSS Variables 定义主题色和间距
168+
- 遵循移动端优先的响应式设计
169+
- 主题色变量：`--c1`, `--c2`, `--c3`（渐变色）
170+
- 文本色变量：`--text`, `--text-2`, `--text-3`
171+
172+
### 组件命名
173+
174+
- Astro 组件：PascalCase，后缀 `.astro`
175+
- Vue 组件：PascalCase，后缀 `.vue`
176+
- 页面文件：小写，使用 `[param]` 表示动态路由
177+
178+
## AI 使用指引
179+
180+
### 添加新语言
181+
182+
1. 在 `src/i18n/ui.ts` 中添加新语言的翻译对象
183+
2. 更新 `Lang` 类型定义
184+
3. 在 `astro.config.mjs` 中更新 `i18n.locales`
185+
4. 为博客创建对应语言目录 `src/content/blog/{lang}/`
186+
187+
### 添加新页面
188+
189+
1. 在 `src/pages/[lang]/` 下创建 `.astro` 文件
190+
2. 实现 `getStaticPaths()` 返回所有语言路径
191+
3. 使用 `BaseLayout` 作为布局组件
192+
4. 使用 `getI18n(lang)` 获取翻译函数
193+
194+
### 添加博客文章
195+
196+
1. 在 `src/content/blog/{lang}/` 下创建 `.md` 文件
197+
2. 添加 frontmatter：`title`, `description`, `pubDate`, `category`, `tags`
198+
3. 支持的分类：`database`, `competition`, `tutorial`, `news`, `research`
199+
200+
### 修改导航
201+
202+
- 桌面端/移动端导航在 `src/components/vue/NavBar.vue`
203+
- 导航文本在 `src/i18n/ui.ts` 的 `nav` 对象
204+
205+
## 变更记录 (Changelog)
206+
207+
| 日期 | 版本 | 变更内容 |
208+
|------|------|----------|
209+
| 2026-02-04 | 1.0.0 | 初始文档生成 |

0 commit comments

Comments
 (0)