Miaoda Pitfalls

---
name: miaoda-pitfalls
description: 飞书妙搭（apaas）平台的已知陷阱速查。在这些情况下加载：要跑 DDL 或改数据库结构、要发版上线、要接飞书能力（回调/卡片/通讯录/链接预览）、要配定时任务、要在本地起服务或打接口、要写验证脚本或冒烟、排查「测试全绿但功能不对」、排查「命令跑了但什么都没发生」。触发词：妙搭, miaoda, apaas, lark-cli, 发版, 上线, DDL, schema.ts, db-execute, 触发器, cron, 飞书回调, 长连接, image_key, 冒烟, 反向验证, 源码断言, 定时任务不跑, 全绿但没生效
---

# 妙搭平台陷阱速查

完整手册：`妙搭平台踩坑手册.md`（与本 skill 同一个资产包）。
下面是**按情境的索引**——先定位到情境，再去手册里读那一节的完整原文。

## 我要动数据库

- `schema.ts` 是 `gen:db-schema` 的生成物，手写的会消失；它还表达不了表达式索引和条件索引
- 本地 `db-query.js` 有 DML 权限、**没有 DDL 权限**
- 平台连接**禁 `WITH`（CTE）和多语句**
- 平台 **DDL 自动提交**，`BEGIN…ROLLBACK` 不能当探测手段
- **online 禁 DDL**
- SQL **必须真的在库上跑过一次**，并确认结果不全是 0
- `EXTRACT` 跟随会话时区，写进 CHECK 必须锚定 UTC
- 兼容期并存的两条唯一索引口径不同 → 新写入路径一上就 500

→ 手册 §2

## 我要发版 / 确认上线了没有

- 上线 = **push 到 sprint/default + 后台发版**，缺一不可；只发版发的是你改动之前那个提交，且提示成功
- 确认部署：`+release-get` 拿 commit_id，再 `git merge-base --is-ancestor`
- 接口报 403（CSRF）**不能**用来判断接口有没有部署——那是路由之前就拒了
- 发布会连库结构一起发，不存在「先发结构还是先发代码」的窗口

→ 手册 §3

## 我要接飞书

- 应用**收不到任何未登录的入站请求** → webhook 走不通，只能长连接（`lark.WSClient`）
- 卡片 `img` 只认 `image_key`，要先把图搬进飞书；`img_key: ''` 会让**整张卡渲染失败**而日志 `code=0`
- `contact.user.batch` **不返回 `department_path`**，补权限也不会返回；层级要自己沿 `parent_department_id` 上溯（**必须有深度上限**）
- 妙搭 userId 与飞书 user_id 是**两个 id 空间**，混用不报错
- 链接预览：四件事都在开发者后台，仅正式版本应用支持，回调必须 3 秒内响应
- 飞书开放平台文档页是客户端渲染的，要抓就抓 `.md` 版

→ 手册 §4

## 我要配定时任务

- 平台 **cron 最小间隔 30 分钟**，精度上限就是 30 分钟，界面文案要如实写误差
- 排查先看 `+automation-list`（存不存在/启没启用/表达式）和 `+log-list`（有没有真跑），**别靠推断**
- 观测类命令**只支持 online**
- 块注释里写不出 cron 表达式（`*` 紧跟 `/` 会提前关掉注释）
- 「读表 A / 只有路径 B 写表 A / 而 B 只对表 A 里已有的人开放」= 闭环，永远不启动且不报错

→ 手册 §5

## 我要在本地跑起来 / 打接口

- 必须 `npm run dev:local`；后端是挂在 vite 里的中间件，**自己不监听端口**
- 请求走 **8080 + 应用前缀** `/app/<app_id>/api/...`，带 CSRF double-submit 头
- `npm run dev` 不刷 PG 连接串，`dev:local` 才刷
- 本地登录身份被 `.env.local` 钉死，**请求头里的 webuser 被忽略**
- `/api/*` 不能在浏览器地址栏里打开

→ 手册 §6

## 我要写验证 / 冒烟 / 反向测试

**这一节是最值钱的，写任何验证之前读一遍。**

- 先断言前置条件再断言结论：打状态码、断言类型、断言非空、**先算出预期条数**
- 空集合满足一切全称命题 —— 「遍历结果找不到坏样本」在结果为空时恒成立
- 检查类命令**不加 `--silent`**；管道里的 `$?` 永远是 0
- 写类验证一律「写 → 回读 → 比对」，每步重新读状态
- 视角类验证第一条断言必须钉住视角
- 反向验证的**锚点必须唯一**，一次只改一处
- 还原**用副本，不要 `git checkout <file>`**
- 假 db 必须真的看一眼条件树，否则条件删光了测试照样全绿

→ 手册 §7

## 命令跑了但什么都没发生

- `lsof -ti :A :B` 非法 → 报错退出 → `||` 打印「都空了」
- zsh 里 `for f in $VAR` 不做词分割
- bash 3.2 把全角字符吞进变量名 → 中文文案里的变量一律加花括号
- 文件里混进 NUL 字节 → `grep` 静默跳过，`file` 显示 `data`
- `npm run <不存在的脚本> --silent` 无输出 + 退出码 0

→ 手册 §8