Digitaltableteur

 _____   _______
|  __ \ |__   __|
| |  | |   | |
| |  | |   | |
| |__| |   | |
|_____/    |_|

Digitaltableteur

“迭代胜过完美——今天发布，明天学习，永远精进。”

Digitaltableteur 是一个混合式单体仓库作品集网站，包含 Next.js 16（生产环境）和 Vite（旧版）应用。它基于 React 19 和 TypeScript 6.x 构建，展示了全面的设计系统、多语言支持（EN/FI/SV）、AI 驱动的聊天界面，以及企业级工具，包括 Sentry 可观测性、Linear 问题管理和 MCP（Model Context Protocol）集成。

🚀 功能

核心架构

• 混合式单体仓库：Next.js 16 App Router（生产环境）与 Vite 6.4（旧版）并行迁移
• AI 文档系统：针对 AI 助手优化的分层 CLAUDE.md/AGENTS.md 结构
• 设计系统：包含 50 多个组件、CSS Modules、设计令牌、Storybook 和视觉回归测试
• 类型安全：TypeScript 6.x 严格模式，配备全面的接口和 JSDoc 文档

用户体验

• 多语言支持：完整的国际化支持，包含英语、芬兰语和瑞典语（100% 翻译覆盖率）
• AI 聊天界面：由 OpenAI 提供支持的聊天功能，包含引导式邮件工作流、动态组件注入和 Markdown 渲染
• 响应式设计：移动优先，支持渐进增强（backdrop-filter、gap、:has() 选择器）
• 渐进式 Web 应用：服务工作线程缓存、离线支持、原生分享 API 集成
• 无障碍访问：符合 WCAG AA 标准，支持 axe-core 测试、语义化 HTML、ARIA 属性和键盘导航

内容与媒体

• 博客平台：集成 Sanity CMS，支持 MDX、语法高亮和阅读时间估算
• 安全 CV 下载：受密码保护，并提供 API 验证和速率限制
• 图像优化：Next.js Image 组件、延迟加载、响应式 srcset 生成
• 联系功能集成：EmailJS 配合引导式多步骤工作流、验证和无障碍支持

开发者体验

• Storybook 10：组件开发，支持 WIP 徽章系统和视觉回归测试
• 测试：Vitest + Testing Library（覆盖率目标 >80%）、无障碍测试、使用 Playwright 进行端到端测试
• MCP 集成：GitHub、Figma、Context7、TypeScript LSP、Sentry，助力 AI 辅助开发
• Linear 自动化：以编程方式创建/更新问题、管理标签和状态工作流
• Sentry 可观测性：错误跟踪、性能监控、版本健康状况和 MCP 查询界面

性能与 SEO

• 代码拆分：动态导入，使用 React.lazy()（Vite）和 next/dynamic（Next.js）
• 打包优化：摇树优化、压缩，以及使用内容哈希进行积极缓存清除
• SEO：使用 generateMetadata() 生成动态元数据、sitemap.xml、robots.txt 和结构化数据
• 分析：集成 Google Analytics 4，并提供隐私控制

🏁 开始使用

先决条件

• Node.js 18+（推荐使用 LTS 版本）
• npm 9+ 或兼容的包管理器

安装

# Clone repository
git clone https://github.com/PetriLahdelma/digitaltableteur.git
cd digitaltableteur

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

环境配置

开发环境必需：

# Analytics
VITE_GA_ID=G-XXXXXXXXXX                      # Google Analytics 4

# Email Services
VITE_EMAILJS_SERVICE_ID=service_xxx
VITE_EMAILJS_TEMPLATE_ID=template_xxx
VITE_EMAILJS_PUBLIC_KEY=xxx

# MCP Servers (optional for enhanced AI features)
FIGMA_TOKEN=figd_xxx                         # Figma design access
GITHUB_MCP_PAT=github_pat_xxx               # GitHub operations
CONTEXT7_API_KEY=xxx                         # Context7 documentation access

# Linear Issue Management (optional)
LINEAR_API_KEY=lin_api_xxx
LINEAR_TEAM_ID=xxx
LINEAR_PROJECT_ID=xxx

# Akaunting Accounting (optional, self-hosted)
[email protected]
AKAUNTING_API_PASSWORD=xxx
AKAUNTING_COMPANY_ID=1

仅用于生产环境：

CV_PASSWORD=xxx                              # Secure resume download
OPENAI_API_KEY=sk-xxx                        # AI chat functionality
SENTRY_DSN=https://[email protected]/xxx
SENTRY_AUTH_TOKEN=xxx                        # Source map upload

完整清单及说明请参阅 .env.example。

⚒️ 开发

开发服务器

# Next.js dev server (production app)
npm run dev                    # http://localhost:3001

# Storybook component development
npm run storybook              # http://localhost:6010

代码质量与测试

# Type checking
npm run typecheck              # TypeScript validation across project

# Linting
npm run lint                   # ESLint + Stylelint
npm run lint:fix               # Auto-fix linting issues

# Testing
npm test                       # Run all tests (Vitest)
npm run test:watch             # Watch mode
npm run test:coverage          # Coverage report (>80% target)
npm run test:a11y              # Accessibility tests (axe-core)
npm run test:visual            # Visual regression (Playwright + Storybook)

# Pre-commit validation (run before PR)
npm run typecheck && npm run lint && npm test && npm run build

MCP 与自动化

# GitHub MCP Server
npm run github:mcp:test        # Test connectivity and authentication

# Figma MCP Server
npm run figma:mcp:test         # Test connectivity and authentication

# Context7 MCP Server
npm run context7:mcp           # Launch locally (respects CONTEXT7_API_KEY)
npm run context7:mcp -- --remote-check  # Test remote endpoint

# TypeScript LSP Status
npm run ts:mcp:status          # Validate TypeScript language server
npm run ts:mcp:status:stub     # Generate stub status

# Linear Issue Management
npx tsx scripts/linear/create-issue.ts              # Interactive issue creation
npx tsx scripts/linear/update-issue.ts --issue DIG-16 --state "Done"
npx tsx scripts/linear/check-issue.ts DIG-16        # Display issue details

# Sentry Observability
node scripts/sentry-mcp.js issues digitaltableteur 10 --unresolved
npm run generate-sentry-summary                      # Generate dashboard data

🏗 构建与部署

构建命令

# Next.js production build
npm run build                  # Output: .next/

# Storybook static build
npm run build-storybook        # Output: storybook-static/

部署

# Vite to GitHub Pages
npm run deploy                 # Build + gh-pages deployment

# Vite + Storybook visual diffs
npm run deploy-with-storybook  # Deploy with visual regression report

# Manual cache busting
npm run cache-bust             # Add version metadata + .nojekyll

# Vercel (production - automatic on push to main)
vercel --prod

混合部署策略：

• Vite 应用：GitHub Pages（https://digitaltableteur.com）
• Next.js 应用：Vercel（https://nextjs-app.vercel.app）
• 无服务器函数：Vercel（/api/* 路由）
• 路由：Vercel 重写规则将特定路径路由到 Next.js（参见 vercel.json）

构建优化

Vite 构建：

• 经 Tree Shaking 处理、带内容哈希的 JavaScript 包
• 带供应商前缀和逻辑属性的压缩 CSS
• 压缩后的图片和字体
• 用于离线缓存的 service worker（Workbox）
• 使用文件名哈希进行强缓存失效处理

Next.js 构建：

• 用于 SEO 的服务器端渲染（SSR）
• 博客文章静态生成
• 使用 Next.js Image 组件优化图片
• 作为 Vercel 无服务器函数的 API 路由
• 按路由自动拆分代码

🤖 AI 文档系统

层级结构

该项目使用针对 AI 助手优化的分层 CLAUDE.md/AGENTS.md 系统：

Root Documentation (Universal Rules)
├── CLAUDE.md (380 lines)          # Comprehensive authority for Claude Code
├── AGENTS.md (150 lines)          # Quick reference for generic agents
└── .github/copilot-instructions.md  # GitHub Copilot specific

Subdirectory Documentation (Specific Context)
├── app/CLAUDE.md + AGENTS.md      # Next.js App Router patterns
├── shared/components/CLAUDE.md + AGENTS.md  # Component library rules
├── api-legacy-vercel-functions/AGENTS.md    # Serverless patterns
├── docs/AGENTS.md                 # Documentation navigation
└── scripts/AGENTS.md              # Automation patterns

Claude Code Configuration
├── .claude/settings.json          # Hooks (auto-format, safety checks)
└── .claude/commands/              # Custom slash commands
    ├── review.md                  # Comprehensive code review
    ├── fix-issue.md               # GitHub issue workflow
    ├── create-component.md        # Component generation
    └── create-linear-issue.md     # Issue creation

主要功能

CLAUDE.md（Claude Code 权威规则）

• 每个文件 200-400 行
• 视为不可变的系统规则
• 按层级读取（从当前工作目录向上读取，并发现子目录）
• 提供全面的模式说明和文件示例

AGENTS.md（通用 AI 快速参考）

• 每个文件 100-200 行
• 使用搜索命令进行 JIT（即时）索引
• 尽量减少重复，最大限度提升效率
• 提供可直接复制粘贴的命令

Claude Code 增强功能

• Hooks：自动格式化（Prettier）、阻止危险命令
• 自定义命令：/review、/fix-issue、/create-component、/create-linear-issue
• Token 效率：与单体文档相比，每次查询减少 60-80% 的 Token 消耗

用法

Claude Code（自动）：

/review                         # Comprehensive code review
/fix-issue 123                  # Analyze and fix GitHub issue
/create-component Button        # Generate component (5 files)
/create-linear-issue Implement X  # Create Linear issue

通用 AI Agent（手动参考）：

cat AGENTS.md                           # Root rules
cat app/AGENTS.md                       # Next.js patterns
cat shared/components/AGENTS.md         # Component rules

文档：

• 迁移指南
• 系统摘要
• 可视化树状图

🎨 设计资源管理

获取 Figma 设计

如果需要原始设计数据，可以将 Figma 文件下载为 JSON。设置 FIGMA_TOKEN 环境变量并填入个人访问令牌，然后运行：

npm run fetch-figma

使用 API 从 Figma 同步设计 Token 和资源。 文件将保存为项目根目录下的 figma.json。

SEO 与内容生成

npm run generate:sitemap    # Generate XML sitemap
npm run generate:llms       # Create LLM-friendly content index
npm run generate:alt-text   # Generate accessibility descriptions (requires OPENAI_API_KEY)

generate:alt-text 会将本地图片字节流式传输到 OpenAI Vision API，以便其描述实际图稿；运行前请将 OPENAI_API_KEY（以及可选的 OPENAI_ALT_MODEL）添加到 .env.local，或者附加 --force 以重新生成每个 <img> 的 alt 属性。

Sanity 博客发布

快速发布工作流：

# Publish single article from Sanity
npm run sanity:publish-single <article-slug>

# Publish all articles
npm run sanity:publish

• 完整的自动化发布工作流请参阅 docs/SANITY_PUBLISHING_AUTOMATION.md
• 完整的迁移工作流请参阅 docs/SANITY_MIGRATION.md（React → Sanity，使用 sanity:parse-posts / sanity:convert / sanity:upload；Sanity → MDX，使用 sanity:sync-from-remote；以及重定向生成和清理辅助工具）

🏗 架构

混合单体仓库结构

digitaltableteur/
├── app/                       # Next.js 16 App Router (production)
│   ├── layout.tsx             # Root layout with providers
│   ├── page.tsx               # Home page (server component)
│   ├── about/page.tsx         # Route pages
│   ├── blog/[slug]/page.tsx   # Dynamic routes
│   └── api/*/route.ts         # API routes (Vercel functions)
│
├── src/                       # Vite app (legacy, being phased out)
│   ├── App.tsx                # React Router configuration
│   ├── pages/                 # Route components (to be migrated)
│   └── components/            # Component library
│
├── shared/                    # Symlinked shared code
│   ├── components/            # Design system (from src/components)
│   ├── hooks/                 # Custom React hooks
│   ├── styles/                # Design tokens & global styles
│   └── locales/               # i18n translation files
│
├── api-legacy-vercel-functions/  # Serverless functions
│   ├── cors.js                # CORS middleware
│   ├── openai-chat.js         # AI chat endpoint
│   ├── save-contact.js        # Contact form handler
│   └── download-cv.js         # Secure CV download
│
├── scripts/                   # Automation & tooling
│   ├── linear/                # Issue management
│   ├── sentry-mcp.js          # Observability queries
│   └── generate-*.js          # Code generation
│
├── docs/                      # Documentation
│   ├── LLM_COMPONENT_GENERATION_RULES.md (12,000+ words)
│   ├── NEXTJS_MIGRATION_PLAN.md
│   ├── LINEAR_AUTOMATION.md
│   └── *_MCP_SETUP.md         # MCP integration guides
│
└── .claude/                   # Claude Code configuration
    ├── settings.json          # Hooks (auto-format, safety)
    └── commands/              # Custom slash commands

技术栈

前端

• React 19：并发特性、Suspense、自动批处理
• TypeScript 6.x：严格模式、装饰器、导入属性
• Next.js 16.2.x：App Router、Server Components、流式 SSR
• Vite 6.4：极速 HMR、优化的生产构建
• React Router 7：支持延迟加载的客户端路由（Vite 应用）

样式与设计

• CSS Modules：采用一致的命名约定，实现作用域样式
• 设计令牌：src/styles/variables.css 中的 CSS 自定义属性
• 渐进增强：使用 @supports 查询检测现代特性
• 逻辑属性：margin-inline、padding-block（支持 RTL）
• 响应式设计：移动优先，采用断点系统

状态与数据

• React Hooks：useState、useEffect、useContext、自定义 Hook
• i18next：通过 React 绑定实现国际化
• EmailJS：联系表单邮件投递
• OpenAI API：支持函数调用的 GPT-4 聊天

后端服务

• Vercel Serverless：带有 CORS 中间件的 Node.js 函数
• GitHub Pages：使用自定义域名托管静态网站
• Sanity CMS：无头博客内容管理
• Sentry：错误跟踪与性能监控

开发者工具

• Storybook 10：组件开发与文档
• Vitest：使用 jsdom 环境进行单元测试
• Testing Library：以用户为中心的测试工具
• Playwright：通过 Storybook 进行视觉回归测试
• ESLint + Stylelint：代码质量检查
• Prettier：统一代码格式

AI 与自动化

• MCP（Model Context Protocol）：GitHub、Figma、Context7、TypeScript LSP
• Linear API：以编程方式管理问题
• Sentry REST API：可观测性查询与仪表板
• Claude Code：用于 AI 结对编程的自定义命令和钩子

📱 组件特性

原生分享集成

SocialShare 组件通过 Web Share API 实现渐进增强：

原生分享支持

• 检测移动设备上的 Web Share API 是否可用
• 通过设备原生分享面板实现无缝分享
• API 不可用时，优雅地回退到剪贴板复制

响应式设计

• 移动设备上使用仅显示图标的模式，布局更紧凑
• 桌面环境中显示完整按钮文本
• 与其他社交媒体图标正确对齐

渐进增强

• 检测 navigator.share 是否可用
• 自动回退到剪贴板复制功能
• 分享失败时进行错误处理并支持重试

无障碍

• 为原生分享和复制操作添加 ARIA 标签
• 支持键盘导航
• 设置适当的 role 属性，方便屏幕阅读器使用

浏览器支持

• 现代移动浏览器：支持原生分享功能
• 桌面浏览器：回退到剪贴板复制
• 旧版浏览器：采用标准剪贴板复制行为

该实现遵循 Web Share API 最佳实践，包含适当的错误处理，并在所有设备类型上提供一致的用户体验。

⚙️ 测试与质量

测试栈

npm test                         # Run all tests
npm run test:watch               # Watch mode
npm run test:coverage            # Generate coverage reports
npm run test:a11y                # Accessibility testing
npm run test:visual              # Visual regression tests
npm run test:visual:update       # Update visual baselines

测试套件覆盖范围：

• 单元测试：组件行为、props、状态管理（覆盖率要求 >80%）
• 集成测试：聊天工作流、邮件表单、导航模式
• 无障碍测试：在所有页面和 Storybook 故事上运行 axe-core
• 视觉回归：通过 Storybook test-runner 使用 Playwright 截图
• 翻译覆盖率：确保 EN/FI/SV 中包含所有 i18n 键

测试库：

• Vitest + jsdom：支持 React 的快速单元测试
• Testing Library：以用户为中心的组件测试
• axe-core：自动化无障碍审计
• Playwright：视觉回归和 E2E 能力

代码质量

npm run lint                     # ESLint + Stylelint
npm run lint:fix                 # Auto-fix linting issues
npm run format                   # Prettier formatting
npm run typecheck                # TypeScript validation

质量标准：

• ESLint：TypeScript 严格模式、React 最佳实践、无障碍规则
• Stylelint：CSS Modules 标准、逻辑属性强制检查
• Prettier：2 个空格缩进、单引号、尾随逗号
• TypeScript：禁止隐式 any、严格空值检查、禁止未使用变量

可观测性

Sentry 集成：

npm run sentry:issues            # Query unresolved issues
npm run sentry:releases          # List recent releases
npm run generate:sentry-summary  # Generate JSON summary

MCP 测试：

npm run github:mcp:test          # Test GitHub MCP connectivity
npm run figma:mcp:test           # Test Figma MCP connectivity
npm run ts:mcp:status            # Validate TypeScript LSP

组件开发

Storybook：

npm run storybook                # Launch Storybook dev server
npm run build-storybook          # Build static Storybook
npm run storybook:deploy         # Deploy to GitHub Pages

WIP 徽章系统：

• 默认情况下，所有 story 都会显示本地化的“进行中”徽章
• 通过 parameters: { wip: { disabled: true } } 移除徽章前，需通过以下检查：
  • ✅ 无障碍测试（axe-core 违规数 = 0）
  • ✅ 视觉回归测试（无意外差异）
  • ✅ 翻译覆盖率（EN/FI/SV 中的所有键）

🌐 国际化

网站支持三种语言，并提供完整的翻译覆盖：

• 英语（EN）：内容完整的主要语言
• 芬兰语（FI）：原生语言支持
• 瑞典语（SV）：区域语言支持

结构：

• 翻译文件：nextjs-app/shared/locales/{en,fi,sv}/translation.json
• 使用命名空间组织，便于维护
• 测试强制要求达到 100% 覆盖率

用法：

• 始终使用 useTranslation() hook 包装面向用户的文本
• 使用嵌套对象表示法（如 "navigation.home"）进行组织
• 合并前同时更新全部三种语言的文件

🔐 安全与性能

安全措施：

• 受密码保护的内容交付
• 使用 .env.local（已加入 gitignore）的环境配置
• 启用 CORS 的 API 端点，并严格验证来源
• 清理用户输入并防范 XSS
• 版本控制中不包含机密信息（参见 .gitignore）

性能优化：

• 使用动态导入和 React.lazy() 进行代码拆分
• 图像优化与延迟加载
• Service Worker 缓存策略（Vite 应用）
• 包分析与 tree shaking
• 使用 Brotli/Gzip 压缩交付资源
• 使用激进的文件名哈希策略实现缓存更新

🚀 构建与部署

生产构建

Next.js 应用：

npm run build                    # Build Next.js app (production)
npm run start                    # Start Next.js production server

Vite 应用（旧版）：

npm run build                    # Vite production build
npm run preview                  # Preview Vite production build
npm run cache-bust               # Manual cache busting

部署策略

混合部署：

• Vercel：托管 Next.js 应用和无服务器 API 函数

  • 从 main 分支自动部署
  • 在 Vercel 控制面板中管理环境变量
  • 用于身份验证、API 路由和 webhook 的 Edge 函数

• GitHub Pages：托管旧版 Vite 应用和 Storybook

  • 通过 npm run deploy 手动部署
  • 自定义域名：digitaltableteur.com
  • 使用哈希文件名实现激进的缓存更新

部署命令：

npm run deploy                   # Deploy Vite app to GitHub Pages
npm run deploy-with-storybook    # Deploy with visual diff report
npm run storybook:deploy         # Deploy Storybook standalone
npm run generate:sitemap         # Generate sitemap.xml

缓存策略

Vite 构建：

• 自动为 JS/CSS 资源生成哈希文件名
• 手动缓存更新脚本会添加版本元数据
• .nojekyll 文件可防止 GitHub Pages 处理 Jekyll

Next.js 构建：

• 内置资源哈希与优化
• 通过 next.config.ts 配置 Cache-Control 标头
• Vercel CDN 负责缓存失效

环境变量

生产环境（Vercel）：

• 所有机密信息均存储在 Vercel 项目设置中
• 预览环境和生产环境相互独立
• 自动为客户端变量添加 NEXTPUBLIC 前缀

生产环境（GitHub Pages）：

• 公共环境变量存储在 GitHub Secrets 中
• 部署工作流会在构建时注入变量
• 不包含服务端机密信息（仅静态托管）

🚀 CI/CD 流水线

GitHub Actions：

• 自动化测试：每个 PR 都会运行 ESLint、Stylelint 和 Vitest
• 预览部署：为拉取请求自动创建预览环境
• 生产部署：自动构建并更新缓存

分支保护：

• 要求通过代码质量状态检查
• main 分支需要 1 个批准
• 合并时压缩提交
• 合并后删除分支

🤝 参与贡献

开发指南

• TypeScript：所有新组件和函数都使用严格类型
• CSS Modules：遵循现有模式并使用设计令牌（绝不使用内联样式）
• 国际化：为所有面向用户的文本添加翻译（EN/FI/SV）
• 组件创建：务必先阅读 docs/LLM_COMPONENT_GENERATION_RULES.md
• Storybook：为每个组件添加 .stories.tsx
• 测试：保持测试覆盖率 >80%，并包含无障碍测试
• 文档：同时更新 CLAUDE.md、AGENTS.md、README.md 和 copilot-instructions.md

工作流

1. Fork 仓库
2. 创建分支：遵循 docs/BRANCH_NAMING.md 中的命名约定

   git checkout -b DT-XXX-feat-description
   

3. 开发：按照上述约定进行更改
4. 质量检查：

   npm run typecheck && npm run lint && npm test && npm run build
   

5. 提交：使用 Conventional Commits 格式

   git commit -m "feat: add amazing feature"
   

6. 推送：推送到你的分支

   git push origin DT-XXX-feat-description
   

7. Pull Request：创建 PR 并附上详细说明
8. 审查：处理反馈并确保 CI 通过
9. 合并：合并时压缩提交，之后删除分支

提交前检查清单

创建 PR 前：

• ✅ 所有测试均通过（npm test）
• ✅ 无 TypeScript 错误（npm run typecheck）
• ✅ 无 lint 问题（npm run lint）
• ✅ 生产构建成功（npm run build）
• ✅ 翻译覆盖完整（EN/FI/SV）
• ✅ 为新组件添加 Storybook 故事
• ✅ 如果 UI 有更改，则更新视觉基线（npm run test:visual:update）
• ✅ 更新文档（README、CLAUDE.md、AGENTS.md）

📁 文件夹概览

• src/ – 应用源代码
• public/ – 静态资源和 HTML 模板
• .storybook/ – Storybook 配置文件
• dist/ – 编译后的生产构建（运行 npm run build 后生成）
• node_modules/ – 通过 npm 安装的项目依赖项

📚 了解更多

项目文档

AI 文档系统：

• 迁移指南 - CLAUDE.md/AGENTS.md 层级结构完整指南
• 系统摘要 - 统计数据和文件概览
• 可视化树 - 文档结构的 ASCII 示意图
• 根目录 CLAUDE.md - Claude Code 的权威综合指南
• 根目录 AGENTS.md - 通用 AI Agent 的快速参考

重要参考资料：

• 组件生成规则 - 关于组件创建的权威指南，超过 12,000 字
• 关键推理与规划 - 规划工作流
• Next.js 迁移计划 - Vite → Next.js 迁移策略
• Linear 自动化 - CLI 脚本、AI 增强的问题受理、MCP 集成
• Linear VS Code 集成 - 扩展配置、混合工作流、键盘快捷键
• GitHub MCP 配置 - GitHub MCP 服务配置
• Figma MCP 配置 - Figma MCP 服务配置

配置与指南：

• Storybook 部署 - 视觉回归配置
• 分支命名 - 分支命名约定
• Sanity 迁移 - 博客迁移工作流

技术文档

前端：

• React 19 - UI 框架
• Next.js 16 - 带有 App Router 的 React 框架
• Vite - 构建工具和开发服务器
• TypeScript - 类型安全
• React Router - 客户端路由（Vite 应用）

样式与设计：

• CSS Modules - 作用域限定的 CSS
• Storybook - 组件开发
• Figma - 设计文件和设计令牌

国际化：

• i18next - i18n 框架
• react-i18next - React 绑定

测试与质量：

• Vitest - 单元测试
• Testing Library - 组件测试
• Playwright - 视觉回归测试
• axe-core - 无障碍测试

后端与部署：

• Vercel - Next.js 托管 + 无服务器
• GitHub Pages - 静态网站托管
• Sanity - 无头 CMS
• Sentry - 错误跟踪

自动化与 AI：

• Linear API - 问题管理
• MCP - 模型上下文协议
• Claude Code - AI 结对编程

✉️ 聊天邮件工作流

聊天界面包含一个引导式、多步骤的邮件撰写工作流，可由自然语言触发。共有两种触发方式：

1. 通用意图（例如“发送邮件”“帮我发送一封邮件”/ FI / SV 变体）→ 助手注入本地化的 chatEmailSendPhrase，并邀请用户开始撰写。
2. 简单关键词（单独出现的 "email" / "sähköposti" / "epost"）→ 助手注入本地化的 chatEmailSimplePhrase，显示 [email protected]，然后询问用户是否要开始撰写。

两种方式最终都会进入由 reducer 驱动的同一流程；区别仅在于初始措辞。简单触发方式使用锚定正则表达式，因此会忽略偶然提及（“我喜欢邮件工作流”）。

触发与检测

messageProcessor.ts 会根据多语言正则匹配设置两个待处理标志之一（pendingEmailWorkflowGeneral 或 pendingEmailWorkflowSimple）。ChatWidget 会在下一轮助手回复时准确消费其中一个标志，注入短语键（chatEmailSendPhrase 或 chatEmailSimplePhrase），以内嵌方式挂载工作流 UI，然后重置该标志。

状态机概览

Reducer 文件：src/components/ChatWidget/emailWorkflow/reducer.ts 类型：src/components/ChatWidget/emailWorkflow/types.ts

状态（简化版）：

• idle – 工作流未激活
• compose – 初始自由格式意图收集（主题 / 用途）
• fields – 按顺序收集结构化字段（姓名、电子邮件、电话（可选）、邮件正文）
• review – 用户查看汇总后的草稿，并可编辑任意字段
• sending – 正在异步提交（应用了 aria-busy）
• success – 显示确认信息和摘要
• error – 错误状态，提供重试和编辑选项

状态转换具有确定性且经过验证；编辑会返回 fields 状态并保留数据。取消操作会彻底重置为 idle。

组件

• ComposePrompt – 收集初始意图 / 主题
• FieldPrompt – 显示当前必填字段的输入项和验证提示
• ReviewSummary – 发送前汇总所有已收集的字段
• SendStatus – 显示发送中、成功或错误反馈

所有组件都位于 src/components/ChatWidget/emailWorkflow/，并遵循标准模式，包含 .stories.tsx 和 .test.tsx 覆盖。样式使用现有设计令牌和 CSS Modules；无障碍标签和描述使用 i18n 键。

验证与服务抽象

• contactValidation.ts – 共享字段验证器（姓名、电子邮件格式、消息长度、可选电话）
• contactEmailService.ts – EmailJS 发送封装，会抛出类型化错误（EmailServiceError），以支持更精细的重试提示

环境变量

将以下内容添加到开发环境的 .env 文件中（添加 Vite 前缀）：

VITE_EMAILJS_SERVICE_ID=<your_service_id>
VITE_EMAILJS_TEMPLATE_ID=<your_template_id>
VITE_EMAILJS_PUBLIC_KEY=<***REMOVED***>

这些变量由工作流和传统联系表单使用。缺少变量时会妥善阻止发送操作（并向用户显示错误状态）。

国际化

所有面向用户的工作流文本都使用 emailWorkflow.* 键前缀（例如 emailWorkflow.compose.heading、emailWorkflow.fields.name.label、emailWorkflow.status.success.title）。合并前，请确保在全部三个语言文件（en、fi、sv）中更新新增内容，否则翻译覆盖率测试将失败。

无障碍

• 每个提示词都使用语义化表单控件，并通过 htmlFor 关联标签
• 发送状态使用 role="status" + aria-busy="true"，并显示本地化进度文本
• 错误状态提供重试操作，焦点顺序清晰，且不存在键盘陷阱
• 审核列表使用结构化标记（定义列表或分组段落），方便屏幕阅读器理解

测试预期

• Reducer 单元测试：覆盖所有主要状态转换（撰写 -> 字段 -> 审核 -> 发送 -> 成功/错误），包括编辑和取消
• 集成测试：常规路径（emailWorkflow.integration.test.tsx）和简单关键词路径（emailWorkflow.simpleTrigger.test.tsx）
• i18n 覆盖率：所有语言文件中均包含全部 emailWorkflow.* 键
• 视觉回归：为每种状态创建 Storybook 快照（布局变化时有意更新）
• 无障碍测试：工作流 Story 和页面均不存在 axe 违规

扩展指南

如需添加其他字段或可选附件：

1. 将新字段添加到 EmailDraft 类型和验证器中
2. 在 reducer 中插入字段步骤逻辑（顺序会影响流程推进）
3. 在 emailWorkflow.fields.<fieldName>.* 下本地化新字符串
4. 更新 ReviewSummary 渲染逻辑和测试
5. 刷新视觉基线和翻译覆盖率

优先采用增量式更改，而非修改现有字段语义，以避免破坏已本地化的内容。

维护

任何架构或触发行为变更，都必须同时更新此 README、.github/copilot-instructions.md、CLAUDE.md 和 docs/donny-chat.md。

🛡️ 可观测性自动化

自动化脚本会生成轻量级 JSON 文件，由 UI 组件（例如摘要卡片）和 Storybook 仪表板使用，渲染时无需调用实时 API：

• Sentry 摘要：public/observability/sentry-summary.json（通过 scripts/generate-sentry-summary.mjs 或 scripts/sentry-mcp.js 命令生成）
• TypeScript MCP 状态：public/observability/ts-mcp-status.json（通过 scripts/ts-mcp-automation.mjs 生成）

命令

npm run ts:mcp:status       # Perform LSP handshake and write status JSON
npm run ts:mcp:status:stub  # Force stub status JSON (no handshake)

Sentry 摘要脚本支持项目和筛选选项（未解决的生产问题）。缺少凭据时可使用存根模式；UI 会通过徽章区分存根数据。

集成说明

• SentrySummaryCard 会读取并渲染 Sentry JSON，并显示本地化的加载、错误和空状态
• 后续的可观测性组件应遵循相同的解耦模式：在构建时或按需生成 JSON，并进行纯渲染
• 确保各语言文件中的翻译键（observability.sentry.*、未来的 observability.ts.*）保持同步

维护要求

每当可观测性架构发生变化（新增字段、属性重命名）时，都要同步更新 README、.github/copilot-instructions.md 和 CLAUDE.md。必须添加或调整测试，以覆盖新状态（例如，存根检测、额外的元数据渲染）。

🤖 MCP 工具

Donny 的无服务器聊天处理程序会自动加载 mcp.json 中声明的所有 MCP 服务。除了本地 TypeScript 语言服务和 Sentry 助手外，仓库现在还包含托管的 Context7 MCP 服务，因此助手提示词无需离开对话即可获取最新的框架／库文档。

• mcp.json → "context7" 条目指向 https://mcp.context7.com/mcp，并发送 Context7-API-Key 标头（其值从 CONTEXT7_API_KEY 解析）。匿名／低频使用时，请勿设置此环境变量。
• 提供了一个便捷的运行程序，用于本地调试：
  npm run context7:mcp -- [optional flags]
  • 添加 --remote-check 以 ping 托管的 Context7 MCP 端点。此助手会自动使用 CONTEXT7_API_KEY 注入 Context7-API-Key 标头。
• 在 .env.local 或 shell 配置文件中设置 CONTEXT7_API_KEY（密钥保存在 Vercel 的项目环境变量中），即可享受更高的速率限制和私有库访问权限。除非手动传入 --api-key，否则脚本会自动注入该密钥。
• 为 Context7 提供支持的 REST API 位于 https://context7.com/api/v1；如果需要在控制面板之外查看账户状态或管理密钥，请使用此基础 URL。

api/donny-tools.ts 会将每个工具命名为 <server>.<toolName>，因此连接后，Context7 功能会显示在 context7.* 命名空间下。这样可让下游提示词明确指定工具，也便于在需要时移除配置块以禁用该服务。

GitHub MCP 服务

官方 GitHub MCP 服务为 AI 工具提供对 GitHub 平台功能的直接访问。

• mcp.json → "github" 条目指向 https://api.githubcopilot.com/mcp/，并发送 Authorization: Bearer 标头（其值从 GITHUB_MCP_PAT 解析）
• 需要设置：在 GitHub Settings 创建 GitHub Personal Access Token，并设置 GITHUB_MCP_PAT 环境变量
• 可用工具集：仓库操作、问题管理、拉取请求、GitHub Actions、代码安全等
• 测试配置：npm run github:mcp:test
• 完整设置指南：docs/GITHUB_MCP_SETUP.md

功能包括：

• 浏览仓库和文件操作
• 问题和拉取请求管理
• 监控 GitHub Actions 工作流
• 代码安全分析和 Dependabot 警报
• 团队协作和组织管理

连接后，GitHub 功能会显示在 github.* 命名空间下，沿用相同的明确工具命名模式。

Figma MCP 服务

figma-developer-mcp为 AI 工具提供对 Figma 设计平台的直接访问，支持从设计到代码的工作流。

• mcp.json → "figma-developer-mcp" 条目以 SSE 服务形式运行，地址为 http://localhost:3333/sse
• 需要设置：在 Figma Settings 创建 Figma Personal Access Token，并设置 FIGMA_TOKEN 环境变量
• 服务管理：使用 MCP 功能前，先通过 npx figma-developer-mcp 启动
• 测试配置：npm run figma:mcp:test
• 完整设置指南：docs/FIGMA_MCP_SETUP.md

功能包括：

• 分析设计文件并提取组件
• 下载资源并提取设计令牌
• 编写设计系统文档并检查一致性
• 生成设计到代码的实现方案并提供指导
• 集成协作设计工作流

连接后，Figma 功能会显示在 figma.* 命名空间下，使 AI 助手能够与设计文件交互，并直接根据 Figma 设计生成实现代码。

其他文档

• 分支命名指南