101 lines
5.0 KiB
Markdown
101 lines
5.0 KiB
Markdown
---
|
||
name: bun-solid-elysia-stack
|
||
description: High-performance SSR stack using Bun, SolidJS, Elysia, and Shadcn-solid
|
||
tags: [bun, solid, elysia, shadcn, ssr]
|
||
---
|
||
|
||
# 🚀 Bun + SolidJS + ElysiaJS + Shadcn 技术栈规范
|
||
|
||
## 🛡️ 核心架构与约束 (Architecture & Constraints)
|
||
|
||
### 1. 运行时与构建 (Bun.js)
|
||
- **Runtime**:强制使用 `Bun.serve()` 作为 HTTP 服务器。
|
||
- **Build**: 使用 `Bun.build()` 及其插件系统。
|
||
- **Testing**: 必须使用 `bun:test` 替代 Jest/Vitest。
|
||
- **Database**: 强制使用 **TypeORM** + **SQLite**。必须使用 Repository 模式进行数据访问，禁止在 Controller 中直接编写 SQL。
|
||
- **Package Manager**: 必须使用 `bun install / add / run`。严禁使用 `npm` 或 `yarn`。
|
||
|
||
### 2. 前端框架 (SolidJS & Solid Start)
|
||
- **Reactivity**:
|
||
- **严禁**解构 Props (会导致响应式丢失)。必须使用 `props.value` 或 `splitProps`。
|
||
- **严禁**使用 `mcp_chrome-devtools` 调试时依赖 React DevTools 思维。Solid 是细粒度更新，无 VDOM diff。
|
||
- **控制流**: 必须使用 `<Show>`, `<For>`, `<Switch>` 等内置组件，禁止使用 `array.map()` 或三元运算符直接渲染列表/条件。
|
||
- **SSR/Hydration**:
|
||
- 服务端数据预取必须在 `routeData` 或 `createServerData$` 中完成。
|
||
- 禁止在 `onMount` 中执行影响首屏内容的操作（会导致水合不匹配）。
|
||
|
||
### 3. 后端服务 (ElysiaJS)
|
||
- **Type Safety**: 必须使用 `t.Object` / `t.String` 等 Elysia 类型系统定义 DTO。
|
||
- **Validation**:所有 API 必须有 schema 验证。
|
||
- **Performance**: 路由注册应当利用 Elysia 的 AOT 编译特性，避免动态路由过度嵌套。
|
||
|
||
### 4. UI 组件库 (Shadcn-solid + Tailwind)
|
||
- **Styling**:
|
||
- 禁止书写 `style` 属性或 CSS 文件。必须使用 Tailwind Utility Classes。
|
||
- 必须使用 `cn()` (clsx + tailwind-merge) 处理动态类名。
|
||
- **Components**:
|
||
- 优先复用 Shadcn-solid 组件。
|
||
- 自定义组件必须支持 `class` 和 `classList` 属性透传。
|
||
- **Dark Mode**: 必须通过 CSS 变量和 Tailwind `dark:` 前缀适配深色模式。
|
||
|
||
### 5. 移动端适配与国际化 (Mobile & i18n)
|
||
- **Responsive Design**:
|
||
- 必须采用 **Mobile-First** 策略：默认样式为移动端，使用 `mm:`, `lg:` 等断点覆盖 PC 端样式。
|
||
- 严禁使用固定像素宽度 (px) 定义主要容器，必须使用百分比、`rem` 或 Tailwind 的 `container`/`w-full`。
|
||
- 交互适配：Touch事件与Hover状态必须兼容（使用 `@media (hover: hover)` 处理仅 PC 显示的交互）。
|
||
- **Internationalization (i18n)**:
|
||
- 必须集成 `@solid-primitives/i18n` 或 Solid Start 官方推荐的 i18n 方案。
|
||
- **严禁**在 JSX 中硬编码文本。所有文案必须提取到 `dictionaries` 或 `locales` 资源文件中。
|
||
- **SSR支持**: 服务端必须解析请求头 `Accept-Language` 或 URL 前缀，在 SSR 阶段注入当前语言字典，杜绝客户端水合时的内容闪烁。
|
||
|
||
---
|
||
|
||
## 🔍 代码审计要点 (@code-spec)
|
||
|
||
当 @code-spec 执行审计时，必须检查以下条目：
|
||
|
||
1. **响应式丢失检查**:
|
||
- 检查组件 Props 是否被解构? (e.g. `const { name } = props` -> ❌)
|
||
2. **控制流优化**:
|
||
- 检查是否使用了 `<For>` 而不是 `.map()`? (Solid 的 `<For>` 对 keyed items 做了优化)
|
||
3. **类型安全**:
|
||
- Elysia 路由是否有 `body`, `query`, `params` 的 `t.*` 定义?
|
||
4. **Bun 兼容性**:
|
||
- 是否引用了 Node.js 特有且 Bun 未实现的 API? (需查阅 Bun 兼容性表)
|
||
5. **样式规范**:
|
||
- 是否存在硬编码颜色值? (应使用 CSS 变量如 `bg-background` `text-primary`)
|
||
6. **国际化规范**:
|
||
- 检查组件中是否存在硬编码的中文/英文字符串? (❌ `<span>登录</span>` -> ✅ `<span>{t('login')}</span>`)
|
||
7. **响应式检查**:
|
||
- 检查是否通过 `md:`, `lg:` 等断点处理了布局变化? 是否存在大块固定 `px` 宽度的容器?
|
||
8. **ORM 规范**:
|
||
- 是否正确使用了 TypeORM 的 `@Entity` 定义模型?
|
||
- 是否通过 Repository 进行数据操作? (严禁裸写 SQL)
|
||
|
||
---
|
||
|
||
## 🧪 测试与验收标准 (@qa-tester)
|
||
|
||
当 @qa-tester 执行测试时，必须验证以下指标：
|
||
|
||
### 1. 性能指标 (Performance)
|
||
- **SSR 渲染耗时**: < 50ms (利用 Bun 高性能 RSC 渲染)
|
||
- **首屏加载 (LCP)**: < 1.0s
|
||
- **水合错误 (Hydration)**: 控制台 **0** Error/Warning
|
||
|
||
### 2. 功能测试
|
||
- **路由跳转**: 必须是 SPA 模式（无全页刷新）。
|
||
- **表单交互**: 提交后必须有 Loading 状态，支持 Enter 提交。
|
||
|
||
### 3. 兼容性
|
||
- **No-JS 支持**: 核心内容在禁用 JavaScript 时必须可见 (SSR 直出)。
|
||
- **浏览器**: Chrome, Safari, Firefox 最新版。
|
||
|
||
### 4. 多端与多语言测试
|
||
- **Viewport**: 必须覆盖 iPhone SE (375px), iPad Mini (768px), Desktop (1280px+)。
|
||
- **Touch**: 移动端下按钮点击区域必须 >= 44x44px。
|
||
- **i18n**:
|
||
- 切换语言必须即时生效（或路由跳转）。
|
||
- 刷新页面后，当前语言状态必须保持。
|
||
- 检查是否存在未翻译的原始 Key 显示在界面上。
|