文档核心

Project/fonrey/TECH_STACK/TECH_STACK 文档要求.md

@@ -0,0 +1,161 @@
+#### 1. 项目概览（Project Overview）
+
+用 2-3 句话说清楚这是什么项目、核心用途、目标用户。AI 需要这个"北极星"来判断所有技术取舍。
+
+md
+
+```md
+## Project Overview
+A B2B SaaS invoice management tool. Target users are SMB accountants.
+Prioritize reliability and data integrity over flashy UI.
+```
+
+---
+
+#### 2. 核心技术栈（Core Stack）
+
+每一层都要写清楚，**不要只写框架名，要写版本号和选型原因**。
+
+md
+
+```md
+## Core Stack
+- Runtime: Node.js 22 (not Bun, not Deno)
+- Framework: Next.js 15 (App Router only, never Pages Router)
+- Language: TypeScript 5.x, strict mode enabled
+- Database: PostgreSQL 16 via Supabase
+- ORM: Drizzle ORM (not Prisma)
+- Styling: Tailwind CSS v4 + shadcn/ui
+- Auth: Clerk
+- Deployment: Vercel
+```
+
+---
+
+#### 3. 关键约定（Key Conventions）
+
+这是 vibe coding 最容易出错的地方，AI 会有自己的"默认习惯"，必须显式覆盖。
+
+md
+
+```md
+## Key Conventions
+- File naming: kebab-case for files, PascalCase for components
+- All server actions in /actions, never inline in components
+- Use `server components` by default; add 'use client' only when needed
+- Environment variables: never hardcode, always use process.env.NEXT_PUBLIC_*
+- Error handling: always use Result pattern, never throw in server actions
+- No `any` types. No `// @ts-ignore`.
+```
+
+---
+
+#### 4. 目录结构（Directory Structure）
+
+AI 需要知道把新文件放在哪里，否则它会自己"发明"结构。
+
+md
+
+```md
+## Directory Structure
+src/
+├── app/          # Next.js routes only, minimal logic
+├── components/   # Reusable UI components
+│   └── ui/       # shadcn primitives, DO NOT edit
+├── actions/      # Server actions
+├── lib/          # Utilities and helpers
+├── db/           # Drizzle schema and migrations
+└── types/        # Global TypeScript types
+```
+
+---
+
+#### 5. 明确禁止的东西（Explicitly Forbidden）
+
+这是最被忽视但最重要的部分。告诉 AI **不要用什么**，比告诉它用什么更有效。
+
+md
+
+```md
+## Do NOT Use
+- ❌ `axios` — use native `fetch`
+- ❌ `moment.js` — use `date-fns`
+- ❌ `useEffect` for data fetching — use server components or React Query
+- ❌ `pages/` directory — App Router only
+- ❌ `class components` — functional only
+- ❌ CSS Modules or styled-components — Tailwind only
+- ❌ `console.log` in production code
+```
+
+---
+
+#### 6. 第三方服务与集成（External Services）
+
+列出已经接入的服务，避免 AI 重复造轮子或引入冲突的 SDK。
+
+md
+
+```md
+## External Services
+- Payments: Stripe (already configured in /lib/stripe.ts)
+- Email: Resend + React Email templates
+- File storage: Supabase Storage (not S3)
+- Analytics: PostHog
+- Error tracking: Sentry
+```
+
+---
+
+#### 7. 代码风格与 Linting（Code Style）
+
+md
+
+```md
+## Code Style
+- Formatter: Prettier (config in .prettierrc)
+- Linter: ESLint with eslint-config-next
+- Imports: absolute paths via `@/` alias, no relative `../../`
+- Prefer `const` over `let`, avoid `var`
+- Async/await over `.then()` chains
+```
+
+---
+
+#### 8. 测试策略（Testing, 如果有的话）
+
+md
+
+```md
+## Testing
+- Unit tests: Vitest
+- E2E tests: Playwright (critical flows only)
+- No snapshot tests
+- Test files co-located: `component.test.ts` next to `component.ts`
+```
+
+---
+
+### 一个实用的小技巧
+
+在文件开头加一句 AI 专用说明：
+
+md
+
+```md
+> **For AI assistants**: Read this entire file before writing any code.
+> All decisions here are final. Do not suggest alternatives unless asked.
+```
+
+---
+
+### 内容优先级总结
+
+|优先级|内容|原因|
+|---|---|---|
+|🔴 必须|核心技术栈 + 禁止列表|防止 AI 用错库|
+|🔴 必须|目录结构 + 文件约定|防止结构混乱|
+|🟡 重要|外部服务清单|防止重复实现|
+|🟡 重要|关键约定|保持风格一致|
+|🟢 加分|测试策略 + 代码风格|提升整体质量|
+
+**核心原则**：写给 AI 看的文档要比写给人看的**更具体、更强硬、更少歧义**。任何"视情况而定"的描述，AI 都会做出你不想要的选择。