mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-10 00:40:30 +08:00
Initial commit: reorganized source tree
- backend/: 13 Maven modules (cw-elevator-application, cloudwalk-cloud, intelligent-cwoscomponent, ninca-crk, etc.) - frontend/: 4 Vue projects (elevator-front, cwos-portal, alarm-front, front_acs) + decompiled + scripts - scripts/: build, test-env, tools (Docker Compose, service templates, API parity) - docs/: AGENTS.md, superpowers specs, architecture docs - .gitignore: standard Java/Maven exclusions Moved from legacy maven-*/ root layout to backend/ organized structure.
This commit is contained in:
hpd840321
@@ -0,0 +1,308 @@
|
||||
# 数据库表结构参考手册 — 设计说明
|
||||
|
||||
**文档性质**：设计说明（非最终产物）
|
||||
**产物路径**：`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 阶段。*
|
||||
Reference in New Issue
Block a user