fix(account): scope account-name uniqueness per organization (#625)

[os-zhuang]

Fixes #625

问题

crm_account 把"客户名称唯一"写成了表级声明索引 indexes: [{ fields: ['name'], unique: true }]。driver-sql 的 normalizeDeclaredIndex() 对声明索引的列原样保留、不做租户加权；只有字段级 unique: true 才会走 uniqueIndexesFromFields() 拿到 (organization_id, ...) 复合索引（framework#3696）。于是物理约束是 UNIQUE (name)，第二个组织创建名为 "Acme Corp" 的客户会被数据库直接拒绝。名称同时是种子数据的 external-id / upsert key（src/data/sales.seed.ts externalId: 'name'），所以这个问题在第一个多租户安装、在任何人录入数据之前就会踩到。

crm_contact.email / crm_lead.email / crm_product.sku 早就换成了字段级写法并在注释里记录了这个坑，crm_account 是最后一个还留着平台级写法的核心对象。

改动

• src/objects/account.object.ts：唯一性声明从表级 indexes[] 挪到字段 name 上（unique: true），并删除旧的 { fields: ['name'], unique: true }——不是两个都留。理由写进了注释：同时声明会让平台级索引胜出、把按租户的复合索引挤成不可达（framework#3991 unique/double-declaration），那样这个修复会"看起来生效、实际什么也没做"。底部 validations 注释里指向"上面那条 name 索引"的旧说明也一并更正。
• 不需要另加 { fields: ['name'] } 普通索引：复合索引以 organization_id 打头，WHERE organization_id = ? AND name = ? 正好是前缀匹配，searchableFields 和种子 upsert 的读路径都被它覆盖。
• content/docs/sales/accounts{,.zh-Hans,.zh-Hant}.mdx:这三份文档里那条规则原本写的是"名称在整个系统中必须唯一（不区分大小写）"。两半都是错的——范围现在是按组织，且没有任何地方做大小写归一（Normalize account matching in lead conversion (split out of #598 scope 2) #626 的分析已确认：flow 模板没有 LOWER/TRIM，公式字段没有物理列，也没有 hook 在做归一）。既然改的就是这句话，就把它一次写准，而不是留一个运行时并不兑现的承诺。

验证方式：真数据库，不是只断言元数据

新增 test/account-name-tenant-scope.test.ts（9 个用例，全绿）。关键点是声明不等于约束——本 bug 恰恰是"元数据说的"和"驱动生成的 DDL"之间的落差，所以只断言元数据形状是抓不住它的。测试分三层：

1. 元数据形状：name.unique === true，且 indexes[] 里没有任何 unique 条目（这一条是给未来的编辑者的：写回表级形式时，红的是带原因的断言，而不是一句裸 SQL 错误）。
2. 驱动推导的索引集：用 @objectstack/objectql 的 applySystemFields(..., { multiTenant: true }) 造出运行时真正交给驱动的 schema（含注入的 organization_id），再喂给 @objectstack/driver-sql 的 expectedIndexes()——正是 issue 里的复现路径。
3. 真 SQLite：SqliteWasmDriver(':memory:') + driver.initObjects([...])（boot 时的同一个调用），然后真的写入。

验收 1、2 是实测出来的：

INDEXES: uniq_crm_account_organization_id_name
         CREATE UNIQUE INDEX `uniq_crm_account_organization_id_name`
           on `crm_account` (`organization_id`, `name`)
org_a "Acme Corp" ok
org_b "Acme Corp" ok
org_a "Globex" 第二次 → UNIQUE constraint failed: crm_account.organization_id, crm_account.name

把 account.object.ts stash 掉再跑同一份测试，9 条里红 7 条，报错正是这个缺陷本身的签名（UNIQUE constraint failed: crm_account.name，且失败发生在 org_b 那次插入上）——测试不是空转的。

顺带一个观察：pnpm lint 在旧写法下不报 unique/double-declaration。那条 framework lint 只抓"两个都声明"的情形，而 crm_account 只有表级那一个，所以工具链此前对这个缺陷是完全沉默的。

升级路径（issue 验收第 3 条）

写在 changeset 里，正文会随发布进 CHANGELOG.md：

• 新建：uniq_crm_account_organization_id_name (organization_id, name) —— create_index，category: 'safe'，boot 时的 reconciler 会自动建。
• 需要删除：旧的 uniq_crm_account_name —— drop_index，category: 'destructive'，reconciler 会跳过，只有 os migrate apply --allow-destructive 才清得掉（docs/MAINTENANCE.md §3.1）。

留着旧索引不是无害的：它严格紧于新索引，只要还在就继续执行平台级唯一约束，这个修复静默失效。今天 HotCRM 只有全新安装——空库上按新元数据建表，uniq_crm_account_name 压根不会被创建，所以这一步现在无人需要执行；但将来一旦出现既存部署，升级必须跑一次 --allow-destructive，否则修了等于没修。这句话在 changeset 里是加粗写死的。

对 #626（客户名归一化）的影响：更好走

• Normalize account matching in lead conversion (split out of #598 scope 2) #626 scope 4 要决定"name_normalized 是否自带唯一索引"。本次改动把"唯一性怎么写"这个问题在本对象上已经答完了：字段级 unique: true，按租户。Normalize account matching in lead conversion (split out of #598 scope 2) #626 若要给归一列加唯一约束，照抄同一行写法即可，不用再重新论证一遍租户范围。
• Normalize account matching in lead conversion (split out of #598 scope 2) #626 提到的危险步骤没有被本次改动放大，反而缩小了：在既存部署上建 UNIQUE 索引会因已有重复而失败。(organization_id, name_normalized) 的冲突面比平台级 (name_normalized) 小——只有同一组织内的重名才会挡住建索引，跨组织的同名不再是障碍。也就是说合并（merge pass）的工作量比在旧模型下更小。
• 唯一需要留意的先后关系：Normalize account matching in lead conversion (split out of #598 scope 2) #626 的归一列如果也要唯一，它的 create_index 应当在旧 uniq_crm_account_name 被清掉之后再谈——但那对今天的全新安装不成立，两者都不会存在。
• 文档那句"不区分大小写"已经被改成实话（"名称按原样精确比较"），所以 Normalize account matching in lead conversion (split out of #598 scope 2) #626 落地时，文档那一行是加强承诺、而不是先去修一个旧谎言。

验证

pnpm validate   ✓ Validation passed (841ms) — 15 Objects 314 Fields
pnpm typecheck  ✓ tsc --noEmit，无输出
pnpm lint       1 warning(0 个与本改动相关：crm_campaign_member field-group，main 上既有)
pnpm hygiene    ✓ source hygiene clean
pnpm build      ✓ Build complete — dist/objectstack.json (1140.5 KB)
pnpm test       ✓ Test Files 44 passed (44) · Tests 1013 passed | 1 skipped (1014)

范围仅限 crm_account 的唯一性声明及其用户文档；未新增/删除字段，未改 i18n bundle（没有新增可翻译标签），未触碰 content/docs/releases/。

🤖 Generated with Claude Code

https://claude.ai/code/session_019SS7C5SXpniKeCApxgARyf

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 2, 2026 6:47pm