@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f3f0e48

package/miaoda/lark-apps-authz/references/role.md

@@ -0,0 +1,122 @@
+# apps role 域命令（应用角色）
+
+管理妙搭应用内的平台角色、角色成员，以及查询某个用户命中的角色。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；沙箱约定（`$app_id`、鉴权自动、exit-10 高风险确认）遵循本 skill [`SKILL.md`](../SKILL.md) 的沙箱约定段。
+
+## 何时用
+
+用户要列出、查看、创建、更新或删除某个妙搭应用内的平台角色，管理角色的用户、部门或群成员，或查询某个用户在应用中命中的角色时使用。多维表格 / Base 的角色与权限不走本命令域；设置谁能访问应用走 `+access-scope-*`，不要路由到本命令域。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+role-list` | 分页列出角色，或按名称筛选角色 | `--app-id`、`--name`、`--page-size`/`--page-token` |
+| `+role-get` | 根据真实 `role_id` 读取角色详情 | `--app-id`、`--role-id` |
+| `+role-match-list` | 查询指定用户命中的角色 | `--app-id`、`--user-id` |
+| `+role-create` | 创建角色 | `--app-id`、`--name`、`--description`、`--role-id` |
+| `+role-update` | 更新角色名称或描述 | `--app-id`、`--role-id`、`--name`/`--description` |
+| `+role-delete` | 永久删除角色 | `--app-id`、`--role-id`、`--yes` |
+| `+role-member-list` | 查询角色的用户、部门和群成员 | `--app-id`、`--role-id`、`--member-type` |
+| `+role-member-add` | 向角色添加用户、部门或群成员 | `--app-id`、`--role-id`、`--users`/`--departments`/`--chats` |
+| `+role-member-remove` | 定向移除或清空角色成员 | `--app-id`、`--role-id`、成员参数或 `--all`、`--yes` |
+
+## 约定（先读）
+
+- 应用 id 在环境变量 `app_id` 里，所有命令用 `--app-id "$app_id"`；其角色和成员只使用 `apps +role-*` / `apps +role-member-*`，不要改走 Base 角色命令或裸 bitable API。
+- 角色名称不是 `role_id`。只有名称时优先用 `+role-list --name` 精确解析；若已取得完整分页列表，也可从中证明精确名称唯一命中。0 条如实报告，多条让用户消歧，唯一命中后才使用返回的真实 ID。
+- `+role-list` 返回 `has_more=true` 时，用本页 `page_token` 继续查询，直到 `has_more=false`；不要根据 `total` 补造条目。
+- `+role-list`、`+role-get`、`+role-match-list` 的角色数据分别位于 `data.items`、`data.role`、`data.roles`，不要混用。
+- 同一角色的写入及依赖该写入结果的操作必须串行。不同角色的独立操作只有在每次写入可单独追溯、失败不影响其它目标且分别验收时才可并行；否则保持串行。互不依赖的名称解析或只读查询可并行。
+
+## 各命令
+
+### 查询角色
+
+```bash
+lark-cli apps +role-list --app-id "$app_id" --page-size 100
+lark-cli apps +role-list --app-id "$app_id" --name '<exact_name>'
+lark-cli apps +role-get --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-match-list --app-id "$app_id" --user-id <ou_x>
+```
+
+整理角色列表时保留 `role_id`、`name` 和 `description`。不要猜测未知 `role_id`，也不要从同名候选中静默选择。
+`items=[]` 时直接报告当前没有角色；不要为表格补造“无”或 `N/A` 占位行。
+`+role-match-list --user-id` 只接受 `ou_...`；用户给的是姓名、邮箱或手机号时，先解析唯一 open ID（见「成员 ID 解析」），再查询命中角色。
+
+### 创建与更新
+
+```bash
+lark-cli apps +role-create --app-id "$app_id" --name '<name>' \
+  --description '<description>'
+
+# 只修改名称
+lark-cli apps +role-update --app-id "$app_id" --role-id <role_id> \
+  --name '<new_name>' --format json
+
+# 只修改描述
+lark-cli apps +role-update --app-id "$app_id" --role-id <role_id> \
+  --description '<new_description>' --format json
+```
+
+- `--description` 和创建时的 `--role-id` 可选；仅在确实需要稳定 ID 时传 `--role-id`，创建后不能修改。
+- 更新时只传用户明确要求变更的字段。
+- 成功响应中的角色位于 `data.role`。只有用户要求独立验证，或结果将用于后续高风险操作时，才额外执行 `+role-get`。
+
+### 删除角色
+
+普通“删除某角色”请求只说明目标，**不等于不可逆确认**。如果用户尚未明确确认删除后果，本轮只能定位角色、读取完整成员并说明影响，最后请求确认；不得在同一轮自动追加 `--yes`。用户已明确确认不可逆删除时才继续。
+
+只有名称时仍按上述规则唯一解析，优先使用 `+role-list --name`。目标写前已不存在时立即停止，如实说明本次是 no-op、没有执行删除，不能把“当前不存在”表述为“删除成功”。
+
+删除前读取准确角色和完整成员范围，向用户说明 app、role、`users` / `departments` / `chats` 影响；得到不可逆删除确认后才使用 `--yes`：
+
+```bash
+lark-cli apps +role-get --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-member-list --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-delete --app-id "$app_id" --role-id <role_id> --yes
+```
+
+成功响应包含匹配的 `data.role_id` 和 `data.deleted=true`。只有用户明确要求独立验证删除结果时，才再用 `+role-list --name` 检查目标 ID 已不存在。
+
+### 成员 ID 解析
+
+成员 flags 只接受 open ID：用户 `ou_...`、部门 `od-...`、群 `oc_...`。用户已提供对应类型的合法 open ID 时直接使用；只有名称或邮箱时才解析。
+对象类型以用户语义为准，不能互换解析器：用户走通讯录用户搜索，群走群搜索；沙箱内没有可用的部门搜索命令，部门让用户直接提供 `od-...`。
+
+```bash
+# 用户：每个姓名或邮箱单独查询。
+lark-cli contact +search-user --query '<姓名或邮箱>' \
+  --exclude-external-users --page-size 30
+
+# 群：拉完分页，只接受名称精确匹配的唯一 chat_id。
+lark-cli im +chat-search --query '<群名称>' --page-size 50
+```
+
+- 只接受与输入姓名、邮箱或群名精确匹配的唯一结果。0 条、多条或分页未完成时停止写入并让用户补充或消歧。
+- 多个对象逐个解析。全部解析成功且总数不超过 100 后，按类型放入一次成员写入；任一对象失败时不要部分写入，也不要自动拆批。
+- `lark-cli api` 不在沙箱命令白名单内，会被策略直接拒绝，**不要**用它解析部门或兜底其它对象；解析失败时让用户直接提供 open ID，不要改用猜测或模糊匹配。
+
+### 成员操作
+
+```bash
+# 省略 --member-type，返回完整 users / departments / chats。
+lark-cli apps +role-member-list --app-id "$app_id" --role-id <role_id>
+
+lark-cli apps +role-member-add --app-id "$app_id" --role-id <role_id> \
+  --users ou_x,ou_y --departments od-x --chats oc_x
+
+lark-cli apps +role-member-remove --app-id "$app_id" --role-id <role_id> \
+  --users ou_x --yes
+
+# 清空成员，不删除角色。
+lark-cli apps +role-member-remove --app-id "$app_id" --role-id <role_id> \
+  --all --yes
+```
+
+- `+role-member-list` 不分页；`--member-type` 只返回选中类型的字段，未返回的成员字段表示“未查询”而不是空。影响确认或完整比较时必须省略它。
+- 汇总 `--member-type` 结果时明确这是过滤投影，不得据此断言角色没有其它类型成员。
+- 用户要求 CLI 原生 table 时，直接执行 `+role-member-list --format table`；可原样转发或做事实摘要，不要先取 JSON 再手工重建一张替代表格。
+- 写入和依赖其结果的回读不得放进同一个并发批次；必须等待写入完整返回成功后，再单独发起回读。误并发时只能以写入完成后的新回读作为结果证据。
+- 添加前仅在用户要求独立证明或确认其他成员类型未变化时读取完整基线，并在写后完整回读；否则成功响应即可作为结果。
+- 定向移除前确认准确成员及影响。若需要证明结果，写后完整回读；不要把过滤结果当作完整成员集合。
+- `--all` 前读取完整成员范围并确认；成功后执行一次无过滤 `+role-member-list`，确认三个成员数组均为空。

package/miaoda/lark-apps-db/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: lark-apps-db
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +db-*` 管理【当前这个已存在的】妙搭应用的 PostgreSQL 数据库：建表/改表、写或排查 RLS policy、用 +db-execute 执行 SQL（SELECT/DML/DDL）、灌 mock 数据、数据导入导出、Base（多维表格）→应用数据库同步任务（+db-sync-*）、dev/online 多环境初始化与发布、DDL 变更历史（changelog）、行级审计（audit）、PITR 时间点恢复、DB 配额。触发词：应用数据库, SQL, 建表, 改表, mock 数据, 示例数据, 数据审计, 变更历史, 数据恢复, PITR, 时间点恢复, 多环境发布, RLS, policy, pgPolicy, 行级权限, 权限策略, 42501, Base 同步, +db-, db-table-list, db-execute."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli apps --help; lark-cli apps +db-table-list --help（各 +db-* 子命令同理）"
+control-by-feature-ab: true
+# AppInit 只做需求理解与概要设计，不建表灌数；且其触发词（建表 / mock 数据 / 示例数据）
+# 在概要设计阶段极易误命中，把「读飞书资源」的意图抢走。
+unavailable-agents:
+  - AppInit
+gate-tools:
+  - tool: bash
+    when-contains:
+      command: "lark-cli apps +db"
+---
+
+# lark-apps-db
+
+妙搭应用数据库操作速查（`lark-cli apps +db-*` 通道）：优先用 `+db-*` 专用子命令，只有 DDL / DML / SELECT 才手写 SQL 走 `+db-execute`。
+
+## 沙箱约定（先读）
+
+- **命令名**：一律 `lark-cli apps +db-*`；命令/flag 细节以 `--help` 为准。
+- **app_id 走环境变量**：所有 `+db-*` 都必填 `--app-id "$app_id"`；应用已存在、id 在环境变量 `app_id` 里，不要自行获取、解析或选择。
+- **鉴权自动**：apps 域请求由运行环境自动打到 innerAPI 并注入鉴权头。**不要** `auth login` / `config init` / `--as`。
+- **不要裸连数据库**：不要从环境变量里取连接串直连数据库；本地调试同样走 `+db-execute`。
+- **失败处理**：命令失败时把 `error.hint` 转述给用户，别原样甩 envelope JSON。
+
+### 高风险写操作审批（exit 10）
+
+`risk: high-risk-write` 的命令（`+db-env-create` / `+db-data-import` / `+db-env-migrate` / `+db-recovery-apply` / `+db-execute` / `+db-sync-create/update/delete`）不带 `--yes` 会 **exit 10** 并返回 `confirmation_required`。处理：
+
+1. 识别 exit code=10 且 `error.type=="confirmation_required"`；
+2. 把 `error.risk.action` + 关键参数给用户，明确"高风险/不可逆"，等显式同意；
+3. 同意 → 原始 argv 末尾加 `--yes` 重试；拒绝 → 终止；
+4. 想先看请求 → `--dry-run`（不触发门禁、不需 `--yes`）；发布/恢复/Base 同步先跑对应预览（`+db-env-diff` / `+db-recovery-diff` / `+db-sync-create --preview`，均免确认）。
+
+**绝不**看到 exit 10 就默认补 `--yes` 静默重试。
+
+## Quick Reference
+
+| 场景 | 首选命令 | 关键规则 |
+|---|---|---|
+| 列表 / 查表结构 | `lark-cli apps +db-table-list --app-id "$app_id"` / `+db-table-get --app-id "$app_id" --table <table>` | 禁止用 `information_schema` / `pg_indexes` 模拟常规结构查询 |
+| 执行 DDL / DML / SELECT | `+db-execute --app-id "$app_id" --sql "<query>" --yes` | 不自动包事务，原子性自己写 `BEGIN…COMMIT` |
+| 批量导入 CSV / JSON | `+db-data-import --app-id "$app_id" --file ./<file> --table <table> --yes` | 目标表已存在；表头 / key 与列名完全一致；≤1 MB / ≤5000 行；无 upsert |
+| 批量导出 | `+db-data-export --app-id "$app_id" --table <table> --output ./<file>` | 格式由 `--output` 扩展名决定（.csv/.json/.sql）；5000 行守卫 + 1 MB 上限 |
+| Base（多维表格）→ 应用数据库同步（高危；本地 csv/json 才走 `+db-data-import`） | `+db-sync-create --app-id "$app_id" --config @sync.json --preview` → 确认后去 `--preview` 加 `--yes`；任务管理 `+db-sync-list/get/enable/disable/update/delete` | 一次只同步**一张 Base 表**；`batch_...` 任务一次性、**不能重新 enable**；enable/disable/update/delete 仅 `streaming_...` |
+| 表结构变更历史 | `+db-changelog-list --app-id "$app_id"` | DDL 维度：CREATE / ALTER / DROP / INDEX |
+| 表数据变更历史 | `+db-audit-status --app-id "$app_id"`；enable / disable / list 另需 `--table <table>` | DML 维度：INSERT / UPDATE / DELETE；需按表启用。两者都禁止直查 `pg_audit` 模拟 |
+| 单库拆 dev/online 多环境（高危） | `+db-env-create --app-id "$app_id" [--sync-data] --yes` | 不可逆；新建 full_stack 应用一般已自带多环境；执行后必须回读 `+db-table-list --environment dev` 确认结构已同步 |
+| dev→online 结构发布（高危） | `+db-env-diff --app-id "$app_id"` → `+db-env-migrate --app-id "$app_id" --yes` | 只发布 DDL |
+| PITR 恢复（高危） | `+db-recovery-diff --app-id "$app_id" --target <时间点>` → `+db-recovery-apply --app-id "$app_id" --target <时间点> --yes` | `--target` 必填；覆盖式不可逆；窗口最长 7 天 |
+| DB 用量 | `+db-quota-get --app-id "$app_id"` | 查容量、表数、视图数 |
+
+**环境**：`--environment dev|online` **默认不传**——省略时服务端按应用形态自动选分支（多环境应用走 `dev`，未开多环境走 `online`）；要固定环境才显式传。**唯一会报错的组合是对未开多环境的应用显式传 `dev`**（无 `dev` 分支，报 `Invalid DB Branch`）。旧名 `--env` 已移除。`+db-env-diff` / `+db-env-migrate`（dev→online 语义）与 `+db-recovery-*` 没有 `--environment`。**例外：`+db-sync-*` 不走自动选分支**——省略默认落 **online**；多环境应用建表（`action=create`）必须显式 `--environment dev`，否则撞 online 禁 DDL（`k_dl_4000001`）。
+
+**何时打开 reference**：各命令完整 flags / 分页 / 输出契约、`+db-execute` 多语句与事务语义、导入导出边界与限额、Base 同步的配置格式与生命周期 / 错误恢复、audit/changelog/env/recovery/quota 参数、时间格式、系统表白名单、user_profile 唯一表达式、pg function、JSONB 复杂注释等长尾限制 → 见 [full-reference.md](references/full-reference.md)。
+
+## Hard Rules
+
+| 规则 | 要求 |
+|---|---|
+| SQL 执行通道 | 只用 `+db-execute`，不要裸连数据库或调用其它 SQL 工具 |
+| 查结构只认 DB | 表结构 / 字段 / 索引 / 约束一律 `+db-table-list` / `+db-table-get --table <table>`。`server/database/schema.ts` 只在写 TS 代码对齐类型时读，**不能用来回答结构问题**——它是生成产物，除了可能滞后于 DB，还会静默丢掉条件索引的 `WHERE` 和 CHECK 约束（丢掉 WHERE 后，部分唯一索引在 `schema.ts` 里读起来是全表唯一） |
+| `schema.ts` 禁止手改 | `schema.ts` 是 `npm run gen:db-schema` 的生成产物。DB 结构不对就改 DDL 后重跑 `npm run gen:db-schema`；DB 正确但 `schema.ts` 渲染错误时同样不手改，向用户说明是 schema 生成器 bug |
+| DDL 后刷新 `schema.ts` | `+db-execute` **不会**自动刷新 `schema.ts`。每次 DDL 成功后立即在应用工程根目录执行 `npm run gen:db-schema`，再写引用新表 / 新列的 TS 代码 |
+| 变更历史只认 DB | 结构变更历史用 `+db-changelog-list`。`git log -- server/database/schema.ts` 只是代码侧痕迹，**不等价**，不能用来回答"做过哪些 DDL 改动" |
+| 要数据就查库 | 用户要的是查询结果本身（计数 / 明细 / 统计）时，直接 `+db-execute` 查完把结果给用户；**不要为一次性查询去新增接口或 service 代码** |
+| DDL 原子性 | CREATE TABLE + RLS + policy + COMMENT + INDEX 放在一次 `--sql` 调用；需要全回滚时显式 `BEGIN; ... COMMIT;` |
+| 高风险授权 | DDL、DELETE/TRUNCATE、`+db-env-create` / `+db-env-migrate` / `+db-recovery-apply` 执行前必须向用户展示影响范围并取得明确授权；exit-10 按沙箱约定协议处理 |
+| `--yes` 边界 | 只跳过 CLI 确认关卡，不能代替用户授权 |
+| 线上发布 / 恢复 | `+db-env-migrate` / `+db-recovery-apply` 前先跑 `+db-env-diff` / `+db-recovery-diff` 预览并给用户确认 |
+| 已有数据安全 | 已有表 / 已有数据禁止直接 DROP / DELETE；优先 ALTER / UPDATE；不确定先问用户 |
+| 环境选择 | 默认不传 `--environment`（服务端自动选分支）；确认应用开了多环境才显式传 `dev` 验写操作 |
+| 平台保留对象 | 禁止创建或修改 `auth`、`users` 等平台保留表；禁止 DROP 平台审计列 |
+| 业务人员字段 | 业务需要“创建人 / 负责人”字段时命名为 `creator` / `owner` / `author`，避免与审计列混淆 |
+| 本地文件路径 | `--file` / `--output` 用工作目录内相对路径；绝对路径或经 `..`/符号链接越出工作目录会被拒 |
+
+## CREATE TABLE Template
+
+新建业务表必须包含 4 个审计列、启用 RLS、创建 4 条默认 policy。
+
+```sql
+CREATE TABLE IF NOT EXISTS <table> (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- ... business columns ...
+  name varchar(100) NOT NULL,
+  _created_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  _created_by user_profile DEFAULT (
+    CASE
+      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
+      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
+    END
+  ),
+  _updated_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  _updated_by user_profile DEFAULT (
+    CASE
+      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
+      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
+    END
+  )
+);
+
+ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY service_role_bypass_policy ON <table>
+  TO service_role USING (true);
+
+CREATE POLICY "修改全部数据" ON <table>
+  AS PERMISSIVE FOR ALL TO authenticated USING (true);
+
+CREATE POLICY "查看全部数据" ON <table>
+  AS PERMISSIVE FOR SELECT TO authenticated, anon USING (true);
+
+CREATE POLICY "修改本人数据" ON <table>
+  AS PERMISSIVE FOR ALL TO authenticated USING (
+    (current_setting('app.user_id'::text) = ANY (ARRAY[]::text[]))
+    AND (current_setting('app.user_id'::text) = ((_created_by).user_id)::text)
+  );
+```
+
+## DDL Rules
+
+### DDL Workflow
+
+1. 先 `+db-table-list` 判断表是否存在；已有表再 `+db-table-get --table <table>` 看 DDL / columns / indexes / comments（`--format pretty` 直接给建表 DDL）。
+2. 生成 DDL 时只写裸表名，不写 `public.` 或 workspace schema。
+3. CREATE TABLE 必须带审计列、RLS、4 条默认 policy；JSONB 字段必须在同一次调用里写 `COMMENT ON COLUMN ... IS '@type { ... }'`。
+4. CREATE TABLE / CREATE INDEX / ALTER TABLE ADD COLUMN 必须带 `IF NOT EXISTS`，避免重复执行失败。
+5. 执行前向用户展示目标对象和变更内容；DROP / DROP COLUMN 还要说明数据丢失风险并取得明确授权。
+6. 执行：`lark-cli apps +db-execute --app-id "$app_id" --sql "<ddl>" --yes`。多条 DDL 是一个逻辑单元时放在一次调用；需要全回滚则显式包事务。
+7. DDL 成功后**立即**在应用工程根目录执行 `npm run gen:db-schema` 刷新 `server/database/schema.ts`——`+db-execute` 不会自动刷新。多批 DDL 每批成功后都跑一次。
+8. 已存在的表只能用 `ALTER TABLE` 修改。`CREATE TABLE IF NOT EXISTS` 只会跳过建表，**不会**更新已有列的类型、默认值或约束；执行 `ALTER TABLE` 后再次用 `+db-table-get --table <table>` 回读 DDL，确认目标定义已经改变。
+
+### DDL Do / Don't
+
+| 场景 | 做法 |
+|---|---|
+| 新建表 | 用本 skill CREATE TABLE Template，一次包含 RLS、policy、COMMENT、INDEX |
+| 修改表 | `ALTER TABLE <table> ADD COLUMN IF NOT EXISTS ...`，相关 COMMENT 同次执行 |
+| 加索引 | `CREATE INDEX IF NOT EXISTS idx_<table>_<cols> ON <table>(...)` |
+| JSONB 类型 | `COMMENT ON COLUMN t.payload IS '@type { key: string }'`（会据此生成 ORM 代码中的 ts 类型） |
+| 删除表 / 列 | 已有业务数据默认禁止；用户明确授权后才执行 |
+
+## SQL Pitfalls
+
+| 陷阱 | 正确做法 |
+|---|---|
+| 表名带 schema 前缀 | 业务表一律裸表名：`SELECT ... FROM user_profile`，不要写 `public.t` |
+| 保留字作标识符 | 避免 `user`、`order`、`desc`、`offset`、`references` 等 |
+| `IF NOT EXISTS` 滥用 | 支持：CREATE TABLE / INDEX / EXTENSION、ALTER TABLE ADD COLUMN；不支持：CREATE TYPE / POLICY / ADD CONSTRAINT |
+| 审计列写错 | 列名是 `_created_at` / `_updated_at` / `_created_by` / `_updated_by`，查询不要写 `created_at` |
+| user_profile 未解引用 | 查询 / 过滤用 `(field).user_id`；raw SQL 不直接返回复合类型给前端 |
+| user_profile 表达式索引 / 唯一性 | 索引用三重括号：`CREATE INDEX ... ON t (((owner).user_id))`；表达式唯一性用 `CREATE UNIQUE INDEX`，不要用 `ALTER TABLE ADD CONSTRAINT UNIQUE` |
+| UUID 手写 | 主键用 `DEFAULT gen_random_uuid()`；INSERT 不手写 UUID，外键用子查询取父表 id |
+| MySQL 方言 | 不用 `SHOW TABLES` / `DESCRIBE` / 内联 `COMMENT`；改用 `+db-table-list/get` 和 `COMMENT ON` |
+| 空数组类型不明 | 写 `ARRAY[]::text[]` 或 `'{}'::text[]` |
+| 标量子查询多行 | `VALUES((SELECT ...))` / `SET col=(SELECT ...)` 必须唯一或 `ORDER BY ... LIMIT 1` |
+| 系统表查询 | 常规结构查询用 `+db-table-list/get`；系统表仅限 reference 中列出的白名单 |
+| 多语句事务误判 | `A; B; C` 不自动包事务，B 失败时 A 不回滚；需要原子性用 `BEGIN/COMMIT` |
+| 时间表达式依赖会话时区 | `timestamptz` 参与日期/小时计算、CHECK 或表达式索引时，显式写 `AT TIME ZONE 'UTC'` 或明确的业务时区；用跨日期边界的时间值验证结果，禁止依赖会话默认时区 |
+
+### 写入前核对全部唯一性
+
+新增或修改 `INSERT`、`UPDATE`、upsert 写入逻辑前，先用 `+db-table-get --table <table> --format pretty` 读取目标表完整 DDL，列出其中**全部** UNIQUE 约束和唯一索引（含条件索引、表达式索引），逐条检查本次写入是否可能冲突。`ON CONFLICT` 只处理它明确匹配的那一条唯一规则，不能挡住其它唯一索引；发现其它冲突时，应在写入前按业务语义处理，或将 `23505` 转成明确的冲突错误，禁止让它冒成 500。
+
+## Data Types and Design
+
+| 项目 | 规则 |
+|---|---|
+| 主键 | 默认 `id UUID PRIMARY KEY DEFAULT gen_random_uuid()`；人员实体表可用 `user_profile PRIMARY KEY` |
+| 命名 | 单数、全小写、snake_case、无冗余后缀 |
+| 短文本 | 分类 / 状态 / 枚举用 `varchar(255)`，值用小写英文 + 下划线 |
+| JSONB | 必须 `COMMENT ON COLUMN ... IS '@type { ... }'` 声明 TypeScript 类型；复杂格式见 reference |
+| 强约束 | UNIQUE / FOREIGN KEY / NOT NULL 默认谨慎，不确定时不用；加 NOT NULL 列必须带 `DEFAULT` 让存量行自动填默认值：`ALTER TABLE <table> ADD COLUMN <col> <type> NOT NULL DEFAULT <默认值>` |
+| 附件 / 图片 | URL 用 `TEXT`，命名 `xxx_url`；图片 mock 遵循下方 generate_image 规则 |
+
+## Mock Data Rules
+
+| 规则 | 要求 |
+|---|---|
+| 数量 | 新建表默认插 3-6 条（除非用户明确不要）；现有表仅用户要求时造数据；要求更多时单表最多 20 条，再多走 `+db-data-import` |
+| 字段一致性 | 页面 / 业务会读的同表字段必须都在 SQL mock 中提供，禁止一半 DB 一半代码拼 |
+| user_id 来源 | 上下文明确 user_id > `env.userId` / `env.user.id` > 测试用户列表；禁止编造。外发字段（通知/发送/提醒/审批/群发/消息收件人，或传给飞书/邮件/IM/审批服务）禁止用测试用户列表或测试用户 `COALESCE`/默认/兜底；只用登录用户、用户明确 @ 或提供的可达对象。无可达对象时，留空收件人，或把样例状态设为 `pending`/`disabled`/仅展示。 |
+| 图片 URL | 写入数据库的任何图片字段，包括 JSONB 内嵌图片，都按“用户上传图 -> 历史语义匹配图 -> `generate_image`”顺序处理；只有工具失败才用带 seed 的 Picsum 兜底 |
+| 关联 | 外键 / 子查询引用的数据必须已存在；UUID 字段不用手写 |
+| 审计列 | `_created_at` / `_updated_at` 可省略；需要归属时显式写 `_created_by` / `_updated_by` |
+
+测试用户（**仅用于数据库 `user_profile` 展示/筛选样例**）：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
+
+> ⚠️ 这些是妙搭数字 user_id，**不是飞书 open_id**：禁止传给 `+role-member-add/remove` 的 `--users`（只收 `ou_`）或任何要 open_id 的飞书接口。
+
+### `user_id` / `user_profile`
+
+- `user_id` 是高频写入规则，不是长尾 reference：只能来自上下文明确给定、`env.userId` / `env.user.id`，或上方测试用户列表，禁止编造。
+- 写入 `user_profile` 字段用 `ROW('<user_id>')::user_profile`；更新复合类型时替换整个字段。
+- 查询 / 过滤 / 索引只用 `(field).user_id`，不依赖 `name` / `email` 等其它子字段。
+
+## SELECT Rules
+
+常规查询（含 `count(*)` 这类计数）直接用 `lark-cli apps +db-execute --app-id "$app_id" --sql "SELECT ..." --yes`，查完把结果给用户；查结构走 `+db-table-list/get`，不走 SELECT。
+
+| 规则 | 要求 |
+|---|---|
+| 字段 | 禁止 `SELECT *`；只返回页面 / 逻辑需要的列 |
+| 行数 | SELECT 返回 1000 行硬上限；必须显式 `LIMIT` 或聚合 |
+| 分页 | 大表优先游标分页：`WHERE id > <last_id> ORDER BY id LIMIT n`，避免大 OFFSET |
+| 统计 | 总数用 `count(*)`；分组用 `GROUP BY`；避免拉全量到 agent 侧统计 |
+| 慢查询 | 用 `EXPLAIN (ANALYZE, BUFFERS)`；大表 Seq Scan 时考虑加索引 |
+| PostgreSQL 函数 | `ROUND` 用 `ROUND(num::numeric, n)` 或 `ROUND(num::double precision)` |
+
+## DML Rules
+
+| 操作 | 规则 |
+|---|---|
+| INSERT | NOT NULL 且无默认值的列必须提供，批量 INSERT 每行列数一致；需要幂等用 `ON CONFLICT ... DO NOTHING` / `DO UPDATE`（mock 数量、UUID / user_id 来源、审计列写法见 Mock Data Rules） |
+| UPDATE | 必须有明确 WHERE，禁止无条件 UPDATE；用户说"修改 / 更新 / 改一下"数据时用 UPDATE，禁止 DELETE + INSERT；修改业务字段时同步 `_updated_at = CURRENT_TIMESTAMP` 和 `_updated_by`；影响范围不明先 `SELECT count(*)` 给用户确认 |
+| DELETE / TRUNCATE | 当前会话中 Agent 自己插入的 mock 可删；已有表 / 已有数据默认禁止，必须先 `SELECT count(*)` 展示命中行数并取得用户明确授权；`TRUNCATE` 影响整表，视同高风险删除 |
+
+`user_profile` 列的 INSERT / UPDATE 写法示例见 [full-reference.md](references/full-reference.md) 的 `user_profile` compound type 一节。
+
+## Import / Export
+
+前置检查、值类型、冲突、限额与 `.sql` 回放写法见 [full-reference.md](references/full-reference.md)。