@lark-apaas/coding-miaoda-sandbox-skills 0.1.27 → 0.1.28

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

@@ -133,6 +133,7 @@ CREATE POLICY "修改本人数据" ON <table>
 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
 
@@ -160,6 +161,11 @@ CREATE POLICY "修改本人数据" ON <table>
 | 标量子查询多行 | `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
 

package/miaoda/miaoda-sql/SKILL.md

@@ -121,6 +121,7 @@ CREATE POLICY "修改本人数据" ON <table>
 4. CREATE TABLE / CREATE INDEX / ALTER TABLE ADD COLUMN 必须带 `IF NOT EXISTS`，避免重复执行失败。
 5. 执行前向用户展示目标对象和变更内容；DROP / DROP COLUMN 还要说明数据丢失风险并取得明确授权。
 6. 执行：`miaoda db sql "<ddl>"`。多条 DDL 是一个逻辑单元时放在一次调用；需要全回滚则显式包事务。
+7. 已存在的表只能用 `ALTER TABLE` 修改。`CREATE TABLE IF NOT EXISTS` 只会跳过建表，**不会**更新已有列的类型、默认值或约束；执行 `ALTER TABLE` 后再次用 `miaoda db schema get <table>` 回读 DDL，确认目标定义已经改变。
 
 ### DDL Do / Don't
 
@@ -149,6 +150,11 @@ CREATE POLICY "修改本人数据" ON <table>
 | 标量子查询多行 | `VALUES((SELECT ...))` / `SET col=(SELECT ...)` 必须唯一或 `ORDER BY ... LIMIT 1` |
 | 系统表查询 | 常规结构查询用 schema 命令；系统表仅限 reference 中列出的白名单 |
 | 多语句事务误判 | `A; B; C` 不自动包事务，B 失败时 A 不回滚；需要原子性用 `BEGIN/COMMIT` |
+| 时间表达式依赖会话时区 | `timestamptz` 参与日期/小时计算、CHECK 或表达式索引时，显式写 `AT TIME ZONE 'UTC'` 或明确的业务时区；用跨日期边界的时间值验证结果，禁止依赖会话默认时区 |
+
+### 写入前核对全部唯一性
+
+新增或修改 `INSERT`、`UPDATE`、upsert 写入逻辑前，先用 `miaoda db schema get <table>` 读取目标表完整 DDL，列出其中**全部** UNIQUE 约束和唯一索引（含条件索引、表达式索引），逐条检查本次写入是否可能冲突。`ON CONFLICT` 只处理它明确匹配的那一条唯一规则，不能挡住其它唯一索引；发现其它冲突时，应在写入前按业务语义处理，或将 `23505` 转成明确的冲突错误，禁止让它冒成 500。
 
 ## Data Types and Design
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [