Portfolio: Cyberpunk

在线访问 · 私有仓库

概览

• 角色： 独立全栈与创意工程师。
• 技术栈： Next.js 16 App Router、React 19、TypeScript、Tailwind CSS 4、MDX、next-intl、Framer Motion、带 Perlin-style distortion 的 custom Canvas waves、Three.js、React Three Fiber、provider-neutral AI integration、MCP/OAuth、Node.js 24 LTS 与 Vercel。
• 关键结果： 将创意前端表达与面向生产环境的全栈集成放在同一个可访问的作品集里。
• 摘要： 数字故障风格服务于信息层级，互动效果不会取代项目内容本身。

产品问题

• 挑战： 让访客快速理解能力范围，同时保留可供技术审阅的深度。
• 受众： 招聘人员、工程负责人、潜在客户与重视设计和架构的开发者。
• 约束： 小屏幕、键盘操作、降低动态效果、九种语言以及外部服务的安全边界都必须成立。

方法与决策

• 架构： Next.js App Router 提供本地化路由与服务端内容，交互部分放入独立客户端壳层。
• 关键决策：
  • 九种语言内容与路由： next-intl 管理 locale 路由和消息，每个项目都有本地化 MDX，缺失时按文档回退到英文。
  • Canvas 与 3D 交互： 带 Perlin-style distortion 的 custom Canvas waves、Framer Motion 与聚焦的 Three.js/React Three Fiber hero 提供表现力强的 motion，不会把整个产品变成 3D 场景。
  • FUI 诊断终端： CRT 质感、scanlines、terminal status readout 与 glitch typography 构成未来界面身份，同时保持清晰层级。
  • 可选语音与配音： local browser feedback、dubbing popup 与 audio sequencing 遵循 user settings 和 browser support。
  • 叠层协调： boot screen、navigation、cursor、scanlines、chat、dubbing popup 与 3D hero 使用刻意 stacking coordination，而非固定 layer count。
  • Oz 助手设计： /api/chat 使用中立的主服务与备用服务路由、静态作品集数据和更深入的 MDX 上下文，以及明确的 UI 工具。
  • 客户端、服务端与状态边界： provider 分别管理主题、国际化与音乐，聊天偏好保留在本地，filter store 仅处理狭窄职责。
  • MCP 与 OAuth： 只读工具采用 OAuth 2.1、PKCE S256 与 portfolio.read scope 保护。
• 国际化： next-intl 负责路由、消息、元数据和项目 MDX，并在缺少条目时使用英文回退。
• Canvas： 波浪和失真被限制在 UI 层，内容路由不依赖动画生命周期。
• 3D： Three.js 与 React Three Fiber 仅在合适的客户端场景加载，不影响阅读。
• 设计系统： CSS 自定义属性和共享 glitch 原语统一色彩、排版、叠层和反馈。
• 可访问性： 降低动态偏好会关闭相关分支，粗指针设备不会显示自定义光标。
• 取舍： 选择渐进增强，不把 Canvas、音频或 3D 当作导航的前提。
• 取舍： 选择有目的的 Canvas 和可选 3D，而不是更重的全 3D 展示，浏览器语音也是可选反馈而非服务端语音流程。
• 数据流： 访客输入进入 /api/chat，获得静态作品集数据和更深入的 MDX 上下文；流式响应返回文字或 UI action，支持的浏览器可选用本地语音。

结果与证据

• 结果： 网站同时提供快速定位与对系统的深入说明。

• 质量与验证： ESLint、TypeScript 检查和生产构建是可重复的质量门槛。

• 安全控制： chat 使用签名临时锁定和速率边界，MCP 使用只读 scope 与一次性授权码。

• 比较与演进： 产品从早期 Portfolio: Glass 演进为可承载本地化叙事和 agent access 的模块化作品集。

• 影响： 它同时呈现创意前端与可维护的内容、集成、安全和部署决策。

• 首屏先传达身份和内容，再提供更深的交互层。

• 项目、技能、经历和联系信息无需账户即可浏览。

• 九个语言路由共享一致的信息架构。

• Oz 助手用对话方式引导至同一组已验证作品集事实。

• 外部集成是可选增强，不会阻塞核心阅读。

技术深入

• 突出细节： CRT 质感、glitch 排版、Canvas、聚焦的 3D hero、音乐控制和本地化内容共享清晰职责，没有过度的全局状态容器。

• 验证： lint、类型检查与生产构建作为质量门槛执行，responsive、reduced-motion 和 coarse-pointer 分支会随 UI 修改复核。

• 优化： client-only shell 隔离浏览器能力，MDX、数据模块与组件化结构避免加载非必要交互。

• 代码质量： TypeScript 类型、组织清晰的 handler、聚焦 provider、狭窄 store 以及服务和安全模块让代码所有权更明确。

• 链接与参考： 参见 components/sections、components/ui、components/chatbot、components/providers、content/projects、messages、data、lib/mcp、lib/security、lib/services 与 stores。

• /api/chat 通过多提供方路由和受控回退为 Oz 提供流式回答。

• 助手读取静态作品集数据和 MDX 上下文，以保持公开内容的依据清晰可审阅。

• 浏览器语音为可选能力，文本体验始终可用。

• MCP 为只读，主要传输方式是 Streamable HTTP，授权使用 OAuth 2.1 Authorization Code 和 PKCE S256。

• Vercel 上由 Upstash Redis 完成原子的一次性授权码兑换，本地开发保留兼容行为。

• 主题、provider 状态、组件本地浏览器持久化和聊天筛选 store 各自保持作用域。

反思

• 不同做法： 持续简化最耗费资源的视觉路径，同时保留编辑风格人格。

• 成功之处： 界面、本地化叙事、助手、音乐和发现面共同呈现为一个产品。

• 经验： 当服务端集成、仅浏览器行为与本地化内容边界明确时，丰富交互更容易维护。

• 内容层级优先，创意动效才会真正增强体验。

• 清晰的客户端和服务器边界比增加集成更重要。

• 本地化案例必须和代码库同步维护，而不是一次性翻译。

我的贡献

• 前端与设计： 设计视觉系统、响应式 section、HUD 构图、Canvas、3D hero 与内容呈现。

• AI 与 Oz： 实现流式助手、主服务和备用服务路由、作品集与 MDX 上下文和 UI action。

• 交互与动画： 调校 motion、scroll、reduced-motion 与响应式互动。

• 设计并实现视觉系统、页面结构与响应式交互。

• 建立本地化内容管线、项目呈现和 MDX 组件。

• 集成 Oz、AI 回退策略及其安全控制。

• 实现 MCP 发现、OAuth、联系、媒体、分析和部署集成。

项目架构

• 分层结构： server component 管理 locale 和文档结构，client component 管理浏览器交互，API route 隔离 chat、contact、media 与 MCP。

• 功能模块： 项目采用按功能组织的 Next.js 结构，使内容、UI、服务端集成和机器可读发现彼此分离。

• 分层： 路由与服务端组件管理 locale 和文档结构，客户端组件管理交互与浏览器 API。

• src/app/[locale]： 本地化页面、layout、loading、error 与项目路由。

• src/components/sections： Hero、About、Experience、Skills、Projects、Contact、Certification。

• src/components/ui： GlitchText、Waves、CustomCursor、HeroModel、SkillGraph 等视觉原语。

• src/components/layout： 导航、启动体验和返回顶部行为。

• src/components/chatbot： 小部件、会话 UI 与客户端聊天服务。

• src/components/providers： 仅客户端 shell 与音乐播放器 provider 边界。

• src/content/projects： 各语言项目详情 MDX。

• src/data 与 src/messages： 已验证静态事实与翻译目录。

• src/lib、src/hooks 与 src/stores： 共享服务、复用行为和小范围 UI/filter state。

• 状态管理： providers 拥有主题、国际化与音乐，聊天偏好与 filter state 保持在所需的最小范围。

• 重构与改进： 模块边界让视觉功能、route handler、内容和集成可以独立演进。

状态不是单一全局容器：主题与 provider 使用各自 context，聊天偏好在合适时保存于浏览器，filter store 仅服务自身 UI。

模块化结构允许替换一个视觉效果或 provider，而不触碰本地化内容和服务端契约。

路由与接口

• PWA 与 SEO： manifest、robots、sitemap、JSON-LD 和本地化元数据服务浏览器与爬虫。
• 九种语言： /[locale] 及其项目路径通过 next-intl 提供 locale-aware 页面层级。
• MCP 与 AI： /api/mcp、OpenAPI 和 .well-known 提供只读 agent access，/api/chat 是 Oz 流式入口。
• Oz 运营： /api/chat、/api/chat/health 与 /api/gallery/[slug] 提供助手的流式、健康检查与带速率限制的 project-media surface，获批的 UI 工具负责导航、项目筛选、已启用图库、联系审核、音乐、主题与语言操作。
• LLM 与人类导出： llms.txt、llms-full.txt、auth.md 和公共发现文件提供清晰上下文。

运行细节

• layout 负责 fonts、providers 与 localized metadata boundary。
• loading 和 error surface 是 route experience 的一部分，而不是独立演示页。
• project slug 会先解析到对应 locale 的 MDX source，再渲染详情。
• Cover component 会在 server 端检查 local asset path 后才渲染媒体。
• 站内导航使用 i18n routing module 的 helpers。
• ghost navigation 在向下滚动时隐藏，向上滚动时恢复。
• body layout 会补偿这一临时 navigation state。
• contact form 经过 SMTP handler，不会把 mail credentials 暴露给 client。
• Spotify 体验使用 login、callback、now-playing surface，不使用通用 music API route。
• /api/gallery/[slug] 是带速率限制的 project media 与 supported gallery surface。
• Oz 的 approved UI actions 可在 gallery 已启用且受支持时打开项目图库，不将其表述为通用 mobile action。
• /api/chat 会验证 same-origin requests。abuse controls 激活时，独立的 signed temporary lockdown cookie 承载 restriction，request 本身并未签名。
• analytics 有 opt-out behavior，且不属于 critical page content。
• PWA manifest 支持 installable metadata，不改变正常 browser flow。
• JSON-LD 提供与 visible portfolio facts 一致的 structured context。
• robots 与 sitemap route 让 public pages 保持可发现性。
• security 与 OAuth discovery 位于 .well-known documents，而不是 client-only hints。
• authorization scope 始终是 portfolio.read，MCP 不会成为 write surface。
• one-time code redemption 在 deployed environment 中降低 replay risk。
• fallback provider 改善 availability，但不改变 portfolio source of truth。
• chatbot response 可以导航或搜索，不能随意修改 content。
• optional reasoning 与 subagent behavior 在启用时具有明确的 server-side controls。
• signed temporary lockdown 用于应对 jailbreak 与重复 abuse。
• 每个 visual primitive 都能在不改变 content model 的前提下测试或关闭。
• Tailwind v4 通过 PostCSS configuration 与项目 CSS token system 工作。
• TypeScript types 明确 portfolio data 与 MDX module contracts。
• production build 是 routes、content、server boundaries 的最终联合检查。

演示预览

• 数字故障首页： 清晰排版、HUD 细节和 Canvas 纹理都服务于内容。
• Oz 助手： 从作品集上下文提供流式、locale-aware 回答与导航帮助。
• 项目浏览： MDX 案例、封面媒体和结构化章节从项目网格延伸到深入阅读。
• FUI 诊断式首页： CRT 质感、扫描线、终端式状态读数与 glitch 排版共同形成清晰的未来界面身份。
• 可选语音与配音： 兼容浏览器可提供用户控制的本地语音反馈与配音弹窗，但音频并非使用网站的前提。
• 响应式网格： 项目、技能、经历与资质以易读的高密度 section 组织，兼顾精细指针、触摸与 reduced-motion 场景。
• 本地化详情： 访问者可用所选语言阅读同一项目的架构与贡献叙述。
• 面向代理的发现： OAuth 与 public discovery documents 说明受控的只读 machine access 如何与 human-facing portfolio 共存。
• 叠层协调： boot screen、navigation、cursor、scanlines、chat、配音弹窗与 3D hero 采用刻意的 stacking coordination，以保持可读和可达。
• 私有代码库： 公开案例介绍在线产品，而代码库保持私有。

托管说明： 该作品集在线运行于 franzdomingo.dev，以 Vercel 为部署目标，并使用 Node.js 24 LTS runtime。