Neo-ZQYY/docs/database/BD_manual_biz_registry_tables.md

BD 手册：biz 注册体系表（NS4.1 registry）

概述

NS4.1 注册体系新增 4 张表，全部位于 biz Schema，建立「连接器 → 租户 → 店铺」三级注册体系。合并原 auth.site_code_mapping，统一管理上游 SaaS 系统、租户和店铺的关系，并为简写ID 提供归属和变更历史。

所有表位于 zqyy_app / test_zqyy_app 数据库。

变更原因

• NS4.1 注册体系设计，建立项目级「连接器 → 租户 → 店铺」三级结构
• 合并原 auth.site_code_mapping 到 biz.sites，增加租户关联和简写ID 变更历史管理
• 数据来源：种子数据从 auth.site_code_mapping 迁移，ETL 增量同步从 dwd.dim_site

变更说明

库	Schema	表	变更类型	说明
zqyy_app	biz	connectors	新建	连接器注册表
zqyy_app	biz	tenants	新建	租户注册表
zqyy_app	biz	sites	新建	店铺注册表（合并原 auth.site_code_mapping）
zqyy_app	biz	site_code_history	新建	简写ID 变更历史表
zqyy_app	auth	site_code_mapping	废弃重命名	→ auth._archived_site_code_mapping

---

1. biz.connectors — 连接器注册表

记录本项目接入的上游 SaaS 系统。当前仅有飞球（feiqiu）一个连接器，预留多连接器扩展能力。

表结构

列名	类型	约束	说明
id	SERIAL	PRIMARY KEY	自增主键
connector_key	VARCHAR(50)	UNIQUE NOT NULL	连接器标识（如 'feiqiu'）
display_name	VARCHAR(100)	NOT NULL	显示名称
is_active	BOOLEAN	NOT NULL DEFAULT true	是否启用
created_at	TIMESTAMPTZ	NOT NULL DEFAULT NOW()	创建时间

约束与索引

名称	类型	列	说明
connectors_pkey	PRIMARY KEY	id	主键
connectors_connector_key_key	UNIQUE	connector_key	连接器标识唯一

种子数据

INSERT INTO biz.connectors (connector_key, display_name) VALUES ('feiqiu', '飞球');

---

2. biz.tenants — 租户注册表

连接器下的租户，tenant_id 来自上游系统。同一连接器下 tenant_id 唯一。

表结构

列名	类型	约束	说明
id	SERIAL	PRIMARY KEY	自增主键
connector_id	INTEGER	NOT NULL FK → biz.connectors(id)	所属连接器
tenant_id	BIGINT	NOT NULL	上游系统租户 ID
tenant_name	VARCHAR(200)	—	租户名称
is_active	BOOLEAN	NOT NULL DEFAULT true	是否启用
created_at	TIMESTAMPTZ	NOT NULL DEFAULT NOW()	创建时间
updated_at	TIMESTAMPTZ	NOT NULL DEFAULT NOW()	更新时间

约束与索引

名称	类型	列	说明
tenants_pkey	PRIMARY KEY	id	主键
tenants_connector_id_tenant_id_key	UNIQUE	(connector_id, tenant_id)	同一连接器下租户唯一
tenants_connector_id_fkey	FOREIGN KEY	connector_id → biz.connectors(id)	外键关联连接器

种子数据

INSERT INTO biz.tenants (connector_id, tenant_id, tenant_name)
VALUES (1, 2790683160709957, '朗朗桌球');

---

3. biz.sites — 店铺注册表

合并原 auth.site_code_mapping，增加租户关联和简写ID 管理。site_id 来自上游系统，全局唯一。site_code 为当前生效的简写ID（6 位字符，3+3 格式），全局唯一。

表结构

列名	类型	约束	说明
id	SERIAL	PRIMARY KEY	自增主键
tenant_id	INTEGER	NOT NULL FK → biz.tenants(id)	所属租户
site_id	BIGINT	NOT NULL UNIQUE	上游系统门店 ID
site_name	VARCHAR(200)	—	门店名称
site_code	VARCHAR(6)	UNIQUE	当前生效的简写ID（3+3 格式，如 LLQ001）
site_label	VARCHAR(50)	—	门店标签
is_active	BOOLEAN	NOT NULL DEFAULT true	是否启用
created_at	TIMESTAMPTZ	NOT NULL DEFAULT NOW()	创建时间
updated_at	TIMESTAMPTZ	NOT NULL DEFAULT NOW()	更新时间

约束与索引

名称	类型	列	说明
sites_pkey	PRIMARY KEY	id	主键
sites_site_id_key	UNIQUE	site_id	上游门店 ID 唯一
sites_site_code_key	UNIQUE	site_code	简写ID 全局唯一
sites_tenant_id_fkey	FOREIGN KEY	tenant_id → biz.tenants(id)	外键关联租户

数据迁移

-- 从 auth.site_code_mapping 迁移真实数据
INSERT INTO biz.sites (tenant_id, site_id, site_name, site_code)
SELECT t.id, scm.site_id, scm.site_name, scm.site_code
FROM auth.site_code_mapping scm
JOIN biz.tenants t ON t.tenant_id = scm.tenant_id
WHERE scm.tenant_id IS NOT NULL;

-- ETL 增量同步补充：通过 FDW 读取 dwd.dim_site（scd2_is_current=1），
-- 补充 auth.site_code_mapping 中没有但 dwd.dim_site 中有的店铺

---

4. biz.site_code_history — 简写ID 变更历史表

增量记录所有使用过的简写ID。site_code 全局唯一（含历史），确保已退役的 code 不会被重新分配。每个 site_id 最多一条 is_current=true 记录。

表结构

列名	类型	约束	说明
id	SERIAL	PRIMARY KEY	自增主键
site_id	BIGINT	NOT NULL	关联 biz.sites.site_id
site_code	VARCHAR(6)	NOT NULL UNIQUE	简写ID（全局唯一，含历史）
is_current	BOOLEAN	NOT NULL DEFAULT false	true=当前生效，每个 site_id 最多一条
created_at	TIMESTAMPTZ	NOT NULL DEFAULT NOW()	创建时间
retired_at	TIMESTAMPTZ	—	退役时间（is_current=false 时设置）

约束与索引

名称	类型	列	说明
site_code_history_pkey	PRIMARY KEY	id	主键
site_code_history_site_code_key	UNIQUE	site_code	简写ID 全局唯一（含历史）

初始数据

-- 为已有 site_code 的店铺创建历史记录
INSERT INTO biz.site_code_history (site_id, site_code, is_current)
SELECT site_id, site_code, true
FROM biz.sites
WHERE site_code IS NOT NULL;

---

兼容性

组件	影响
后端 API	全部切换到 biz.sites + biz.site_code_history。新增 admin_registry 路由模块（租户列表、店铺列表、简写ID 管理）。admin_tenant_admins 路由中 tenant_id 从 biz.tenants 选择。tenant_users 路由中 site_code 查询从 auth.site_code_mapping 切换到 biz.sites
ETL	无直接影响。店铺同步通过 FDW 只读访问 ETL 库 dwd.dim_site，写入 biz.sites。ETL 流程本身不变
小程序	无需改动。用户申请时的 site_code 验证由后端 API 透明切换到 biz.sites + biz.site_code_history
管理后台（admin-web）	新增注册体系 API 调用（src/api/registry.ts），租户管理员创建流程从 biz.tenants/biz.sites 选择
原 auth.site_code_mapping	迁移完成后重命名为 auth._archived_site_code_mapping，保留供回滚

回滚策略

完整回滚（逆序 DROP + 恢复原表）

BEGIN;
-- 1. 逆序删除注册体系表
DROP TABLE IF EXISTS biz.site_code_history CASCADE;
DROP TABLE IF EXISTS biz.sites CASCADE;
DROP TABLE IF EXISTS biz.tenants CASCADE;
DROP TABLE IF EXISTS biz.connectors CASCADE;

-- 2. 恢复原表（如已重命名）
ALTER TABLE IF EXISTS auth._archived_site_code_mapping
  RENAME TO site_code_mapping;
COMMENT ON TABLE auth.site_code_mapping IS '店铺简写ID 映射表（已恢复）';
COMMIT;

注意：

• 回滚前需确认后端代码已切换回 auth.site_code_mapping 查询
• CASCADE 会级联删除依赖对象
• 如果 biz.sites 中已有新增店铺（ETL 同步补充的），回滚后这些数据将丢失

验证 SQL

-- 1. 验证 biz.sites 中已有 site_code 的店铺数量
SELECT COUNT(*) FROM biz.sites WHERE site_code IS NOT NULL;
-- 预期：与原 auth.site_code_mapping 中有 site_code 的行数一致

-- 2. 验证 sites 与 site_code_history 的一致性
SELECT s.site_id, s.site_code, h.is_current
FROM biz.sites s
LEFT JOIN biz.site_code_history h
  ON h.site_id = s.site_id AND h.site_code = s.site_code
WHERE s.site_code IS NOT NULL;
-- 预期：所有行的 h.is_current = true（每个有 code 的店铺在历史表中有对应的当前记录）

-- 3. 验证三级注册体系关联完整性
SELECT c.connector_key, t.tenant_name, COUNT(s.id) AS site_count
FROM biz.connectors c
JOIN biz.tenants t ON t.connector_id = c.id
LEFT JOIN biz.sites s ON s.tenant_id = t.id
GROUP BY c.connector_key, t.tenant_name;
-- 预期：至少 1 行（feiqiu / 朗朗桌球 / N），site_count > 0

-- 4. 验证 4 张注册体系表全部存在
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'biz'
  AND table_name IN ('connectors', 'tenants', 'sites', 'site_code_history')
ORDER BY table_name;
-- 预期：返回 4 行

-- 5. 验证 site_code 全局唯一性（sites + history 无冲突）
SELECT site_code, COUNT(*) AS cnt
FROM biz.site_code_history
GROUP BY site_code
HAVING COUNT(*) > 1;
-- 预期：返回 0 行（每个 site_code 在历史表中最多出现一次）

-- 6. 验证种子数据
SELECT connector_key, display_name FROM biz.connectors WHERE connector_key = 'feiqiu';
-- 预期：1 行（feiqiu / 飞球）
SELECT tenant_id, tenant_name FROM biz.tenants WHERE tenant_id = 2790683160709957;
-- 预期：1 行（2790683160709957 / 朗朗桌球）

关联文件

• DDL 基线（biz）：docs/database/ddl/zqyy_app__biz.sql
• 迁移脚本：db/zqyy_app/migrations/2026-03-22__ns41_registry_tables.sql
• 后端路由：apps/backend/app/routers/admin_registry.py
• 后端 Schema：apps/backend/app/schemas/admin_registry.py
• 管理员路由：apps/backend/app/routers/admin_tenant_admins.py
• 前端 API：apps/admin-web/src/api/registry.ts
• Spec：.kiro/specs/admin-web-enhancement/
• PRD：docs/prd/Neo_Specs/NS4.1-tenant-admin-redesign.md