fix: 重新生成 docs

docs/pitfalls.md

@@ -0,0 +1,21 @@
+# 踩坑指南 (Pitfalls)
+
+## 1. Prisma 客户端生成
+
+- **现象**: 修改 `schema.prisma` 后代码报错找不到类型。
+- **解决**: 需要在 `apps/server` 下运行 `pnpm prisma generate`。本项目将生成的代码放在了 `generated/` 目录而非 node_modules，请注意引用路径。
+
+## 2. zx 环境变量继承
+
+- **现象**: 在流水线脚本中找不到 `node` 或 `git` 命令。
+- **解决**: `PipelineRunner` 在调用 `zx` 时必须手动扩展 `env: { ...process.env, ...userEnv }`，否则会丢失系统 PATH。
+
+## 3. Koa BodyParser 顺序
+
+- **现象**: 获取不到 `ctx.request.body`。
+- **解决**: `koa-bodyparser` 中间件必须在 `router` 中间件之前注册。
+
+## 4. SQLite 并发写入
+
+- **现象**: 部署日志极快输出时偶发 `SQLITE_BUSY`。
+- **解决**: 适当增加 `better-sqlite3` 的 busy timeout。