mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
9.0 KiB
9.0 KiB
Specification — v2 Features
Document:
spec-v2.mdVersion: 0.1.0 Status: Draft — awaiting review Branch:dev_v2Parent branch:dev(v0.0.1)
Overview
Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào:
- Resume download (P1)
- Blog system — MDX-based articles (P1)
- SEO — metadata, Open Graph, sitemap (P1)
- Analytics — privacy-friendly page view tracking (P2)
- Testing — Vitest + Testing Library (P5)
- CI/CD pipeline (P5)
1. Resume Download
Requirement
- Nút "Download Resume" trong nav hoặc Contact page
- Link đến file PDF (placeholder ban đầu)
- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon"
- PDF sẽ upload vào
public/resume.pdf
Implementation
// Navigation.tsx
{resumeAvailable && (
<Link to="/resume" className="nav-link">Resume</Link>
)}
// OR ContactPage.tsx
<a href="/resume.pdf" download className="btn-primary">Download Resume</a>
Data
public/resume.pdf— PDF file (user tự upload)- Không cần data module
Acceptance
- Nút Resume hiển thị trong nav
- Click → download PDF
- Khi chưa có PDF → nút ẩn hoặc disabled
- Responsive trên mobile
2. Blog System
Requirement
Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
Architecture
src/
content/
blog/
post-1.mdx
post-2.mdx
components/
blog/
BlogListPage.tsx
BlogPostPage.tsx
ArticleCard.tsx
CodeBlock.tsx
Features
2.1. Frontmatter
Mỗi article có frontmatter:
---
title: "Building High-Performance Event Simulation with Go"
date: "2024-06-15"
tags: ["engineering", "golang", "simulation"]
summary: "Discrete event simulation for logistics facilities"
---
2.2. Blog List Page (/blog)
- Hiển thị danh sách articles
- Sort theo date (newest first)
- Filter theo tags (pill buttons)
- Mỗi article card: title, date, tags, summary
2.3. Article Page (/blog/:slug)
- Render MDX content
- Code blocks với syntax highlighting
- TOC (table of contents) sidebar (desktop)
- Reading time estimate
- Breadcrumb navigation
2.4. Code Highlighting
- Dùng
rehype-prism-plushoặcrehype-raw+prismjs - Không dùng library nặng như
react-syntax-highlighter - Theme: dark/light compatible với CSS variables
2.5. MDX Processing
- Dùng
@mdx-js/react+@mdx-js/rollup(Vite plugin) - Build-time compilation (không runtime)
- Frontmatter extracted tại build time
Vite Config Changes
// vite.config.ts
import mdx from '@mdx-js/rollup'
export default defineConfig({
plugins: [
react(),
mdx({
providerImportSource: '@mdx-js/react',
}),
],
})
Acceptance
/bloghiển thị danh sách articles- Article card có title, date, tags, summary
- Click article → navigate đến
/blog/:slug - MDX content render đúng
- Code blocks có syntax highlighting
- Tags filter hoạt động
- TOC sidebar (desktop only)
- Reading time hiển thị
- Responsive
- Không crash khi missing article
3. SEO
Requirement
Mỗi page có metadata riêng cho SEO và social sharing.
Implementation
3.1. Dynamic Metadata
Dùng react-helmet-async (hoặc @remix-run/react helmet nếu cần SSR sau này).
import { Helmet } from 'react-helmet-async'
// HomePage.tsx
<Helmet>
<title>{profile.name} — Senior Software Engineer</title>
<meta name="description" content={profile.bio} />
<link rel="canonical" href={siteUrl} />
</Helmet>
3.2. Open Graph
Mỗi page có OG tags:
<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:image" content="/og-image.png" />
<meta property="og:url" content="..." />
<meta property="og:type" content="website" />
3.3. Sitemap
- Generate
sitemap.xmltại build time - Dùng
vite-plugin-sitemaphoặc tự viết script - Include tất cả public pages
3.4. Robots.txt
public/robots.txt- Allow all (trừ
/adminnếu có sau này)
3.5. Structured Data (JSON-LD)
Personschema cho homepageArticleschema cho blog postsBreadcrumbListcho nested pages
Acceptance
- Mỗi page có
<title>và<meta description>riêng - OG tags đúng trên mỗi page
sitemap.xmlgenerated tại buildrobots.txtcó trongpublic/- JSON-LD structured data
- Canonical URL đúng
4. Analytics
Requirement
Privacy-friendly analytics — không dùng Google Analytics.
Options
Option A: Plausible Analytics (recommended)
- Lightweight, privacy-first
- No cookie banner needed
- Simple script integration
Option B: Umami
- Self-hosted option
- Open source
- Similar to Plausible
Option C: Custom minimal tracking
- Track page views only
- Store in localStorage
- Batch send to endpoint (optional)
Implementation (Plausible)
// main.tsx
<script
defer
data-domain="yourdomain.com"
src="https://plausible.io/js/script.outbound-links.js"
/>
Hoặc dùng react-use-plausible:
import { usePlausible } from 'react-use-plausible'
const plausible = usePlausible()
// Auto pageview tracking
Acceptance
- Page view tracking hoạt động
- Không cookie banner
- Không ảnh hưởng performance
- Configurable via env var (ENABLE_ANALYTICS)
5. Testing
Requirement
Unit tests cho components và hooks. E2E tests cho critical paths.
Stack
- Vitest — unit/integration tests
- @testing-library/react — component tests
- @testing-library/jest-dom — assertions
- Playwright — E2E tests
Test Structure
src/
__tests__/
hooks/
useTheme.test.tsx
components/
Navigation.test.tsx
Footer.test.tsx
Badge.test.tsx
pages/
HomePage.test.tsx
e2e/
navigation.spec.ts
theme.spec.ts
responsive.spec.ts
Critical Tests
useTheme
test('cycles through themes correctly', () => {
const { result } = renderHook(() => useTheme())
act(() => { result.current.cycleTheme() })
expect(result.current.theme).toBe('light') // or 'dark'
})
test('persists theme to localStorage', () => {
renderHook(() => useTheme())
expect(localStorage.getItem('portfolio-theme')).toBe('dark')
})
Navigation
test('renders all nav items', () => {
render(<Navigation />)
navItems.forEach(item => {
expect(screen.getByText(item.label)).toBeInTheDocument()
})
})
test('NavLink highlights active route', () => {
render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>)
expect(screen.getByText('About')).toHaveClass('active')
})
HomePage
test('renders hero section', () => {
render(<HomePage />)
expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
})
Acceptance
- useTheme tests pass
- Navigation tests pass
- HomePage tests pass
- E2E: navigation works
- E2E: theme toggle works
- E2E: responsive layout correct
- Test coverage > 70%
6. CI/CD Pipeline
Requirement
GitHub Actions pipeline:
- Lint — oxlint
- Type check — tsc -b
- Test — vitest
- Build — vite build
- Deploy — to Vercel (on main branch push)
GitHub Actions
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [dev, main]
pull_request:
branches: [dev]
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm build
- run: pnpm test
Vercel Integration
- Connect GitHub repo
- Auto deploy on
dev→ preview - Auto deploy on
main→ production - Environment variables:
SITE_URL,PLAUSIBLE_DOMAIN(optional)
Acceptance
- CI pass trên push vào dev
- Lint pass
- Build pass
- Tests pass
- Preview deploy trên Vercel
- Production deploy khi merge vào main
Implementation Order
Ưu tiên thực hiện:
- Resume download (5 phút, trivial)
- SEO (metadata, OG, sitemap) — cần làm trước khi deploy
- Blog system (MDX + articles) — P1, substantial work
- Analytics (Plausible) — quick win
- Testing (Vitest + E2E) — P5, important but can iterate
- CI/CD (GitHub Actions) — P5, automate after features done
Out of Scope (v2)
- CMS integration (Phase 5+)
- Multi-language / i18n (Phase 5+)
- Interactive diagrams / simulations (Phase 5+)
- Search functionality (Phase 5+)
- Contact form with backend (Phase 5+)
- Resume PDF generation (user uploads manually)
Approval
- All requirements reviewed and confirmed
- Implementation order agreed
- Ready to start coding