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` 执行：

```sql
-- 表清单
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`），除非该列参与唯一约束

```mermaid
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"` | 虚线，标注跨库 |

```mermaid
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` 按数据库分组，避免单图过大：

```mermaid
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 表格：

```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 阶段。*