@lark-apaas/coding-steering 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
@@ -16,6 +16,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "chiya": {
+    "markdownIsSource": true
+  },
   "keywords": [
     "miaoda",
     "coding-steering"

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

@@ -367,17 +367,30 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 
 ## 本地 dev API 调试
 
-### 入口端口：**只走 vite/rspack dev server**
+### 入口端口和 base path：**只走 vite/rspack dev server**
 
-本地 dev 跑起来有**两个端口**：
+本地 dev 跑起来有**两个端口 + 一个前缀**，都由 `.env.local` 里的 env 控制：
 
-| 端口 | 进程 | env | 默认 | 角色 |
+| Env | 进程 / 用途 | 默认 | 沙箱 env-pull 下发？ | 备注 |
 |---|---|---|---|---|
-| **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 用 |
+| `CLIENT_DEV_PORT` | vite / rspack dev server | `8080` | ❌ 不下发 | **唯一入口**：serve 前端 + 反代 `/api/*` 给 NestJS + 注入 `x-larkgw-suda-webuser` 模拟登录态。端口被占就 Agent 自己改 `.env.local` |
+| `SERVER_PORT` | NestJS | `3000` | ❌ 不下发 | 仅 vite/rspack 反代用，不直接给 agent / curl 用。端口被占就 Agent 自己改 `.env.local` |
+| `CLIENT_BASE_PATH` | 前端路由 base + 后端 routes.json serve 路径 | `/` | ✅ `/app/<app_id>` | 浏览器 URL 前缀；agent / curl 调 `/api/*` 也必须带这个前缀 |
 
-启动日志里 vite/rspack 打印的 `Local: http://localhost:<CLIENT_DEV_PORT>/...` 才是入口
-（具体端口看 `.env.local` 的 `CLIENT_DEV_PORT`，常见值是 `8080` 或 `8001`）。
+完整入口形态 = `http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/...`。启动日志里
+vite/rspack 打印的 `Local: http://localhost:<port>/...` 才是入口，具体值以 `.env.local`
+为准（沙箱 `lark-cli +env-pull` 会把 `CLIENT_BASE_PATH` 下发成 `/app/<app_id>`，本地裸
+跑不设则退到 `/`）。
+
+> **端口冲突时**：`CLIENT_DEV_PORT` / `SERVER_PORT` 不归 env-pull 管，Agent 自己在
+> `.env.local` 加 `CLIENT_DEV_PORT=8001`（或别的空闲端口）然后重启 `npm run dev`
+> 即可。**不要去改 `vite.config.ts` / NestJS bootstrap 里的硬编码端口**，preset 已经
+> 自己读这两个 env，业务侧改源码反而会跟 sandbox 配置发散。
+
+> **dev vs prod 的 base path 差异**：dev 模式下 vite/rspack 把前端组件 basePath 强制
+> 成 `''`（preset 里 `isDev ? { basePath: '' } : ...`），所以前端 router 用相对路径就
+> 行；但 dev server 自己 serve 路由 / 反代 `/api/*` 的路径**仍然带 `CLIENT_BASE_PATH`
+> 前缀**，浏览器 URL 跟 prod 一样长。这也是 agent / curl 必须带前缀的原因。
 
 **绕过 vite/rspack 直连 NestJS 端口的后果**：vite/rspack dev server 是从
 `SUDA_WEBUSER` env 读出 webuser 拼到 `x-larkgw-suda-webuser` header 再转发给 NestJS 的，
@@ -401,10 +414,11 @@ NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userCo
   NestJS 端口）：
 
    ```bash
-   # <PORT> = .env.local 里的 CLIENT_DEV_PORT，常见 8080 / 8001
+   # <PORT> = .env.local 里的 CLIENT_DEV_PORT（常见 8080 / 8001）
+   # <BASE_PATH> = .env.local 里的 CLIENT_BASE_PATH（沙箱下发为 /app/<app_id>，本地裸跑可能为空）
    curl -H 'Cookie: suda-csrf-token=x' \
         -H 'X-Suda-Csrf-Token: x' \
-        http://localhost:<PORT>/app/<app_id>/api/notes
+        http://localhost:<PORT><BASE_PATH>/api/notes
    ```
 
   **不要**因为撞 403 就去改后端 csrf 中间件或者怀疑业务逻辑 —— csrf 保护是有意的，