数据库

Quark ERP 在 PostgreSQL 上使用 TypeORM。多数表优先用共享默认 DataSource。插件还可用 @Database 打开一个或多个自定义连接，其他插件可通过所有者插件名（及可选连接名）注入并复用这些连接。

技术栈

PostgreSQL — 主持久化存储（环境变量来自 PluginEnv / base .env）
TypeORM — 实体、仓储、QueryRunner、迁移
默认数据源 — 共享核心连接；多数插件用 plugin: "default" 并入
自定义数据源 — 在根 @Module 上用 @Database；同一插件可声明多个命名连接
跨插件复用 — @InjectDatabaseSource("other-plugin", "connection-name?")

@InjectDatabaseSource

在服务属性上注入 TypeORM DataSource（不支持构造函数注入）。第一个参数是拥有该连接的插件；第二个参数是可选连接名（该插件声明了多个 @Database 时使用）。

DataSourceManager.DEFAULT_PLUGIN — 主核心数据源
metadata.name — 本插件自己的默认自定义连接
"other-plugin" — 其他插件创建的连接
第二个参数 name — 所有者插件有多个 @Database 时的命名连接（如 "analytics"）

TSXinject

import { DataSource } from "typeorm";
import {
  InjectDatabaseSource,
  DataSourceManager,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { OrderEntity } from "./order.entity.js";

@Service()
export class OrderService {
  // Shared core Postgres
  @InjectDatabaseSource(DataSourceManager.DEFAULT_PLUGIN)
  source: DataSource;

  // This plugin’s own connection (default name)
  @InjectDatabaseSource(metadata.name)
  pluginSource: DataSource;

  // This plugin’s named connection
  @InjectDatabaseSource(metadata.name, "analytics")
  analyticsSource: DataSource;

  // Connection owned by another plugin
  @InjectDatabaseSource("warehouse", "replica")
  warehouseReplica: DataSource;

  private get repo() {
    return this.source.getRepository(OrderEntity);
  }
}

定义实体

表名必须以插件名开头。在模板字符串中使用 metadata.name。始终继承 BaseEntity 以获得创建/更新/软删除列。

TSXentity

import { BaseEntity } from "@quan-erp/shared-backend-core";
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
import metadata from "../../../../module.metadata.json" with { type: "json" };

@Entity(`${metadata.name}_driver_document`)
export class DriverDocumentEntity extends BaseEntity {
  @PrimaryGeneratedColumn("increment")
  id: number;

  @Column()
  documentName: string;
}

在模块中注册

按数据源分组实体。主共享连接用 plugin: "default"。自定义 @Database 时，plugin（及可选 name）须与该连接匹配。

TSXdefault datasource

import { Module } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { OrderController } from "./order.controller.js";
import { OrderService } from "./order.service.js";
import { DriverDocumentEntity } from "./driver-document.entity.js";

@Module({
  name: metadata.name,
  providers: [OrderService],
  controllers: [OrderController],
  entities: [
    {
      plugin: "default",
      entities: [DriverDocumentEntity],
    },
  ],
})
export class MyPluginModule {}

自定义数据源（@Database）

在根模块上用一个或多个 @Database 声明 TypeORM 连接。仅在确实需要隔离（独立主机/schema、报表库、副本等）时使用。凭据从环境变量读取，不要硬编码。

@Database({ name?, options }) 加在根 @Module 类上
name — 同一插件打开多个库时需要
options — TypeORM DataSourceOptions
实体 — 用匹配的 plugin + name 注册
同一模块类上多个 @Database = 多条连接

TSXmultiple connections in one plugin

import {
  Database,
  Module,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { AnalyticsEntity } from "./analytics.entity.js";
import { WarehouseEntity } from "./warehouse.entity.js";
import { AnalyticsService } from "./analytics.service.js";

@Database({
  name: "analytics",
  options: {
    type: "postgres",
    host: process.env.ANALYTICS_DB_HOST,
    port: Number(process.env.ANALYTICS_DB_PORT ?? 5432),
    username: process.env.ANALYTICS_DB_USERNAME,
    password: process.env.ANALYTICS_DB_PASSWORD,
    database: process.env.ANALYTICS_DB_SCHEMA,
    synchronize: process.env.ANALYTICS_DB_SYNC === "true",
  },
})
@Database({
  name: "replica",
  options: {
    type: "postgres",
    host: process.env.REPLICA_DB_HOST,
    port: Number(process.env.REPLICA_DB_PORT ?? 5432),
    username: process.env.REPLICA_DB_USERNAME,
    password: process.env.REPLICA_DB_PASSWORD,
    database: process.env.REPLICA_DB_SCHEMA,
    synchronize: false,
  },
})
@Module({
  name: metadata.name,
  providers: [AnalyticsService],
  controllers: [],
  entities: [
    {
      plugin: metadata.name,
      name: "analytics",
      entities: [AnalyticsEntity],
    },
    {
      plugin: metadata.name,
      name: "replica",
      entities: [WarehouseEntity],
    },
  ],
})
export class MyPluginModule {}

使用其他插件的连接

连接按所有者插件（+ 可选 name）登记在进程级 DataSource 注册表中。消费方插件不要为同一库再声明 @Database，而是注入所有者的连接；需要时把实体注册到相同的 plugin + name 范围。

所有者插件 — 声明 @Database，并先启动（写入 pluginDependencies）
消费方 — @InjectDatabaseSource("owner-plugin", "connection-name")
外键连接上的实体 — plugin: "owner-plugin"，name: "connection-name"
不要在每个消费方重复声明相同的 @Database
所有者插件安装并加载后，消费方才能注入其 DataSource

TSXconsumer plugin service

import { DataSource } from "typeorm";
import { InjectDatabaseSource, Service } from "@quan-erp/shared-backend-core";

@Service()
export class ReportService {
  // "warehouse" plugin declared @Database({ name: "replica", ... })
  @InjectDatabaseSource("warehouse", "replica")
  warehouseReplica: DataSource;
}

TSXconsumer module entities on foreign connection

@Module({
  name: metadata.name,
  providers: [ReportService],
  controllers: [],
  entities: [
    {
      plugin: "warehouse",
      name: "replica",
      entities: [ReportSnapshotEntity],
    },
  ],
})
export class ReportPluginModule {}

CRUD 模式

创建：repo.insert(...) → 从 identifiers 返回 { id }
更新：repo.update 并检查 affected
删除：优先 repo.softDelete + 检查 affected

数据库

技术栈