global

工作指导手册

你好，AI 助手！这份文档是你的核心工作指南。在你进行任何编码、重构或分析工作之前，必须完整阅读并理解本文档。你的首要任务是确保你的所有操作都与本文档中描述的架构和原则保持一致，并在你对项目架构做出任何修改后，**主动更新本文档本身 global.mdc **。

1. 项目核心定位

这是一个基于 Cloudflare 技术栈的、生产级、类型安全的 Hono + React + D1 全栈应用模板。

• 核心价值: 提供开箱即用的开发体验，整合最佳实践，实现从数据库到前端的端到端类型安全。
• 目标用户: 希望在 Cloudflare 生态中快速构建现代化 Web 应用的开发者。
• 你的角色: 维护并增强这个模板的工程化能力、易用性和健壮性。始终以"最佳实践"和"最低维护成本"为原则进行开发。

2. 核心技术与架构

2.1. 整体架构

这是一个混合渲染模式 (Hybrid Rendering) 的单体应用，部署在 Cloudflare Pages & Workers 上。

• 开发环境 (pnpm dev):
  • Hono 后端 (Wrangler) 运行在 localhost:8787，作为主入口。
  • Vite 前端服务器运行在 localhost:5173。
  • 关键认知: index.ts 中的开发逻辑会将所有非 API 的前端请求代理到 Vite 服务器 (5173)。这使得前端能享受 Vite 带来的热更新 (HMR)。你绝不能假设开发时后端可以直接访问 frontend/dist 下的任何文件。
• 生产环境 (pnpm deploy):
  • Vite 将前端代码构建为静态资源，输出到 frontend/dist 目录。
  • Hono 后端 (src/index.ts) 会根据 manifest.json 服务器端渲染 (SSR) 初始 HTML，并由 Cloudflare Pages 提供静态资源。
  • 关键认知: index.ts 中通过动态 import() 来加载生产构建产物 (manifest.json 和 index.html)，这是为了避免在开发环境中因找不到这些文件而导致构建失败。这是本项目的核心架构设计，必须理解并维护。

2.2. 后端 (src/)

• 入口: src/index.ts:
  • 这是应用的统一入口。
  • 使用 if (c.env.NODE_ENV === "development") 来分离开发和生产逻辑。
  • OpenAPI 注册: API 路由通过一个独立的 OpenAPIHono 实例 (apiApp) 进行注册，然后统一挂载到主 app 上。这是为了确保 Swagger UI 能正确发现所有端点。在添加新的 API 模块时，必须遵循这个模式。
• 路由: src/routes/:
  • Hono 的路由模块。示例为 post.ts。
  • 使用 @hono/zod-openapi 的 createRoute 来创建类型安全且自动生成文档的路由。
• 数据校验: src/validators/:
  • 使用 Zod 定义所有 API 的请求/响应/路径参数的 Schema。这些 Schema 是类型安全和 API 文档的来源。
• 数据库 ORM: src/db/:
  • schema.ts 文件使用 Drizzle ORM 定义数据库表结构。这是唯一的数据源 (Single Source of Truth)。
• 集中化配置管理:
  • SEO 配置: src/config/seo.ts - 所有 SEO 相关配置的单一数据源
  • 工具函数: src/utils/htmlTemplate.ts - 统一的 HTML 模板生成器，避免重复代码
  • 自动化脚本: scripts/generateHtml.ts - 自动生成开发环境的 HTML 模板

2.3. 前端 (frontend/)

• 统一路由配置:
  • 核心改进: frontend/src/routes.tsx - 唯一的路由定义文件，被客户端和服务端入口共享使用。
  • 开发友好: 添加新页面时，只需要在此文件中修改一次，避免了在多个入口文件中重复定义。
• 入口文件:
  • entry-client.tsx: 客户端入口。负责在浏览器中"激活"(hydrate) 由服务器渲染的 HTML。使用统一的路由配置。
  • entry-server.tsx: 服务器端渲染入口。负责在后端生成初始的 HTML 字符串。使用统一的路由配置。
  • 关键优化: 两个入口文件都使用 AppRoutes 组件，确保路由定义的一致性。
• 主题系统:
  • 核心:
    • frontend/src/context/ThemeContextProvider.tsx 提供了一个全局的 AppThemeProvider 和 useAppTheme hook。
    • frontend/src/theme/ 目录是我们中心化的主题定义模块。
  • 架构与规则:
    • 自定义主题: 我们通过对 Material-UI 主题进行模块扩展 (module augmentation) 来添加自定义、类型安全的主题属性。类型定义位于 frontend/src/theme/types.ts。
    • 中心化管理: 所有与主题相关的样式（如特定页面的背景、自定义组件颜色等）都必须在 frontend/src/theme/index.ts 中的 lightTheme 和 darkTheme 对象里进行定义。
    • 组件内使用: 组件禁止通过 theme.palette.mode === 'dark' 这样的条件判断来硬编码样式。必须直接从主题对象中获取预先定义好的自定义属性 (例如 theme.pageBackground)。
    • 状态切换: 所有主题状态的读取和切换都必须通过 useAppTheme hook 进行。
• 页面与布局:
  • pages/: 存放页面级组件。
  • App.tsx: 应用内部的主布局，包含导航栏、页脚和主题切换按钮。
• Vite 配置: vite.config.mts:
  • 关键认知: 配置了 resolve.alias 来支持 @/ 路径别名。如果未来有构建问题，应检查此处的配置。