starRiverProperty/docs/superpowers/specs/2026-05-01-database-schema-reference-design.md

数据库表结构参考手册 — 设计说明

文档性质：设计说明（非最终产物）
产物路径：docs/superpowers/specs/2026-05-01-database-schema-reference.md（待生成）
设计日期：2026-05-01
状态：待评审

---

1. 目标与范围

走查代码和 .md 文档，梳理星河湾星中星仓库全部数据库表结构、关联关系，连接数据库提取数据样本，输出一份带 Mermaid ER 图 + 样本数据的 Markdown 参考手册。

1.1 范围

覆盖	不覆盖
5 个数据库的全部业务表	系统表（如 quartz_*、QRTZ_*）
代码层 MyBatis Mapper 映射的表	纯运维/监控表
跨库业务关联（business_id、personId）	数据库级外键（本项目不声明 FK）
每表 1-3 行脱敏样本	全量数据导出

1.2 涉及数据库

数据库	主机	模块	采集方式
component-organization	192.168.3.12:3307	组织服务（独立微服务）	🔗 直连查询
cw-elevator-application	192.168.3.12:3307	maven-cw-elevator-application	🔗 直连查询
ninca_crk_std	10.128.123.108:3306	maven-ninca-crk	📄 代码推导
alarm_deploy	10.128.161.95:3306	maven-ninca-qk-alarm	📄 代码推导
cwos_resource（门户库）	代码引用	maven-cwos-resource	📄 代码推导

---

2. 产物结构

文件：docs/superpowers/specs/2026-05-01-database-schema-reference.md

# 星河湾星中星 — 数据库表结构参考手册

## 1. 数据库概览
  - 5 库表格：库名、主机、引擎版本、表数量、采集方式

## 2. 组件组织库 — component-organization
  - ER 图（Mermaid）
  - 表清单（名称、行数、引擎、注释）
  - 逐表详情（列名、类型、可空、默认值、键、注释）
  - 关系说明
  - 样本数据

## 3. 电梯应用库 — cw-elevator-application
  - （同上结构）

## 4. 人脸识别库 — ninca_crk_std ⚠️ 代码推导
  - ER 图（从 Mapper XML 推导）
  - 逐表详情（从 Mapper `resultMap` / SQL 推导列）
  - 标注「未连接生产库」

## 5. 报警库 — alarm_deploy ⚠️ 代码推导
  - （同上结构）

## 6. 门户资源库 — cwos_resource ⚠️ 代码推导
  - （同上结构）

## 7. 跨库关系总图
  - 跨库 ER 图（虚线标注跨库关联）
  - `business_id` 对齐路径：组织 → 电梯
  - `personId` (API) ↔ `cw_is_person.ID` ↔ `image_rule_ref.person_id`
  - Feign 调用链中的库切换点

## 8. 代码-表映射索引
  - MyBatis Mapper XML → 表名
  - Java DAO/DTO → 表名
  - SQL DDL 文件位置

## 9. 附录
  - 完整 INFORMATION_SCHEMA 原始输出（折叠）
  - 脱敏样本数据完整集（折叠）
  - 验证 SQL 模板

---

3. 数据采集策略

3.1 三步并行流程

Step 1 (并行)                    Step 2 (并行)
┌──────────────────┐          ┌─────────────────────┐
│ 连接 192.168.3.12 │          │ 扫描全部 Mapper XML │
│ INFORMATION_SCHEMA│          │ 提取表/列/JOIN 关系 │
│ + SELECT 样本     │          │ 扫描 SQL DDL 文件   │
└──────┬───────────┘          └──────────┬──────────┘
       │                                 │
       └──────────┬──────────────────────┘
                  ▼
         Step 3 (汇总)
       ┌──────────────────┐
       │ 交叉验证           │
       │ 代码表 vs 库表     │
       │ DDL vs 实际列     │
       │ 生成 ER 图 + 文档  │
       └──────────────────┘

3.2 Step 1：直连查询（可连库）

对 component-organization 和 cw-elevator-application 执行：

-- 表清单
SELECT TABLE_NAME, TABLE_ROWS, ENGINE, TABLE_COMMENT
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA = ?
ORDER BY TABLE_NAME;

-- 列定义
SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_DEFAULT,
       COLUMN_KEY, EXTRA, COLUMN_COMMENT
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
ORDER BY ORDINAL_POSITION;

-- 索引
SELECT INDEX_NAME, COLUMN_NAME, NON_UNIQUE
FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?;

-- 样本（每表 3 行）
SELECT * FROM <table> ORDER BY 1 DESC LIMIT 3;

3.3 Step 2：代码推导（全部模块）

对每个 Maven 模块，读取 MyBatis Mapper XML 提取：

提取项	XML 元素	用途
表名	INSERT INTO / UPDATE / FROM / JOIN	确定 Mapper 操作的表
列映射	<resultMap> / <result column="...">	列名与 Java 字段对应
JOIN 关系	SQL 中的 JOIN ... ON 子句	推导表间关联
分表逻辑	ShardingSphere 配置中的 actual-data-nodes	标注年度分表

对 maven-cwos-resource：Mapper XML 分布在 db2/、mysql/、oracle/ 三个目录下，代表三种数据库方言实现，以 mysql/ 为准推导列。

3.4 不可达库的标注

对 ninca_crk_std、alarm_deploy、cwos_resource（无法从 192.168.3.12 访问）：

• 表名从 Mapper XML 和应用配置文件推导
• 列定义从 Mapper 的 <resultMap> 和 SQL 语句推导
• 在文档中显式标注：⚠️ 未连接生产库，以下信息从代码推导
• 不提供样本数据

---

4. ER 图绘制规范

4.1 实体定义

每表仅列业务关键列：

• 主键（PK）
• 唯一键（UK）
• 外键关联列
• 业务核心字段
• 跳过审计列（created_by、created_at、updated_by、updated_at），除非该列参与唯一约束

erDiagram
  tenant_visitor_floor_policy {
    varchar id PK "主键"
    varchar business_id UK "租户ID"
    varchar policy_type "策略类型"
    text allow_zone_ids "JSON数组"
    tinyint enabled "1启用0停用"
    bigint policy_version "版本号"
  }

4.2 关系标注

关系类型	Mermaid 语法	说明
数据库 PK/FK/UK 约束	||--o{	实线，有约束
代码层 JOIN（无 FK）	|o--o{	虚线，逻辑关联
跨库关联	.. 虚线 + : "跨库 label"	虚线，标注跨库

erDiagram
  cw_is_organization ||--o{ cw_is_organization : "PARENT_ID 自引用"
  cw_is_organization ||--o{ cw_is_person_organization_ref : "ORG_ID"
  cw_is_person ||--o{ cw_is_person_organization_ref : "PERSON_ID"
  tenant_visitor_floor_policy |o--o{ image_rule_ref : "business_id 对齐"

4.3 分包

用 subgraph 按数据库分组，避免单图过大：

erDiagram
  subgraph orgLib [component-organization]
    cw_is_organization {...}
    cw_is_person {...}
    cw_is_person_organization_ref {...}
  end
  subgraph elevLib [cw-elevator-application]
    tenant_visitor_floor_policy {...}
    image_rule_ref {...}
  end

4.4 跨库关系图

第七节单独一张图，用虚线标出跨库对齐路径：

• cw_is_organization.BUSINESS_ID ↔ tenant_visitor_floor_policy.business_id
• cw_is_person.ID ↔ image_rule_ref.person_id（通过 API 字段 personId）
• Feign 调用链：AcsPersonController → PersonService_detail → PersonRuleServiceImpl → TenantVisitorFloorPolicyDao

---

5. 样本数据规范

5.1 采集

每表执行 SELECT * FROM <table> ORDER BY 1 DESC LIMIT 3;

5.2 展示格式

主文档中每表嵌入 Markdown 表格：

### image_rule_ref — 样本数据

| id | business_id | zone_id | zone_name | person_id | is_default |
|----|-------------|---------|-----------|-----------|------------|
| `abc123...` | `25246398...` | `60556054...` | 28F | `def456...` | 1 |

_共 3 行 × 15 列（12 列省略，完整数据见 §9 附录）_

5.3 脱敏规则

列内容	处理方式
id / UUID 主键	完整展示（非 PII）
business_id	完整展示（已在公开文档中出现）
person_id / visitor_id	完整展示（系统内部 ID）
人员姓名 NAME	截断为 张**
手机号	截断为 138****1234
IP 地址	替换为 x.x.x.x
密码 / token	跳过该列（SELECT 时排除）
Unix 毫秒时间戳	转换为 2026-04-30 14:30:00

5.4 数据量

• 主文档每表 ≤ 3 行
• 附录完整样本（折叠块）≤ 500 行总计
• 不可达库不提供样本数据

---

6. 质量校验

6.1 交叉验证

校验项	方法
代码表 vs 库表	列出「库中有但代码无 Mapper」的表（标注为运维/外部表）
DDL vs 实际列	对比 docs/sql/*.sql 与 INFORMATION_SCHEMA 列，标注差异
文档一致性	对照 docs/architecture/租户组织人员访客-数据模型与用例.md 中的列定义

6.2 完整性检查

• 每库有 ER 图
• 每表有列清单
• 可连库的表有样本数据
• 跨库关系图覆盖所有已识别关联
• 每表关联到至少一个 Mapper XML 或标注「无代码映射」
• 无 TBD、TODO、待补充 占位符

---

7. 文件清单

文件	说明
docs/superpowers/specs/2026-05-01-database-schema-reference.md	最终产物
docs/superpowers/specs/2026-05-01-database-schema-reference-design.md	本设计说明
data/schema_raw/（产物中引用）	INFORMATION_SCHEMA 原始 JSON 缓存

---

8. 已知风险

风险	缓解
192.168.3.12 不可达	降级为全代码推导，标注「库不可达」
分表（ShardingSphere 2020..2030）导致 INFORMATION_SCHEMA 不完整	从 ShardingSphere 配置提取逻辑表名，标注物理表范围
alarm_deploy 等库可能含 Elasticsearch 数据（非 MySQL）	标注 ES 索引，不纳入本次 MySQL 范围
样本数据量过大导致 token 消耗	严格限制每表 3 行 + 跳过宽表（> 30 列）

---

本设计说明待评审，评审通过后转入 implementation 阶段。