@lark-apaas/coding-steering 0.1.7-beta.0 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.7-beta.0",
+  "version": "0.1.8",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/nestjs-react-fullstack/skills_local/coding-guide/SKILL.md

@@ -365,9 +365,59 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 - **最后一页时 nextCursor 必须为 undefined**
 - DESC 降序配 LessThan(游标)，ASC 升序配 GreaterThan(游标)
 
+## 本地 dev API 调试
+
+### 入口端口：**只走 vite/rspack dev server**
+
+本地 dev 跑起来有**两个端口**：
+
+| 端口 | 进程 | env | 默认 | 角色 |
+|---|---|---|---|---|
+| **client dev port** | vite / rspack | `CLIENT_DEV_PORT` | `8080` | **唯一入口**：serve 前端 + 反代 `/api/*` 给 NestJS + 注入 `x-larkgw-suda-webuser` 模拟登录态 |
+| nest server port | NestJS | `SERVER_PORT` | `3000` | 仅 vite/rspack 反代用，不直接给 agent / curl 用 |
+
+启动日志里 vite/rspack 打印的 `Local: http://localhost:<CLIENT_DEV_PORT>/...` 才是入口
+（具体端口看 `.env.local` 的 `CLIENT_DEV_PORT`，常见值是 `8080` 或 `8001`）。
+
+**绕过 vite/rspack 直连 NestJS 端口的后果**：vite/rspack dev server 是从
+`SUDA_WEBUSER` env 读出 webuser 拼到 `x-larkgw-suda-webuser` header 再转发给 NestJS 的，
+NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userContext.userId === ""` →
+任何依赖 `userContext` 的逻辑（`drizzle eq(table.createdBy, userId)`、`@NeedLogin()` 拒
+访等）行为异常，但表面看接口是 200 / 返回值正常，**症状难追到根因**。
+
+### CSRF token（double-submit cookie）
+
+后端 csrf 中间件用 **double-submit cookie** 模式守门所有 `/api/*` 请求：
+`Cookie: suda-csrf-token=<X>` 和 `X-Suda-Csrf-Token: <X>` header 两个值**字面相等**
+才放行。缺 cookie 直接 403；cookie 在但 header 跟它不等也 403。
+
+- **浏览器侧零感知**：首页加载时后端 Set-Cookie 写入 csrf cookie + 把同值注入到
+  `window.csrfToken`，前端 axios 拦截器读取这个值塞到 `X-Suda-Csrf-Token` header，
+  浏览器又自动随请求带上 cookie —— 业务代码不需要管。**优先用浏览器/DevTools Network
+  调试**：cookie 链由浏览器一次性建立，是验证接口最自然的方式。
+
+- **`curl` / 第三方 HTTP 客户端 / agent 工具直接打 `/api/*` 接口**：必须同时塞 cookie
+  和 header，值字面相等才放行。任意非空相等值都行（注意打**client dev port**，不是
+  NestJS 端口）：
+
+   ```bash
+   # <PORT> = .env.local 里的 CLIENT_DEV_PORT，常见 8080 / 8001
+   curl -H 'Cookie: suda-csrf-token=x' \
+        -H 'X-Suda-Csrf-Token: x' \
+        http://localhost:<PORT>/app/<app_id>/api/notes
+   ```
+
+  **不要**因为撞 403 就去改后端 csrf 中间件或者怀疑业务逻辑 —— csrf 保护是有意的，
+  业务本身没问题。
+
+- **依赖用户信息的接口**（看 `req.userContext` 的）即便过了 csrf 也拿不到用户身份，
+  浏览器才能补齐 webuser header。这种接口直接 `curl` 永远拿不到合理响应，**用浏览器
+  或者 `think` 工具推理**，别陷在 curl 里反复调。
+
 ## 问题排查指引
 
-1. 用 `curl` / 浏览器 DevTools / 第三方 HTTP 客户端测试不依赖用户信息的接口
+1. 用 `curl` / 浏览器 DevTools / 第三方 HTTP 客户端测试不依赖用户信息的接口（**必须**
+   带 csrf cookie + header + 打 client dev port，见上节"本地 dev API 调试"）
 2. 查看 `logs/server.log` / `logs/server.std.log` 找后端报错;无有效日志时主动补 logger 打印
 3. dev 服务无响应:在跑 `npm run dev` 的终端 Ctrl+C 后重新启动
 4. API 测试返回 HTML 内容时:检查模块注册顺序、路由顺序、请求路径。禁止修改内置 ViewController

package/steering/nestjs-react-fullstack/tech.md

@@ -1,21 +0,0 @@
-# NestJS + React 全栈技术栈说明
-
-本 stack 对应 miaoda CLI 的 **application scene（MIAODA_APP_TYPE=3）**。
-
-## 技术构成
-
-- **客户端**：Vite 7 + React 18 + TypeScript 5；shadcn/ui + Tailwind v4
-- **服务端**：NestJS 10 + Express + Drizzle ORM + PostgreSQL
-- **共享**：`shared/` 子目录放跨端类型 / 常量；客户端用 vite-tsconfig-paths 解析，服务端走 NestJS 编译输出
-- **构建**：`@lark-apaas/fullstack-{vite-preset,nestjs-core,cli}` 三件套；本地 dev 由 `scripts/dev.js` 编排 server + client，本地纯净 dev 走 `scripts/dev-local.sh`
-
-## 关键 env
-
-- `MIAODA_LOCAL_DEV=1`：本地 dev 总开关，开启 SDK 内置的 sandbox 反代 / cookie+webuser 兜底
-- `FORCE_AUTHN_PREVIEW_SESSION_ID`：后端下发的 session id，SDK 自动拼成 sandbox cookie
-- `SANDBOX_PUBLIC_URL`：沙箱公网域，反代 `/__runtime__/*` 的 target
-- `CLIENT_BASE_PATH=/app/<app_id>/`：路径前缀，决定 React Router basename + Vite base
-
-## 待补 skills
-
-本目录 `skills/` 目前是 .gitkeep 占位。stack 专属编码规则（DTO 装饰器、ORM 用法、view-engine 模板等）后续按需补充。