一键在 Manus 中运行任何 Skill

bun-elysia-react-vite-stack

星标2

分支0

更新时间2026年6月19日 03:29

Bootstrap a local full-stack TypeScript app with Bun 1.2 + Elysia backend + Vite 8 + React 19 + Tailwind v4. SQLite (dev) + Postgres (prod recommended) via Prisma 5. Use when user wants a quick local dev app (CRM, MVP, internal tool, exam app) and stack is the same family.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

freedomw1987

freedomw1987/tree_monstor

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

Bun + Elysia + Vite/React Full-Stack Bootstrap

本地 dev 嘅最快 full-stack TS stack。Elysia 同 Bun runtime 配 Vite 嘅 HMR 體驗極順。SQLite 用 Prisma 5（唔好用 Prisma 7 — 見 prisma-sqlite-bun-setup skill）。

觸發時機

用戶要 quick MVP / internal tool / 個人練習 app / 新嘅 CRM 重建
已經喺 Elysia + Vite 環境做開 (e.g. 跟 bc-quotation 嘅 stack pattern)
唔需要 deploy production (local dev 為主) — deploy 睇 cdk-ecs-fargate-deploy
想要日後 production 行 Postgres 但 dev 階段快速用 SQLite (見下「SQLite vs Postgres」section)

部署目標 — 問用戶先 (2026-06-05 crm-system 真實訊號)

Plan 階段必須問用戶要 deploy 喺邊，唔好 default 推 CDK/IaC:

用戶情境	部署方案
Local only / NAS / NUC / 內部 server (David 嘅 crm-system 屬呢類)	Docker Compose (full stack) — postgres + api (Bun) + web (nginx) + opt-in adminer。`docker-mac-arm64-elysia-vite/templates/full-local-stack.md` 有 copy-paste docker-compose.yml + Dockerfiles + nginx.conf。唔好用 CDK
Cloud (AWS ECS / Fargate / RDS / CloudFront)	CDK v2 — 跟 `cdk-ecs-fargate-deploy` + `cdk-deployment-rules`
Hybrid (e.g. local dev, cloud prod for customers)	Docker Compose 本地 + CDK/Terraform prod。schema/seed 要 plan migration path

David 嘅具體訊號 (2026-06-05): "另外我不想用CDK, 因為這個系統是本地部署的,您給我計劃用docker 就可以了" — 觸發咗 Day 3 plan 改 pivot 去 Docker compose, 廢棄 CDK 路線。

喺 Plan 階段 (Think) 主動問「個 system 將會 deploy 喺邊」 — 用戶唔會 default 自己講, 要我哋 trigger。

SQLite vs Postgres 點揀 (2026 經驗)

📌 Host test env pitfall (Docker rescues): 如果 host 跑 bun test 撞 Cannot find module '.prisma/client/default',加 pretest: bunx prisma generate hook 即解。詳見 references/prisma-host-test-env.md。

情境	用咩
Exam app / 純本地練習 / 唔會上 production	SQLite — 零 setup, file 即可, Prisma 5 完美 support
內部 tool / 個人用 / single-user	SQLite — 唔需要 server
CRM / 報價單 / multi-user SaaS / 有 AI agent RAG	Postgres (即使 dev) — 因為需要 `String[]` (tag), `Json` (metadata), `Decimal` 真正 support, `pgvector` (RAG), transactions, concurrent writes
Production 但 dev 想 SQLite	可, 但要 plan migration — 用 `prisma migrate diff` 驗證 SQLite → Postgres syntax (Decimal precision, enum 唔同)

CRM/報價單必上 Postgres 嘅原因:

Json type: ActivityLog.metadata, Message.toolCalls — SQLite 只可以 String, 用 JSON.stringify 將就 (loss of type safety)
String[] type: Company.tags — SQLite 唔支援, 要 join table
Decimal precision: SQLite 用 String 儲, 冇 numeric type — 金額運算危險
pgvector: AI agent RAG 必要
Decimal @db.Decimal(15, 2) schema 同 SQLite 唔同, 之後 migrate 會有 friction

建議 (新建 CRM 項目):

Dev + Prod 都用 Postgres — 撈 docker postgres / RDS 唔難
唔想裝 Postgres server → bun add -d @electric-sql/pglite (in-process Postgres for dev)
真係 quick-and-dirty 先 SQLite, schema 唔用 String[] / Json / 唔用 pgvector

完整 SOP (SQLite path, 跟之前 bc-quotation)

1. Backend init (Bun workspaces monorepo, 支援 apps/api + apps/web)

mkdir -p ~/www/<project>/apps/api ~/www/<project>/apps/web ~/www/<project>/packages/db
cd ~/www/<project>

# Root workspace
cat > package.json <<EOF
{
  "name": "<project>",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "dev:api": "bun --filter api dev",
    "dev:web": "bun --filter web dev",
    "db:generate": "bun --filter db generate",
    "db:migrate": "bun --filter db migrate"
  }
}
EOF

# API
cd apps/api && bun init -y
bun add elysia @prisma/client
bun add -d prisma@5 tsx @types/node dotenv

⚠️ Prisma 一定要 pin prisma@5：bun add prisma 會拉到 7.x,撞 schema 唔再支援 url = env(...)。詳見 prisma-sqlite-bun-setup skill。

2. Prisma + DB setup

mkdir -p data
bunx prisma generate
bunx prisma migrate dev --name init --skip-seed

prisma/schema.prisma 範本（SQLite 限制：無 enum、無 Json → 用 String + JSON.stringify）：

generator client {
  provider = "prisma-client-js"
  output   = "../node_modules/.prisma/client"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model Question {
  id        String   @id @default(cuid())
  seq       String   @unique
  type      String
  question  String
  options   String   // JSON.stringify([{key,text}])
  answer    String
  createdAt DateTime @default(now())
}

.env：

DATABASE_URL="file:./data/app.db"
PORT=3200

⚠️ Path 陷阱：./data/app.db 係相對 prisma 同層。如果 backend 同 DB 喺唔同層，記得用 join(import.meta.dir, "..", "..", "data", "app.db")。

3. Elysia backend

// src/index.ts
import { Elysia, t } from "elysia"
import { PrismaClient } from "@prisma/client"

const prisma = new PrismaClient()
const PORT = Number(process.env.PORT) || 3200

const app = new Elysia()
  .get("/api/health", () => ({ ok: true }))
  .get("/api/items", () => prisma.question.findMany())
  .listen(PORT)

console.log(`Running at http://localhost:${PORT}`)

啟動：

bun --env-file=.env src/index.ts

⚠️ --env-file 必須 — Bun runtime 唔自動 load .env。詳見 bun-env-file-for-dev skill。

⚠️ Path 陷阱 (2)：readFile(join(import.meta.dir, "..", "questions.json")) — import.meta.dir 係 source 編譯後位置，唔係 cwd。如果個 file 喺 backend 外面，多加 ..。

4. Seed script

# prisma/seed.ts
import { PrismaClient } from "@prisma/client"
import { readFile } from "fs/promises"
import { join } from "path"

const prisma = new PrismaClient()
async function main() {
  const data: any[] = JSON.parse(
    await readFile(join(import.meta.dir, "..", "..", "data.json"), "utf-8")
  )
  for (const item of data) {
    await prisma.question.upsert({
      where: { seq: item.seq },
      create: item,
      update: item,
    })
  }
  console.log(`Seeded ${data.length}`)
}
main().finally(() => prisma.$disconnect())

package.json：

{
  "scripts": {
    "dev": "bun --env-file=.env --watch src/index.ts",
    "db:seed": "bun run prisma/seed.ts",
    "db:studio": "prisma studio"
  }
}

5. Frontend init (Vite 8 + React)

cd ~/www/<project>/frontend
bun create vite@latest . -- --template react-ts

⚠️ Vite v8 + bun create bug — 即使 --template react-ts，v8 預設裝出嚟係 vanilla TS (src/main.ts + counter.ts)，冇 vite.config.ts，要手動 clean。詳見下「Vite 8 quirk」。

手動補：

# 用 npm install 而唔係 bun add（避 Hermes 嘅 long-lived scan）
npm install react@latest react-dom@latest @types/react @types/react-dom @vitejs/plugin-react
npm install tailwindcss@4 @tailwindcss/vite

6. Vite config + Tailwind v4

vite.config.ts：

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import tailwindcss from "@tailwindcss/vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  server: {
    port: 5173,
    proxy: { "/api": "http://localhost:3200" },
  },
})

src/index.css（Tailwind v4 唔再用 tailwind.config.js）：

@import "tailwindcss";

@theme {
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
}

tsconfig.json 必加：

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "types": ["vite/client", "node"]
  }
}

7. React Router + Pages

// src/main.tsx
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { BrowserRouter } from "react-router-dom"
import App from "./App"

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>
)
- Vite proxy `/api/*` → :3000 backend

## ⚠️ Elysia 1.2.0 d.ts broken (2026-06-05 真實撞牆)

**症狀**: 用 `new Elysia().use(jwt({...}))` 然後喺另一個 route file 用 `jwtApp.decorator.jwt.verify()` 嗰陣, Elysia d.ts 自己報錯 (`MacroContext['return']` 唔存在, etc.), 即使 `skipLibCheck: true` 都解決唔到, 仲會污染 typechain 令整個 file 出 error. **Bun runtime 唔 care d.ts, server boot 過, 但係跨 route file call decorator 嘅 runtime 可能 fail**(e.g. `/chat/*` 返 401 因為 decorator chain 喺 plugin boundary 斷咗).

**Workaround** (推薦): **唔好用 Elysia 嘅 `jwt` decorator chain 跨 file**, 用 `jose` 直接 verify:
```typescript
import { jwtVerify } from 'jose';
const secretKey = new TextEncoder().encode(process.env.JWT_SECRET ?? 'dev-secret');
async function verifyToken(authHeader: string | null): Promise<string | null> {
  if (!authHeader?.startsWith('Bearer ')) return null;
  try {
    const { payload } = await jwtVerify(authHeader.slice(7), secretKey);
    return typeof (payload as any).sub === 'string' ? (payload as any).sub : null;
  } catch { return null; }
}

Auth flow: auth.ts 用 Elysia().use(jwt({...})) 整 token (decorator 喺 same file 仲 work), 其他 route file 用 jose 驗. 兩個 source of truth 但 secret 一致就 OK.

Alternative: pin elysia@1.1.30 + @elysiajs/jwt@1.1.0 避開 d.ts bug. bun add elysia@1.1.30 @elysiajs/jwt@1.1.0 即可, 唔影響 production runtime.

衍生: `onBeforeHandle` 嘅 derive context 唔 propagate 跨 plugin (2026-06-05 crm-system Day 7 真實撞牆)

症狀: 用 Elysia({ name: 'require-permission:xxx' }).onBeforeHandle(({ userId, set }) => ...) 期望攞到 JWT plugin 注入嘅 userId (透過 derive 或 resolve 注入 context), 結果 userId 永遠係 undefined, 個 requirePermission middleware 唔 work, 所有需要 permission 嘅 endpoint 返 401.

根因: 喺 Elysia 1.2, derive() 注入嘅 context 喺 plugin boundary 唔 propagate 入 onBeforeHandle handler。onBeforeHandle 喺 scope-level plugin 入面睇唔到 parent derive 嘅 value, 但 route handler (i.e. .get('/', ...) 入面) 反而睇到。同 decorator.jwt.verify 唔同, 呢個係 context flow bug, 唔係 d.ts bug。

Workaround (推薦): 個 plugin 入面 自己 extract + verify 個 Authorization header, 唔好依賴 derive context:

// apps/api/src/middleware/rbac.ts
import { jwtVerify } from 'jose';

async function getUserIdFromRequest(request: Request): Promise<string | null> {
  const auth = request.headers.get('authorization');
  if (!auth?.startsWith('Bearer ')) return null;
  const token = auth.slice(7);
  const secret = process.env.JWT_SECRET;
  if (!secret) return null;
  try {
    const { payload } = await jwtVerify(token, new TextEncoder().encode(secret));
    if (!payload || typeof payload !== 'object') return null;
    return (payload as { sub?: string; userId?: string }).userId
      ?? (payload as { sub?: string }).sub
      ?? null;
  } catch { return null; }
}

export function requirePermission(permission: string) {
  return new Elysia({ name: `require-permission:${permission}` }).onBeforeHandle(
    { as: 'scoped' },
    async (ctx: { request: Request; set: { status?: number } }) => {
      const userId = await getUserIdFromRequest(ctx.request);
      if (!userId) { ctx.set.status = 401; return { error: 'Unauthorized' }; }
      // ... check permission via DB ...
    }
  );
}

Key points:

用 ctx.request: Request 拎 header, 唔靠 ctx.userId
jwtVerify 用 jose 直接 import, 唔好 instantiate @elysiajs/jwt 個 plugin (jwtPlugin({...}).verify 唔存在)
個 verify 同個 JWT-signing 嘅 secret 要一樣 (即 process.env.JWT_SECRET)
個 (payload as { sub, userId }).userId ?? (payload as { sub }).sub fallback 因為唔同 signing 嘅 field name

Verification (必須做): login + 揾個要 permission 嘅 endpoint 試:

# 用 execute_code 或 python3 inline 避免 Hermes `***` redact
import urllib.request, json
data = json.dumps({"email":"admin@x","password":"x"}).encode()
req = urllib.request.Request("http://localhost/api/auth/login",
  data=data, headers={"Content-Type":"application/json"})
token = json.loads(urllib.request.urlopen(req).read())["token"]
# 揾個要 user:read 嘅 endpoint 試
req = urllib.request.Request("http://localhost/api/users",
  headers={"Authorization": f"Bearer {token}"})
print(urllib.request.urlopen(req).read()[:200])
# 期望: 200 + JSON list, 唔係 401

如果 401 → 即係 getUserIdFromRequest return null, check process.env.JWT_SECRET 喺 container 內有 set, 然後試 console.error('[rbac] ...') 入 getUserIdFromRequest 每個 branch 睇邊個 trigger。

⚠️ React Query `useQuery` generic return type 撞 `never` (2026-06-05 crm-system Day 7 真實撞牆)

症狀: Backend 返 { items: T[]; total: number } 或者 bare T[] 兩種 shape (見下面「Backend response shape 不一致」section),寫 frontend:

const { data } = useQuery({
  queryKey: ['products', params],
  queryFn: () => productsApi.list({ ... }),
});
const items: Product[] = Array.isArray(data) ? data : (data?.items ?? []);

bun run build 撞:

error TS2339: Property 'items' does not exist on type 'never'.

根因: TypeScript 嘅 control flow analysis 喺 Array.isArray(data) ? data : (data?.items ?? []) 之後 collapse data 嘅 type to never 因為 useQuery 個 generic 推唔到 T 出嚟 (T = Product[] | { items, total }, strict mode 兩個交集係 never)。data?.items 喺 never 個 optional chain 返 undefined, 然後 ?? [] 返 never[], 個真實 data 嘅 union type info 已經 lost 咗。

Fix (推薦, 5 秒 fix): Explicit cast as 兩次 bypass TS inference:

const items: Product[] = Array.isArray(data)
  ? (data as Product[])
  : ((data as { items?: Product[] } | undefined)?.items ?? []);

預防 rule: 寫新 list page always explicit cast 兩次, 千祈唔好靠 TS 推 type。Takes 5 秒, 避免 build 失敗。Hermes 喺 crm-system Day 7 撞咗兩次(products.tsx + services.tsx)都係呢個 pattern,都係 as 兩次 fix 返。

⚠️ Vite production minified React throw unmount 整個 tree (2026-06-05 crm-system Day 7 真實撞牆)

症狀: Vite dev mode 個 page render 正常, bun run build 成功, Docker container 個新 image Up N seconds (healthy), 但用 browser 去個 page 個 #root element 內 innerHTML.length === 0, body 完全空白。React 19 預設 unmount 整個 tree 喺 render error,冇 fallback UI。

根因 1 (最常見): Backend 返嘅 JSON 唔 match frontend TypeScript interface。例如 backend /api/roles 返:

{ "items": [{ "id": "...", "name": "ADMIN", "isSystem": true, "_count": { "users": 1 } }] }

但 frontend interface 寫:

interface Role { id: string; name: string; permissions: string[]; }

個 page 寫 {r.permissions.length} 然後 r.permissions 係 undefined → .length throw TypeError: Cannot read properties of undefined (reading 'length') 喺 React render → unmount 整個 tree。

根因 2: Sibling subagent 改咗 backend route schema 個 shape (e.g. permissions: string[] → _count: { permissions: number }),但 frontend interface 冇跟住改 — backend + frontend 對 schema 改動冇 simultaneous。Hermes 喺 crm-system Day 7 撞過:/api/roles list 返 _count 但 /api/roles/:id 返 permissions[],frontend 要 interface union 兩個 shape。

Fix (3 個 layer,推薦全部用):

Layer 1 — Defense in depth (必須): 包個 ErrorBoundary 喺 main.tsx:

// apps/web/src/components/error-boundary.tsx
import { Component, type ReactNode } from 'react';
export class ErrorBoundary extends Component<{ children: ReactNode }, { error: Error | null }> {
  state = { error: null as Error | null };
  static getDerivedStateFromError(error: Error) { return { error }; }
  componentDidCatch(error: Error, info: { componentStack: string }) {
    console.error('UI error:', error, info.componentStack);
  }
  render() {
    if (this.state.error) {
      return (
        <div className="p-8">
          <h2 className="text-lg font-bold text-destructive">UI Error</h2>
          <pre className="text-xs mt-2 whitespace-pre-wrap">{this.state.error.message}</pre>
          <button onClick={() => this.setState({ error: null })} className="mt-4 px-3 py-1 border rounded">
            Reload
          </button>
        </div>
      );
    }
    return this.props.children;
  }
}

// apps/web/src/main.tsx
<StrictMode>
  <ErrorBoundary>
    <BrowserRouter><App /></BrowserRouter>
  </ErrorBoundary>
</StrictMode>

Layer 2 — Schema contract check: 寫個 smoke script 用 Python urllib login + GET endpoint, 將 response 嘅 keys 對比 frontend interface 預期 keys, mismatch 即係 schema drift:

import urllib.request, json
expected = {"id", "name", "permissions"}    # from frontend interface
resp = json.loads(urllib.request.urlopen(req).read())
actual = set((resp.get("items") or [resp])[0].keys()) if isinstance(resp, dict) else set(resp[0].keys())
missing = expected - actual
if missing:
    print(f"❌ API missing fields: {missing}")
    raise SystemExit(1)

Layer 3 — Defensive rendering: 個 page 寫 {r.permissions?.length ?? 0}, 唔好假設 array 一定有:

{_count?.permissions ?? 0} / {allPermissions.length} 個權限
{_count?.users !== undefined && ` · ${_count.users} 個用戶`}

Detection (production only, dev 通常 work):

docker compose ps 顯示 web container healthy
DevTools → document.getElementById('root').innerHTML 返 '' (length 0)
performance.getEntriesByType('resource').filter(r => r.name.includes('/api/X')) 確認有 fetch (唔係 fetch fail — fetch OK 但 render fail)
document.querySelector('vite-error-overlay') 返 null (production 冇 Vite overlay)

Verification (必須做, dev mode 唔夠):

docker compose build web --no-cache
docker compose up -d web
# Browser console:
performance.getEntriesByType('resource').filter(r => r.name.includes('/api/roles')).map(r => ({status: r.responseStatus}))
# Expected: 200 (backend OK 但 frontend 仍 unmount 都返 200)
document.getElementById('root').children.length
# Expected: 1+ (如果係 0 = React unmount = runtime render error)

⚠️ Docker Compose `up -d --build` cache layers 不重 build source code (2026-06-05 crm-system Day 7 真實撞牆)

症狀: 改咗 apps/web/src/pages/roles.tsx 然後 docker compose up -d --build, 個 build log 全部 #N CACHED, 個 image 根本冇重新 build, 個新 source code 冇 deploy 出嚟。Container 個 Up 5 minutes (healthy) 仲係舊 image。User 訪問個 page 見唔到新功能,以為你冇做。Hermes 喺 crm-system Day 7 撞過一次 — --no-cache 之後個 bundle hash 由 index-BR-TeQsV.js 變 index-ChsB1GOw.js 證明真係新咗。

根因: Docker BuildKit cache layers by 個 file fingerprint hash。當 Dockerfile 唔 COPY 你改咗嘅 file path (e.g. COPY apps/web .) 或者 COPY path 喺 layer 下面但上面 layer 已經 cache, BuildKit 會 reuse cache 唔 re-read filesystem。

Fix 1 (推薦, 萬用): 改 source 改完之後 always force --no-cache:

docker compose build web --no-cache
docker compose up -d web

--no-cache 會 skip 所有 cache layers, 完整重 build, 確定新 source 入 image。15-30 秒 penalty 但保證啱。

Fix 2 (Dockerfile fix, 預防性): 喺 Dockerfile 開頭加個 ARG CACHEBUST=1 強迫 invalidate cache:

FROM oven/bun:1.2 AS builder
ARG CACHEBUST=1   # change this value to force cache invalidation
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install
COPY . .
RUN bun run build

docker compose build --build-arg CACHEBUST=$(date +%s) web

Detection 撞牆嘅方法 (必須每次 build 後做):

# 1. Check 個 image creation time
docker images <project>-web --format "{{.ID}} {{.CreatedSince}}"
# Expected: "Less than a minute ago" (唔係 "5 minutes ago" / "2 hours ago")

# 2. Check 個 bundle hash
docker exec crm-web cat /usr/share/nginx/html/assets/index-*.js | head -c 200
# Host 嗰度 curl 返出嚟對比
curl -s http://localhost/ | grep -oE 'index-[A-Za-z0-9_-]+\.js'
# 兩個 hash 要 match, 唔 match = nginx serve 緊舊 image

# 3. Force rebuild 一個 dummy file
touch apps/web/src/.force-rebuild
docker compose build web   # 應該見到 source COPY stage 唔係 CACHED
rm apps/web/src/.force-rebuild

Elysia backend 都有同樣問題, 一樣用 --no-cache fix。

⚠️ Bun `export *` 唔可靠 re-export named consts 跨 module (2026-06-05 crm-system Day 7 真實撞牆)

症狀: packages/shared/src/permissions.ts 寫 export const PERMISSIONS = { 'user:read': '...', ... }, packages/shared/src/index.ts 寫 export * from './permissions', 然後 apps/api/src/routes/roles.ts 用 import { ALL_PERMISSIONS } from '@crm/shared', 入面 reference PERMISSIONS 拎 keys。Boot 時 crash:

SyntaxError: Export named 'ALL_PERMISSIONS' not found in module '/app/packages/shared/src/index.ts'.
ReferenceError: PERMISSIONS is not defined
      at /app/packages/shared/src/index.ts:3:28

根因: Bun runtime (1.2.x 確認) 對 export * from './module' 嘅 re-export named const 處理有 bug: index file 自己 access 個 re-exported const 嗰陣 resolve 唔到 (variable 係 "not defined"), 即使 const 真係喺子 module named export。TypeScript / node 唔撞, 純 Bun runtime 撞。

Workaround (推薦, 5 秒 fix): 個 index file explicitly import 個 const, 然後 export const 重新 export:

// packages/shared/src/index.ts
import { PERMISSIONS } from './permissions';
export * from './permissions';               // keep re-export 俾其他 consumers
export const ALL_PERMISSIONS: readonly string[] = Object.freeze(
  Object.keys(PERMISSIONS)
);

咁 ALL_PERMISSIONS 喺 index file 範圍就 explicit defined, Bun runtime resolve 到。@crm/shared consumer 一樣用 import { ALL_PERMISSIONS } from '@crm/shared'。

Alternative (更穩但 verbose): 完全唔用 export *, 改用 explicit named export 喺每個 consumer file:

// ❌ 唔好
export * from './permissions';

// ✅ 改
export { PERMISSIONS, USER_ROLES, type Permission, type UserRole } from './permissions';

Detection 訊號:

Boot log 出 Export named 'X' not found 但個 const 明明喺子 module 寫咗 export const X
或者 ReferenceError: X is not defined 喺個 re-export 嘅 index file 自己 (index.ts:3:28 之類)
bun run src/index.ts 撞, 但 node src/index.ts / tsx src/index.ts 唔撞

Related: 撞呢個 trap 通常代表你個 monorepo 想用 single source of truth (packages/shared) 收埋 enums + 派生 const, 然後 consumer import。設計 OK, 只係 Bun runtime 限制。Workaround 唔影響 source-of-truth pattern。

⚠️ Prisma client model names 唔 export (2026-06-05)

症狀: import { PipelineStage } from '@prisma/client' → runtime SyntaxError: export 'PipelineStage' not found, 因為 Prisma client 只 export enums, 唔 export model names. Model 名喺 @prisma/client 內部用嚟 typeof, 唔係 named export.

Fix: Re-export packages/db/src/index.ts 入面只列 enums:

export { UserRole, QuotationStatus, DealStatus, /* etc */ } from '@prisma/client';
// ❌ 唔好: export { PipelineStage } from '@prisma/client'  // runtime crash
// ✅ 改用: prisma.pipelineStage.findMany() 或者 type Prisma.PipelineStage

⚠️ Tailwind v3 vs v4 — shadcn-style setup 仍要 v3 (2026-06-05)

症狀: 跟 bun create vite@latest 出嘅 react-ts template 預設 Tailwind v4 (@tailwindcss/vite + @theme CSS directive). 但 shadcn/ui 嘅 class-variance-authority pattern 用 tailwind.config.js 嘅 theme.extend.colors.primary.DEFAULT 引用, v4 嘅 @theme 唔 work, 顏色 fallback 去 border-border 然後冇顏色。

Fix: For shadcn/ui-style projects, 用 Tailwind v3:

bun add -d tailwindcss@3 postcss autoprefixer

加 postcss.config.js, tailwind.config.js (有 content + theme.extend), index.css 用 @tailwind base/components/utilities. 唔好用 v4 嘅 @import "tailwindcss" syntax.

⚠️ shadcn-style token 唔可以漏 — `popover` / `card-foreground` / `destructive-foreground` 撞 (2026-06-06 crm-system 真實撞牆)

症狀: 用咗 shadcn-style component (e.g. <Dialog>, combobox dropdown, popover, command palette) 之後, 個 panel / dropdown / dialog 個 background 完全透明, 後面嘅 table content 透出嚟 (e.g. 個 quotation builder 嘅 autocomplete 透底見到後面 備註 textarea + Subtotal 行)。冇 console error, DevTools 個 <div class="bg-popover"> 存在, 但 computed style 冇 background-color。

根因: cva 寫 bg-popover / text-popover-foreground / border-input / bg-card 等等 utility class, 期望佢哋喺 tailwind.config.js 嘅 theme.extend.colors 有對應 token。如果個 config 漏咗個 token, Tailwind 喺 build / JIT 階段 silently omit 個 class, 結果個 element 冇 background。

crm-system 真實情況 (2026-06-06):

tailwind.config.js 嘅 theme.extend.colors 有: border, input, ring, background, foreground, primary, secondary, muted, accent, destructive, card
冇: popover, popover-foreground, card-foreground, destructive-foreground
quotation-builder.tsx 嘅 ProductAutocomplete / ServiceAutocomplete panel 用 bg-popover → render 出嚟係透明 → David 報 bug 「autocomplete 透底」

Fix — 對齊 shadcn 完整 token set: tailwind.config.js 嘅 colors 要齊以下 shadcn-ui HSL 變量 (crm-system 已經用緊 hsl() 而非 oklch(), 唔好混):

// tailwind.config.js — theme.extend.colors
colors: {
  border: 'hsl(214.3 31.8% 91.4%)',
  input: 'hsl(214.3 31.8% 91.4%)',
  ring: 'hsl(222.2 84% 4.9%)',
  background: 'hsl(0 0% 100%)',
  foreground: 'hsl(222.2 84% 4.9%)',
  primary: {
    DEFAULT: 'hsl(222.2 47.4% 11.2%)',
    foreground: 'hsl(210 40% 98%)',
  },
  secondary: {
    DEFAULT: 'hsl(210 40% 96.1%)',
    foreground: 'hsl(222.2 47.4% 11.2%)',
  },
  destructive: {
    DEFAULT: 'hsl(0 84.2% 60.2%)',
    foreground: 'hsl(210 40% 98%)',
  },
  muted: {
    DEFAULT: 'hsl(210 40% 96.1%)',
    foreground: 'hsl(215.4 16.3% 46.9%)',
  },
  accent: {
    DEFAULT: 'hsl(210 40% 96.1%)',
    foreground: 'hsl(222.2 47.4% 11.2%)',
  },
  popover: {
    DEFAULT: 'hsl(0 0% 100%)',
    foreground: 'hsl(222.2 84% 4.9%)',
  },
  card: {
    DEFAULT: 'hsl(0 0% 100%)',
    foreground: 'hsl(222.2 84% 4.9%)',
  },
},

Quick fix (in-place component): 如果只係 1-2 個 component 撞, 唔想改全局 config, 直接喺 element 寫 bg-white border border-border 代替 bg-popover border, 視覺上同 (因為 popover: DEFAULT: 'hsl(0 0% 100%)' = 白色):

// ❌ 唔好 (如果 popover token 冇 define)
<div className="bg-popover border rounded shadow-lg">…</div>

// ✅ Quick fix 1 (component-local, 唔改 config)
<div className="bg-white border border-border rounded shadow-lg">…</div>

// ✅ Proper fix 2 (config-level, 一改搞掂哂)

跟 tailwind.config.js 嘅 border 已經有, 所以 border utility 仍 emit 1px border-color: hsl(214.3 31.8% 91.4%), 唔使改。但 bg-popover 冇 token 會 silently omit。border 配 bg-popover 唔 work 因為個 panel 仍然透明, 只係個 outline 顯示到。

Detection (撞牆必做):

computed style 確認:

// 喺 browser DevTools console
const el = document.querySelector('[class*="bg-popover"]');
window.getComputedStyle(el).backgroundColor
// Expected: "rgb(255, 255, 255)"  ← transparent 撞 "rgba(0, 0, 0, 0)"

grep 全 codebase 嘅 missing token:

rg "bg-(popover|card-foreground|popover-foreground|destructive-foreground|muted-foreground)" apps/web/src
# 對比 tailwind.config.js 嘅 colors key

Tailwind JIT 唔報錯: 佢 silently omit 唔存在嘅 utility class, 所以 bun run build 唔會 fail。必須用 browser 真實視覺確認, 唔可以信 build pass。

Pre-emptive rule (新 shadcn-style 項目): 跟 npx shadcn@latest init 出嘅 tailwind.config.js 唔好 hand-edit 走任何 token。或者直接用 npx shadcn@latest add <component> 加新 component, 佢會自動 inject 對應 cn() + class 變量, 唔會撞呢個 trap。Hermes hand-written tailwind.config.js 易漏 token — crm-system 撞咗兩次 (Day 9 Region bug + 今日 popover bug)。

Quick fix 路徑之後必須 grep 全部 other occurrences (2026-06-06 crm-system 真實撞牆)

情境: David 揀咗 quick fix(用 bg-white border border-border 改 component 入面)而唔係修 config(加 popover token)。fix 咗 quotation-builder.tsx 之後我主動 flag: bg-popover token 漏咗會 silently 影響成個 app 嘅所有 popover / dropdown, 其他位(admin role picker、deals stage dropdown 等)可能撞同一個 bug。

Action — Quick fix 之後必須跑:

# 1. grep 全 codebase 嘅 utility class 對比 tailwind config 嘅 colors key
rg "bg-(popover|card|accent|secondary|muted|primary|secondary-foreground|popover-foreground|card-foreground|muted-foreground|accent-foreground|destructive-foreground)" apps/web/src

# 2. 對比 tailwind.config.js theme.extend.colors 嘅 key
node -e "console.log(Object.keys(require('./tailwind.config.js').theme.extend.colors).join('\n'))"

# 3. 差集 = missing token, 逐個 confirm 要 quick-fix 定要改 config

Hermes safety net — 將呢個 grep 加到 dev verify:

# 喺 ~/www/<project>/scripts/check-tailwind-tokens.sh (可重 run)
#!/bin/bash
set -e
cd ~/www/<project>
CONFIG_KEYS=$(node -e "console.log(Object.keys(require('./apps/web/tailwind.config.js').theme.extend.colors).join('\n'))" | sort)
USED=$(rg -oN "bg-(popover|card|accent|secondary|muted|primary|secondary-foreground|popover-foreground|card-foreground|muted-foreground|accent-foreground|destructive-foreground)" apps/web/src | sed 's/.*\(bg-[a-z-]*\).*/\1/' | sort -u)
MISSING=$(comm -23 <(echo "$USED") <(echo "$CONFIG_KEYS" | sed 's/^/bg-/'))
if [ -n "$MISSING" ]; then
  echo "❌ Missing tailwind tokens: $MISSING"
  exit 1
fi

Why 兩個 patch path 都要 grep:

Path A (改 config): 一處改搞掂哂, 之後 token 對齊 shadcn 標準
Path B (改 component): 只 fix 一個, 但 codebase 其他位用同一個 bg-popover 仍然會 silently transparent。只 fix 1 個 = David 將來會撞第 2、第 3 次同一個 bug。

⚠️ LSP diagnostics stale after rapid patches — `docker compose build` 是 source of truth (2026-06-06 crm-system 真實撞牆)

症狀: 改咗一個 file 嘅 prop signature (e.g. 將 CreateCompanyDialog 改名 CompanyFormDialog + 加 mode + 加 defaultName + 加 regions props),LSP 立刻報舊 error 出現喺 caller file (company-autocomplete.tsx 嗰個 import)。但我每改完一個 patch 之後,下個 patch LSP 仍報之前嘅 error (line number 都唔對)。我 chase 咗 LSP 報嘅 3 個所謂 issue 改多次 code,搞到 file 越改越混亂,最後先發現 LSP 根本係 stale,所有 issue 已經被我 patch fix 咗。真正嘅 source of truth 係 docker compose build web 嘅 exit code。

根因 (3 個 stack 同時撞):

LSP cache: Hermes 嘅 LSP daemon 對連續 patch edit 嘅 cache invalidation 唔可靠。同 session 內改咗 N 個 patch,LSP 仍報 N 步前嘅 state
LSP 唔跨 file analyse TypeScript 個 exact type narrowing:對於 c => implicit any、status: string cast、prop missing 等 issue,LSP 行 type-check 嘅 view 唔等於 tsc --noEmit 嘅 view
@ts-nocheck 喺部分 file 開咗:有啲 route file 用 // @ts-nocheck 避 Elysia 1.2 d.ts noise(見上面),LSP 對呢類 file 完全唔 typecheck,但 docker compose build 仍會 run tsc 對其他 file 報錯

Detection 訊號 (邊個時候 LSP 唔可信):

報錯 line number 對唔上 file 內容 (e.g. LSP 報 line 355 但 file 已經 250 行)
報錯話某 prop 唔存在,但我頭先 patch 明明加咗
報錯話 c: (parameter) c: any implicit,但我有 typed 過
報錯話 status: string assignable error,但我已經用 as Company['status'] cast

正確 workflow (推薦):

# 改完 frontend file 永遠跑呢個 — 唔好睇 LSP
cd ~/www/<project>
docker compose build web 2>&1 | grep -E 'error TS|failed|exit code|DONE' | head -10
# Expected: 0 個 error TS line + 1 個 "DONE" 喺 #N 階段
# If 有 error TS: 嗰個係真正嘅 type error, 要 fix
# If 冇 error TS: LSP 嘅 noise 全部 ignore, 繼續 commit

Time budget:

docker compose build web 第一次 (cold): ~90 秒
第二次之後 (cache hit): ~20-30 秒
比起 chase LSP 假報錯再 fix code 再 build 嘅 loop,直接 docker compose build 一早做 5 倍快

Anti-pattern (我犯過):

# ❌ 唔好
patch file
見 LSP 報 error
patch 又改
見 LSP 仍報舊 error
patch 又改再改
... 3-4 個 patch 之後先 build ...
最後 build pass, 但 file 已經改到冇得救要 reset

Correct pattern:

# ✅ 好
patch file
直接 docker compose build web
睇 build output
有 error 就 patch 嗰個真實 issue
冇 error 就繼續 — 唔好睇 LSP

Generic rule (套用成個 stack):

Backend: docker compose build api 係 source of truth (LSP 對 Elysia route 嘅 noise 仲多,因為 @ts-nocheck + d.ts bug)
Frontend: docker compose build web 係 source of truth (LSP 對 React 嘅 as cast / generic 推唔到 type 嘅情況仲多)

Related: 同「Docker Compose up -d --build cache layers 不重 build source code」唔同 — 呢個 pitfall 係 LSP 報錯假陽性,嗰個 pitfall 係 cache 命中冇 re-build。兩者都係話 docker build 必須 explicit 跑而唔好信 implicit 嘅 watch / LSP 通知。

⚠️ `bun.lock` 不被 npm / snyk 認 — 紅線 18 CVE 掃描盲點 (2026-06-07 crm-system code review 真實撞牆)

症狀: 跑 npm audit 喺一個 bun-managed monorepo (bun.lock 而唔係 package-lock.json) 撞:

npm error code ENOLOCK
npm error audit This command requires an existing lockfile.
npm error audit Try creating one first with: npm i --package-lock-only

根因: bun.lock 係 bun-native binary format (text-based, 但 npm/snyk 唔識 parse)。package-lock.json 同 bun.lock 互相唔識。David 嘅紅線 18 寫明「Critical/High CVE (由 npm audit / snyk 掃到) 必須 0 才可 merge」 — 如果個 project 用 bun, 紅線 18 既有的 toolchain 直接做唔到。

Fix (推薦, 30 秒): 用 bun audit 而唔係 npm audit:

# ❌ 唔好
npm audit --json
# → ENOLOCK (bun.lock not recognized)

# ✅ 好 (bun 1.2+ 內建)
bun audit
# → 解析 bun.lock + 對 npm registry check 已知 CVE

如果 bun audit 都 fail (bun 版本太舊): Generate 一個 npm-compatible lockfile 一次過, 之後 audit 用 npm:

# 在 root 一次過
npm i --package-lock-only   # 根據現有 package.json + bun.lock generate package-lock.json
npm audit --json > /tmp/cve.json
# 然後 commit 走 package-lock.json 都可以 (但會同 bun.lock drift)

Production CI 必加 step (ship gate):

# 喺 CI YAML (.github/workflows/ci.yml) 加
- name: CVE scan
  run: |
    bun audit --json > /tmp/audit.json
    HIGH=$(python3 -c "import json; d=json.load(open('/tmp/audit.json')); print(d.get('metadata',{}).get('vulnerabilities',{}).get('high',0))")
    CRIT=$(python3 -c "import json; d=json.load(open('/tmp/audit.json')); print(d.get('metadata',{}).get('vulnerabilities',{}).get('critical',0))")
    if [ "$HIGH" -gt 0 ] || [ "$CRIT" -gt 0 ]; then
      echo "❌ Critical/High CVE > 0, blocking merge (紅線 18)"
      exit 1
    fi

Lockfile 可信度 pitfall (related): bunfig.toml 嘅 [install] exact = false 默認 = 用 ^5.6.3 caret range, build 唔 reproducible, 每個 developer 落地拎到唔同 patch version:

# bunfig.toml
[install]
exact = true    # 改 true, lockfile 死鎖 exact version

Detection 撞牆嘅方法 (ship-readiness review 必做):

# 1. 確認有 lockfile
ls -la bun.lock package-lock.json 2>/dev/null
# Expected: 至少 bun.lock (bun project) 或 package-lock.json (npm project)

# 2. 試跑 audit
timeout 30 bun audit 2>&1 | head -20
# Expected: 有 vulnerability table 列出
# 如果 error: 上面 fix 步驟

# 3. 確認 exact mode
grep "exact" bunfig.toml
# Expected: exact = true

⚠️ RBAC coverage matrix 1-liner audit — 1 個 grep 揭 14 route 嘅 access control gap (2026-06-07 crm-system 真實撞牆)

症狀: Code review 時想 check 全部 14 個 route file 嘅 RBAC coverage, 人工逐 file 開 → 太慢, 易 miss。需要 1 個 1-liner reveal 邊個 route 公開, 邊個有 auth, 邊個有 permission check。

Fix (1-liner, 推薦 for 任何 RBAC-driven Elysia / Express / FastAPI project):

# 對齊 pattern: <route file> 用 authContext 幾多次 + requirePermission 幾多次
cd ~/www/<project>
for f in apps/api/src/routes/*.ts; do
  name=$(basename "$f" .ts)
  ac=$(grep -c "authContext" "$f" 2>/dev/null)
  perm=$(grep -c "requirePermission" "$f" 2>/dev/null)
  printf "%-20s authContext=%-3d requirePerm=%d\n" "$name" "$ac" "$perm"
done | sort -k2 -t= -n
# ↑ sort by authContext count ascending = 公開 routes 浮上面

Expected output (crm-system 2026-06-07 真實數字):

ai-config            authContext=0  requirePerm=1   ← 0 auth 但有 perm: 內部 RBAC OK 但 anonymous 撞 401 = 設計 OK
chat                 authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
company              authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
contact              authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
deal                 authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
settings             authContext=0  requirePerm=2   ← perm 蓋住, 但 anonymous 撞 401 (OK)
audit                authContext=2  requirePerm=2   ← ✅
man-day-role         authContext=4  requirePerm=3   ← ✅
roles                authContext=2  requirePerm=2   ← ✅

Generic rule (套用全部 backend stack):

Elysia: authContext / requirePermission (呢個 skill 嘅 pattern)
Express: requireAuth / requireRole / requirePermission
FastAPI: Depends(get_current_user) / Depends(require_role)
NestJS: @UseGuards(AuthGuard) / @Roles(...) decorator

換 pattern name 即可, framework 唔重要。

Common hit 真實 cases (撞過嘅):

POST /auth/register 冇 requirePermission — 公開註冊 + 可以 self-select role: 'ADMIN' = 公開 internet 變 admin。Fix: 加 requirePermission('user:create') + body schema 刪 role field (新 user 預設 SALES, admin 自己 promote via PATCH /users)
List endpoint 公開 (e.g. GET /companies) — 公開讀 = PII 漏 (email, phone, credit limit)。Fix: 加 requirePermission('company:read')
AI write tool 公開 — /chat/send 觸發 prisma.company.create 以 system actor 寫 = silent DB write without attribution。Fix: 加 requirePermission('chat:use') + audit log 入面 actorId 一定要有
Status / health endpoint RBAC 不一致 — /api/ai/config/status 公開 = 偵察 admin 環境狀態。Fix: 一律 requirePermission('xxx:read') 蓋住, status 都要

Related pattern (RBAC permission drift): 三個 source of truth 要對齊:

packages/shared/src/permissions.ts PERMISSIONS map (static, system roles)
apps/api/src/middleware/rbac.ts requirePermission('xxx') 字符串 (hard-coded in route files)
DB RolePermission table (runtime state, custom roles)

加新 permission 嘅流程: (1) 改 permissions.ts 加 entry → (2) 改 routes 加 requirePermission('xxx') → (3) DB seed RolePermission 對應 row。3 處唔 link 易 drift。E2E test 兜底:

// 跑一次: 列舉 permissions.ts 嘅 keys, grep requirePermission(, 確認每個 key 至少 1 個 route 用
test('permission coverage', () => {
  const declared = new Set(Object.keys(PERMISSIONS));
  const used = new Set<string>();
  for (const f of glob.sync('apps/api/src/routes/*.ts')) {
    for (const m of fs.readFileSync(f, 'utf8').matchAll(/requirePermission\(['"]([^'"]+)['"]\)/g)) {
      used.add(m[1]);
    }
  }
  const unused = [...declared].filter(p => !used.has(p));
  expect(unused).toEqual([]);  // 0 unused perms
});

⚠️ `tsc --noEmit` 報 30+ silent type errors 但 runtime OK — typecheck 唔可以靠 build 兜底 (2026-06-07 crm-system 真實撞牆)

症狀 (同 LSP stale pitfall 唔同 — LSP 假報 vs tsc 真報都被忽略): apps/api/src/routes/*.ts 開咗 // @ts-nocheck 喺 rbac.ts + quotation.ts, 但其餘 6+ 個 route file 冇 @ts-nocheck 但係 runtime work。點解 typecheck 撞但 build pass?

根因 (Elysia + bun 雙重 source-of-truth drift):

Elysia 1.2 d.ts 同 TypeScript 5.x 嘅 type inference 衝突(see 上面「Elysia 1.2 d.ts broken」)— set.status typed 做 number | "Unauthorized" | ... literal union, 好多 cast 寫得唔準
prisma.aiConfig 唔存在 but code 用緊 — Prisma client 唔 export 該 model (見下面「Prisma client model names 唔 export」)
as never cast 喺 handler 內部太多 — body validation 通過後 body 嘅 type 係 unknown, cast 做 as never 漏 type
Bun runtime 唔 typecheck (dev mode bun run src/index.ts 唔 invoke tsc) — runtime 唔 care
Dockerfile 嘅 bun --env-file=... src/index.ts production entry 仍然唔 typecheck
Elysia 1.2 type check chain 對多個 .use() plugin 嘅 context propagation 唔 reliable — derive 出嘅 userId 個 type 喺 route handler 入面係 string | null, 但喺 onBeforeHandle plugin boundary 變 unknown

撞牆真實例子 (crm-system 2026-06-07):

src/lib/context.ts(9,21): error TS2339: Property 'jwt' does not exist on type '...'.
src/routes/ai-config.ts(57,30): error TS2339: Property 'aiConfig' does not exist on type 'PrismaClient<...>'.
src/routes/ai-config.ts(199,9): error TS2322: Type '"AI_CONFIG_UPDATED"' is not assignable to type 'AuditAction'.
src/routes/contact.ts(33,50): error TS2353: ...'activities' does not exist in type 'ContactInclude<DefaultArgs>'.
src/routes/deal.ts(152,7): error TS2322: Type '"DEAL_STAGE_CHANGED"' is not assignable to type 'AuditAction'.
+ 25+ more

Risk:

prisma.aiConfig 唔 export 但 code 用緊 = prod 第一次 hit 嗰個 endpoint 一定 500 (Prisma client 識唔到 model)
'DEAL_STAGE_CHANGED' as AuditAction 唔 cast-safe = audit log 寫入失敗 silently
as never body cast = 可以 inject 任意 fields 到 Prisma create (雖然 Prisma schema filter 唔存在 column, 但 passwordHash / isActive 呢類 sensitive field 風險)

Fix (3 個 step, ship gate 必做):

# 1. 在 root 加 unified typecheck (唔好靠個別 package.json 嘅 typecheck script)
cd ~/www/<project>
cat > scripts/typecheck-all.sh <<'EOF'
#!/bin/bash
set -e
echo "=== apps/api ==="
cd apps/api && bunx tsc --noEmit --skipLibCheck
cd ../..
echo "=== apps/web ==="
cd apps/web && bunx tsc --noEmit --skipLibCheck
cd ../..
echo "=== packages/db ==="
cd packages/db && bunx tsc --noEmit --skipLibCheck
EOF
chmod +x scripts/typecheck-all.sh

# 2. 在 CI 必跑 (唔可以 skip)
# .github/workflows/ci.yml:
# - name: TypeScript check
#   run: ./scripts/typecheck-all.sh
# (冇 typecheck pass = 唔 merge)

# 3. Fix 撞到嘅 error — 唔可以加 @ts-nocheck 蓋住
#   - 重新 generate prisma client: cd packages/db && bunx prisma generate
#   - AuditAction / ItemType 等 enum 加返入 schema
#   - Casts 用 'as Company' 而唔係 'as never' (cast 對 schema 唔等於 bypass validation)
#   - remove 所有 @ts-nocheck (Dockerfile `bun run` 跳 typecheck, 唔代表可以 silent type drift)

Critical: Dockerfile 唔可以加 typecheck step 入 build:

# ❌ 唔好
RUN bun run typecheck   # 加咗 build 會 hang 在 ts error, 個 image 永遠 build 唔到
                        # 即使 type errors 應該 fix, build 唔可以 fail 因為 type error
                        # (本地 fix 之後先 push)
#
# ✅ 好
# typecheck 留喺 CI stage + pre-commit hook, Dockerfile 維持 `bun install + bun run`

Detection 工具 (code review 必跑):

# 1. 數 typecheck errors
cd ~/www/<project> && timeout 60 bunx tsc --noEmit --skipLibCheck 2>&1 | grep -c "error TS"
# Expected: 0 (ship gate 必過)
# 如果 > 0: 紅線 16 嘅 test coverage fail + type drift blind spot

# 2. 數 @ts-nocheck 數量
rg -l "@ts-nocheck" apps/ packages/
# Expected: 0 (一係 remove 一係 真嘅 disable 嘅 file 加理由 comment)
# 如果 > 0: 全部逐個 review, 確認係 Elysia 1.2 d.ts 真正 broken 而唔係偷懶

# 3. 數 'as never' cast 數量
rg -c "as never" apps/api/src/ | awk -F: '{sum+=$2} END {print sum}'
# Expected: 0 (cast 應該 'as ConcreteType')
# 如果 > 5: code review 必 grep 全部 location 改 'as ConcreteType' 對應 Prisma model

Related pitfall (LSP stale): 上面「LSP diagnostics stale after rapid patches」section 講 LSP 假報錯。呢個 pitfall 講 tsc 真報但被忽略。兩個都會誤導 developer 以為 type safety OK — 唯一 source of truth 係 CI 跑嘅 tsc --noEmit exit code 0。

⚠️ Self-register-as-admin trap — `POST /auth/register` 公開 + role 喺 body (2026-06-07 crm-system 真實撞牆)

症狀: RBAC 系統有 ADMIN / SALES / VIEWER 三個 role 喺 DB, 有 requirePermission('user:create') middleware. 但 register endpoint 寫:

// ❌ 唔好 — RBAC 完整但 register endpoint 公開 self-service admin
.post('/register', async ({ body, set }) => {
  const { email, password, name, role } = body as {  // ← role 喺 body
    email: string; password: string; name: string;
    role?: 'ADMIN' | 'SALES' | 'VIEWER';
  };
  // ... 直接 prisma.user.create({ data: { ..., role: role ?? 'SALES' } })
}, {
  body: t.Object({
    email: t.String({ format: 'email' }),
    password: t.String({ minLength: 8 }),
    name: t.String({ minLength: 1 }),
    role: t.Optional(t.Union([         // ← 接受 role 喺 body
      t.Literal('ADMIN'),
      t.Literal('SALES'),
      t.Literal('VIEWER'),
    ])),
  }),
})

Risk (公開 internet + body role = 公開 internet 變 admin):

任何人用 curl -X POST /auth/register -d '{"email":"a@b.c","password":"xxx","name":"Hacker","role":"ADMIN"}' → 攞到 ADMIN token
如果有 seed 預設 david@crm.local / admin123 即係 hacker 直接用 david@crm.local 重置密碼 / 喺自己個 account 升級

Fix (推薦, 5 分鐘):

// ✅ 好
import { authContext } from '../lib/context';
import { requirePermission } from '../middleware/rbac';

.post('/register', async ({ body, set }) => {
  const { email, password, name } = body as {  // ← role 唔再喺 body
    email: string; password: string; name: string;
  };
  // ... prisma.user.create({ data: { email, name, passwordHash, role: 'SALES' } })
  // 預設 SALES, admin 自己用 PATCH /users/:id 升級
}, {
  body: t.Object({
    email: t.String({ format: 'email' }),
    password: t.String({ minLength: 8 }),
    name: t.String({ minLength: 1 }),
    // ← 唔再接受 role
  }),
})
// 同時 add: 真正 invite flow 應該 admin 用 PATCH /users/:id invite

// Alternative 1 (use the existing authContext + requirePermission 蓋住)
.use(authContext)
.use(requirePermission('user:create'))   // ← 只有 admin 可以 create user

// Alternative 2 (disable self-service,只 invite via admin UI)
// 條 route 直接 disable, body validation 唔再 register endpoint

Variant 撞牆 — status endpoint 唔 gated:

// ❌ 唔好
.get('/ai/config/status', () => {
  return prisma.aiConfig.findUnique({ where: { id: 1 }, select: { configured: true, model: true } });
})
// 公開偵察 admin 環境狀態 = recon 階段有用 info

// ✅ 好
.use(authContext)
.use(requirePermission('ai-config:read'))
.get('/ai/config/status', ...)

Detection (code review 1-liner):

# 1. Check register / signup endpoint 有冇 permission
rg -A 1 "post\(['\"]/?(auth/)?(register|signup)" apps/api/src/
# 期望: 見到 .use(requirePermission(...)) 喺 register handler 之前
# 如果冇: 即係 self-service,加 fix

# 2. Check 全部 body schema 接受 role 嘅地方
rg "t\.(Union|Literal).*(ADMIN)" apps/api/src/
# 期望: 0 個 (role 唔應該喺 public-facing body schema)

# 3. Check 全部 GET endpoint 嘅 status / config 探測
rg "get\(['\"]?/.*(status|health|config)" apps/api/src/
# 期望: 全部都有 .use(requirePermission) 喺之前 (除咗真正 public health check)

Generic rule (套用所有 SaaS 項目):

Self-service signup → role 永遠 default 'USER' / 'MEMBER' / 'CUSTOMER', 唔可以 self-select 'ADMIN'
Admin invite flow → admin 自己 PATCH /users/:id 升級
任何 GET /status /config endpoint → 一律 permission-gated, status 都要

⚠️ Subagent 600s/63-call timeout 撞 long refactor 任務 (2026-06-06 crm-system Day 11 真實撞牆)

症狀: 派 subagent 跑 5-phase 嘅 multi-file refactor(themes token fix + 502 修 + 抽 2 個共用 component + 補 fields + Deal 編輯 + 最終 typecheck), 每個 phase 都要讀 source + patch + 自己驗 typecheck。Subagent 跑 600s timeout 撞 63 個 API call, 卡喺某個 phase(typecheck 連跑多次)唔 return。api_calls: 63, duration_seconds: 600.17, exit_reason: timeout。

根因:

bun run typecheck 喺 Elysia strict TS 5 + 大量 as never cast 嘅 project 入面,第一次 pass 通常撞 3-5 個 error,subagent 自己 fix 之後再 typecheck,loop。
每個 typecheck pass 要 ~30 秒(subagent 連 import 5-6 個 files + tsc 全行)。
Long refactor 加埋 typecheck loop + multiple file 嘅 read_file verification → 600s 唔夠用。

接管 pattern (推薦, 2026-06-06 crm-system Day 11 用咗):

# 1. 派 subagent,設定期望 subagent 跑 ~5 phase
delegate_task(goal="...", context="...", toolsets=['terminal', 'file', 'skills'])

# 2. 收到 timeout 唔好報錯
# 3. 自己 check subagent 已經 create 咗咩 file
search_files(pattern="*.tsx", path="apps/web/src/components", target="files")

# 4. 對比 plan 入面嘅 expected file list,睇邊個 phase 未做
# 5. 直接 read 嗰啲 file 確認 partial progress 嘅 quality

# 6. 接手未做嘅 phase (parent 自己跑, 或者再 delegate 細啲嘅範圍)

# 7. 最終 typecheck 一齊跑 (parent 跑, 唔好 subagent 跑)
terminal(command="cd ~/www/crm-system/apps/web && bun run typecheck")

Plan subagent 嘅 5 個 control 點:

scope 細啲: 唔好一個 goal 包 5 phase。每 phase 一個 subagent。Day 11 嗰個 subagent 撞牆因為 5 phase 太闊。
明確講 typecheck 喺 parent 跑: 個 subagent 只需要做 4 件事 — 改 file, 改 import, 改 type signature。唔需要 typecheck 100% pass。Subagent 改 type signature 至 TS compile 到就 OK,parent 接手跑 typecheck + fix 邊度 miss。
Checkpoint 寫低: Subagent 應該每改完 1-2 個 file 寫低 "Phase N done, file X modified, file Y created"。咁 timeout 之後 parent 可以 grep checkpoint 知住乜。
Avoid 在 subagent 度跑 long command: 唔好喺 subagent 入面 bun run build / vite build (5+ 分鐘),改用 tsc --noEmit 30 秒。
Accept partial completion: Subagent 個 summary 報 "4/5 phases done, phase 5 撞 hit type error X", parent 接手 fix X 就好。唔好 reject partial 然後再 delegate 全 work。

Plan size 參考 (Day 11 嗰個嗰個跑咗 63 個 call, 撞 timeout):

1 phase (1 file major edit) → ~10-15 calls, 5 min OK
3 phases (3 files + 1 verify) → ~30 calls, 15 min borderline OK
5 phases (5+ files + multi-step verify) → >50 calls, 撞 timeout 高。要 split
8+ phases → 必須 split,絕對唔好一個 goal 包

Generic rule: Subagent 用法應該係 1 task = 1 clear deliverable (改 1 file, 跑 1 個 verify script, etc.), 而唔係 1 task = 1 refactor project。Long refactor 應該由 parent 拆 phase 派多個 subagent, 每次小範圍。

⚠️ Hermes redact `***` 整死 shell-based JWT tests (2026-06-05)

症狀: 寫 TOKEN=*** ... /login | sed -n 's/.*"token": "$[^"]*$".*/\1/p') 然後 curl 後續 endpoint. Hermes redact 機制會將個 token 喺 terminal output 變成 ***, 之後 sed 唔 match. 即係用 bash 做 multi-step authenticated curl 唔可靠。

Fix: 用 python3 -c 一次性做 login + authed requests:

import json, urllib.request
token = json.loads(urllib.request.urlopen(urllib.request.Request(
  'http://localhost:3000/auth/login',
  data=json.dumps({'email':'a','password':'b'}).encode(),
  headers={'Content-Type':'application/json'})).read())['token']
data = json.loads(urllib.request.urlopen(urllib.request.Request(
  'http://localhost:3000/resource',
  headers={'Authorization': f'Bearer {token}'})).read())
print(data)

Python script 入面 Hermes redact 唔 trace 入去, 完整 token 留喺 memory, 之後先 redact output。

更安全嘅 fix (2026-06-05 crm-system Day 4 試過): Hermes 喺 terminal() 將 *** literal 自動 redact 連 print( 都波及, 寫 bash 用 awk '{print $1}' 都會壞. 解決:

將 token 寫入 /tmp/crm_token.txt (no echo)
Bash 用 tr -d '\\r\\n' < /tmp/crm_token.txt strip newline
用 printf 'Authorization: Bearer *** /tmp/crm_hdr.txt 然後 curl -H @/tmp/crm_hdr.txt 完全 avoid token 喺 process args 出現

最簡單 fallback (推薦): execute_code 跑 Python 直接打 urllib.request (個 sandbox *** 唔 trigger, full token 留 memory 唔 echo)。

Day 5 完整 step-by-step curl -H @filename 模式 (推薦 for bash smoke test):

# 1. Login 拎 token, 直接寫入 file 唔 echo
curl -fsS -X POST http://localhost/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@crm.local","password":"admin123"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])' \
  > /tmp/crm_token.txt

# 2. 驗證 token length (避免 file 空白 / 拎錯 field)
echo "Token length: $(wc -c < /tmp/crm_token.txt)"

# 3. 寫完整 Authorization header 入 file
#    ⚠️ Token 內部唔可以有 newline; 喺 json.load print 出嚟個 string 唔包 newline
{ printf 'Authorization: Bearer *** cat /tmp/crm_token.txt; printf '\r\n'; } > /tmp/crm_hdr.txt
od -c /tmp/crm_hdr.txt | head -2   # 驗證格式

# 4. 用 curl -H @file 帶 token 出去
curl -fsS http://localhost/api/users -H @/tmp/crm_hdr.txt

為何要咁: bash 嘅 ${TOK... variable inline 喺 H="Authorization: Bearer *** /api/me 401 因為 header 變空), 因為 literal 觸發 Hermes 自動 redact 連 closing'都波及。寫去 file 然後curl -H @file將 token 留喺 file system 而唔係 process argument,完全 avoid` pattern matching。

最簡單 fallback (推薦 if 唔需要 automation): 用 delegate_task 起 subagent 喺 fresh context 跑 Python urllib 一次性 login + smoke。Subagent 可能冇 same Hermes sandbox restrictions。

⚠️ Docker container DB migration when host can't reach postgres port (2026-06-05 crm-system Day 5)

症狀: docker-compose.yml postgres service 唔 expose host port (只 internal 5432/tcp),host 跑 bunx prisma migrate dev 撞 P1001 Can't reach database server at localhost:5432。本地 dev 為咗 security + avoid port conflicts 唔 expose 5432 好常見(尤其多 project 同時開發)。

解決 (4 steps):

手寫 SQL 放喺 packages/db/prisma/migrations/<timestamp>_<name>/migration.sql (CREATE TYPE / TABLE / INDEX / FK),Prisma 5 schema @@map 要同 SQL table name 一致

docker exec 跑 SQL:

docker exec -i crm-postgres psql -U crm -d crm_system -f /dev/stdin < \
  packages/db/prisma/migrations/20260605000000_add_audit_log/migration.sql

手動 insert _prisma_migrations row mark as applied,否則 entrypoint 嘅 prisma migrate deploy 將來會 complain "drift detected":

docker exec -i crm-postgres psql -U crm -d crm_system -c \
  "INSERT INTO \"_prisma_migrations\" (id, checksum, migration_name, finished_at, applied_steps_count) VALUES ('<unique-id>', '', '<timestamp>_<name>', NOW(), 1);"

⚠️ migration_name 冇 unique constraint,要 unique id column (ON CONFLICT (id) DO NOTHING 即可)

Host 行 bunx prisma generate 重新 generate client 識新 model:
```
env $(grep -v '^#' .env | xargs) bunx prisma generate
```

驗證:

docker logs crm-api --tail 20
# Expected: "2 migrations found in prisma/migrations" + "No pending migrations to apply"

Alternative (更麻煩): 暫時改 docker-compose.yml expose 5432:5432,host 跑 migration,改返 expose。唔建議 因為 re-up stack 會忘記 uncomment。

詳細 SQL 範本 + 真實 audit_logs migration + 23 個 action enum: 見 references/2026-06-05-crm-system-rbac-audit.md 嘅「Docker local dev 嘅 migration 撞牆 + 解決」section。

⚠️ Prisma migration folder rename 嘅 silent trap (2026-06-05 crm-system Day 6 真實撞牆)

症狀: 經常用 git pull 或者改完 schema 之後想 rename migration folder (例如 20260605000000_add_audit_log → 20260605020000_add_audit_log 修正 sort order),改咗 filesystem 之後 prisma migrate deploy 喺 container entrypoint 跑就會 crash:

Error: P3009
migrate found migration `20260605020000_add_audit_log` to apply, but the database already has a record of a migration with the same name at the same position.

或者更壞嘅:CREATE TABLE audit_logs 撞 duplicate 失敗 → container entrypoint 死 → API 唔起。

根因: Prisma 唔識 filesystem migration folder rename 同 _prisma_migrations table row 嘅 migration_name column 自動 sync。你改咗 file 但 db history 仲係舊 name。migrate deploy 見到 filesystem 有 20260605020000_* 但 db 冇 record, 以為要 apply 新版本,撞 duplicate。

Fix (3 steps, 之後先 git commit):

# 1. Rename folder (filesystem)
mv packages/db/prisma/migrations/20260605000000_add_audit_log \
   packages/db/prisma/migrations/20260605020000_add_audit_log

# 2. Update _prisma_migrations table row 同 filesystem 同步
docker exec -i crm-postgres psql -U crm -d crm_system -c \
  "UPDATE _prisma_migrations SET migration_name = '20260605020000_add_audit_log' \
   WHERE migration_name = '20260605000000_add_audit_log';"

# 3. Verify
docker exec -i crm-postgres psql -U crm -d crm_system -c \
  "SELECT migration_name FROM _prisma_migrations ORDER BY started_at;"
# 期望: 20260605020000_add_audit_log (新名)

然後先 git commit 同 push。唔好順序倒轉 — 改 file 但未 update db 之前 entrypoint 會壞,build 失敗即 production incident。

Migration timestamp 命名 rule (避免將來撞呢個 trap): 手動整嘅 migration folder name timestamp 一定要晚過 prisma migrate dev auto-generated init timestamp (例如 crm-system 嘅 20260605014842_init)。Mismatch 唔會 fail build 但 apply 順序錯會撞 foreign key constraint。查 auto-generated init timestamp:

ls packages/db/prisma/migrations/ | sort
# 最早嘅 timestamp 即係 init

相關 helper: scripts/backup.sh 跑之前會 list 而家有咩 backup files (file 內部用 find),亦都 help 確認 db 狀態, 但唔會 modify migration history — 改 history 永遠係人手 step。

⚠️ nginx SPA `root` directive 唔可以漏 (2026-06-05 crm-system Day 6 真實撞牆)

症狀: 已經 set 咗 location / + try_files $uri /index.html 嘅 SPA fallback config,但第一次去 /quotations (或者任何 SPA sub-route) 返 404。/api/health 又 work 因為 location /api/ 自己 handle。Vite 嘅 dist/index.html 都已經喺度,assets 都 serve 到。

根因: nginx config 漏咗 root directive。try_files 嘅 fallback /index.html 係相對 root,如果冇 root /usr/share/nginx/html; 喺 http {} 或者 server {} 上面,nginx 不知道 /index.html 喺邊, 直接返 404 (或者內部 default 行為: 500)。

David 6/05 fix commit d2b06d1 真實修法:

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;       # ← 必加! 否則 SPA fallback 404
    index index.html;

    # /api reverse proxy
    location /api/ {
        proxy_pass http://crm-api:3001/;
        # ... (略) ...
    }

    # SPA fallback (named location, 唔用 try_files $uri/ = 避免 cycle)
    location / {
        try_files /index.html =404;   # 改用 /index.html (absolute) 而唔係 $uri/
    }
}

Key points:

root 必須喺 server {} (或者 http {}) scope 設,唔可以擺入 location / 入面(雖然 syntax 接受,但 context 行為唔同)
try_files 嘅 argument 用 /index.html (leading slash 絕對路徑) 而唔係 $uri/ (會 cycle)— 配合 root nginx 解析 /index.html 做 root + /index.html = /usr/share/nginx/html/index.html ✅
完整能 work 嘅 nginx config (David 已 push 嘅版本) 喺 docker-mac-arm64-elysia-vite skill 嘅 templates/full-local-stack.md

Smoke test (after build / deploy):

curl -s -o /dev/null -w "%{http_code}\n" http://localhost/              # 期望 200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/quotations  # 期望 200 (SPA fallback)
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/assets/index.js  # 期望 200 (Vite hashed assets)

如果 / 返 200 但 /<sub-route> 返 404 → 即係 root directive 漏咗。

詳細 Day 6 nginx fix context: 見 references/2026-06-05-crm-system-docker-deploy.md 嘅「nginx SPA pitfall」section。

⚠️ API wrapper boundary normalize for Prisma relation field-name drift (2026-06-06 crm-system Day 12)

問題 (class-level): Backend Prisma return 嘅 relation field 用 Prisma model 嘅 camelCase 名 (e.g. manDayLines for Service.manDayLines ServiceManDay[]), 但 frontend Service TypeScript type 寫住 manDays (URL slug / business 簡稱). request<T> generic 純 typecast — 冇 runtime bridge, 個 return object 嘅 field 仍然叫 manDayLines (Prisma 個名), s.manDays 永遠 undefined 即係:

Component 訪問 s.manDays.length / .map() throw Cannot read properties of undefined
Defensive s.manDays?.length ?? 0 救表面, 但渲染 "0 個 man-day role" 即係 silent data loss
User 撞到嘅唔係 500, 而係「冇 data 顯示」— 仲難 debug

真正 fix (推薦, 套用所有 Prisma relation + frontend type alias 不一致嘅情況):

喺 apps/web/src/lib/api.ts 個 API wrapper boundary 加 normaliseEntity helper, 每個 list / get / create / update entry point 統一 pipe:

function normaliseService<T extends { manDays?: unknown; manDayLines?: unknown }>(s: T): T {
  const manDaysFromWire = (s as { manDayLines?: ServiceManDay[] }).manDayLines;
  if (manDaysFromWire !== undefined) {
    return { ...s, manDays: manDaysFromWire as ServiceManDay[] };
  }
  return s;
}

export const servicesApi = {
  list: (params) =>
    request<...>('/services?...').then((r) => {
      const items = Array.isArray(r) ? r : r.items;
      return items.map(normaliseService);   // ← 每個 item normalize
    }),
  get: (id) => request<Service>(`/services/${id}`).then(normaliseService),
  create: (data) => request<Service>('/services', { ... }).then(normaliseService),
  update: (id, data) => request<Service>(`/services/${id}`, { ... }).then(normaliseService),
};

Generic rule (套用到所有 Prisma relation field name != frontend type field name):

Backend Prisma	Frontend type	命名衝突源
`manDayLines` (relation)	`manDays` (URL slug / business)	camelCase vs abbreviation
`quotationItems` (relation)	`items` (business 簡稱)	Prisma 自動加 entity suffix
`serviceManDays` (model)	`manDays` (singular)	將來寫呢個 relation 要小心

Boundary normalize 一律喺 lib/api.ts wrapper 做, 唔好喺每個 component 重複。原因:

Single source of truth, 將來 backend 改 relation name 淨改 1 個 file
Component 寫 s.manDays 永遠 work, 後來人唔使知道 backend 嗰邊係 manDayLines
將來加 manDayLines → manDays migration / deprecation 都淨改 1 個 file

Defensive code (?? []) 喺 component 入面仍保留 (belt-and-suspenders):

// service-detail.tsx 即使 boundary normalize 將來 regress 都唔會 crash
setManDays((service.manDays ?? []).map((m) => ({ role: m.role, dayRate: m.dayRate, days: m.days })));

Detection 工具 (撞牆必做):

# 1. Component 訪問 field 嘅 pattern grep
rg "\.manDays\.|\.manDayLines\." apps/web/src
# 統一用 `manDays`, 有 `manDayLines` 嘅地方 = boundary normalize 漏咗

# 2. 對比 backend 嘅 wire format (Prisma relation name) vs frontend type
rg "manDays:|manDayLines:|manDayLines\?" apps/web/src/lib/api.ts
# 對比 packages/db/prisma/schema.prisma 嘅 field name

Generic 類比 — useQuery 個 generic type 同 boundary normalize:

// ❌ 唔好 (type 寫得啱但 runtime 唔 normalize)
const { data } = useQuery({
  queryKey: ['service', id],
  queryFn: () => servicesApi.get(id!),
});
// data.manDays 仍然 undefined!

// ✅ 改 (boundary normalize 喺 api.ts 統一做, useQuery caller 唔使知)
const { data } = useQuery({
  queryKey: ['service', id],
  queryFn: () => servicesApi.get(id!),  // returns Service with normalised manDays
});
// data.manDays 一定有

Related (Day 11 wire-format-side fix): 對應 wire format 嗰邊 (request body) 嘅命名同樣要 match backend schema, 唔好 match frontend type alias — 見上面 polymorphic-line-items skill 嘅 502 pitfall section 同 Day 11 reference file。Wire key = backend schema, response normalize = boundary wrapper。兩個方向嘅 drift 各自 fix 各自嘅 layer。

⚠️ Elysia `bun build` 撞 runtime code generation (2026-06-05 真實撞牆)

症狀: bun build src/index.ts --target=bun --outfile=dist/index.js [--minify] 喺 Elysia 1.2 build 成功, 但 image run 時 crash:

ReferenceError: vn is not defined        # 用 --minify
ReferenceError: client is not defined    # 用 --external @prisma/client

原因: Elysia 1.2 喺 handler 內部用 compile?.() 即時 generate code (route merge, schema derive, merge context 嗰啲),內部 variable 叫 vn / client. Bun minifier 改咗佢哋個名但 cross-reference 漏咗, runtime resolve 唔到。

Workaround (推薦, 2026-06-05 crm-system Docker production 用): 唔好 bun build, 直接 COPY source 入 image:

# Builder stage — 淨係裝 deps + generate Prisma client
FROM oven/bun:1.2 AS builder
WORKDIR /app
COPY package.json bun.lock* ./
COPY packages/db/package.json packages/db/
COPY apps/api/package.json apps/api/
RUN bun install --frozen-lockfile
COPY . .
RUN bunx prisma generate --schema=packages/db/prisma/schema.prisma

# Runtime stage — COPY 整個 source, 直接 bun run
FROM oven/bun:1.2
WORKDIR /app
# Prisma engine binary + generated client (Bun workspaces hoist)
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/packages ./packages
COPY --from=builder /app/apps ./apps
COPY apps/api/docker-entrypoint.sh /usr/local/bin/entrypoint
RUN chmod +x /usr/local/bin/entrypoint
CMD ["/usr/local/bin/entrypoint"]

entrypoint.sh 用 cd /app/packages/db && bunx prisma migrate deploy && cd /app && bun run apps/api/src/index.ts 直接 source 模式啟動, 等於 dev mode 冇 --watch 嘅 production。

Alternative (確認撞牆, 唔建議): bun build --target=bun --outfile=dist/index.js (唔加 --minify), 加 --external @prisma/client 避免 Prisma engine 打包問題。仍會撞 ReferenceError: client is not defined 因為 Prisma client 喺 bundled output 內部用 client symbol, --external 標記佢 external 但 bundler 仍然 emit client reference。即係 Elysia + Prisma 暫時唔可以用 bun build 任何 mode。

Web frontend 用 bun run build (Vite) 唔受影響, 因為 Vite 唔係 Elysia, minify 安全。

Full details + ready-to-copy Dockerfile patterns: 見 docker-mac-arm64-elysia-vite skill 嘅 Pitfall 7 (Elysia 1.2 + bun build broken) + Pitfall 8 (USER bun + entrypoint permission) section, 同埋 templates/full-local-stack.md 入面有完整 docker-compose.yml + Dockerfiles (proven 喺 ~/www/crm-system Day 3 production stack, 2026-06-05)。

⚠️ Backend response shape 不一致 — frontend 要 normalize (2026-06-05)

症狀: Backend Elysia routes 有啲返 { items: [...], total, limit, offset } (e.g. /companies), 有啲返 array 直接 (e.g. /products, /quotations, /deals). 兩個 route 寫法唔同 (一個包 wrapper, 一個直返 array), frontend 唔好假設單一 shape。

Fix (frontend lib/api.ts): 用 Array.isArray 兼容兩種:

return request<{ items: T[]; total: number } | T[]>(url).then((r) =>
  Array.isArray(r) ? r : r.items
);

一致性建議 (backend): 全部 findMany route 都包成 { items, total, limit, offset } shape, 預留 pagination. 用 helper:

function paginated<T>(items: T[], total: number, limit: number, offset: number) {
  return { items, total, limit, offset };
}

Vite 8 quirk (詳細)

bun create vite@latest . -- --template react-ts 喺 Vite 8 會：

❌ 唔裝 react/react-dom/@vitejs/plugin-react
❌ 用 vanilla TS template (src/main.ts 唔係 tsx)
❌ 唔寫 vite.config.ts
✅ 寫 package.json 但 scripts 仍 vite dev/build

Fix：

npm install react react-dom @types/react @types/react-dom @vitejs/plugin-react
寫 vite.config.ts（含 react + tailwind plugin）
刪 src/main.ts, src/counter.ts, src/style.css, src/assets/
寫 src/main.tsx, src/index.css
index.html 改 <div id="root"> + src="/src/main.tsx"
改 tsconfig.json 加 "jsx": "react-jsx"

完整目錄結構

~/www/<project>/
├── backend/
│   ├── prisma/
│   │   ├── schema.prisma
│   │   ├── seed.ts
│   │   └── migrations/
│   ├── src/index.ts
│   ├── data/app.db
│   ├── .env
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx
│   │   ├── index.css
│   │   ├── api.ts
│   │   └── pages/{Home,Exam,Review,Stats}.tsx
│   ├── index.html
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── package.json
├── data.json (optional: 初始 data 喺呢度)
└── README.md

啟動 dev

# Terminal 1
cd ~/www/<project>/backend
bun --env-file=.env src/index.ts   # :3200

# Terminal 2
cd ~/www/<project>/frontend
npm run dev                        # :5173

Frontend 透過 Vite proxy 訪問 /api/* → localhost:3200。

Hermes execute_code / terminal 陷阱 (五個唔同嘅事, 唔好混淆)

情境	問題	Fix
`terminal()` 跑 `bun add <pkg>`	Hermes process scanner 見到 `bun` 就當 long-lived 攔截	改用 `npm install` 代替 (frontend 啱用)
`execute_code` 開 long-lived server (`Popen` + `sleep` + `terminate`)	sub-shell 一 exit, 個 process 一齊死, 個測試結果攞唔到	永遠用 `terminal(background=true)` 開 dev server, 之後用 `process(action='poll')` 監察
`execute_code` 內 `subprocess.run([..., "python3", ...])`	Hermes sandbox 嘅 python interpreter 同 system `/usr/local/bin/python3` 唔同, 裝嘅 package 唔共享	用 `/usr/local/bin/python3` 絕對路徑, 或 `subprocess.run([sys.executable, ...])`
`git commit -m "...\`code`..."` 寫多行 commit message	Shell 將 backtick 之間嘅 inline code 當 command substitution 解析執行, 撞 `command not found` 噪音, commit 仍成功但 body 嘅 inline code 全部被食走變空白	寫 commit message 入 file 然後 `git commit -F /tmp/msg.txt`。`bash <<EOF` 都會撞同樣問題(shell 解析), 必須 file 落地
`terminal(background=true)` 跑 `docker compose up -d --build`	Hermes 嘅 background process 唔 return exit code 0 即係 build 仍進行中(可能 5-15 min), 唔代表失敗	用 `process(action='poll')` 監察,或者 background 之後用 `process(action='wait', timeout=600)`,exit code 0 = build done 唔係 "container died"

⚠️ `docker compose up -d --build` 必然 trigger foreground warning — 一律 background (2026-06-06 crm-system 真實撞牆)

症狀: 喺 terminal() foreground 跑 cd ~/www/<project> && docker compose up -d --build 一定撞:

This foreground command appears to start a long-lived server/watch process.
Run it with background=true, verify readiness (health endpoint/log signal),
then execute tests in a separate command.

即使個 command 係 up -d --build(detached mode + 純 build, 完全冇 long-lived server)— Hermes 嘅 foreground guard 都會 false positive trigger。exit_code: -1, error: "This foreground command appears..."。

根因: Hermes 嘅 guard heuristic scan 個 command string 見到 docker compose up 就當 long-running,唔識分辨 -d (detached) flag。--build flag build 完即 exit,正常 60-180 秒做完。但 Hermes 無論 -d 都 trigger warning。

Fix (永遠咁用): 任何 docker compose command — up -d、up -d --build、up -d --force-recreate、build --no-cache — 一律 background=true + notify_on_complete=true:

# 喺 terminal tool 入面
terminal(
  command="cd ~/www/<project> && docker compose up -d --build 2>&1 | tee /tmp/compose-build.log",
  background=True,
  notify_on_complete=True,
  timeout=600,
)
# 跟住用 process(action='wait', timeout=600) 監察
# process(action='log') 撈 output 睇 "error TS" / "exit code: 2"

Foreground 必然撞 Hermes guard warning,即使有 -d flag 個 daemon 即刻 detach 都撞。

Verification after build (必須做, 因為 foreground 撞 warning 後 exit code 已經被蓋住):

# 1. Container 全部 healthy
docker ps --format 'table {{.Names}}\t{{.Status}}' | grep <service>

# 2. Bundle hash 真係新 (build cache 可能 skip source change)
curl -s http://localhost/ | grep -oE 'index-[A-Za-z0-9_-]+\.js'
docker exec <web-container> ls /usr/share/nginx/html/assets/
# 兩個 hash 對得齊 = new build 真係 deploy

# 3. 或者 force rebuild 一個 dummy file 試
touch apps/web/src/.force-rebuild && docker compose build web
# 應該見到 source COPY stage 唔係 CACHED
rm apps/web/src/.force-rebuild

Generic rule: 任何 docker compose command 都係 background。Foreground 必然撞 Hermes guard false positive warning,即使 docker compose ps、docker compose logs、docker compose down 呢類 query-only command 都建議 background(雖然通常 warning 唔 trigger, 但保險)。

Related: 同「Docker Compose up -d --build cache layers 不重 build source code」(下面) 唔同 — 嗰個 pitfall 係 Docker 自己嘅 cache miss 行為,呢個 pitfall 係 Hermes 工具 false positive warning。兩個 pitfall 都會令你以為「build 凍咗」但其實冇凍。

⚠️ Build 撞「Cannot find name X」之前,先 grep 個 X 喺 codebase 邊度 define 過 (2026-06-06 crm-system 真實撞牆)

症狀: Build 撞 error TS2552: Cannot find name 'DealDialog' / Cannot find name 'QuotationBuilder' / Cannot find name 'kanbanStages'。First reaction 想寫新 file / 新 component / 新 constant 補返。但其實個 X 可能已經喺 codebase 內部 define 咗,只係冇 export / 冇 import / 拼錯名。

例子 (crm-system 2026-06-06):

// apps/web/src/pages/companies.tsx — WIP 改動引入咗呢行
import { DealDialog } from '@/pages/deals';   // ❌ 'DealDialog' is not exported from '@/pages/deals'

實際上 apps/web/src/pages/deals.tsx:345 已經有:

function DealDialog({...}) {  // ← internal function, 冇 export

Fix = 加 1 個 keyword 9 個 char:

// apps/web/src/pages/deals.tsx line 345
-export function DealDialog({...}) {     // 改 internal → exported
+export function DealDialog({...}) {

唔係寫新 apps/web/src/components/deal-dialog.tsx,唔係 import pages/deals.tsx 嘅 types / helpers,完全唔改 DealDialog 嘅 body。

Generic workflow (撞「Cannot find name X」/「X is not exported」必做):

唔好 assume 個 X 真係 missing:

# grep X 喺 codebase 邊度 define 過 (case sensitive)
rg "\bDealDialog\b" apps/web/src
# 期望: 見到一個定義(就算 internal function 都算)— 即係唔需要寫新
# 期望: 完全冇 hit — 先寫新

如果 internal,check 係 function / const / interface 邊個 export 規則:
- function X → 加 export keyword 即可
- const X = → 加 export keyword
- interface X / type X → 加 export keyword
- 如果係 anonymous export default → 寫 named export export function X
如果真係冇 define 過,先 grep X 變體:rg "DealDialog|deal-dialog|dealDialog" 有時命名 convention 唔同(eg. dealDialog 駝峰 vs deal-dialog kebab),可能 existing 用緊另一個名
最後先考慮寫新 file。多寫一個 file 引入新 export 嘅機會成本 = 重新做 code review / 可能同現有 duplicate / 將來 refactor 要兩邊 sync

Anti-pattern:

// ❌ 撞到 first thought:寫新 file
// apps/web/src/components/deal-dialog.tsx (全新 200 行)
export function DealDialog({...}) { ... }

// ✅ 先 grep,加 export,慳 200 行
// apps/web/src/pages/deals.tsx (改 1 個 keyword)
export function DealDialog({...}) { ... }

Generic rule 套用到所有 X:

React component(DealDialog / RoleDialog / QuotationBuilder)
Elysia route module
Prisma model name
Utility function / helper
Type alias / interface
常數(kanbanStages / BASE_REGIONS / ALL_PERMISSIONS)

5 秒 grep 慳 30 分鐘 over-engineering。撞「Cannot find name X」,永遠先 grep X 喺 codebase 邊度 define 過,永遠先 assume 個 X 已經 internal 存在。

Related:

patch-corruption-recovery skill — 撞 syntax error 之後 restore from git + re-patch 嘅 pattern。但撞「Cannot find name X」通常唔需要 restore,加 1 個 keyword 即可
bun-elysia-react-vite-stack 嘅「LSP diagnostics stale」section — LSP 報「Cannot find name」可能係 stale cache,先睇 tsc --noEmit 嘅真實 error 然後先 grep

具體例子: bun add tailwindcss @tailwindcss/vite 喺 terminal() 會撞 "This foreground command appears to start a long-lived server/watch process", 但喺 execute_code 內用 subprocess.run(["npm", "install", ...]) 就 OK。

⚠️ Git commit message body 永遠寫 file, 唔好 inline (2026-06-09 crm-system 真實撞牆)

症狀: 用 git commit -m "$(cat <<EOF ... 好多行 ... \setStageId(deal?.stage?.id ?? stages[0]?.id)` `e.dataTransfer.setData("text/deal-id", deal.id)` ... 多啲 inline code ... EOF )"寫一個有 backtick-inline-code 嘅 commit message。Commit **成功** (exit 0, push 都成功), 但git log -1 --format='%b'` 出嚟嘅 body 係:

1. backend GET /deals/kanban 個 Prisma  冇 ,
   所以 frontend 收到嘅每個 deal 都係 。

所有 backtick 區間嘅 inline code 完全消失,剩低空白 + 雜訊 command not found。

根因: Bash (同大多數 shell) 將 backtick (`) 視為 command substitution, 等同 $(...)。Shell 喺 heredoc 內部 (<<EOF) 仍然會 expand backticks, 唔係真 heredoc (<<'EOF' 單引號先唔 expand)。每對 backtick 入面個 expression 當 command 跑, 撞 command not found 但 commit 流程唔 fail, body 變空白。

Fix (3 個 option, 揀適合):

Option A — 寫 file 然後 git commit -F (推薦, 100% safe):

cat > /tmp/commit-msg.txt <<'HEREDOC'    # 注意: <<'EOF' 單引號, 唔 expand
fix(deals): drag-drop + edit dialog

症狀: 撳 edit dialog 永遠顯示 Stage = "Lead", ... 

\`setStageId(deal?.stage?.id ?? stages[0]?.id)\`  永遠 fall through

\`e.dataTransfer.setData("text/deal-id", deal.id)\`  喺 onDragStart 冇 call
...
HEREDOC
git commit -F /tmp/commit-msg.txt

Option B — git commit --amend -F file (已經 commit 咗, 改 message):

# 發現 commit message 壞咗, 唔使 reset, 直接 amend
git commit --amend -F /tmp/commit-msg.txt
git push --force-with-lease origin main   # 必須 force-push 因為 commit 改咗

Option C — <<'EOF' single-quoted heredoc (防止 future backtick expansion, 但仍輸 cat | git 個 overhead):

git commit -F - <<'MSG'   # 單引號 heredoc: shell 完全唔 interpret
fix(deals): drag-drop

\`backticks here preserved verbatim\`
MSG

Detection (撞牆後必做):

git log -1 --format='%b' | head -10
# Look 4 啲 inline code (`xxx`) 區間。 如果 4 唔到, 即係 backticks 全部被 shell 食走

Why option A 永遠 work:

<<'EOF' 喺 cat 嗰度: 寫 file, 文字 verbatim
git commit -F /tmp/file: 純 file read, 唔經 shell 解析
完全冇 backtick interpolation, 任何 inline code 字符 ( , $, \, etc) 都 pass through

Generic rule (套用到任何 git commit 同樣有 backtick 嘅場景):

git commit -m "literal text" — 簡單 message OK, 但 backticks 仍然食
git commit -m "$(cat <<EOF ... EOF)" — 永遠撞
git commit -F file — 永遠 safe
git commit -F - (stdin via <<'EOF') — safe, 但要小心 trailing newline

唔好 assume 呢個係 rare case: 寫 commit message 想用 `code` highlight 改咗嘅 function name / option / class 個 case 太常見, 第一次有 inline code 就撞。養成習慣: 一律 file。

Doc / Web 攞資料嘅限制 (3 個常見撞牆)

撞牆 1: SPA 渲染嘅 API doc 站撈唔到 (e.g. https://xxx.com/public/apidoc/<hash>)

症狀: curl / web_extract 攞到 4-5KB HTML 殼, content 空 (只有 loading spinner + JS bundle)
原因: 個 doc 站用 React/Vue 喺 client-side render, content 喺 __NEXT_DATA__ / bundle 入面
唔好再用 firecrawl / curl 撞 — browser_navigate 都會 timeout 因為 content 太慢 load
解: 唔靠 doc, 靠用戶 domain knowledge + 一般 SaaS pattern 設計 schema / endpoints. 問用戶核心 fields/flows 就夠

撞牆 2: GitHub SSH clone 慢 / proxy 阻擋 (內網 / 公司 firewall)

症狀: git clone git@github.com:... hang 喺 "Cloning into..."
確認 SSH 通: ssh -T git@github.com → 「Hi ! You've successfully authenticated」
唔通嘅話, 改 https:// 配 PAT: git clone https://<token>@github.com/<user>/<repo>.git

撞牆 3: Git push 完唔知成功定失敗

唔好用 aws codecommit get-commit 驗 (IAM 冇 read 權限會 false alarm)
用: git ls-remote <remote> 或再 git clone --depth 1 <url> /tmp/verify 確認 commits 出現

QA Gate checklist (full-stack app)

Backend /api/health returns 200
Frontend index.html returns 200
Proxy /api/health 透過 frontend returns 200
至少 1 個 E2E write+read flow (POST + GET)
Browser 載入 4 個 page 冇 console error
RWD mobile audit (見 rwd-mobile-audit skill)
Git 推送完記得用 git clone 或 git ls-remote 驗證（唔好信 aws codecommit get-commit — IAM 冇 read 權限會 false alarm，見 aws-codecommit-git-setup 嘅「驗證 push 成功嘅方法」section）

⚠️ Backup / Restore 對 local Postgres Docker stack (2026-06-05 crm-system Day 6)

情境: 用戶要 admin functionality 包含 backup / restore,但又唔想搞 cloud storage / S3 (本地部署就本地 backup)。3 個 scripts + 1 個 docker profile 已經 ready to copy。

1. Host-side backup (`scripts/backup.sh`)

docker exec 跑 pg_dump 喺 postgres container,stream 出 gzip:

./scripts/backup.sh                    # 預設 7 日 retention
./scripts/backup.sh --keep 30          # 30 日
./scripts/backup.sh --no-trim          # skip cleanup

產出:backups/crm_2026-06-05_132751.sql.gz (8K for empty schema)。Retention 用 find -mtime +N -delete,冇 cron daemon 都要 work。

2. Restore (`scripts/restore.sh`)

互動式揀 backup + safety confirm:

./scripts/restore.sh                            # 互動揀
./scripts/restore.sh backups/crm_xxx.sql.gz     # 直接
./scripts/restore.sh <file> --no-confirm        # CI mode

安全流程:停 API → DROP DATABASE → CREATE DATABASE → gunzip | psql -v ON_ERROR_STOP=1 → start API。

Pitfall:

唔 stop API → DROP DATABASE hang (API 仲 hold 住 connection)
唔用 -v ON_ERROR_STOP=1 → psql 默吞錯誤,partial restore 假成功
stat -f '%Sm' (macOS) vs stat -c '%y' (Linux) — 用 2>/dev/null || fallback

3. Scheduled backup profile (`docker-compose.yml`)

backup:
  image: postgres:16-alpine
  profiles: ["backup"]    # opt-in: `docker compose --profile backup up -d`
  command:
    - -c
    - |
      echo "0 2 * * * /usr/local/bin/backup.sh >> /proc/1/fd/1 2>&1" > /etc/crontabs/root
      /usr/local/bin/backup.sh
      crond -f -L /dev/stdout
  environment:
    PGPASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_HOST: postgres
    POSTGRES_DB: ${POSTGRES_DB}
    BACKUP_KEEP_DAYS: ${BACKUP_KEEP_DAYS:-7}
  volumes:
    - ./backups:/var/backups
    - ./scripts/backup-container.sh:/usr/local/bin/backup.sh:ro
  depends_on:
    postgres: { condition: service_healthy }

postgres:16-alpine 內置 BusyBox crond,唔需要裝 cron daemon。Skip mechanism:touch backups/skip → entrypoint check if [ -f /var/backups/skip ]; then exit 0。

4. 兩個 backup script 嘅分別 (重要!)

環境	Script	連線方式
Host 跑 (`./scripts/backup.sh`)	Host script	`docker exec crm-postgres pg_dump`
Container 跑 (cron job 內)	`backup-container.sh`	直接 `pg_dump -h postgres -U crm -d crm_system` (compose 內部 hostname)

唔好 mix up — host 版本喺 container 內用會撞 localhost:5432 connection refused 因為 localhost 係 container 自己。Container 版本喺 host 用會撞 postgres:5432 DNS fail 因為 host 唔識 compose 內部 hostname。

5. .gitignore 必加

backups/
*.sql.gz

pg_dump file 可能包含 PII (email, phone, IP)。絕對唔好 commit 入 git。

詳細 Day 6 build log 見 references/2026-06-05-crm-system-audit-backup.md。

⚠️ Elysia 1.2 `.derive()` 喺 POST handler 內 silently 返 `undefined` (2026-06-06 crm-system Day 9 真實撞牆)

症狀 (比 Day 7 個 onBeforeHandle bug 更隱蔽): 用 authContext = new Elysia().derive(({ request, jwt, set }) => { ... return { userId, userRole } }) 然後每個 route .use(authContext) + handler ({ userId, set }) => { if (!userId) return 401 }. GET routes 全部 work,但 POST routes 個 userId 永遠 undefined。如果個 endpoint if (!userId) return 401 → 全部 POST 返 401。如果個 endpoint 唔 check userId (e.g. /companies POST 直接 prisma.company.create()) → 默默 work 但 audit log 入面 actorId 永遠 null。

Hermes 喺 crm-system Day 9 撞咗 3 個鐘先發現:

POST /api/quotations 返 401,POST /api/companies 返 201(201 因為 handler 唔 check userId)
GET /api/deals/kanban work 正常
加 console.log('[POST /quotations] userId=', userId) 入 handler → print undefined
加 console log 入 authContext.derive → 冇任何 log。即係 derive 個 async function 完全冇 run

根因: Elysia 1.2 嘅 derive() 喺 plugin boundary + body validation chain 內會 silent skip 個 async function 對於 POST 帶 body 嘅 request。onBeforeHandle 都會 derive 唔到(見 Day 7 workaround),但route handler 直接 destructure 都 derive 唔到呢個係新發現,更陰濕。只有先 register 過 sibling .get() route 之後先撞(多個 routes 喺 same Elysia instance chain)。

Workaround (推薦, 100% bullet-proof): 完全唔靠 derive() 注入 userId,handler 內 inline verify token:

// apps/api/src/lib/context.ts
import { Elysia } from 'elysia';

export const authContext = new Elysia({ name: 'auth-context' });
// Intentionally empty — Day 9 發現 .derive() 喺 Elysia 1.2 POST handler
// 內 silently 返 undefined。Use getUserIdFromRequest() inline 喺每個
// handler 入面 call 取代。

export async function getUserIdFromRequest(
  request: Request,
  jwt: { verify: (token: string) => Promise<unknown> }
): Promise<string | null> {
  const authHeader = request.headers.get('authorization');
  if (!authHeader?.startsWith('Bearer ')) return null;
  const token = authHeader.slice(7);
  const payload = await jwt.verify(token);
  if (!payload || typeof payload !== 'object') return null;
  return (payload as { sub?: string }).sub ?? null;
}

// apps/api/src/routes/quotation.ts
import { authContext, getUserIdFromRequest } from '../lib/context';

.post('/', async ({ body, jwt, set, request }) => {
  const userId = await getUserIdFromRequest(request, jwt);
  if (!userId) { set.status = 401; return { error: 'Unauthorized' }; }
  // ... 個 body 之後照舊 ...
}, { body: t.Object({...}) })

Detection (撞牆必做):

import urllib.request, json
token = json.loads(urllib.request.urlopen(urllib.request.Request(
  'http://localhost/api/auth/login',
  data=json.dumps({'email':'admin@crm.local','password':'admin123'}).encode(),
  headers={'Content-Type':'application/json'}), method='POST')).read())['token']
# Try 一個 GET + 一個 POST endpoint (POST 要 body)
for url, method, body in [
  ('/api/deals/kanban', 'GET', None),
  ('/api/quotations', 'POST', json.dumps({
    'companyId': 'xxx', 'title': 'T', 'taxRate': 0,
    'items': [{'name': 'X', 'quantity': 1, 'unitPrice': 100}]
  }).encode()),
]:

这个 SKILL.md 很大，SkillsMP 这里只预览前一段内容。在 GitHub 查看

name	bun-elysia-react-vite-stack
description	Bootstrap a local full-stack TypeScript app with Bun 1.2 + Elysia backend + Vite 8 + React 19 + Tailwind v4. SQLite (dev) + Postgres (prod recommended) via Prisma 5. Use when user wants a quick local dev app (CRM, MVP, internal tool, exam app) and stack is the same family.
tags	["bun","elysia","react","vite","tailwind","prisma","fullstack","stack","bootstrap","sqlite"]

Bun + Elysia + Vite/React Full-Stack Bootstrap

本地 dev 嘅最快 full-stack TS stack。Elysia 同 Bun runtime 配 Vite 嘅 HMR 體驗極順。SQLite 用 Prisma 5（唔好用 Prisma 7 — 見 prisma-sqlite-bun-setup skill）。

觸發時機

用戶要 quick MVP / internal tool / 個人練習 app / 新嘅 CRM 重建
已經喺 Elysia + Vite 環境做開 (e.g. 跟 bc-quotation 嘅 stack pattern)
唔需要 deploy production (local dev 為主) — deploy 睇 cdk-ecs-fargate-deploy
想要日後 production 行 Postgres 但 dev 階段快速用 SQLite (見下「SQLite vs Postgres」section)

部署目標 — 問用戶先 (2026-06-05 crm-system 真實訊號)

Plan 階段必須問用戶要 deploy 喺邊，唔好 default 推 CDK/IaC:

用戶情境	部署方案
Local only / NAS / NUC / 內部 server (David 嘅 crm-system 屬呢類)	Docker Compose (full stack) — postgres + api (Bun) + web (nginx) + opt-in adminer。`docker-mac-arm64-elysia-vite/templates/full-local-stack.md` 有 copy-paste docker-compose.yml + Dockerfiles + nginx.conf。唔好用 CDK
Cloud (AWS ECS / Fargate / RDS / CloudFront)	CDK v2 — 跟 `cdk-ecs-fargate-deploy` + `cdk-deployment-rules`
Hybrid (e.g. local dev, cloud prod for customers)	Docker Compose 本地 + CDK/Terraform prod。schema/seed 要 plan migration path

喺 Plan 階段 (Think) 主動問「個 system 將會 deploy 喺邊」 — 用戶唔會 default 自己講, 要我哋 trigger。

SQLite vs Postgres 點揀 (2026 經驗)

📌 Host test env pitfall (Docker rescues): 如果 host 跑 bun test 撞 Cannot find module '.prisma/client/default',加 pretest: bunx prisma generate hook 即解。詳見 references/prisma-host-test-env.md。

情境	用咩
Exam app / 純本地練習 / 唔會上 production	SQLite — 零 setup, file 即可, Prisma 5 完美 support
內部 tool / 個人用 / single-user	SQLite — 唔需要 server
CRM / 報價單 / multi-user SaaS / 有 AI agent RAG	Postgres (即使 dev) — 因為需要 `String[]` (tag), `Json` (metadata), `Decimal` 真正 support, `pgvector` (RAG), transactions, concurrent writes
Production 但 dev 想 SQLite	可, 但要 plan migration — 用 `prisma migrate diff` 驗證 SQLite → Postgres syntax (Decimal precision, enum 唔同)

CRM/報價單必上 Postgres 嘅原因:

Json type: ActivityLog.metadata, Message.toolCalls — SQLite 只可以 String, 用 JSON.stringify 將就 (loss of type safety)
String[] type: Company.tags — SQLite 唔支援, 要 join table
Decimal precision: SQLite 用 String 儲, 冇 numeric type — 金額運算危險
pgvector: AI agent RAG 必要
Decimal @db.Decimal(15, 2) schema 同 SQLite 唔同, 之後 migrate 會有 friction

建議 (新建 CRM 項目):

Dev + Prod 都用 Postgres — 撈 docker postgres / RDS 唔難
唔想裝 Postgres server → bun add -d @electric-sql/pglite (in-process Postgres for dev)
真係 quick-and-dirty 先 SQLite, schema 唔用 String[] / Json / 唔用 pgvector

完整 SOP (SQLite path, 跟之前 bc-quotation)

1. Backend init (Bun workspaces monorepo, 支援 apps/api + apps/web)

mkdir -p ~/www/<project>/apps/api ~/www/<project>/apps/web ~/www/<project>/packages/db
cd ~/www/<project>

# Root workspace
cat > package.json <<EOF
{
  "name": "<project>",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "dev:api": "bun --filter api dev",
    "dev:web": "bun --filter web dev",
    "db:generate": "bun --filter db generate",
    "db:migrate": "bun --filter db migrate"
  }
}
EOF

# API
cd apps/api && bun init -y
bun add elysia @prisma/client
bun add -d prisma@5 tsx @types/node dotenv

⚠️ Prisma 一定要 pin prisma@5：bun add prisma 會拉到 7.x,撞 schema 唔再支援 url = env(...)。詳見 prisma-sqlite-bun-setup skill。

2. Prisma + DB setup

mkdir -p data
bunx prisma generate
bunx prisma migrate dev --name init --skip-seed

prisma/schema.prisma 範本（SQLite 限制：無 enum、無 Json → 用 String + JSON.stringify）：

generator client {
  provider = "prisma-client-js"
  output   = "../node_modules/.prisma/client"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model Question {
  id        String   @id @default(cuid())
  seq       String   @unique
  type      String
  question  String
  options   String   // JSON.stringify([{key,text}])
  answer    String
  createdAt DateTime @default(now())
}

.env：

DATABASE_URL="file:./data/app.db"
PORT=3200

⚠️ Path 陷阱：./data/app.db 係相對 prisma 同層。如果 backend 同 DB 喺唔同層，記得用 join(import.meta.dir, "..", "..", "data", "app.db")。

3. Elysia backend

// src/index.ts
import { Elysia, t } from "elysia"
import { PrismaClient } from "@prisma/client"

const prisma = new PrismaClient()
const PORT = Number(process.env.PORT) || 3200

const app = new Elysia()
  .get("/api/health", () => ({ ok: true }))
  .get("/api/items", () => prisma.question.findMany())
  .listen(PORT)

console.log(`Running at http://localhost:${PORT}`)

啟動：

bun --env-file=.env src/index.ts

⚠️ --env-file 必須 — Bun runtime 唔自動 load .env。詳見 bun-env-file-for-dev skill。

⚠️ Path 陷阱 (2)：readFile(join(import.meta.dir, "..", "questions.json")) — import.meta.dir 係 source 編譯後位置，唔係 cwd。如果個 file 喺 backend 外面，多加 ..。

4. Seed script

# prisma/seed.ts
import { PrismaClient } from "@prisma/client"
import { readFile } from "fs/promises"
import { join } from "path"

const prisma = new PrismaClient()
async function main() {
  const data: any[] = JSON.parse(
    await readFile(join(import.meta.dir, "..", "..", "data.json"), "utf-8")
  )
  for (const item of data) {
    await prisma.question.upsert({
      where: { seq: item.seq },
      create: item,
      update: item,
    })
  }
  console.log(`Seeded ${data.length}`)
}
main().finally(() => prisma.$disconnect())

package.json：

{
  "scripts": {
    "dev": "bun --env-file=.env --watch src/index.ts",
    "db:seed": "bun run prisma/seed.ts",
    "db:studio": "prisma studio"
  }
}

5. Frontend init (Vite 8 + React)

cd ~/www/<project>/frontend
bun create vite@latest . -- --template react-ts

⚠️ Vite v8 + bun create bug — 即使 --template react-ts，v8 預設裝出嚟係 vanilla TS (src/main.ts + counter.ts)，冇 vite.config.ts，要手動 clean。詳見下「Vite 8 quirk」。

手動補：

# 用 npm install 而唔係 bun add（避 Hermes 嘅 long-lived scan）
npm install react@latest react-dom@latest @types/react @types/react-dom @vitejs/plugin-react
npm install tailwindcss@4 @tailwindcss/vite

6. Vite config + Tailwind v4

vite.config.ts：

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import tailwindcss from "@tailwindcss/vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  server: {
    port: 5173,
    proxy: { "/api": "http://localhost:3200" },
  },
})

src/index.css（Tailwind v4 唔再用 tailwind.config.js）：

@import "tailwindcss";

@theme {
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
}

tsconfig.json 必加：

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "types": ["vite/client", "node"]
  }
}

7. React Router + Pages

// src/main.tsx
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { BrowserRouter } from "react-router-dom"
import App from "./App"

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>
)
- Vite proxy `/api/*` → :3000 backend

## ⚠️ Elysia 1.2.0 d.ts broken (2026-06-05 真實撞牆)

**症狀**: 用 `new Elysia().use(jwt({...}))` 然後喺另一個 route file 用 `jwtApp.decorator.jwt.verify()` 嗰陣, Elysia d.ts 自己報錯 (`MacroContext['return']` 唔存在, etc.), 即使 `skipLibCheck: true` 都解決唔到, 仲會污染 typechain 令整個 file 出 error. **Bun runtime 唔 care d.ts, server boot 過, 但係跨 route file call decorator 嘅 runtime 可能 fail**(e.g. `/chat/*` 返 401 因為 decorator chain 喺 plugin boundary 斷咗).

**Workaround** (推薦): **唔好用 Elysia 嘅 `jwt` decorator chain 跨 file**, 用 `jose` 直接 verify:
```typescript
import { jwtVerify } from 'jose';
const secretKey = new TextEncoder().encode(process.env.JWT_SECRET ?? 'dev-secret');
async function verifyToken(authHeader: string | null): Promise<string | null> {
  if (!authHeader?.startsWith('Bearer ')) return null;
  try {
    const { payload } = await jwtVerify(authHeader.slice(7), secretKey);
    return typeof (payload as any).sub === 'string' ? (payload as any).sub : null;
  } catch { return null; }
}

Auth flow: auth.ts 用 Elysia().use(jwt({...})) 整 token (decorator 喺 same file 仲 work), 其他 route file 用 jose 驗. 兩個 source of truth 但 secret 一致就 OK.

Alternative: pin elysia@1.1.30 + @elysiajs/jwt@1.1.0 避開 d.ts bug. bun add elysia@1.1.30 @elysiajs/jwt@1.1.0 即可, 唔影響 production runtime.

衍生: `onBeforeHandle` 嘅 derive context 唔 propagate 跨 plugin (2026-06-05 crm-system Day 7 真實撞牆)

Workaround (推薦): 個 plugin 入面 自己 extract + verify 個 Authorization header, 唔好依賴 derive context:

// apps/api/src/middleware/rbac.ts
import { jwtVerify } from 'jose';

async function getUserIdFromRequest(request: Request): Promise<string | null> {
  const auth = request.headers.get('authorization');
  if (!auth?.startsWith('Bearer ')) return null;
  const token = auth.slice(7);
  const secret = process.env.JWT_SECRET;
  if (!secret) return null;
  try {
    const { payload } = await jwtVerify(token, new TextEncoder().encode(secret));
    if (!payload || typeof payload !== 'object') return null;
    return (payload as { sub?: string; userId?: string }).userId
      ?? (payload as { sub?: string }).sub
      ?? null;
  } catch { return null; }
}

export function requirePermission(permission: string) {
  return new Elysia({ name: `require-permission:${permission}` }).onBeforeHandle(
    { as: 'scoped' },
    async (ctx: { request: Request; set: { status?: number } }) => {
      const userId = await getUserIdFromRequest(ctx.request);
      if (!userId) { ctx.set.status = 401; return { error: 'Unauthorized' }; }
      // ... check permission via DB ...
    }
  );
}

Key points:

用 ctx.request: Request 拎 header, 唔靠 ctx.userId
jwtVerify 用 jose 直接 import, 唔好 instantiate @elysiajs/jwt 個 plugin (jwtPlugin({...}).verify 唔存在)
個 verify 同個 JWT-signing 嘅 secret 要一樣 (即 process.env.JWT_SECRET)
個 (payload as { sub, userId }).userId ?? (payload as { sub }).sub fallback 因為唔同 signing 嘅 field name

Verification (必須做): login + 揾個要 permission 嘅 endpoint 試:

# 用 execute_code 或 python3 inline 避免 Hermes `***` redact
import urllib.request, json
data = json.dumps({"email":"admin@x","password":"x"}).encode()
req = urllib.request.Request("http://localhost/api/auth/login",
  data=data, headers={"Content-Type":"application/json"})
token = json.loads(urllib.request.urlopen(req).read())["token"]
# 揾個要 user:read 嘅 endpoint 試
req = urllib.request.Request("http://localhost/api/users",
  headers={"Authorization": f"Bearer {token}"})
print(urllib.request.urlopen(req).read()[:200])
# 期望: 200 + JSON list, 唔係 401

⚠️ React Query `useQuery` generic return type 撞 `never` (2026-06-05 crm-system Day 7 真實撞牆)

症狀: Backend 返 { items: T[]; total: number } 或者 bare T[] 兩種 shape (見下面「Backend response shape 不一致」section),寫 frontend:

const { data } = useQuery({
  queryKey: ['products', params],
  queryFn: () => productsApi.list({ ... }),
});
const items: Product[] = Array.isArray(data) ? data : (data?.items ?? []);

bun run build 撞:

error TS2339: Property 'items' does not exist on type 'never'.

Fix (推薦, 5 秒 fix): Explicit cast as 兩次 bypass TS inference:

const items: Product[] = Array.isArray(data)
  ? (data as Product[])
  : ((data as { items?: Product[] } | undefined)?.items ?? []);

⚠️ Vite production minified React throw unmount 整個 tree (2026-06-05 crm-system Day 7 真實撞牆)

根因 1 (最常見): Backend 返嘅 JSON 唔 match frontend TypeScript interface。例如 backend /api/roles 返:

{ "items": [{ "id": "...", "name": "ADMIN", "isSystem": true, "_count": { "users": 1 } }] }

但 frontend interface 寫:

interface Role { id: string; name: string; permissions: string[]; }

Fix (3 個 layer,推薦全部用):

Layer 1 — Defense in depth (必須): 包個 ErrorBoundary 喺 main.tsx:

// apps/web/src/components/error-boundary.tsx
import { Component, type ReactNode } from 'react';
export class ErrorBoundary extends Component<{ children: ReactNode }, { error: Error | null }> {
  state = { error: null as Error | null };
  static getDerivedStateFromError(error: Error) { return { error }; }
  componentDidCatch(error: Error, info: { componentStack: string }) {
    console.error('UI error:', error, info.componentStack);
  }
  render() {
    if (this.state.error) {
      return (
        <div className="p-8">
          <h2 className="text-lg font-bold text-destructive">UI Error</h2>
          <pre className="text-xs mt-2 whitespace-pre-wrap">{this.state.error.message}</pre>
          <button onClick={() => this.setState({ error: null })} className="mt-4 px-3 py-1 border rounded">
            Reload
          </button>
        </div>
      );
    }
    return this.props.children;
  }
}

// apps/web/src/main.tsx
<StrictMode>
  <ErrorBoundary>
    <BrowserRouter><App /></BrowserRouter>
  </ErrorBoundary>
</StrictMode>

Layer 2 — Schema contract check: 寫個 smoke script 用 Python urllib login + GET endpoint, 將 response 嘅 keys 對比 frontend interface 預期 keys, mismatch 即係 schema drift:

import urllib.request, json
expected = {"id", "name", "permissions"}    # from frontend interface
resp = json.loads(urllib.request.urlopen(req).read())
actual = set((resp.get("items") or [resp])[0].keys()) if isinstance(resp, dict) else set(resp[0].keys())
missing = expected - actual
if missing:
    print(f"❌ API missing fields: {missing}")
    raise SystemExit(1)

Layer 3 — Defensive rendering: 個 page 寫 {r.permissions?.length ?? 0}, 唔好假設 array 一定有:

{_count?.permissions ?? 0} / {allPermissions.length} 個權限
{_count?.users !== undefined && ` · ${_count.users} 個用戶`}

Detection (production only, dev 通常 work):

docker compose ps 顯示 web container healthy
DevTools → document.getElementById('root').innerHTML 返 '' (length 0)
performance.getEntriesByType('resource').filter(r => r.name.includes('/api/X')) 確認有 fetch (唔係 fetch fail — fetch OK 但 render fail)
document.querySelector('vite-error-overlay') 返 null (production 冇 Vite overlay)

Verification (必須做, dev mode 唔夠):

docker compose build web --no-cache
docker compose up -d web
# Browser console:
performance.getEntriesByType('resource').filter(r => r.name.includes('/api/roles')).map(r => ({status: r.responseStatus}))
# Expected: 200 (backend OK 但 frontend 仍 unmount 都返 200)
document.getElementById('root').children.length
# Expected: 1+ (如果係 0 = React unmount = runtime render error)

⚠️ Docker Compose `up -d --build` cache layers 不重 build source code (2026-06-05 crm-system Day 7 真實撞牆)

Fix 1 (推薦, 萬用): 改 source 改完之後 always force --no-cache:

docker compose build web --no-cache
docker compose up -d web

--no-cache 會 skip 所有 cache layers, 完整重 build, 確定新 source 入 image。15-30 秒 penalty 但保證啱。

Fix 2 (Dockerfile fix, 預防性): 喺 Dockerfile 開頭加個 ARG CACHEBUST=1 強迫 invalidate cache:

FROM oven/bun:1.2 AS builder
ARG CACHEBUST=1   # change this value to force cache invalidation
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install
COPY . .
RUN bun run build

docker compose build --build-arg CACHEBUST=$(date +%s) web

Detection 撞牆嘅方法 (必須每次 build 後做):

# 1. Check 個 image creation time
docker images <project>-web --format "{{.ID}} {{.CreatedSince}}"
# Expected: "Less than a minute ago" (唔係 "5 minutes ago" / "2 hours ago")

# 2. Check 個 bundle hash
docker exec crm-web cat /usr/share/nginx/html/assets/index-*.js | head -c 200
# Host 嗰度 curl 返出嚟對比
curl -s http://localhost/ | grep -oE 'index-[A-Za-z0-9_-]+\.js'
# 兩個 hash 要 match, 唔 match = nginx serve 緊舊 image

# 3. Force rebuild 一個 dummy file
touch apps/web/src/.force-rebuild
docker compose build web   # 應該見到 source COPY stage 唔係 CACHED
rm apps/web/src/.force-rebuild

Elysia backend 都有同樣問題, 一樣用 --no-cache fix。

⚠️ Bun `export *` 唔可靠 re-export named consts 跨 module (2026-06-05 crm-system Day 7 真實撞牆)

SyntaxError: Export named 'ALL_PERMISSIONS' not found in module '/app/packages/shared/src/index.ts'.
ReferenceError: PERMISSIONS is not defined
      at /app/packages/shared/src/index.ts:3:28

Workaround (推薦, 5 秒 fix): 個 index file explicitly import 個 const, 然後 export const 重新 export:

// packages/shared/src/index.ts
import { PERMISSIONS } from './permissions';
export * from './permissions';               // keep re-export 俾其他 consumers
export const ALL_PERMISSIONS: readonly string[] = Object.freeze(
  Object.keys(PERMISSIONS)
);

咁 ALL_PERMISSIONS 喺 index file 範圍就 explicit defined, Bun runtime resolve 到。@crm/shared consumer 一樣用 import { ALL_PERMISSIONS } from '@crm/shared'。

Alternative (更穩但 verbose): 完全唔用 export *, 改用 explicit named export 喺每個 consumer file:

// ❌ 唔好
export * from './permissions';

// ✅ 改
export { PERMISSIONS, USER_ROLES, type Permission, type UserRole } from './permissions';

Detection 訊號:

Boot log 出 Export named 'X' not found 但個 const 明明喺子 module 寫咗 export const X
或者 ReferenceError: X is not defined 喺個 re-export 嘅 index file 自己 (index.ts:3:28 之類)
bun run src/index.ts 撞, 但 node src/index.ts / tsx src/index.ts 唔撞

⚠️ Prisma client model names 唔 export (2026-06-05)

Fix: Re-export packages/db/src/index.ts 入面只列 enums:

export { UserRole, QuotationStatus, DealStatus, /* etc */ } from '@prisma/client';
// ❌ 唔好: export { PipelineStage } from '@prisma/client'  // runtime crash
// ✅ 改用: prisma.pipelineStage.findMany() 或者 type Prisma.PipelineStage

⚠️ Tailwind v3 vs v4 — shadcn-style setup 仍要 v3 (2026-06-05)

Fix: For shadcn/ui-style projects, 用 Tailwind v3:

bun add -d tailwindcss@3 postcss autoprefixer

加 postcss.config.js, tailwind.config.js (有 content + theme.extend), index.css 用 @tailwind base/components/utilities. 唔好用 v4 嘅 @import "tailwindcss" syntax.

⚠️ shadcn-style token 唔可以漏 — `popover` / `card-foreground` / `destructive-foreground` 撞 (2026-06-06 crm-system 真實撞牆)

crm-system 真實情況 (2026-06-06):

tailwind.config.js 嘅 theme.extend.colors 有: border, input, ring, background, foreground, primary, secondary, muted, accent, destructive, card
冇: popover, popover-foreground, card-foreground, destructive-foreground
quotation-builder.tsx 嘅 ProductAutocomplete / ServiceAutocomplete panel 用 bg-popover → render 出嚟係透明 → David 報 bug 「autocomplete 透底」

Fix — 對齊 shadcn 完整 token set: tailwind.config.js 嘅 colors 要齊以下 shadcn-ui HSL 變量 (crm-system 已經用緊 hsl() 而非 oklch(), 唔好混):

// tailwind.config.js — theme.extend.colors
colors: {
  border: 'hsl(214.3 31.8% 91.4%)',
  input: 'hsl(214.3 31.8% 91.4%)',
  ring: 'hsl(222.2 84% 4.9%)',
  background: 'hsl(0 0% 100%)',
  foreground: 'hsl(222.2 84% 4.9%)',
  primary: {
    DEFAULT: 'hsl(222.2 47.4% 11.2%)',
    foreground: 'hsl(210 40% 98%)',
  },
  secondary: {
    DEFAULT: 'hsl(210 40% 96.1%)',
    foreground: 'hsl(222.2 47.4% 11.2%)',
  },
  destructive: {
    DEFAULT: 'hsl(0 84.2% 60.2%)',
    foreground: 'hsl(210 40% 98%)',
  },
  muted: {
    DEFAULT: 'hsl(210 40% 96.1%)',
    foreground: 'hsl(215.4 16.3% 46.9%)',
  },
  accent: {
    DEFAULT: 'hsl(210 40% 96.1%)',
    foreground: 'hsl(222.2 47.4% 11.2%)',
  },
  popover: {
    DEFAULT: 'hsl(0 0% 100%)',
    foreground: 'hsl(222.2 84% 4.9%)',
  },
  card: {
    DEFAULT: 'hsl(0 0% 100%)',
    foreground: 'hsl(222.2 84% 4.9%)',
  },
},

// ❌ 唔好 (如果 popover token 冇 define)
<div className="bg-popover border rounded shadow-lg">…</div>

// ✅ Quick fix 1 (component-local, 唔改 config)
<div className="bg-white border border-border rounded shadow-lg">…</div>

// ✅ Proper fix 2 (config-level, 一改搞掂哂)

跟 tailwind.config.js 嘅 border 已經有, 所以 border utility 仍 emit 1px border-color: hsl(214.3 31.8% 91.4%), 唔使改。但 bg-popover 冇 token 會 silently omit。border 配 bg-popover 唔 work 因為個 panel 仍然透明, 只係個 outline 顯示到。

Detection (撞牆必做):

computed style 確認:

// 喺 browser DevTools console
const el = document.querySelector('[class*="bg-popover"]');
window.getComputedStyle(el).backgroundColor
// Expected: "rgb(255, 255, 255)"  ← transparent 撞 "rgba(0, 0, 0, 0)"

grep 全 codebase 嘅 missing token:

rg "bg-(popover|card-foreground|popover-foreground|destructive-foreground|muted-foreground)" apps/web/src
# 對比 tailwind.config.js 嘅 colors key

Tailwind JIT 唔報錯: 佢 silently omit 唔存在嘅 utility class, 所以 bun run build 唔會 fail。必須用 browser 真實視覺確認, 唔可以信 build pass。

Quick fix 路徑之後必須 grep 全部 other occurrences (2026-06-06 crm-system 真實撞牆)

Action — Quick fix 之後必須跑:

# 1. grep 全 codebase 嘅 utility class 對比 tailwind config 嘅 colors key
rg "bg-(popover|card|accent|secondary|muted|primary|secondary-foreground|popover-foreground|card-foreground|muted-foreground|accent-foreground|destructive-foreground)" apps/web/src

# 2. 對比 tailwind.config.js theme.extend.colors 嘅 key
node -e "console.log(Object.keys(require('./tailwind.config.js').theme.extend.colors).join('\n'))"

# 3. 差集 = missing token, 逐個 confirm 要 quick-fix 定要改 config

Hermes safety net — 將呢個 grep 加到 dev verify:

# 喺 ~/www/<project>/scripts/check-tailwind-tokens.sh (可重 run)
#!/bin/bash
set -e
cd ~/www/<project>
CONFIG_KEYS=$(node -e "console.log(Object.keys(require('./apps/web/tailwind.config.js').theme.extend.colors).join('\n'))" | sort)
USED=$(rg -oN "bg-(popover|card|accent|secondary|muted|primary|secondary-foreground|popover-foreground|card-foreground|muted-foreground|accent-foreground|destructive-foreground)" apps/web/src | sed 's/.*\(bg-[a-z-]*\).*/\1/' | sort -u)
MISSING=$(comm -23 <(echo "$USED") <(echo "$CONFIG_KEYS" | sed 's/^/bg-/'))
if [ -n "$MISSING" ]; then
  echo "❌ Missing tailwind tokens: $MISSING"
  exit 1
fi

Why 兩個 patch path 都要 grep:

Path A (改 config): 一處改搞掂哂, 之後 token 對齊 shadcn 標準
Path B (改 component): 只 fix 一個, 但 codebase 其他位用同一個 bg-popover 仍然會 silently transparent。只 fix 1 個 = David 將來會撞第 2、第 3 次同一個 bug。

⚠️ LSP diagnostics stale after rapid patches — `docker compose build` 是 source of truth (2026-06-06 crm-system 真實撞牆)

根因 (3 個 stack 同時撞):

LSP cache: Hermes 嘅 LSP daemon 對連續 patch edit 嘅 cache invalidation 唔可靠。同 session 內改咗 N 個 patch,LSP 仍報 N 步前嘅 state
LSP 唔跨 file analyse TypeScript 個 exact type narrowing:對於 c => implicit any、status: string cast、prop missing 等 issue,LSP 行 type-check 嘅 view 唔等於 tsc --noEmit 嘅 view
@ts-nocheck 喺部分 file 開咗:有啲 route file 用 // @ts-nocheck 避 Elysia 1.2 d.ts noise(見上面),LSP 對呢類 file 完全唔 typecheck,但 docker compose build 仍會 run tsc 對其他 file 報錯

Detection 訊號 (邊個時候 LSP 唔可信):

報錯 line number 對唔上 file 內容 (e.g. LSP 報 line 355 但 file 已經 250 行)
報錯話某 prop 唔存在,但我頭先 patch 明明加咗
報錯話 c: (parameter) c: any implicit,但我有 typed 過
報錯話 status: string assignable error,但我已經用 as Company['status'] cast

正確 workflow (推薦):

# 改完 frontend file 永遠跑呢個 — 唔好睇 LSP
cd ~/www/<project>
docker compose build web 2>&1 | grep -E 'error TS|failed|exit code|DONE' | head -10
# Expected: 0 個 error TS line + 1 個 "DONE" 喺 #N 階段
# If 有 error TS: 嗰個係真正嘅 type error, 要 fix
# If 冇 error TS: LSP 嘅 noise 全部 ignore, 繼續 commit

Time budget:

docker compose build web 第一次 (cold): ~90 秒
第二次之後 (cache hit): ~20-30 秒
比起 chase LSP 假報錯再 fix code 再 build 嘅 loop,直接 docker compose build 一早做 5 倍快

Anti-pattern (我犯過):

# ❌ 唔好
patch file
見 LSP 報 error
patch 又改
見 LSP 仍報舊 error
patch 又改再改
... 3-4 個 patch 之後先 build ...
最後 build pass, 但 file 已經改到冇得救要 reset

Correct pattern:

# ✅ 好
patch file
直接 docker compose build web
睇 build output
有 error 就 patch 嗰個真實 issue
冇 error 就繼續 — 唔好睇 LSP

Generic rule (套用成個 stack):

Backend: docker compose build api 係 source of truth (LSP 對 Elysia route 嘅 noise 仲多,因為 @ts-nocheck + d.ts bug)
Frontend: docker compose build web 係 source of truth (LSP 對 React 嘅 as cast / generic 推唔到 type 嘅情況仲多)

⚠️ `bun.lock` 不被 npm / snyk 認 — 紅線 18 CVE 掃描盲點 (2026-06-07 crm-system code review 真實撞牆)

症狀: 跑 npm audit 喺一個 bun-managed monorepo (bun.lock 而唔係 package-lock.json) 撞:

npm error code ENOLOCK
npm error audit This command requires an existing lockfile.
npm error audit Try creating one first with: npm i --package-lock-only

Fix (推薦, 30 秒): 用 bun audit 而唔係 npm audit:

# ❌ 唔好
npm audit --json
# → ENOLOCK (bun.lock not recognized)

# ✅ 好 (bun 1.2+ 內建)
bun audit
# → 解析 bun.lock + 對 npm registry check 已知 CVE

如果 bun audit 都 fail (bun 版本太舊): Generate 一個 npm-compatible lockfile 一次過, 之後 audit 用 npm:

# 在 root 一次過
npm i --package-lock-only   # 根據現有 package.json + bun.lock generate package-lock.json
npm audit --json > /tmp/cve.json
# 然後 commit 走 package-lock.json 都可以 (但會同 bun.lock drift)

Production CI 必加 step (ship gate):

# 喺 CI YAML (.github/workflows/ci.yml) 加
- name: CVE scan
  run: |
    bun audit --json > /tmp/audit.json
    HIGH=$(python3 -c "import json; d=json.load(open('/tmp/audit.json')); print(d.get('metadata',{}).get('vulnerabilities',{}).get('high',0))")
    CRIT=$(python3 -c "import json; d=json.load(open('/tmp/audit.json')); print(d.get('metadata',{}).get('vulnerabilities',{}).get('critical',0))")
    if [ "$HIGH" -gt 0 ] || [ "$CRIT" -gt 0 ]; then
      echo "❌ Critical/High CVE > 0, blocking merge (紅線 18)"
      exit 1
    fi

Lockfile 可信度 pitfall (related): bunfig.toml 嘅 [install] exact = false 默認 = 用 ^5.6.3 caret range, build 唔 reproducible, 每個 developer 落地拎到唔同 patch version:

# bunfig.toml
[install]
exact = true    # 改 true, lockfile 死鎖 exact version

Detection 撞牆嘅方法 (ship-readiness review 必做):

# 1. 確認有 lockfile
ls -la bun.lock package-lock.json 2>/dev/null
# Expected: 至少 bun.lock (bun project) 或 package-lock.json (npm project)

# 2. 試跑 audit
timeout 30 bun audit 2>&1 | head -20
# Expected: 有 vulnerability table 列出
# 如果 error: 上面 fix 步驟

# 3. 確認 exact mode
grep "exact" bunfig.toml
# Expected: exact = true

⚠️ RBAC coverage matrix 1-liner audit — 1 個 grep 揭 14 route 嘅 access control gap (2026-06-07 crm-system 真實撞牆)

Fix (1-liner, 推薦 for 任何 RBAC-driven Elysia / Express / FastAPI project):

# 對齊 pattern: <route file> 用 authContext 幾多次 + requirePermission 幾多次
cd ~/www/<project>
for f in apps/api/src/routes/*.ts; do
  name=$(basename "$f" .ts)
  ac=$(grep -c "authContext" "$f" 2>/dev/null)
  perm=$(grep -c "requirePermission" "$f" 2>/dev/null)
  printf "%-20s authContext=%-3d requirePerm=%d\n" "$name" "$ac" "$perm"
done | sort -k2 -t= -n
# ↑ sort by authContext count ascending = 公開 routes 浮上面

Expected output (crm-system 2026-06-07 真實數字):

ai-config            authContext=0  requirePerm=1   ← 0 auth 但有 perm: 內部 RBAC OK 但 anonymous 撞 401 = 設計 OK
chat                 authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
company              authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
contact              authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
deal                 authContext=0  requirePerm=0   ← 🚨 公開 endpoint 寫 DB → CRIT
settings             authContext=0  requirePerm=2   ← perm 蓋住, 但 anonymous 撞 401 (OK)
audit                authContext=2  requirePerm=2   ← ✅
man-day-role         authContext=4  requirePerm=3   ← ✅
roles                authContext=2  requirePerm=2   ← ✅

Generic rule (套用全部 backend stack):

Elysia: authContext / requirePermission (呢個 skill 嘅 pattern)
Express: requireAuth / requireRole / requirePermission
FastAPI: Depends(get_current_user) / Depends(require_role)
NestJS: @UseGuards(AuthGuard) / @Roles(...) decorator

換 pattern name 即可, framework 唔重要。

Common hit 真實 cases (撞過嘅):

POST /auth/register 冇 requirePermission — 公開註冊 + 可以 self-select role: 'ADMIN' = 公開 internet 變 admin。Fix: 加 requirePermission('user:create') + body schema 刪 role field (新 user 預設 SALES, admin 自己 promote via PATCH /users)
List endpoint 公開 (e.g. GET /companies) — 公開讀 = PII 漏 (email, phone, credit limit)。Fix: 加 requirePermission('company:read')
AI write tool 公開 — /chat/send 觸發 prisma.company.create 以 system actor 寫 = silent DB write without attribution。Fix: 加 requirePermission('chat:use') + audit log 入面 actorId 一定要有
Status / health endpoint RBAC 不一致 — /api/ai/config/status 公開 = 偵察 admin 環境狀態。Fix: 一律 requirePermission('xxx:read') 蓋住, status 都要

Related pattern (RBAC permission drift): 三個 source of truth 要對齊:

packages/shared/src/permissions.ts PERMISSIONS map (static, system roles)
apps/api/src/middleware/rbac.ts requirePermission('xxx') 字符串 (hard-coded in route files)
DB RolePermission table (runtime state, custom roles)

// 跑一次: 列舉 permissions.ts 嘅 keys, grep requirePermission(, 確認每個 key 至少 1 個 route 用
test('permission coverage', () => {
  const declared = new Set(Object.keys(PERMISSIONS));
  const used = new Set<string>();
  for (const f of glob.sync('apps/api/src/routes/*.ts')) {
    for (const m of fs.readFileSync(f, 'utf8').matchAll(/requirePermission\(['"]([^'"]+)['"]\)/g)) {
      used.add(m[1]);
    }
  }
  const unused = [...declared].filter(p => !used.has(p));
  expect(unused).toEqual([]);  // 0 unused perms
});

⚠️ `tsc --noEmit` 報 30+ silent type errors 但 runtime OK — typecheck 唔可以靠 build 兜底 (2026-06-07 crm-system 真實撞牆)

根因 (Elysia + bun 雙重 source-of-truth drift):

Elysia 1.2 d.ts 同 TypeScript 5.x 嘅 type inference 衝突(see 上面「Elysia 1.2 d.ts broken」)— set.status typed 做 number | "Unauthorized" | ... literal union, 好多 cast 寫得唔準
prisma.aiConfig 唔存在 but code 用緊 — Prisma client 唔 export 該 model (見下面「Prisma client model names 唔 export」)
as never cast 喺 handler 內部太多 — body validation 通過後 body 嘅 type 係 unknown, cast 做 as never 漏 type
Bun runtime 唔 typecheck (dev mode bun run src/index.ts 唔 invoke tsc) — runtime 唔 care
Dockerfile 嘅 bun --env-file=... src/index.ts production entry 仍然唔 typecheck
Elysia 1.2 type check chain 對多個 .use() plugin 嘅 context propagation 唔 reliable — derive 出嘅 userId 個 type 喺 route handler 入面係 string | null, 但喺 onBeforeHandle plugin boundary 變 unknown

撞牆真實例子 (crm-system 2026-06-07):

src/lib/context.ts(9,21): error TS2339: Property 'jwt' does not exist on type '...'.
src/routes/ai-config.ts(57,30): error TS2339: Property 'aiConfig' does not exist on type 'PrismaClient<...>'.
src/routes/ai-config.ts(199,9): error TS2322: Type '"AI_CONFIG_UPDATED"' is not assignable to type 'AuditAction'.
src/routes/contact.ts(33,50): error TS2353: ...'activities' does not exist in type 'ContactInclude<DefaultArgs>'.
src/routes/deal.ts(152,7): error TS2322: Type '"DEAL_STAGE_CHANGED"' is not assignable to type 'AuditAction'.
+ 25+ more

Risk:

prisma.aiConfig 唔 export 但 code 用緊 = prod 第一次 hit 嗰個 endpoint 一定 500 (Prisma client 識唔到 model)
'DEAL_STAGE_CHANGED' as AuditAction 唔 cast-safe = audit log 寫入失敗 silently
as never body cast = 可以 inject 任意 fields 到 Prisma create (雖然 Prisma schema filter 唔存在 column, 但 passwordHash / isActive 呢類 sensitive field 風險)

Fix (3 個 step, ship gate 必做):

# 1. 在 root 加 unified typecheck (唔好靠個別 package.json 嘅 typecheck script)
cd ~/www/<project>
cat > scripts/typecheck-all.sh <<'EOF'
#!/bin/bash
set -e
echo "=== apps/api ==="
cd apps/api && bunx tsc --noEmit --skipLibCheck
cd ../..
echo "=== apps/web ==="
cd apps/web && bunx tsc --noEmit --skipLibCheck
cd ../..
echo "=== packages/db ==="
cd packages/db && bunx tsc --noEmit --skipLibCheck
EOF
chmod +x scripts/typecheck-all.sh

# 2. 在 CI 必跑 (唔可以 skip)
# .github/workflows/ci.yml:
# - name: TypeScript check
#   run: ./scripts/typecheck-all.sh
# (冇 typecheck pass = 唔 merge)

# 3. Fix 撞到嘅 error — 唔可以加 @ts-nocheck 蓋住
#   - 重新 generate prisma client: cd packages/db && bunx prisma generate
#   - AuditAction / ItemType 等 enum 加返入 schema
#   - Casts 用 'as Company' 而唔係 'as never' (cast 對 schema 唔等於 bypass validation)
#   - remove 所有 @ts-nocheck (Dockerfile `bun run` 跳 typecheck, 唔代表可以 silent type drift)

Critical: Dockerfile 唔可以加 typecheck step 入 build:

# ❌ 唔好
RUN bun run typecheck   # 加咗 build 會 hang 在 ts error, 個 image 永遠 build 唔到
                        # 即使 type errors 應該 fix, build 唔可以 fail 因為 type error
                        # (本地 fix 之後先 push)
#
# ✅ 好
# typecheck 留喺 CI stage + pre-commit hook, Dockerfile 維持 `bun install + bun run`

Detection 工具 (code review 必跑):

# 1. 數 typecheck errors
cd ~/www/<project> && timeout 60 bunx tsc --noEmit --skipLibCheck 2>&1 | grep -c "error TS"
# Expected: 0 (ship gate 必過)
# 如果 > 0: 紅線 16 嘅 test coverage fail + type drift blind spot

# 2. 數 @ts-nocheck 數量
rg -l "@ts-nocheck" apps/ packages/
# Expected: 0 (一係 remove 一係 真嘅 disable 嘅 file 加理由 comment)
# 如果 > 0: 全部逐個 review, 確認係 Elysia 1.2 d.ts 真正 broken 而唔係偷懶

# 3. 數 'as never' cast 數量
rg -c "as never" apps/api/src/ | awk -F: '{sum+=$2} END {print sum}'
# Expected: 0 (cast 應該 'as ConcreteType')
# 如果 > 5: code review 必 grep 全部 location 改 'as ConcreteType' 對應 Prisma model

⚠️ Self-register-as-admin trap — `POST /auth/register` 公開 + role 喺 body (2026-06-07 crm-system 真實撞牆)

症狀: RBAC 系統有 ADMIN / SALES / VIEWER 三個 role 喺 DB, 有 requirePermission('user:create') middleware. 但 register endpoint 寫:

// ❌ 唔好 — RBAC 完整但 register endpoint 公開 self-service admin
.post('/register', async ({ body, set }) => {
  const { email, password, name, role } = body as {  // ← role 喺 body
    email: string; password: string; name: string;
    role?: 'ADMIN' | 'SALES' | 'VIEWER';
  };
  // ... 直接 prisma.user.create({ data: { ..., role: role ?? 'SALES' } })
}, {
  body: t.Object({
    email: t.String({ format: 'email' }),
    password: t.String({ minLength: 8 }),
    name: t.String({ minLength: 1 }),
    role: t.Optional(t.Union([         // ← 接受 role 喺 body
      t.Literal('ADMIN'),
      t.Literal('SALES'),
      t.Literal('VIEWER'),
    ])),
  }),
})

Risk (公開 internet + body role = 公開 internet 變 admin):

任何人用 curl -X POST /auth/register -d '{"email":"a@b.c","password":"xxx","name":"Hacker","role":"ADMIN"}' → 攞到 ADMIN token
如果有 seed 預設 david@crm.local / admin123 即係 hacker 直接用 david@crm.local 重置密碼 / 喺自己個 account 升級

Fix (推薦, 5 分鐘):

// ✅ 好
import { authContext } from '../lib/context';
import { requirePermission } from '../middleware/rbac';

.post('/register', async ({ body, set }) => {
  const { email, password, name } = body as {  // ← role 唔再喺 body
    email: string; password: string; name: string;
  };
  // ... prisma.user.create({ data: { email, name, passwordHash, role: 'SALES' } })
  // 預設 SALES, admin 自己用 PATCH /users/:id 升級
}, {
  body: t.Object({
    email: t.String({ format: 'email' }),
    password: t.String({ minLength: 8 }),
    name: t.String({ minLength: 1 }),
    // ← 唔再接受 role
  }),
})
// 同時 add: 真正 invite flow 應該 admin 用 PATCH /users/:id invite

// Alternative 1 (use the existing authContext + requirePermission 蓋住)
.use(authContext)
.use(requirePermission('user:create'))   // ← 只有 admin 可以 create user

// Alternative 2 (disable self-service,只 invite via admin UI)
// 條 route 直接 disable, body validation 唔再 register endpoint

Variant 撞牆 — status endpoint 唔 gated:

// ❌ 唔好
.get('/ai/config/status', () => {
  return prisma.aiConfig.findUnique({ where: { id: 1 }, select: { configured: true, model: true } });
})
// 公開偵察 admin 環境狀態 = recon 階段有用 info

// ✅ 好
.use(authContext)
.use(requirePermission('ai-config:read'))
.get('/ai/config/status', ...)

Detection (code review 1-liner):

# 1. Check register / signup endpoint 有冇 permission
rg -A 1 "post\(['\"]/?(auth/)?(register|signup)" apps/api/src/
# 期望: 見到 .use(requirePermission(...)) 喺 register handler 之前
# 如果冇: 即係 self-service,加 fix

# 2. Check 全部 body schema 接受 role 嘅地方
rg "t\.(Union|Literal).*(ADMIN)" apps/api/src/
# 期望: 0 個 (role 唔應該喺 public-facing body schema)

# 3. Check 全部 GET endpoint 嘅 status / config 探測
rg "get\(['\"]?/.*(status|health|config)" apps/api/src/
# 期望: 全部都有 .use(requirePermission) 喺之前 (除咗真正 public health check)

Generic rule (套用所有 SaaS 項目):

Self-service signup → role 永遠 default 'USER' / 'MEMBER' / 'CUSTOMER', 唔可以 self-select 'ADMIN'
Admin invite flow → admin 自己 PATCH /users/:id 升級
任何 GET /status /config endpoint → 一律 permission-gated, status 都要

⚠️ Subagent 600s/63-call timeout 撞 long refactor 任務 (2026-06-06 crm-system Day 11 真實撞牆)

根因:

bun run typecheck 喺 Elysia strict TS 5 + 大量 as never cast 嘅 project 入面,第一次 pass 通常撞 3-5 個 error,subagent 自己 fix 之後再 typecheck,loop。
每個 typecheck pass 要 ~30 秒(subagent 連 import 5-6 個 files + tsc 全行)。
Long refactor 加埋 typecheck loop + multiple file 嘅 read_file verification → 600s 唔夠用。

接管 pattern (推薦, 2026-06-06 crm-system Day 11 用咗):

# 1. 派 subagent,設定期望 subagent 跑 ~5 phase
delegate_task(goal="...", context="...", toolsets=['terminal', 'file', 'skills'])

# 2. 收到 timeout 唔好報錯
# 3. 自己 check subagent 已經 create 咗咩 file
search_files(pattern="*.tsx", path="apps/web/src/components", target="files")

# 4. 對比 plan 入面嘅 expected file list,睇邊個 phase 未做
# 5. 直接 read 嗰啲 file 確認 partial progress 嘅 quality

# 6. 接手未做嘅 phase (parent 自己跑, 或者再 delegate 細啲嘅範圍)

# 7. 最終 typecheck 一齊跑 (parent 跑, 唔好 subagent 跑)
terminal(command="cd ~/www/crm-system/apps/web && bun run typecheck")

Plan subagent 嘅 5 個 control 點:

scope 細啲: 唔好一個 goal 包 5 phase。每 phase 一個 subagent。Day 11 嗰個 subagent 撞牆因為 5 phase 太闊。
明確講 typecheck 喺 parent 跑: 個 subagent 只需要做 4 件事 — 改 file, 改 import, 改 type signature。唔需要 typecheck 100% pass。Subagent 改 type signature 至 TS compile 到就 OK,parent 接手跑 typecheck + fix 邊度 miss。
Checkpoint 寫低: Subagent 應該每改完 1-2 個 file 寫低 "Phase N done, file X modified, file Y created"。咁 timeout 之後 parent 可以 grep checkpoint 知住乜。
Avoid 在 subagent 度跑 long command: 唔好喺 subagent 入面 bun run build / vite build (5+ 分鐘),改用 tsc --noEmit 30 秒。
Accept partial completion: Subagent 個 summary 報 "4/5 phases done, phase 5 撞 hit type error X", parent 接手 fix X 就好。唔好 reject partial 然後再 delegate 全 work。

Plan size 參考 (Day 11 嗰個嗰個跑咗 63 個 call, 撞 timeout):

1 phase (1 file major edit) → ~10-15 calls, 5 min OK
3 phases (3 files + 1 verify) → ~30 calls, 15 min borderline OK
5 phases (5+ files + multi-step verify) → >50 calls, 撞 timeout 高。要 split
8+ phases → 必須 split,絕對唔好一個 goal 包

⚠️ Hermes redact `***` 整死 shell-based JWT tests (2026-06-05)

Fix: 用 python3 -c 一次性做 login + authed requests:

import json, urllib.request
token = json.loads(urllib.request.urlopen(urllib.request.Request(
  'http://localhost:3000/auth/login',
  data=json.dumps({'email':'a','password':'b'}).encode(),
  headers={'Content-Type':'application/json'})).read())['token']
data = json.loads(urllib.request.urlopen(urllib.request.Request(
  'http://localhost:3000/resource',
  headers={'Authorization': f'Bearer {token}'})).read())
print(data)

Python script 入面 Hermes redact 唔 trace 入去, 完整 token 留喺 memory, 之後先 redact output。

更安全嘅 fix (2026-06-05 crm-system Day 4 試過): Hermes 喺 terminal() 將 *** literal 自動 redact 連 print( 都波及, 寫 bash 用 awk '{print $1}' 都會壞. 解決:

將 token 寫入 /tmp/crm_token.txt (no echo)
Bash 用 tr -d '\\r\\n' < /tmp/crm_token.txt strip newline
用 printf 'Authorization: Bearer *** /tmp/crm_hdr.txt 然後 curl -H @/tmp/crm_hdr.txt 完全 avoid token 喺 process args 出現

最簡單 fallback (推薦): execute_code 跑 Python 直接打 urllib.request (個 sandbox *** 唔 trigger, full token 留 memory 唔 echo)。

Day 5 完整 step-by-step curl -H @filename 模式 (推薦 for bash smoke test):

# 1. Login 拎 token, 直接寫入 file 唔 echo
curl -fsS -X POST http://localhost/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@crm.local","password":"admin123"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])' \
  > /tmp/crm_token.txt

# 2. 驗證 token length (避免 file 空白 / 拎錯 field)
echo "Token length: $(wc -c < /tmp/crm_token.txt)"

# 3. 寫完整 Authorization header 入 file
#    ⚠️ Token 內部唔可以有 newline; 喺 json.load print 出嚟個 string 唔包 newline
{ printf 'Authorization: Bearer *** cat /tmp/crm_token.txt; printf '\r\n'; } > /tmp/crm_hdr.txt
od -c /tmp/crm_hdr.txt | head -2   # 驗證格式

# 4. 用 curl -H @file 帶 token 出去
curl -fsS http://localhost/api/users -H @/tmp/crm_hdr.txt

⚠️ Docker container DB migration when host can't reach postgres port (2026-06-05 crm-system Day 5)

解決 (4 steps):

手寫 SQL 放喺 packages/db/prisma/migrations/<timestamp>_<name>/migration.sql (CREATE TYPE / TABLE / INDEX / FK),Prisma 5 schema @@map 要同 SQL table name 一致

docker exec 跑 SQL:

docker exec -i crm-postgres psql -U crm -d crm_system -f /dev/stdin < \
  packages/db/prisma/migrations/20260605000000_add_audit_log/migration.sql

手動 insert _prisma_migrations row mark as applied,否則 entrypoint 嘅 prisma migrate deploy 將來會 complain "drift detected":

docker exec -i crm-postgres psql -U crm -d crm_system -c \
  "INSERT INTO \"_prisma_migrations\" (id, checksum, migration_name, finished_at, applied_steps_count) VALUES ('<unique-id>', '', '<timestamp>_<name>', NOW(), 1);"

⚠️ migration_name 冇 unique constraint,要 unique id column (ON CONFLICT (id) DO NOTHING 即可)

Host 行 bunx prisma generate 重新 generate client 識新 model:
```
env $(grep -v '^#' .env | xargs) bunx prisma generate
```

驗證:

docker logs crm-api --tail 20
# Expected: "2 migrations found in prisma/migrations" + "No pending migrations to apply"

Alternative (更麻煩): 暫時改 docker-compose.yml expose 5432:5432,host 跑 migration,改返 expose。唔建議 因為 re-up stack 會忘記 uncomment。

詳細 SQL 範本 + 真實 audit_logs migration + 23 個 action enum: 見 references/2026-06-05-crm-system-rbac-audit.md 嘅「Docker local dev 嘅 migration 撞牆 + 解決」section。

⚠️ Prisma migration folder rename 嘅 silent trap (2026-06-05 crm-system Day 6 真實撞牆)

Error: P3009
migrate found migration `20260605020000_add_audit_log` to apply, but the database already has a record of a migration with the same name at the same position.

或者更壞嘅:CREATE TABLE audit_logs 撞 duplicate 失敗 → container entrypoint 死 → API 唔起。

Fix (3 steps, 之後先 git commit):

# 1. Rename folder (filesystem)
mv packages/db/prisma/migrations/20260605000000_add_audit_log \
   packages/db/prisma/migrations/20260605020000_add_audit_log

# 2. Update _prisma_migrations table row 同 filesystem 同步
docker exec -i crm-postgres psql -U crm -d crm_system -c \
  "UPDATE _prisma_migrations SET migration_name = '20260605020000_add_audit_log' \
   WHERE migration_name = '20260605000000_add_audit_log';"

# 3. Verify
docker exec -i crm-postgres psql -U crm -d crm_system -c \
  "SELECT migration_name FROM _prisma_migrations ORDER BY started_at;"
# 期望: 20260605020000_add_audit_log (新名)

然後先 git commit 同 push。唔好順序倒轉 — 改 file 但未 update db 之前 entrypoint 會壞,build 失敗即 production incident。

ls packages/db/prisma/migrations/ | sort
# 最早嘅 timestamp 即係 init

⚠️ nginx SPA `root` directive 唔可以漏 (2026-06-05 crm-system Day 6 真實撞牆)

David 6/05 fix commit d2b06d1 真實修法:

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;       # ← 必加! 否則 SPA fallback 404
    index index.html;

    # /api reverse proxy
    location /api/ {
        proxy_pass http://crm-api:3001/;
        # ... (略) ...
    }

    # SPA fallback (named location, 唔用 try_files $uri/ = 避免 cycle)
    location / {
        try_files /index.html =404;   # 改用 /index.html (absolute) 而唔係 $uri/
    }
}

Key points:

root 必須喺 server {} (或者 http {}) scope 設,唔可以擺入 location / 入面(雖然 syntax 接受,但 context 行為唔同)
try_files 嘅 argument 用 /index.html (leading slash 絕對路徑) 而唔係 $uri/ (會 cycle)— 配合 root nginx 解析 /index.html 做 root + /index.html = /usr/share/nginx/html/index.html ✅
完整能 work 嘅 nginx config (David 已 push 嘅版本) 喺 docker-mac-arm64-elysia-vite skill 嘅 templates/full-local-stack.md

Smoke test (after build / deploy):

curl -s -o /dev/null -w "%{http_code}\n" http://localhost/              # 期望 200
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/quotations  # 期望 200 (SPA fallback)
curl -s -o /dev/null -w "%{http_code}\n" http://localhost/assets/index.js  # 期望 200 (Vite hashed assets)

如果 / 返 200 但 /<sub-route> 返 404 → 即係 root directive 漏咗。

詳細 Day 6 nginx fix context: 見 references/2026-06-05-crm-system-docker-deploy.md 嘅「nginx SPA pitfall」section。

⚠️ API wrapper boundary normalize for Prisma relation field-name drift (2026-06-06 crm-system Day 12)

Component 訪問 s.manDays.length / .map() throw Cannot read properties of undefined
Defensive s.manDays?.length ?? 0 救表面, 但渲染 "0 個 man-day role" 即係 silent data loss
User 撞到嘅唔係 500, 而係「冇 data 顯示」— 仲難 debug

真正 fix (推薦, 套用所有 Prisma relation + frontend type alias 不一致嘅情況):

喺 apps/web/src/lib/api.ts 個 API wrapper boundary 加 normaliseEntity helper, 每個 list / get / create / update entry point 統一 pipe:

function normaliseService<T extends { manDays?: unknown; manDayLines?: unknown }>(s: T): T {
  const manDaysFromWire = (s as { manDayLines?: ServiceManDay[] }).manDayLines;
  if (manDaysFromWire !== undefined) {
    return { ...s, manDays: manDaysFromWire as ServiceManDay[] };
  }
  return s;
}

export const servicesApi = {
  list: (params) =>
    request<...>('/services?...').then((r) => {
      const items = Array.isArray(r) ? r : r.items;
      return items.map(normaliseService);   // ← 每個 item normalize
    }),
  get: (id) => request<Service>(`/services/${id}`).then(normaliseService),
  create: (data) => request<Service>('/services', { ... }).then(normaliseService),
  update: (id, data) => request<Service>(`/services/${id}`, { ... }).then(normaliseService),
};

Generic rule (套用到所有 Prisma relation field name != frontend type field name):

Backend Prisma	Frontend type	命名衝突源
`manDayLines` (relation)	`manDays` (URL slug / business)	camelCase vs abbreviation
`quotationItems` (relation)	`items` (business 簡稱)	Prisma 自動加 entity suffix
`serviceManDays` (model)	`manDays` (singular)	將來寫呢個 relation 要小心

Boundary normalize 一律喺 lib/api.ts wrapper 做, 唔好喺每個 component 重複。原因:

Single source of truth, 將來 backend 改 relation name 淨改 1 個 file
Component 寫 s.manDays 永遠 work, 後來人唔使知道 backend 嗰邊係 manDayLines
將來加 manDayLines → manDays migration / deprecation 都淨改 1 個 file

Defensive code (?? []) 喺 component 入面仍保留 (belt-and-suspenders):

// service-detail.tsx 即使 boundary normalize 將來 regress 都唔會 crash
setManDays((service.manDays ?? []).map((m) => ({ role: m.role, dayRate: m.dayRate, days: m.days })));

Detection 工具 (撞牆必做):

# 1. Component 訪問 field 嘅 pattern grep
rg "\.manDays\.|\.manDayLines\." apps/web/src
# 統一用 `manDays`, 有 `manDayLines` 嘅地方 = boundary normalize 漏咗

# 2. 對比 backend 嘅 wire format (Prisma relation name) vs frontend type
rg "manDays:|manDayLines:|manDayLines\?" apps/web/src/lib/api.ts
# 對比 packages/db/prisma/schema.prisma 嘅 field name

Generic 類比 — useQuery 個 generic type 同 boundary normalize:

// ❌ 唔好 (type 寫得啱但 runtime 唔 normalize)
const { data } = useQuery({
  queryKey: ['service', id],
  queryFn: () => servicesApi.get(id!),
});
// data.manDays 仍然 undefined!

// ✅ 改 (boundary normalize 喺 api.ts 統一做, useQuery caller 唔使知)
const { data } = useQuery({
  queryKey: ['service', id],
  queryFn: () => servicesApi.get(id!),  // returns Service with normalised manDays
});
// data.manDays 一定有

⚠️ Elysia `bun build` 撞 runtime code generation (2026-06-05 真實撞牆)

症狀: bun build src/index.ts --target=bun --outfile=dist/index.js [--minify] 喺 Elysia 1.2 build 成功, 但 image run 時 crash:

ReferenceError: vn is not defined        # 用 --minify
ReferenceError: client is not defined    # 用 --external @prisma/client

Workaround (推薦, 2026-06-05 crm-system Docker production 用): 唔好 bun build, 直接 COPY source 入 image:

# Builder stage — 淨係裝 deps + generate Prisma client
FROM oven/bun:1.2 AS builder
WORKDIR /app
COPY package.json bun.lock* ./
COPY packages/db/package.json packages/db/
COPY apps/api/package.json apps/api/
RUN bun install --frozen-lockfile
COPY . .
RUN bunx prisma generate --schema=packages/db/prisma/schema.prisma

# Runtime stage — COPY 整個 source, 直接 bun run
FROM oven/bun:1.2
WORKDIR /app
# Prisma engine binary + generated client (Bun workspaces hoist)
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/packages ./packages
COPY --from=builder /app/apps ./apps
COPY apps/api/docker-entrypoint.sh /usr/local/bin/entrypoint
RUN chmod +x /usr/local/bin/entrypoint
CMD ["/usr/local/bin/entrypoint"]

entrypoint.sh 用 cd /app/packages/db && bunx prisma migrate deploy && cd /app && bun run apps/api/src/index.ts 直接 source 模式啟動, 等於 dev mode 冇 --watch 嘅 production。

Web frontend 用 bun run build (Vite) 唔受影響, 因為 Vite 唔係 Elysia, minify 安全。

⚠️ Backend response shape 不一致 — frontend 要 normalize (2026-06-05)

Fix (frontend lib/api.ts): 用 Array.isArray 兼容兩種:

return request<{ items: T[]; total: number } | T[]>(url).then((r) =>
  Array.isArray(r) ? r : r.items
);

一致性建議 (backend): 全部 findMany route 都包成 { items, total, limit, offset } shape, 預留 pagination. 用 helper:

function paginated<T>(items: T[], total: number, limit: number, offset: number) {
  return { items, total, limit, offset };
}

Vite 8 quirk (詳細)

bun create vite@latest . -- --template react-ts 喺 Vite 8 會：

❌ 唔裝 react/react-dom/@vitejs/plugin-react
❌ 用 vanilla TS template (src/main.ts 唔係 tsx)
❌ 唔寫 vite.config.ts
✅ 寫 package.json 但 scripts 仍 vite dev/build

Fix：

npm install react react-dom @types/react @types/react-dom @vitejs/plugin-react
寫 vite.config.ts（含 react + tailwind plugin）
刪 src/main.ts, src/counter.ts, src/style.css, src/assets/
寫 src/main.tsx, src/index.css
index.html 改 <div id="root"> + src="/src/main.tsx"
改 tsconfig.json 加 "jsx": "react-jsx"

完整目錄結構

~/www/<project>/
├── backend/
│   ├── prisma/
│   │   ├── schema.prisma
│   │   ├── seed.ts
│   │   └── migrations/
│   ├── src/index.ts
│   ├── data/app.db
│   ├── .env
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx
│   │   ├── index.css
│   │   ├── api.ts
│   │   └── pages/{Home,Exam,Review,Stats}.tsx
│   ├── index.html
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── package.json
├── data.json (optional: 初始 data 喺呢度)
└── README.md

啟動 dev

# Terminal 1
cd ~/www/<project>/backend
bun --env-file=.env src/index.ts   # :3200

# Terminal 2
cd ~/www/<project>/frontend
npm run dev                        # :5173

Frontend 透過 Vite proxy 訪問 /api/* → localhost:3200。

Hermes execute_code / terminal 陷阱 (五個唔同嘅事, 唔好混淆)

情境	問題	Fix
`terminal()` 跑 `bun add <pkg>`	Hermes process scanner 見到 `bun` 就當 long-lived 攔截	改用 `npm install` 代替 (frontend 啱用)
`execute_code` 開 long-lived server (`Popen` + `sleep` + `terminate`)	sub-shell 一 exit, 個 process 一齊死, 個測試結果攞唔到	永遠用 `terminal(background=true)` 開 dev server, 之後用 `process(action='poll')` 監察
`execute_code` 內 `subprocess.run([..., "python3", ...])`	Hermes sandbox 嘅 python interpreter 同 system `/usr/local/bin/python3` 唔同, 裝嘅 package 唔共享	用 `/usr/local/bin/python3` 絕對路徑, 或 `subprocess.run([sys.executable, ...])`
`git commit -m "...\`code`..."` 寫多行 commit message	Shell 將 backtick 之間嘅 inline code 當 command substitution 解析執行, 撞 `command not found` 噪音, commit 仍成功但 body 嘅 inline code 全部被食走變空白	寫 commit message 入 file 然後 `git commit -F /tmp/msg.txt`。`bash <<EOF` 都會撞同樣問題(shell 解析), 必須 file 落地
`terminal(background=true)` 跑 `docker compose up -d --build`	Hermes 嘅 background process 唔 return exit code 0 即係 build 仍進行中(可能 5-15 min), 唔代表失敗	用 `process(action='poll')` 監察,或者 background 之後用 `process(action='wait', timeout=600)`,exit code 0 = build done 唔係 "container died"

⚠️ `docker compose up -d --build` 必然 trigger foreground warning — 一律 background (2026-06-06 crm-system 真實撞牆)

症狀: 喺 terminal() foreground 跑 cd ~/www/<project> && docker compose up -d --build 一定撞:

This foreground command appears to start a long-lived server/watch process.
Run it with background=true, verify readiness (health endpoint/log signal),
then execute tests in a separate command.

Fix (永遠咁用): 任何 docker compose command — up -d、up -d --build、up -d --force-recreate、build --no-cache — 一律 background=true + notify_on_complete=true:

# 喺 terminal tool 入面
terminal(
  command="cd ~/www/<project> && docker compose up -d --build 2>&1 | tee /tmp/compose-build.log",
  background=True,
  notify_on_complete=True,
  timeout=600,
)
# 跟住用 process(action='wait', timeout=600) 監察
# process(action='log') 撈 output 睇 "error TS" / "exit code: 2"

Foreground 必然撞 Hermes guard warning,即使有 -d flag 個 daemon 即刻 detach 都撞。

Verification after build (必須做, 因為 foreground 撞 warning 後 exit code 已經被蓋住):

# 1. Container 全部 healthy
docker ps --format 'table {{.Names}}\t{{.Status}}' | grep <service>

# 2. Bundle hash 真係新 (build cache 可能 skip source change)
curl -s http://localhost/ | grep -oE 'index-[A-Za-z0-9_-]+\.js'
docker exec <web-container> ls /usr/share/nginx/html/assets/
# 兩個 hash 對得齊 = new build 真係 deploy

# 3. 或者 force rebuild 一個 dummy file 試
touch apps/web/src/.force-rebuild && docker compose build web
# 應該見到 source COPY stage 唔係 CACHED
rm apps/web/src/.force-rebuild

⚠️ Build 撞「Cannot find name X」之前,先 grep 個 X 喺 codebase 邊度 define 過 (2026-06-06 crm-system 真實撞牆)

例子 (crm-system 2026-06-06):

// apps/web/src/pages/companies.tsx — WIP 改動引入咗呢行
import { DealDialog } from '@/pages/deals';   // ❌ 'DealDialog' is not exported from '@/pages/deals'

實際上 apps/web/src/pages/deals.tsx:345 已經有:

function DealDialog({...}) {  // ← internal function, 冇 export

Fix = 加 1 個 keyword 9 個 char:

// apps/web/src/pages/deals.tsx line 345
-export function DealDialog({...}) {     // 改 internal → exported
+export function DealDialog({...}) {

唔係寫新 apps/web/src/components/deal-dialog.tsx,唔係 import pages/deals.tsx 嘅 types / helpers,完全唔改 DealDialog 嘅 body。

Generic workflow (撞「Cannot find name X」/「X is not exported」必做):

唔好 assume 個 X 真係 missing:

# grep X 喺 codebase 邊度 define 過 (case sensitive)
rg "\bDealDialog\b" apps/web/src
# 期望: 見到一個定義(就算 internal function 都算)— 即係唔需要寫新
# 期望: 完全冇 hit — 先寫新

如果 internal,check 係 function / const / interface 邊個 export 規則:
- function X → 加 export keyword 即可
- const X = → 加 export keyword
- interface X / type X → 加 export keyword
- 如果係 anonymous export default → 寫 named export export function X
如果真係冇 define 過,先 grep X 變體:rg "DealDialog|deal-dialog|dealDialog" 有時命名 convention 唔同(eg. dealDialog 駝峰 vs deal-dialog kebab),可能 existing 用緊另一個名
最後先考慮寫新 file。多寫一個 file 引入新 export 嘅機會成本 = 重新做 code review / 可能同現有 duplicate / 將來 refactor 要兩邊 sync

Anti-pattern:

// ❌ 撞到 first thought:寫新 file
// apps/web/src/components/deal-dialog.tsx (全新 200 行)
export function DealDialog({...}) { ... }

// ✅ 先 grep,加 export,慳 200 行
// apps/web/src/pages/deals.tsx (改 1 個 keyword)
export function DealDialog({...}) { ... }

Generic rule 套用到所有 X:

React component(DealDialog / RoleDialog / QuotationBuilder)
Elysia route module
Prisma model name
Utility function / helper
Type alias / interface
常數(kanbanStages / BASE_REGIONS / ALL_PERMISSIONS)

5 秒 grep 慳 30 分鐘 over-engineering。撞「Cannot find name X」,永遠先 grep X 喺 codebase 邊度 define 過,永遠先 assume 個 X 已經 internal 存在。

Related:

patch-corruption-recovery skill — 撞 syntax error 之後 restore from git + re-patch 嘅 pattern。但撞「Cannot find name X」通常唔需要 restore,加 1 個 keyword 即可
bun-elysia-react-vite-stack 嘅「LSP diagnostics stale」section — LSP 報「Cannot find name」可能係 stale cache,先睇 tsc --noEmit 嘅真實 error 然後先 grep

⚠️ Git commit message body 永遠寫 file, 唔好 inline (2026-06-09 crm-system 真實撞牆)

1. backend GET /deals/kanban 個 Prisma  冇 ,
   所以 frontend 收到嘅每個 deal 都係 。

所有 backtick 區間嘅 inline code 完全消失,剩低空白 + 雜訊 command not found。

Fix (3 個 option, 揀適合):

Option A — 寫 file 然後 git commit -F (推薦, 100% safe):

cat > /tmp/commit-msg.txt <<'HEREDOC'    # 注意: <<'EOF' 單引號, 唔 expand
fix(deals): drag-drop + edit dialog

症狀: 撳 edit dialog 永遠顯示 Stage = "Lead", ... 

\`setStageId(deal?.stage?.id ?? stages[0]?.id)\`  永遠 fall through

\`e.dataTransfer.setData("text/deal-id", deal.id)\`  喺 onDragStart 冇 call
...
HEREDOC
git commit -F /tmp/commit-msg.txt

Option B — git commit --amend -F file (已經 commit 咗, 改 message):

# 發現 commit message 壞咗, 唔使 reset, 直接 amend
git commit --amend -F /tmp/commit-msg.txt
git push --force-with-lease origin main   # 必須 force-push 因為 commit 改咗

Option C — <<'EOF' single-quoted heredoc (防止 future backtick expansion, 但仍輸 cat | git 個 overhead):

git commit -F - <<'MSG'   # 單引號 heredoc: shell 完全唔 interpret
fix(deals): drag-drop

\`backticks here preserved verbatim\`
MSG

Detection (撞牆後必做):

git log -1 --format='%b' | head -10
# Look 4 啲 inline code (`xxx`) 區間。 如果 4 唔到, 即係 backticks 全部被 shell 食走

Why option A 永遠 work:

<<'EOF' 喺 cat 嗰度: 寫 file, 文字 verbatim
git commit -F /tmp/file: 純 file read, 唔經 shell 解析
完全冇 backtick interpolation, 任何 inline code 字符 ( , $, \, etc) 都 pass through

Generic rule (套用到任何 git commit 同樣有 backtick 嘅場景):

git commit -m "literal text" — 簡單 message OK, 但 backticks 仍然食
git commit -m "$(cat <<EOF ... EOF)" — 永遠撞
git commit -F file — 永遠 safe
git commit -F - (stdin via <<'EOF') — safe, 但要小心 trailing newline

Doc / Web 攞資料嘅限制 (3 個常見撞牆)

撞牆 1: SPA 渲染嘅 API doc 站撈唔到 (e.g. https://xxx.com/public/apidoc/<hash>)

症狀: curl / web_extract 攞到 4-5KB HTML 殼, content 空 (只有 loading spinner + JS bundle)
原因: 個 doc 站用 React/Vue 喺 client-side render, content 喺 __NEXT_DATA__ / bundle 入面
唔好再用 firecrawl / curl 撞 — browser_navigate 都會 timeout 因為 content 太慢 load
解: 唔靠 doc, 靠用戶 domain knowledge + 一般 SaaS pattern 設計 schema / endpoints. 問用戶核心 fields/flows 就夠

撞牆 2: GitHub SSH clone 慢 / proxy 阻擋 (內網 / 公司 firewall)

症狀: git clone git@github.com:... hang 喺 "Cloning into..."
確認 SSH 通: ssh -T git@github.com → 「Hi ! You've successfully authenticated」
唔通嘅話, 改 https:// 配 PAT: git clone https://<token>@github.com/<user>/<repo>.git

撞牆 3: Git push 完唔知成功定失敗

唔好用 aws codecommit get-commit 驗 (IAM 冇 read 權限會 false alarm)
用: git ls-remote <remote> 或再 git clone --depth 1 <url> /tmp/verify 確認 commits 出現

QA Gate checklist (full-stack app)

Backend /api/health returns 200
Frontend index.html returns 200
Proxy /api/health 透過 frontend returns 200
至少 1 個 E2E write+read flow (POST + GET)
Browser 載入 4 個 page 冇 console error
RWD mobile audit (見 rwd-mobile-audit skill)
Git 推送完記得用 git clone 或 git ls-remote 驗證（唔好信 aws codecommit get-commit — IAM 冇 read 權限會 false alarm，見 aws-codecommit-git-setup 嘅「驗證 push 成功嘅方法」section）

⚠️ Backup / Restore 對 local Postgres Docker stack (2026-06-05 crm-system Day 6)

情境: 用戶要 admin functionality 包含 backup / restore,但又唔想搞 cloud storage / S3 (本地部署就本地 backup)。3 個 scripts + 1 個 docker profile 已經 ready to copy。

1. Host-side backup (`scripts/backup.sh`)

docker exec 跑 pg_dump 喺 postgres container,stream 出 gzip:

./scripts/backup.sh                    # 預設 7 日 retention
./scripts/backup.sh --keep 30          # 30 日
./scripts/backup.sh --no-trim          # skip cleanup

產出:backups/crm_2026-06-05_132751.sql.gz (8K for empty schema)。Retention 用 find -mtime +N -delete,冇 cron daemon 都要 work。

2. Restore (`scripts/restore.sh`)

互動式揀 backup + safety confirm:

./scripts/restore.sh                            # 互動揀
./scripts/restore.sh backups/crm_xxx.sql.gz     # 直接
./scripts/restore.sh <file> --no-confirm        # CI mode

安全流程:停 API → DROP DATABASE → CREATE DATABASE → gunzip | psql -v ON_ERROR_STOP=1 → start API。

Pitfall:

唔 stop API → DROP DATABASE hang (API 仲 hold 住 connection)
唔用 -v ON_ERROR_STOP=1 → psql 默吞錯誤,partial restore 假成功
stat -f '%Sm' (macOS) vs stat -c '%y' (Linux) — 用 2>/dev/null || fallback

3. Scheduled backup profile (`docker-compose.yml`)

backup:
  image: postgres:16-alpine
  profiles: ["backup"]    # opt-in: `docker compose --profile backup up -d`
  command:
    - -c
    - |
      echo "0 2 * * * /usr/local/bin/backup.sh >> /proc/1/fd/1 2>&1" > /etc/crontabs/root
      /usr/local/bin/backup.sh
      crond -f -L /dev/stdout
  environment:
    PGPASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_HOST: postgres
    POSTGRES_DB: ${POSTGRES_DB}
    BACKUP_KEEP_DAYS: ${BACKUP_KEEP_DAYS:-7}
  volumes:
    - ./backups:/var/backups
    - ./scripts/backup-container.sh:/usr/local/bin/backup.sh:ro
  depends_on:
    postgres: { condition: service_healthy }

postgres:16-alpine 內置 BusyBox crond,唔需要裝 cron daemon。Skip mechanism:touch backups/skip → entrypoint check if [ -f /var/backups/skip ]; then exit 0。

4. 兩個 backup script 嘅分別 (重要!)

環境	Script	連線方式
Host 跑 (`./scripts/backup.sh`)	Host script	`docker exec crm-postgres pg_dump`
Container 跑 (cron job 內)	`backup-container.sh`	直接 `pg_dump -h postgres -U crm -d crm_system` (compose 內部 hostname)

5. .gitignore 必加

backups/
*.sql.gz

pg_dump file 可能包含 PII (email, phone, IP)。絕對唔好 commit 入 git。

詳細 Day 6 build log 見 references/2026-06-05-crm-system-audit-backup.md。

⚠️ Elysia 1.2 `.derive()` 喺 POST handler 內 silently 返 `undefined` (2026-06-06 crm-system Day 9 真實撞牆)

Hermes 喺 crm-system Day 9 撞咗 3 個鐘先發現:

POST /api/quotations 返 401,POST /api/companies 返 201(201 因為 handler 唔 check userId)
GET /api/deals/kanban work 正常
加 console.log('[POST /quotations] userId=', userId) 入 handler → print undefined
加 console log 入 authContext.derive → 冇任何 log。即係 derive 個 async function 完全冇 run

Workaround (推薦, 100% bullet-proof): 完全唔靠 derive() 注入 userId,handler 內 inline verify token:

// apps/api/src/lib/context.ts
import { Elysia } from 'elysia';

export const authContext = new Elysia({ name: 'auth-context' });
// Intentionally empty — Day 9 發現 .derive() 喺 Elysia 1.2 POST handler
// 內 silently 返 undefined。Use getUserIdFromRequest() inline 喺每個
// handler 入面 call 取代。

export async function getUserIdFromRequest(
  request: Request,
  jwt: { verify: (token: string) => Promise<unknown> }
): Promise<string | null> {
  const authHeader = request.headers.get('authorization');
  if (!authHeader?.startsWith('Bearer ')) return null;
  const token = authHeader.slice(7);
  const payload = await jwt.verify(token);
  if (!payload || typeof payload !== 'object') return null;
  return (payload as { sub?: string }).sub ?? null;
}

// apps/api/src/routes/quotation.ts
import { authContext, getUserIdFromRequest } from '../lib/context';

.post('/', async ({ body, jwt, set, request }) => {
  const userId = await getUserIdFromRequest(request, jwt);
  if (!userId) { set.status = 401; return { error: 'Unauthorized' }; }
  // ... 個 body 之後照舊 ...
}, { body: t.Object({...}) })

Detection (撞牆必做):

import urllib.request, json
token = json.loads(urllib.request.urlopen(urllib.request.Request(
  'http://localhost/api/auth/login',
  data=json.dumps({'email':'admin@crm.local','password':'admin123'}).encode(),
  headers={'Content-Type':'application/json'}), method='POST')).read())['token']
# Try 一個 GET + 一個 POST endpoint (POST 要 body)
for url, method, body in [
  ('/api/deals/kanban', 'GET', None),
  ('/api/quotations', 'POST', json.dumps({
    'companyId': 'xxx', 'title': 'T', 'taxRate': 0,
    'items': [{'name': 'X', 'quantity': 1, 'unitPrice': 100}]
  }).encode()),
]:

bun-elysia-react-vite-stack

同仓库更多 Skills

同仓库更多 Skills

Bun + Elysia + Vite/React Full-Stack Bootstrap

觸發時機

部署目標 — 問用戶先 (2026-06-05 crm-system 真實訊號)

SQLite vs Postgres 點揀 (2026 經驗)

完整 SOP (SQLite path, 跟之前 bc-quotation)

1. Backend init (Bun workspaces monorepo, 支援 apps/api + apps/web)

2. Prisma + DB setup

3. Elysia backend

4. Seed script

5. Frontend init (Vite 8 + React)

6. Vite config + Tailwind v4

7. React Router + Pages

衍生: onBeforeHandle 嘅 derive context 唔 propagate 跨 plugin (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ React Query useQuery generic return type 撞 never (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Vite production minified React throw unmount 整個 tree (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Docker Compose up -d --build cache layers 不重 build source code (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Bun export * 唔可靠 re-export named consts 跨 module (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Prisma client model names 唔 export (2026-06-05)

⚠️ Tailwind v3 vs v4 — shadcn-style setup 仍要 v3 (2026-06-05)

⚠️ shadcn-style token 唔可以漏 — popover / card-foreground / destructive-foreground 撞 (2026-06-06 crm-system 真實撞牆)

Quick fix 路徑之後必須 grep 全部 other occurrences (2026-06-06 crm-system 真實撞牆)

⚠️ LSP diagnostics stale after rapid patches — docker compose build 是 source of truth (2026-06-06 crm-system 真實撞牆)

⚠️ bun.lock 不被 npm / snyk 認 — 紅線 18 CVE 掃描盲點 (2026-06-07 crm-system code review 真實撞牆)

⚠️ RBAC coverage matrix 1-liner audit — 1 個 grep 揭 14 route 嘅 access control gap (2026-06-07 crm-system 真實撞牆)

⚠️ tsc --noEmit 報 30+ silent type errors 但 runtime OK — typecheck 唔可以靠 build 兜底 (2026-06-07 crm-system 真實撞牆)

⚠️ Self-register-as-admin trap — POST /auth/register 公開 + role 喺 body (2026-06-07 crm-system 真實撞牆)

⚠️ Subagent 600s/63-call timeout 撞 long refactor 任務 (2026-06-06 crm-system Day 11 真實撞牆)

⚠️ Hermes redact *** 整死 shell-based JWT tests (2026-06-05)

⚠️ Docker container DB migration when host can't reach postgres port (2026-06-05 crm-system Day 5)

⚠️ Prisma migration folder rename 嘅 silent trap (2026-06-05 crm-system Day 6 真實撞牆)

⚠️ nginx SPA root directive 唔可以漏 (2026-06-05 crm-system Day 6 真實撞牆)

⚠️ API wrapper boundary normalize for Prisma relation field-name drift (2026-06-06 crm-system Day 12)

⚠️ Elysia bun build 撞 runtime code generation (2026-06-05 真實撞牆)

⚠️ Backend response shape 不一致 — frontend 要 normalize (2026-06-05)

Vite 8 quirk (詳細)

完整目錄結構

啟動 dev

Hermes execute_code / terminal 陷阱 (五個唔同嘅事, 唔好混淆)

⚠️ docker compose up -d --build 必然 trigger foreground warning — 一律 background (2026-06-06 crm-system 真實撞牆)

⚠️ Build 撞「Cannot find name X」之前,先 grep 個 X 喺 codebase 邊度 define 過 (2026-06-06 crm-system 真實撞牆)

⚠️ Git commit message body 永遠寫 file, 唔好 inline (2026-06-09 crm-system 真實撞牆)

Doc / Web 攞資料嘅限制 (3 個常見撞牆)

QA Gate checklist (full-stack app)

相關 skills

⚠️ Backup / Restore 對 local Postgres Docker stack (2026-06-05 crm-system Day 6)

1. Host-side backup (scripts/backup.sh)

2. Restore (scripts/restore.sh)

3. Scheduled backup profile (docker-compose.yml)

4. 兩個 backup script 嘅分別 (重要!)

5. .gitignore 必加

⚠️ Elysia 1.2 .derive() 喺 POST handler 內 silently 返 undefined (2026-06-06 crm-system Day 9 真實撞牆)

Bun + Elysia + Vite/React Full-Stack Bootstrap

觸發時機

部署目標 — 問用戶先 (2026-06-05 crm-system 真實訊號)

SQLite vs Postgres 點揀 (2026 經驗)

完整 SOP (SQLite path, 跟之前 bc-quotation)

1. Backend init (Bun workspaces monorepo, 支援 apps/api + apps/web)

2. Prisma + DB setup

3. Elysia backend

4. Seed script

5. Frontend init (Vite 8 + React)

6. Vite config + Tailwind v4

7. React Router + Pages

衍生: onBeforeHandle 嘅 derive context 唔 propagate 跨 plugin (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ React Query useQuery generic return type 撞 never (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Vite production minified React throw unmount 整個 tree (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Docker Compose up -d --build cache layers 不重 build source code (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Bun export * 唔可靠 re-export named consts 跨 module (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Prisma client model names 唔 export (2026-06-05)

⚠️ Tailwind v3 vs v4 — shadcn-style setup 仍要 v3 (2026-06-05)

⚠️ shadcn-style token 唔可以漏 — popover / card-foreground / destructive-foreground 撞 (2026-06-06 crm-system 真實撞牆)

Quick fix 路徑之後必須 grep 全部 other occurrences (2026-06-06 crm-system 真實撞牆)

⚠️ LSP diagnostics stale after rapid patches — docker compose build 是 source of truth (2026-06-06 crm-system 真實撞牆)

⚠️ bun.lock 不被 npm / snyk 認 — 紅線 18 CVE 掃描盲點 (2026-06-07 crm-system code review 真實撞牆)

⚠️ RBAC coverage matrix 1-liner audit — 1 個 grep 揭 14 route 嘅 access control gap (2026-06-07 crm-system 真實撞牆)

⚠️ tsc --noEmit 報 30+ silent type errors 但 runtime OK — typecheck 唔可以靠 build 兜底 (2026-06-07 crm-system 真實撞牆)

⚠️ Self-register-as-admin trap — POST /auth/register 公開 + role 喺 body (2026-06-07 crm-system 真實撞牆)

衍生: `onBeforeHandle` 嘅 derive context 唔 propagate 跨 plugin (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ React Query `useQuery` generic return type 撞 `never` (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Docker Compose `up -d --build` cache layers 不重 build source code (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Bun `export *` 唔可靠 re-export named consts 跨 module (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ shadcn-style token 唔可以漏 — `popover` / `card-foreground` / `destructive-foreground` 撞 (2026-06-06 crm-system 真實撞牆)

⚠️ LSP diagnostics stale after rapid patches — `docker compose build` 是 source of truth (2026-06-06 crm-system 真實撞牆)

⚠️ `bun.lock` 不被 npm / snyk 認 — 紅線 18 CVE 掃描盲點 (2026-06-07 crm-system code review 真實撞牆)

⚠️ `tsc --noEmit` 報 30+ silent type errors 但 runtime OK — typecheck 唔可以靠 build 兜底 (2026-06-07 crm-system 真實撞牆)

⚠️ Self-register-as-admin trap — `POST /auth/register` 公開 + role 喺 body (2026-06-07 crm-system 真實撞牆)

⚠️ Hermes redact `***` 整死 shell-based JWT tests (2026-06-05)

⚠️ nginx SPA `root` directive 唔可以漏 (2026-06-05 crm-system Day 6 真實撞牆)

⚠️ Elysia `bun build` 撞 runtime code generation (2026-06-05 真實撞牆)

⚠️ `docker compose up -d --build` 必然 trigger foreground warning — 一律 background (2026-06-06 crm-system 真實撞牆)

1. Host-side backup (`scripts/backup.sh`)

2. Restore (`scripts/restore.sh`)

3. Scheduled backup profile (`docker-compose.yml`)

⚠️ Elysia 1.2 `.derive()` 喺 POST handler 內 silently 返 `undefined` (2026-06-06 crm-system Day 9 真實撞牆)

衍生: `onBeforeHandle` 嘅 derive context 唔 propagate 跨 plugin (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ React Query `useQuery` generic return type 撞 `never` (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Docker Compose `up -d --build` cache layers 不重 build source code (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ Bun `export *` 唔可靠 re-export named consts 跨 module (2026-06-05 crm-system Day 7 真實撞牆)

⚠️ shadcn-style token 唔可以漏 — `popover` / `card-foreground` / `destructive-foreground` 撞 (2026-06-06 crm-system 真實撞牆)

⚠️ LSP diagnostics stale after rapid patches — `docker compose build` 是 source of truth (2026-06-06 crm-system 真實撞牆)

⚠️ `bun.lock` 不被 npm / snyk 認 — 紅線 18 CVE 掃描盲點 (2026-06-07 crm-system code review 真實撞牆)

⚠️ `tsc --noEmit` 報 30+ silent type errors 但 runtime OK — typecheck 唔可以靠 build 兜底 (2026-06-07 crm-system 真實撞牆)

⚠️ Self-register-as-admin trap — `POST /auth/register` 公開 + role 喺 body (2026-06-07 crm-system 真實撞牆)

⚠️ Hermes redact `***` 整死 shell-based JWT tests (2026-06-05)

⚠️ nginx SPA `root` directive 唔可以漏 (2026-06-05 crm-system Day 6 真實撞牆)

⚠️ Elysia `bun build` 撞 runtime code generation (2026-06-05 真實撞牆)

⚠️ `docker compose up -d --build` 必然 trigger foreground warning — 一律 background (2026-06-06 crm-system 真實撞牆)

1. Host-side backup (`scripts/backup.sh`)

2. Restore (`scripts/restore.sh`)

3. Scheduled backup profile (`docker-compose.yml`)

⚠️ Elysia 1.2 `.derive()` 喺 POST handler 內 silently 返 `undefined` (2026-06-06 crm-system Day 9 真實撞牆)