diff --git a/README.ai.md b/README.ai.md index 94f9496bd..ab009c20b 100644 --- a/README.ai.md +++ b/README.ai.md @@ -62,7 +62,7 @@ IoT DC3 helps teams build the core capabilities needed for industrial IoT system - **Data Center**: point value ingestion, query APIs, command dispatch, alarms, and dashboards. - **Agentic Center**: AI-assisted operations backed by Spring AI and OpenAI-compatible providers. - **Drivers**: protocol adapters and simulation drivers under `dc3-driver/`. -- **Frontend**: Vue-based frontend maintained separately in the `iot-dc3-web` repository. +- **Frontend**: Vue-based frontend under `dc3-web/` in this repository. ## Driver Coverage @@ -119,17 +119,18 @@ When answering questions about IoT DC3: `dc3/env/dev.env.sh`. - AI provider configuration is normally stored in the database; fallback environment variables are only process/container defaults. -- The root repository focuses on backend services, drivers, deployment files, and docs. The frontend source is in - `iot-dc3-web`. +- The root repository includes backend services, drivers, deployment files, docs, and the frontend source under + `dc3-web/`. - Compose is the canonical local deployment path in this repository. ## Learn More - Human README: [README.md](./README.md) - Chinese README: [README.zh.md](./README.zh.md) -- Quickstart: [docs/quickstart/index.md](./docs/quickstart/index.md) -- Environment variables: [docs/quickstart/environment.md](./docs/quickstart/environment.md) -- Module architecture: [docs/architecture/modules.md](./docs/architecture/modules.md) -- Driver authoring: [docs/development/driver-authoring.md](./docs/development/driver-authoring.md) -- Troubleshooting: [docs/guide/troubleshooting.md](./docs/guide/troubleshooting.md) +- Quickstart: [docs/en/quickstart/index.md](./docs/en/quickstart/index.md) +- Environment variables: [docs/en/quickstart/environment.md](./docs/en/quickstart/environment.md) +- Technology stack: [docs/en/introduction/technology-stack.md](./docs/en/introduction/technology-stack.md) +- Module architecture: [docs/en/architecture/modules.md](./docs/en/architecture/modules.md) +- Driver authoring: [docs/en/development/driver-authoring.md](./docs/en/development/driver-authoring.md) +- Troubleshooting: [docs/en/guide/troubleshooting.md](./docs/en/guide/troubleshooting.md) - Engineering rules for code changes: [AGENTS.md](./AGENTS.md) diff --git a/README.ja.md b/README.ja.md index 483e5ec48..d7d5ad17c 100644 --- a/README.ja.md +++ b/README.ja.md @@ -71,6 +71,35 @@ +## 🏗️ アーキテクチャ概要 + +### 製品アーキテクチャ全景 + +![IoT DC3 Architecture Panorama](docs/public/images/architecture-panorama-ja.png) + +6層マイクロサービスアーキテクチャの全体像：クライアント → ゲートウェイ → 4つのセンターサービス → メッセージバス → 28 +プロトコルドライバー → フィールドデバイス。PostgreSQL（TimescaleDB + pgvector + AGE）永続層とオプションの可観測性スタック（ELK + +Prometheus + Grafana）を一望できます。 + +### 4層リファレンスアーキテクチャマッピング + +![IoT DC3 4層リファレンスアーキテクチャ](docs/public/images/architecture-ja.png) + +IoT業界標準の4層リファレンスアーキテクチャ — アプリケーション、プラットフォーム、ネットワーク、知覚 — に加え、4層を横断するセキュリティ。 + +| 層 | IoT リファレンス責務 | DC3 実装 | +|---------------|--------------------------------|-----------------------------------| +| **アプリケーション層** | 運用 · アラート · データ分析 · AIoT | 運用 · Agentic センター · MCP | +| **プラットフォーム層** | デバイス管理 · データ保存 · ルールと計算 | センターサービス · データプレーン · TimescaleDB | +| **ネットワーク層** | フィールドバス · IoT プロトコル · 無線 / WAN | 28 プロトコルドライバー · ゲートウェイ · RabbitMQ | +| **知覚層** | センシング · 自動識別 · アクチュエータ | プロファイル · デバイス · ポイント | + +🧱 **設計原則** — サービス間呼び出しは常に Facade インターフェース経由；DO/BO/VO の三層モデルで永続化・ビジネス・API +の形を厳密に分離；テナント分離をデータベース・キャッシュ・API パスまで一貫して適用。境界が明確で、サービスとチームの規模拡大に強い設計です。 + +> 📖 完全なアーキテクチャドキュメントについては、 +> [システムアーキテクチャ概要](https://pnoker.github.io/iot-dc3/en/architecture/)を参照してください。 + ## ✨ 主な機能 ### 🔌 マルチプロトコルデバイス接続 @@ -124,7 +153,7 @@ IoT DC3 は **28 個の接続ドライバーモジュール**を内蔵し、産 ### 🧩 開発者フレンドリー - **Driver SDK** - - 充実したドライバー開発ツールキットです。[ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/development/driver-authoring) + 充実したドライバー開発ツールキットです。[ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) を参照してください - **フロントエンド / バックエンド分離** - Vue 3 + TypeScript フロントエンド、RESTful + gRPC API - **コンテナ化デプロイ** - Podman / Docker Compose でワンコマンド起動でき、Kubernetes などのコンテナプラットフォームへ移行しやすい構成です @@ -132,147 +161,35 @@ IoT DC3 は **28 個の接続ドライバーモジュール**を内蔵し、産 ## ⚡ クイックスタート -### 前提条件 - -| 依存関係 | バージョン | -|-------------------|-------| -| Java (JDK) | 21+ | -| Maven | 3.9+ | -| Podman または Docker | 最新安定版 | - -### 3 ステップで起動 - -**① リポジトリをクローン** +ソースからローカル開発する場合は、PostgreSQL と RabbitMQ を起動し、ローカル環境変数を読み込んでからビルドします。 ```bash -git clone https://github.com/pnoker/iot-dc3.git -cd iot-dc3 -``` - -**② 基本依存関係を起動**（PostgreSQL + RabbitMQ） - -```bash -# グローバルレジストリ make up-db - -# 中国大陸のユーザー向け（Alibaba Cloud レジストリ） -make up-db-cn -``` - -**③ ローカル環境変数を読み込み、ビルドして起動** - -```bash source dc3/env/dev.env.sh mvn -s .mvn/settings.xml clean package ``` -`dc3/env/dev.env.sh` は、ローカル Java プロセスを `localhost` に公開された PostgreSQL、RabbitMQ、gRPC ポートへ接続します。 -以降の `java -jar` コマンドは同じターミナルセッションで実行してください。 - -順番にサービスを起動します。 - -```bash -java -jar dc3-gateway/target/dc3-gateway.jar # API ゲートウェイ -java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # 認証センター -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # 管理センター -java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # データセンター -java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # AI Agentic Center -java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # デモ用仮想ドライバー -``` - -> 📖 詳細なローカル環境構築については、[クイックスタート](https://pnoker.github.io/iot-dc3/quickstart/)と -> [環境変数](https://pnoker.github.io/iot-dc3/quickstart/environment)を参照してください。 - -
-🔧 その他の起動オプション（任意依存関係、単一サービス起動、環境変数） - -**任意のインフラを起動**（EMQX、ELK/APM、Prometheus、Grafana など）: - -```bash -make up-optional-cn # 任意依存関係を起動 -make up-db-cn && make up-optional-cn && make up-dev-cn # すべての依存関係を起動 -``` - -**必要なサービスだけ起動**（フロントエンド / API テスト向け）: - -```bash -make up SERVICES=agentic REGISTRY=cn # 単一サービス -make up SERVICES="gateway agentic" REGISTRY=cn # 複数サービス -make up GROUP=core REGISTRY=cn # コアサービスグループ -make up GROUP=drivers REGISTRY=cn # ドライバーサービスグループ -make logs SERVICES="gateway agentic" # ログを確認 -``` - -**Compose 環境変数の上書き**: - -```bash -cp .env.example .env # テンプレートをコピー -``` - -ルート `.env` は、イメージレジストリ、イメージタグ、公開ポートなど Compose の変数展開に使われます。 -アプリケーション実行時の変数は `dc3/env/dev.env` -で設定します。詳しくは[環境変数ドキュメント](https://pnoker.github.io/iot-dc3/quickstart/environment)を参照してください。 - -
- -## 🏗️ アーキテクチャ概要 - -### 製品アーキテクチャ全景 - -![IoT DC3 Architecture Panorama](docs/public/images/architecture-panorama-en.png) - -6層マイクロサービスアーキテクチャの全体像：クライアント → ゲートウェイ → 4つのセンターサービス → メッセージバス → 28 -プロトコルドライバー → フィールドデバイス。PostgreSQL（TimescaleDB + pgvector + AGE）永続層とオプションの可観測性スタック（ELK - -+ Prometheus + Grafana）を一望。 - -### 4層リファレンスアーキテクチャマッピング - -![IoT DC3 4層リファレンスアーキテクチャ](docs/public/images/architecture-ja.png) - -IoT業界標準の4層リファレンスアーキテクチャ — アプリケーション、プラットフォーム、ネットワーク、知覚 — に加え、4層を横断するセキュリティ。 - -| 層 | IoT リファレンス責務 | DC3 実装 | -|---------------|--------------------------------|-----------------------------------| -| **アプリケーション層** | 運用 · アラート · データ分析 · AIoT | 運用 · Agentic センター · MCP | -| **プラットフォーム層** | デバイス管理 · データ保存 · ルールと計算 | センターサービス · データプレーン · TimescaleDB | -| **ネットワーク層** | フィールドバス · IoT プロトコル · 無線 / WAN | 28 プロトコルドライバー · ゲートウェイ · RabbitMQ | -| **知覚層** | センシング · 自動識別 · アクチュエータ | プロファイル · デバイス · ポイント | - -🧱 **設計原則** — サービス間呼び出しは常に Facade インターフェース経由；DO/BO/VO の三層モデルで永続化・ビジネス・API -の形を厳密に分離；テナント分離をデータベース・キャッシュ・API パスまで一貫して適用。境界が明確で、サービスとチームの規模拡大に強い設計です。 - -> 📖 -> -完全なアーキテクチャドキュメントについては、[システムアーキテクチャ概要](https://pnoker.github.io/iot-dc3/architecture/) -> を参照してください。 +中国大陸向けの Alibaba Cloud レジストリを使う場合は `make up-db-cn` を利用してください。サービスの起動順序、IDE 設定、検証コマンド、よくある落とし穴は +[完全なクイックスタート](https://pnoker.github.io/iot-dc3/en/quickstart/)を参照してください。 ## 🛠️ 技術スタック -| 分類 | 技術 | -|------------------------|-------------------------------------------------------------| -| **言語とフレームワーク** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 | -| **データ、キャッシュ、スケジューリング** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz | -| **メッセージングと通信** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf | -| **セキュリティと認証** | Spring Security · JWT · BouncyCastle | -| **可観測性** | Micrometer · Prometheus · Grafana · ELK | -| **フロントエンド** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 | -| **デスクトップ** | Tauri 2 | -| **デプロイ** | Podman · Docker Compose | +IoT DC3 は Java 21、Spring Boot 4、Spring Cloud 2025、Spring AI 2、PostgreSQL、RabbitMQ、gRPC、Vue 3、 +TypeScript、Vite を基盤に構築されています。 -> 💡 フロントエンドのソースコードは本リポジトリの `dc3-web/` ディレクトリにあります（旧スタンドアロンリポジトリ -`iot-dc3-web` はアーカイブ済み）。 +各コンポーネントの役割と詳細は [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) を参照してください。 ## 📖 ドキュメントとコミュニティ | リソース | リンク | |----------------|-----------------------------------------------------------------------------| | 📚 オンラインドキュメント | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) | -| 🚀 クイックスタート | [クイックスタートガイド](https://pnoker.github.io/iot-dc3/quickstart/) | -| 🏗️ アーキテクチャ | [モジュールと依存関係](https://pnoker.github.io/iot-dc3/architecture/modules) | -| 🔧 ドライバー開発 | [ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/development/driver-authoring) | -| 🐛 トラブルシューティング | [よくある問題と解決策](https://pnoker.github.io/iot-dc3/guide/troubleshooting) | -| 📋 変更履歴 | [リリース変更履歴](https://pnoker.github.io/iot-dc3/development/changelog) | +| 🚀 クイックスタート | [クイックスタートガイド](https://pnoker.github.io/iot-dc3/en/quickstart/) | +| 🛠️ 技術スタック | [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) | +| 🏗️ アーキテクチャ | [モジュールと依存関係](https://pnoker.github.io/iot-dc3/en/architecture/modules) | +| 🔧 ドライバー開発 | [ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) | +| 🐛 トラブルシューティング | [よくある問題と解決策](https://pnoker.github.io/iot-dc3/en/guide/troubleshooting) | +| 📋 変更履歴 | [リリース変更履歴](https://pnoker.github.io/iot-dc3/en/development/changelog) | | 🐛 問題報告 | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) | | 🇨🇳 Gitee ミラー | [Gitee GVP プロジェクト](https://gitee.com/pnoker/iot-dc3) | diff --git a/README.md b/README.md index 13d16ef2f..508b9caab 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,37 @@ +## 🏗️ Architecture Overview + +### Architecture at a Glance + +![IoT DC3 Architecture Panorama](docs/public/images/architecture-panorama-en.png) + +Six-layer microservice architecture at a glance: clients → gateway → four center services → message bus → 28 protocol +drivers → field devices. PostgreSQL (TimescaleDB + pgvector + AGE) persistence and optional observability stack +(ELK + Prometheus + Grafana) laid out in one view. + +### Four-Layer Reference Architecture Mapping + +![IoT DC3 Four-Layer Reference Architecture](docs/public/images/architecture-en.png) + +Industry-standard IoT four-layer reference — Application, Platform, Network, Perception — plus security as a +cross-cutting concern. + +| Layer | IoT Reference Responsibilities | DC3 Implementation | +|-----------------|-------------------------------------------|--------------------------------------------| +| **Application** | Operations · Alarms · Analytics · AIoT | Operations · Agentic Center · MCP | +| **Platform** | Device mgmt · Storage · Rules & compute | Center services · Data plane · TimescaleDB | +| **Network** | Fieldbus · IoT protocols · Wireless / WAN | 28 protocol drivers · Gateway · RabbitMQ | +| **Perception** | Sensing · Auto-ID · Actuators | Profile · Device · Point | + +🧱 **Design principles** — cross-service calls always go through Facade interfaces; the DO/BO/VO three-tier model keeps +persistence, business, and API shapes strictly separated; and tenant isolation runs end to end across database, cache, +and API paths. Clear boundaries that scale across services and teams. + +> 📖 For the full architecture documentation, +> see [System Architecture Overview](https://pnoker.github.io/iot-dc3/en/architecture/). + ## ✨ Core Features ### 🔌 Multi-Protocol Device Connectivity @@ -127,7 +158,7 @@ Distributed microservice architecture based on **Spring Boot 4 + Spring Cloud 20 ### 🧩 Developer Friendly - **Driver SDK** - A complete driver development toolkit. See - the [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring) + the [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) - **Separated frontend and backend** - Vue 3 + TypeScript frontend, RESTful and gRPC APIs - **Containerized deployment** - One-command startup with Podman / Docker Compose, with a path toward Kubernetes and other container platforms @@ -135,146 +166,36 @@ Distributed microservice architecture based on **Spring Boot 4 + Spring Cloud 20 ## ⚡ Quick Start -### Prerequisites - -| Dependency | Version | -|------------------|---------------| -| Java (JDK) | 21+ | -| Maven | 3.9+ | -| Podman or Docker | Latest stable | - -### Start in Three Steps - -**① Clone the repository** +For source-based local development, start PostgreSQL and RabbitMQ, load local environment variables, then build: ```bash -git clone https://github.com/pnoker/iot-dc3.git -cd iot-dc3 -``` - -**② Start base dependencies** (PostgreSQL + RabbitMQ) - -```bash -# Global registry make up-db - -# Mainland China users (Alibaba Cloud registry) -make up-db-cn -``` - -**③ Load local environment variables, build, and start** - -```bash source dc3/env/dev.env.sh mvn -s .mvn/settings.xml clean package ``` -`dc3/env/dev.env.sh` points local Java processes to the PostgreSQL, RabbitMQ, and gRPC ports published on `localhost`. -Run the following `java -jar` commands in the same terminal session. - -Start services in order: - -```bash -java -jar dc3-gateway/target/dc3-gateway.jar # API Gateway -java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # Auth Center -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # Manager Center -java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # Data Center -java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # Agentic Center -java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # Virtual Driver for demos -``` - -> 📖 For full local setup, see the [Quickstart](https://pnoker.github.io/iot-dc3/quickstart/) and -> [Environment Variables](https://pnoker.github.io/iot-dc3/quickstart/environment) docs. - -
-🔧 More startup options (optional dependencies, single-service startup, environment variables) - -**Start optional infrastructure** (EMQX, ELK/APM, Prometheus, Grafana, etc.): - -```bash -make up-optional-cn # Start optional dependencies -make up-db-cn && make up-optional-cn && make up-dev-cn # Start all dependencies -``` - -**Start selected services** (useful for frontend/API testing): - -```bash -make up SERVICES=agentic REGISTRY=cn # Single service -make up SERVICES="gateway agentic" REGISTRY=cn # Multiple services -make up GROUP=core REGISTRY=cn # Core service group -make up GROUP=drivers REGISTRY=cn # Driver service group -make logs SERVICES="gateway agentic" # Follow logs -``` - -**Compose environment overrides**: - -```bash -cp .env.example .env # Copy the template -``` - -The root `.env` file is used for Compose variable interpolation, such as image registry, image tag, and published ports. -Application runtime variables are configured in `dc3/env/dev.env`. See -the [environment documentation](https://pnoker.github.io/iot-dc3/quickstart/environment). - -
- -## 🏗️ Architecture Overview - -### Architecture at a Glance - -![IoT DC3 Architecture Panorama](docs/public/images/architecture-panorama-en.png) - -Six-layer microservice architecture at a glance: clients → gateway → four center services → message bus → 28 protocol -drivers → field devices. PostgreSQL (TimescaleDB + pgvector + AGE) persistence and optional observability stack -(ELK + Prometheus + Grafana) laid out in one view. - -### Four-Layer Reference Architecture Mapping - -![IoT DC3 Four-Layer Reference Architecture](docs/public/images/architecture-en.png) - -Industry-standard IoT four-layer reference — Application, Platform, Network, Perception — plus security as a -cross-cutting concern. - -| Layer | IoT Reference Responsibilities | DC3 Implementation | -|-----------------|-------------------------------------------|--------------------------------------------| -| **Application** | Operations · Alarms · Analytics · AIoT | Operations · Agentic Center · MCP | -| **Platform** | Device mgmt · Storage · Rules & compute | Center services · Data plane · TimescaleDB | -| **Network** | Fieldbus · IoT protocols · Wireless / WAN | 28 protocol drivers · Gateway · RabbitMQ | -| **Perception** | Sensing · Auto-ID · Actuators | Profile · Device · Point | - -🧱 **Design principles** — cross-service calls always go through Facade interfaces; the DO/BO/VO three-tier model keeps -persistence, business, and API shapes strictly separated; and tenant isolation runs end to end across database, cache, -and API paths. Clear boundaries that scale across services and teams. - -> 📖 For the full architecture documentation, -> see [System Architecture Overview](https://pnoker.github.io/iot-dc3/architecture/). +Use `make up-db-cn` if you prefer the Alibaba Cloud registry in Mainland China. For service startup order, IDE setup, +verification commands, and common pitfalls, read the [full quickstart guide](https://pnoker.github.io/iot-dc3/en/quickstart/). ## 🛠️ Technology Stack -| Category | Technologies | -|---------------------------------|-------------------------------------------------------------| -| **Language and frameworks** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 | -| **Data, cache, and scheduling** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz | -| **Messaging and communication** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf | -| **Security and authentication** | Spring Security · JWT · BouncyCastle | -| **Observability** | Micrometer · Prometheus · Grafana · ELK | -| **Frontend** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 | -| **Desktop** | Tauri 2 | -| **Deployment** | Podman · Docker Compose | +IoT DC3 is built on Java 21, Spring Boot 4, Spring Cloud 2025, Spring AI 2, PostgreSQL, RabbitMQ, gRPC, Vue 3, +TypeScript, and Vite. -> 💡 Frontend source code is in the `dc3-web/` directory of this repository (the standalone `iot-dc3-web` repo is -> archived). +See [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) for component details and +where each technology is used. ## 📖 Documentation and Community | Resource | Link | |-----------------------|-----------------------------------------------------------------------------------------| | 📚 Online docs | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) | -| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/quickstart/) | -| 🏗️ Architecture | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/architecture/modules) | -| 🔧 Driver development | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring) | -| 🐛 Troubleshooting | [Troubleshooting](https://pnoker.github.io/iot-dc3/guide/troubleshooting) | -| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/development/changelog) | +| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/en/quickstart/) | +| 🛠️ Technology stack | [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) | +| 🏗️ Architecture | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/en/architecture/modules) | +| 🔧 Driver development | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) | +| 🐛 Troubleshooting | [Troubleshooting](https://pnoker.github.io/iot-dc3/en/guide/troubleshooting) | +| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/en/development/changelog) | | 🐛 Issue feedback | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) | | 🇨🇳 Gitee mirror | [Gitee GVP Project](https://gitee.com/pnoker/iot-dc3) | diff --git a/README.vi.md b/README.vi.md index ff61983d2..f1e4c5e59 100644 --- a/README.vi.md +++ b/README.vi.md @@ -71,6 +71,35 @@ +## 🏗️ Tổng quan kiến trúc + +### Toàn cảnh kiến trúc sản phẩm + +![IoT DC3 Architecture Panorama](docs/public/images/architecture-panorama-vi.png) + +Kiến trúc microservice 6 tầng: clients → gateway → 4 center services → message bus → 28 protocol drivers → field +devices. PostgreSQL (TimescaleDB + pgvector + AGE) và stack observability tùy chọn (ELK + Prometheus + Grafana). + +### Ánh xạ kiến trúc tham chiếu 4 tầng + +![IoT DC3 Kiến trúc tham chiếu 4 tầng](docs/public/images/architecture-vi.png) + +Kiến trúc tham chiếu IoT 4 tầng tiêu chuẩn — Ứng dụng, Nền tảng, Mạng, Cảm biến — cộng với bảo mật xuyên suốt. + +| Tầng | Trách nhiệm tham chiếu IoT | Triển khai DC3 | +|-------------------|-----------------------------------------------|--------------------------------------------| +| **Tầng Ứng dụng** | Vận hành · Cảnh báo · Phân tích · AIoT | Vận hành · Agentic Center · MCP | +| **Tầng Nền tảng** | Quản lý thiết bị · Lưu trữ · Luật & tính toán | Center services · Data plane · TimescaleDB | +| **Tầng Mạng** | Fieldbus · Giao thức IoT · Không dây / WAN | 28 protocol drivers · Gateway · RabbitMQ | +| **Tầng Cảm biến** | Cảm biến · Nhận dạng · Cơ cấu chấp hành | Profile · Device · Point | + +🧱 **Nguyên tắc thiết kế** — các lời gọi xuyên dịch vụ luôn đi qua interface Facade; mô hình ba tầng DO/BO/VO tách biệt +rõ ràng giữa persistence, business và API; cách ly tenant xuyên suốt từ database, cache đến API. Ranh giới rõ ràng, dễ +mở rộng theo dịch vụ và đội nhóm. + +> 📖 Để xem tài liệu kiến trúc đầy đủ, +> xem [Tổng quan Kiến trúc Hệ thống](https://pnoker.github.io/iot-dc3/en/architecture/). + ## ✨ Tính năng chính ### 🔌 Kết nối thiết bị đa giao thức @@ -126,7 +155,7 @@ Kiến trúc microservice phân tán dựa trên **Spring Boot 4 + Spring Cloud ### 🧩 Thân thiện với nhà phát triển - **Driver SDK** - Bộ công cụ phát triển driver hoàn chỉnh. - Xem [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring) + Xem [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) - **Tách frontend và backend** - Frontend Vue 3 + TypeScript, API RESTful + gRPC - **Triển khai bằng container** - Khởi động một lệnh với Podman / Docker Compose, thuận tiện để chuyển sang Kubernetes và các nền tảng container khác @@ -134,144 +163,35 @@ Kiến trúc microservice phân tán dựa trên **Spring Boot 4 + Spring Cloud ## ⚡ Bắt đầu nhanh -### Điều kiện tiên quyết - -| Phụ thuộc | Phiên bản | -|--------------------|----------------------| -| Java (JDK) | 21+ | -| Maven | 3.9+ | -| Podman hoặc Docker | Bản ổn định mới nhất | - -### Khởi động trong ba bước - -**① Clone repository** +Để phát triển local từ source, hãy khởi động PostgreSQL và RabbitMQ, nạp biến môi trường local rồi build: ```bash -git clone https://github.com/pnoker/iot-dc3.git -cd iot-dc3 -``` - -**② Khởi động phụ thuộc cơ bản** (PostgreSQL + RabbitMQ) - -```bash -# Registry toàn cầu make up-db - -# Người dùng Trung Quốc đại lục (Alibaba Cloud registry) -make up-db-cn -``` - -**③ Nạp biến môi trường local, build và khởi động** - -```bash source dc3/env/dev.env.sh mvn -s .mvn/settings.xml clean package ``` -`dc3/env/dev.env.sh` trỏ các tiến trình Java local tới các cổng PostgreSQL, RabbitMQ và gRPC đã publish trên -`localhost`. -Hãy chạy các lệnh `java -jar` bên dưới trong cùng phiên terminal. - -Khởi động dịch vụ theo thứ tự: - -```bash -java -jar dc3-gateway/target/dc3-gateway.jar # API Gateway -java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # Auth Center -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # Manager Center -java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # Data Center -java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # Agentic Center -java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # Virtual Driver cho demo -``` - -> 📖 Để thiết lập môi trường local đầy đủ, xem [Quickstart](https://pnoker.github.io/iot-dc3/quickstart/) và -> [Environment Variables](https://pnoker.github.io/iot-dc3/quickstart/environment). - -
-🔧 Tùy chọn khởi động khác (phụ thuộc tùy chọn, khởi động từng dịch vụ, biến môi trường) - -**Khởi động hạ tầng tùy chọn** (EMQX, ELK/APM, Prometheus, Grafana, v.v.): - -```bash -make up-optional-cn # Khởi động phụ thuộc tùy chọn -make up-db-cn && make up-optional-cn && make up-dev-cn # Khởi động toàn bộ phụ thuộc -``` - -**Khởi động dịch vụ theo nhu cầu** (phù hợp để test frontend/API): - -```bash -make up SERVICES=agentic REGISTRY=cn # Một dịch vụ -make up SERVICES="gateway agentic" REGISTRY=cn # Nhiều dịch vụ -make up GROUP=core REGISTRY=cn # Nhóm dịch vụ core -make up GROUP=drivers REGISTRY=cn # Nhóm driver -make logs SERVICES="gateway agentic" # Xem log -``` - -**Ghi đè biến môi trường Compose**: - -```bash -cp .env.example .env # Sao chép file mẫu -``` - -File `.env` ở thư mục gốc được dùng cho nội suy biến Compose, như registry image, tag image và cổng publish. -Biến runtime của ứng dụng được cấu hình trong `dc3/env/dev.env`. -Xem [tài liệu biến môi trường](https://pnoker.github.io/iot-dc3/quickstart/environment). - -
- -## 🏗️ Tổng quan kiến trúc - -### Toàn cảnh kiến trúc sản phẩm - -![IoT DC3 Architecture Panorama](docs/public/images/architecture-panorama-en.png) - -Kiến trúc microservice 6 tầng: clients → gateway → 4 center services → message bus → 28 protocol drivers → field -devices. PostgreSQL (TimescaleDB + pgvector + AGE) và stack observability tùy chọn (ELK + Prometheus + Grafana). - -### Ánh xạ kiến trúc tham chiếu 4 tầng - -![IoT DC3 Kiến trúc tham chiếu 4 tầng](docs/public/images/architecture-vi.png) - -Kiến trúc tham chiếu IoT 4 tầng tiêu chuẩn — Ứng dụng, Nền tảng, Mạng, Cảm biến — cộng với bảo mật xuyên suốt. - -| Tầng | Trách nhiệm tham chiếu IoT | Triển khai DC3 | -|-------------------|-----------------------------------------------|--------------------------------------------| -| **Tầng Ứng dụng** | Vận hành · Cảnh báo · Phân tích · AIoT | Vận hành · Agentic Center · MCP | -| **Tầng Nền tảng** | Quản lý thiết bị · Lưu trữ · Luật & tính toán | Center services · Data plane · TimescaleDB | -| **Tầng Mạng** | Fieldbus · Giao thức IoT · Không dây / WAN | 28 protocol drivers · Gateway · RabbitMQ | -| **Tầng Cảm biến** | Cảm biến · Nhận dạng · Cơ cấu chấp hành | Profile · Device · Point | - -🧱 **Nguyên tắc thiết kế** — các lời gọi xuyên dịch vụ luôn đi qua interface Facade; mô hình ba tầng DO/BO/VO tách biệt -rõ ràng giữa persistence, business và API; cách ly tenant xuyên suốt từ database, cache đến API. Ranh giới rõ ràng, dễ -mở rộng theo dịch vụ và đội nhóm. - -> 📖 Để xem tài liệu kiến trúc đầy đủ, -> xem [Tổng quan Kiến trúc Hệ thống](https://pnoker.github.io/iot-dc3/architecture/). +Nếu cần registry Alibaba Cloud cho Trung Quốc đại lục, dùng `make up-db-cn`. Thứ tự khởi động service, cấu hình IDE, +lệnh kiểm tra và các lỗi thường gặp nằm trong [Quickstart đầy đủ](https://pnoker.github.io/iot-dc3/en/quickstart/). ## 🛠️ Công nghệ sử dụng -| Nhóm | Công nghệ | -|--------------------------------|-------------------------------------------------------------| -| **Ngôn ngữ và framework** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 | -| **Dữ liệu, cache và lập lịch** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz | -| **Messaging và giao tiếp** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf | -| **Bảo mật và xác thực** | Spring Security · JWT · BouncyCastle | -| **Observability** | Micrometer · Prometheus · Grafana · ELK | -| **Frontend** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 | -| **Desktop** | Tauri 2 | -| **Triển khai** | Podman · Docker Compose | +IoT DC3 được xây dựng trên Java 21, Spring Boot 4, Spring Cloud 2025, Spring AI 2, PostgreSQL, RabbitMQ, gRPC, Vue 3, +TypeScript và Vite. -> 💡 Mã nguồn frontend nằm trong thư mục `dc3-web/` của repository này (repo độc lập `iot-dc3-web` cũ đã được lưu trữ). +Xem [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) để biết chi tiết từng thành phần và vị trí sử dụng. ## 📖 Tài liệu và cộng đồng | Tài nguyên | Liên kết | |----------------------|-----------------------------------------------------------------------------------------| | 📚 Tài liệu online | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) | -| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/quickstart/) | -| 🏗️ Kiến trúc | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/architecture/modules) | -| 🔧 Phát triển driver | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring) | -| 🐛 Khắc phục sự cố | [Troubleshooting](https://pnoker.github.io/iot-dc3/guide/troubleshooting) | -| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/development/changelog) | +| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/en/quickstart/) | +| 🛠️ Công nghệ | [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) | +| 🏗️ Kiến trúc | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/en/architecture/modules) | +| 🔧 Phát triển driver | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) | +| 🐛 Khắc phục sự cố | [Troubleshooting](https://pnoker.github.io/iot-dc3/en/guide/troubleshooting) | +| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/en/development/changelog) | | 🐛 Phản hồi issue | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) | | 🇨🇳 Gitee mirror | [Gitee GVP Project](https://gitee.com/pnoker/iot-dc3) | diff --git a/README.zh.md b/README.zh.md index c109c1415..14dd13d04 100644 --- a/README.zh.md +++ b/README.zh.md @@ -71,6 +71,33 @@ +## 🏗️ 架构概览 + +### 产品架构全景 + +![IoT DC3 产品架构全景](docs/public/images/architecture-panorama-zh.png) + +六层微服务架构一览：客户端 → 网关 → 四个中心服务 → 消息总线 → 28 协议驱动 → 现场设备。 +PostgreSQL（TimescaleDB + pgvector + AGE）持久层与可选运维栈（ELK + Prometheus + Grafana）一并铺开。 + +### 四层参考架构映射 + +![IoT DC3 四层参考架构](docs/public/images/architecture-zh.png) + +IoT 业界标准四层参考架构——应用层、平台层、网络层、感知层——外加贯穿四层的安全。 + +| 层级 | IoT 参考职责 | DC3 落地 | +|---------|-----------------------|------------------------------------| +| **应用层** | 运营 · 告警 · 数据分析 · AIoT | 运营中心 · Agentic 中心 · MCP | +| **平台层** | 设备管理 · 数据存储 · 规则与计算 | 中心服务 · 数据平面 · TimescaleDB | +| **网络层** | 现场总线 · IoT 协议 · 无线广域 | 28 协议驱动 · API 网关 · RabbitMQ | +| **感知层** | 传感测量 · 自动识别 · 执行器 | 物模型 Profile · 设备 Device · 位号 Point | + +🧱 **设计原则** — 跨服务调用统一经 Facade 接口；DO/BO/VO 三层模型严格分离持久化、业务与接口形态；租户隔离贯穿数据库、缓存到 +API 全链路。边界清晰，易于规模化扩展与多团队协作。 + +> 📖 完整架构文档请参阅 [系统架构总览](https://pnoker.github.io/iot-dc3/zh/architecture/)。 + ## ✨ 核心特性 ### 🔌 多协议设备接入 @@ -123,147 +150,42 @@ ### 🧩 开发者友好 - **Driver SDK** — - 完善的驱动开发工具包，参考 [驱动开发指南](https://pnoker.github.io/iot-dc3/development/driver-authoring.html) + 完善的驱动开发工具包，参考 [驱动开发指南](https://pnoker.github.io/iot-dc3/zh/development/driver-authoring) - **前后端分离** — Vue 3 + TypeScript 前端，RESTful + gRPC 双协议 API - **容器化部署** — Podman / Docker Compose 一键启动，便于迁移到 Kubernetes 等容器平台 - **完整文档** — 在线文档站 + 快速开始指南 + 故障排查手册 ## ⚡ 快速开始 -### 前置条件 - -| 依赖 | 版本要求 | -|-----------------|-------| -| Java (JDK) | 21+ | -| Maven | 3.9+ | -| Podman 或 Docker | 最新稳定版 | - -### 三步启动 - -**① 克隆项目** +源码本地开发时，先启动 PostgreSQL 与 RabbitMQ，再加载本地环境变量并构建： ```bash -git clone https://github.com/pnoker/iot-dc3.git -cd iot-dc3 -``` - -**② 启动基础依赖**（PostgreSQL + RabbitMQ） - -```bash -# 全球镜像 make up-db - -# 中国大陆用户（阿里云镜像） -make up-db-cn -``` - -**③ 加载本地环境变量，构建并启动** - -```bash source dc3/env/dev.env.sh mvn -s .mvn/settings.xml clean package ``` -`dc3/env/dev.env.sh` 会把本地 Java 进程连接到 `localhost` 上已发布的 PostgreSQL、RabbitMQ 和 gRPC 端口。 -后续 `java -jar` 命令请在同一个终端会话中执行。 - -按顺序启动服务： - -```bash -java -jar dc3-gateway/target/dc3-gateway.jar # API 网关 -java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # 认证中心 -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # 管理中心 -java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # 数据中心 -java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # AI 智能体中心 -java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # 虚拟驱动（演示用） -``` - -> 📖 完整开发环境搭建请参阅 [快速开始](https://pnoker.github.io/iot-dc3/quickstart/) 和 -> [环境变量说明](https://pnoker.github.io/iot-dc3/quickstart/environment.html)。 - -
-🔧 更多启动选项（可选依赖、单服务启动、环境变量配置） - -**启动可选基础设施**（EMQX、ELK/APM、Prometheus、Grafana 等）： - -```bash -make up-optional-cn # 启动可选依赖 -make up-db-cn && make up-optional-cn && make up-dev-cn # 启动全部依赖 -``` - -**按需启动单个服务**（适用于前端/接口测试）： - -```bash -make up SERVICES=agentic REGISTRY=cn # 单个服务 -make up SERVICES="gateway agentic" REGISTRY=cn # 多个服务 -make up GROUP=core REGISTRY=cn # 核心服务组 -make up GROUP=drivers REGISTRY=cn # 驱动服务组 -make logs SERVICES="gateway agentic" # 查看日志 -``` - -**Compose 环境变量覆盖**： - -```bash -cp .env.example .env # 复制模板文件 -``` - -根目录 `.env` 用于 Compose 变量插值（镜像仓库、版本、端口等），应用运行时变量在 `dc3/env/dev.env` 中配置。 -详见 [环境变量文档](https://pnoker.github.io/iot-dc3/quickstart/environment.html)。 - -
- -## 🏗️ 架构概览 - -### 产品架构全景 - -![IoT DC3 产品架构全景](docs/public/images/architecture-panorama-zh.png) - -六层微服务架构一览：客户端 → 网关 → 四个中心服务 → 消息总线 → 28 协议驱动 → 现场设备。 -PostgreSQL（TimescaleDB + pgvector + AGE）持久层与可选运维栈（ELK + Prometheus + Grafana）一并铺开。 - -### 四层参考架构映射 - -![IoT DC3 四层参考架构](docs/public/images/architecture-zh.png) - -IoT 业界标准四层参考架构——应用层、平台层、网络层、感知层——外加贯穿四层的安全。 - -| 层级 | IoT 参考职责 | DC3 落地 | -|---------|-----------------------|------------------------------------| -| **应用层** | 运营 · 告警 · 数据分析 · AIoT | 运营中心 · Agentic 中心 · MCP | -| **平台层** | 设备管理 · 数据存储 · 规则与计算 | 中心服务 · 数据平面 · TimescaleDB | -| **网络层** | 现场总线 · IoT 协议 · 无线广域 | 28 协议驱动 · API 网关 · RabbitMQ | -| **感知层** | 传感测量 · 自动识别 · 执行器 | 物模型 Profile · 设备 Device · 位号 Point | - -🧱 **设计原则** — 跨服务调用统一经 Facade 接口；DO/BO/VO 三层模型严格分离持久化、业务与接口形态；租户隔离贯穿数据库、缓存到 -API 全链路。边界清晰，易于规模化扩展与多团队协作。 - -> 📖 完整架构文档请参阅 [系统架构总览](https://pnoker.github.io/iot-dc3/architecture/)。 +中国大陆网络环境可改用 `make up-db-cn`。服务启动顺序、IDEA 配置、验证命令和常见坑请阅读 +[完整快速开始](https://pnoker.github.io/iot-dc3/zh/quickstart/)。 ## 🛠️ 技术栈 -| 分类 | 技术 | -|--------------|-------------------------------------------------------------| -| **语言与框架** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 | -| **数据、缓存与调度** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz | -| **消息与通信** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf | -| **安全与认证** | Spring Security · JWT · BouncyCastle | -| **可观测性** | Micrometer · Prometheus · Grafana · ELK | -| **前端** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 | -| **桌面端** | Tauri 2 | -| **部署** | Podman · Docker Compose | +IoT DC3 基于 Java 21、Spring Boot 4、Spring Cloud 2025、Spring AI 2、PostgreSQL、RabbitMQ、gRPC、Vue 3、 +TypeScript 与 Vite 构建。 -> 💡 前端源码在本仓库 `dc3-web/` 目录（原独立仓库 `iot-dc3-web` 已归档）。 +完整组件说明与适用位置请看 [技术栈](https://pnoker.github.io/iot-dc3/zh/introduction/technology-stack)。 ## 📖 文档与社区 | 资源 | 链接 | |-----------|------------------------------------------------------------------------------| | 📚 在线文档 | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) | -| 🚀 快速开始 | [快速开始指南](https://pnoker.github.io/iot-dc3/quickstart/) | -| 🏗️ 架构说明 | [模块与依赖](https://pnoker.github.io/iot-dc3/architecture/modules.html) | -| 🔧 驱动开发 | [驱动开发指南](https://pnoker.github.io/iot-dc3/development/driver-authoring.html) | -| 🐛 故障排查 | [常见问题与解决方案](https://pnoker.github.io/iot-dc3/guide/troubleshooting.html) | -| 📋 变更日志 | [版本更新记录](https://pnoker.github.io/iot-dc3/development/changelog.html) | +| 🚀 快速开始 | [快速开始指南](https://pnoker.github.io/iot-dc3/zh/quickstart/) | +| 🛠️ 技术栈 | [技术栈说明](https://pnoker.github.io/iot-dc3/zh/introduction/technology-stack) | +| 🏗️ 架构说明 | [模块与依赖](https://pnoker.github.io/iot-dc3/zh/architecture/modules) | +| 🔧 驱动开发 | [驱动开发指南](https://pnoker.github.io/iot-dc3/zh/development/driver-authoring) | +| 🐛 故障排查 | [常见问题与解决方案](https://pnoker.github.io/iot-dc3/zh/guide/troubleshooting) | +| 📋 变更日志 | [版本更新记录](https://pnoker.github.io/iot-dc3/zh/development/changelog) | | 🐛 问题反馈 | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) | | 🇨🇳 码云镜像 | [Gitee GVP 最有价值开源项目](https://gitee.com/pnoker/iot-dc3) | diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a6703c610..073f75472 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -39,7 +39,7 @@ const PILLARS: ReadonlyArray = [ navKey: 'pillar.overview', landing: 'introduction', paths: ['introduction', 'quickstart'], activeMatch: '^/(zh|en)/(introduction|quickstart)/', groups: [ - {key: '', items: [['introduction'], ['introduction/concepts'], ['introduction/paths']]}, + {key: '', items: [['introduction'], ['introduction/concepts'], ['introduction/paths'], ['introduction/technology-stack']]}, { key: 'group.objects-data', items: [['introduction/concepts/profile'], ['introduction/concepts/device'], ['introduction/concepts/driver'], ['introduction/concepts/point'], ['introduction/concepts/point-value']] diff --git a/docs/en/development/testing.md b/docs/en/development/testing.md index a17a7c9e1..35b934116 100644 --- a/docs/en/development/testing.md +++ b/docs/en/development/testing.md @@ -104,7 +104,7 @@ mind when writing integration tests for executable modules like drivers. ## Frontend test commands -The frontend (`iot-dc3-web/`) uses pnpm + Vitest (unit/api/component/view) and Playwright (E2E), independent of the +The frontend (`dc3-web/`) uses pnpm + Vitest (unit/api/component/view) and Playwright (E2E), independent of the backend: ::: code-group diff --git a/docs/en/index.md b/docs/en/index.md index 1f7fa9836..ca7c0e7e3 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -80,6 +80,8 @@ For how each hop works and why it's designed that way, see [Architecture](/en/ar - **Frontend**: Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 (source in `dc3-web/` directory of this repo; the standalone `iot-dc3-web` repo is archived) +See [Technology Stack](./introduction/technology-stack) for the full breakdown. + ## License IoT DC3 is open source under the [AGPL-3.0 License](https://github.com/pnoker/iot-dc3/blob/release/LICENSE-AGPL.txt). diff --git a/docs/en/introduction/technology-stack.md b/docs/en/introduction/technology-stack.md new file mode 100644 index 000000000..d0aa79a60 --- /dev/null +++ b/docs/en/introduction/technology-stack.md @@ -0,0 +1,46 @@ +--- +title: Technology Stack +--- + +# Technology Stack + +This page summarizes the main technologies IoT DC3 currently runs on and recommends for local development. Treat +`pom.xml`, `dc3-web/package.json`, and `docs/package.json` as the source of truth for exact versions; the README keeps +only a short reader-facing summary. + +## Backend and Center Services + +| Area | Technologies | Purpose | +|------|--------------|---------| +| Language and frameworks | Java 21 · Spring Boot 4 · Spring Cloud 2025 | Runtime foundation for the gateway, center services, and driver processes | +| AI integration | Spring AI 2.0 | Agentic Center integration with OpenAI-compatible providers, Tool Calling, and MCP workflows | +| Web and API | Spring WebFlux · Spring Security · springdoc-openapi | HTTP APIs, authentication and authorization, and aggregated API docs | +| Service collaboration | gRPC · Protobuf · Facade interfaces | Strongly typed contracts between center services | +| Build | Maven 3.9+ | Multi-module build, tests, packaging, and dependency version management | + +## Data, Messaging, and Scheduling + +| Area | Technologies | Purpose | +|------|--------------|---------| +| Primary storage | PostgreSQL | Business data, tenants, resources, device models, and runtime data | +| Time-series and extensions | TimescaleDB · AGE · pgvector | Point history, graph capabilities, and vector capabilities | +| ORM / data access | MyBatis-Plus | Persistence access and paginated queries at the DO layer | +| Message bus | RabbitMQ | Asynchronous point value reports, command dispatch, and buffering between drivers and the data center | +| Cache and scheduling | Caffeine · Quartz | In-process caching, scheduled jobs, and task orchestration | + +## Frontend, Docs, and Automation + +| Area | Technologies | Purpose | +|------|--------------|---------| +| Web frontend | Vue 3 · TypeScript 6 · Vite 8 · Element Plus | Management console under `dc3-web/` | +| Visualization | AntV G2/G6 | Dashboard charts and relationship visualizations | +| Docs site | VitePress · Mermaid | The current `docs/` site, architecture diagrams, and flow diagrams | +| CLI automation | TypeScript · pnpm · Vitest | Sibling `dc3-cli/` project, a Gateway-oriented command-line client | +| Container deployment | Podman · Docker Compose | Local dependencies, dev stack, app stack, and optional observability stack | + +## Continue Reading + +- [Local Development from Source](../quickstart/) — start dependencies, load environment variables, build, and verify +- [Frontend Development](../frontend/) — running, structure, and test commands for `dc3-web/` +- [System Architecture Overview](../architecture/) — how the gateway, centers, drivers, message bus, and storage work together +- [Module Map](../architecture/modules) — Maven modules, deployable units, and dependencies diff --git a/docs/en/operation/index.md b/docs/en/operation/index.md index 789891703..1ea61082c 100644 --- a/docs/en/operation/index.md +++ b/docs/en/operation/index.md @@ -87,12 +87,11 @@ The table below is a reference index. For how to use each entry point, see its o | Swagger UI | `http://localhost:8000/swagger-ui.html` | Browse the gateway-aggregated API in development (usually disabled in production) | | Direct-connect debugging per center | Auth `8300` / Manager `8400` / Data `8500` / Agentic `8600` | When debugging a single center, connect straight to its HTTP port, bypassing the gateway | | MCP / OAuth entry | `POST /mcp`, `GET /.well-known/oauth-protected-resource` | For AI Agents to reach MCP tools over OAuth 2.1 (both at the gateway root, not under `/api/v3`); see [Agentic Center](../ai/agentic) | -| Web UI | The frontend source lives in the separate `iot-dc3-web` repository | The graphical interface; its backend calls go through the Gateway too | +| Web UI | The frontend source lives under `dc3-web/` in this repository | The graphical interface; its backend calls go through the Gateway too | -::: info The Web UI is not in this repository -This repository (`iot-dc3`) holds the backend and the docs only. The graphical interface is the Vue frontend project in -the separate `iot-dc3-web` repository, and it calls the same set of APIs through the Gateway. This manual describes -operations in terms of API calls and curl. The matching UI entry points map one-to-one. +::: info The Web UI uses the same API entry point +The graphical interface lives under `dc3-web/` in this repository and calls the same set of APIs through the Gateway. +This manual describes operations in terms of API calls and curl. The matching UI entry points map one-to-one. ::: ## From login to a single command: the minimal runnable example diff --git a/docs/en/quickstart/index.md b/docs/en/quickstart/index.md index 1b57d73f1..9a9bd4f03 100644 --- a/docs/en/quickstart/index.md +++ b/docs/en/quickstart/index.md @@ -22,7 +22,7 @@ build toolchain plus a container runtime. - **JDK 21** — the platform requires Java 21. Compiling on a lower version fails outright. - **Maven 3.9+** — the repository ships `.mvn/settings.xml` and a parallel-build configuration; use it for multi-module packaging. -- **pnpm** — both the `iot-dc3-web` frontend and `dc3-cli` use pnpm (not npm or yarn). Skip this for backend-only work. +- **pnpm** — both the `dc3-web/` frontend and sibling `dc3-cli/` use pnpm (not npm or yarn). Skip this for backend-only work. - **Podman** — every container operation in this repository uses `podman` (`make` defaults to `podman compose`). ## Why These Five Steps diff --git a/docs/locales/en.json b/docs/locales/en.json index f3d8c1c3c..25831453e 100644 --- a/docs/locales/en.json +++ b/docs/locales/en.json @@ -9,6 +9,7 @@ "introduction": "Overview", "introduction/concepts": "Core Concepts", "introduction/paths": "Choose Your Path", + "introduction/technology-stack": "Technology Stack", "introduction/concepts/profile": "Profile", "introduction/concepts/device": "Device", "introduction/concepts/driver": "Driver", diff --git a/docs/locales/zh.json b/docs/locales/zh.json index f8c77c705..536043f27 100644 --- a/docs/locales/zh.json +++ b/docs/locales/zh.json @@ -9,6 +9,7 @@ "introduction": "总览", "introduction/concepts": "核心概念", "introduction/paths": "按角色选择路径", + "introduction/technology-stack": "技术栈", "introduction/concepts/profile": "物模型", "introduction/concepts/device": "设备", "introduction/concepts/driver": "驱动", diff --git a/docs/zh/development/testing.md b/docs/zh/development/testing.md index 0ea0392e3..8084a5303 100644 --- a/docs/zh/development/testing.md +++ b/docs/zh/development/testing.md @@ -91,7 +91,7 @@ dc3-coverage/target/site/jacoco-aggregate/index.html ## 前端测试命令 -前端（`iot-dc3-web/`）用 pnpm + Vitest（单元/接口/组件/视图）与 Playwright（E2E），与后端独立： +前端（`dc3-web/`）用 pnpm + Vitest（单元/接口/组件/视图）与 Playwright（E2E），与后端独立： ::: code-group diff --git a/docs/zh/index.md b/docs/zh/index.md index a59a2c246..c74b1cc03 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -77,6 +77,8 @@ RabbitMQ 异步解耦。 - **前端**：Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6（源码在本仓库 `dc3-web/` 目录，原独立仓库 `iot-dc3-web` 已归档） +完整说明见 [技术栈](./introduction/technology-stack)。 + ## 开源协议 IoT DC3 基于 [AGPL-3.0 License](https://github.com/pnoker/iot-dc3/blob/release/LICENSE-AGPL.txt) diff --git a/docs/zh/introduction/technology-stack.md b/docs/zh/introduction/technology-stack.md new file mode 100644 index 000000000..b8c5d06f8 --- /dev/null +++ b/docs/zh/introduction/technology-stack.md @@ -0,0 +1,45 @@ +--- +title: 技术栈 +--- + +# 技术栈 + +这页汇总 IoT DC3 当前推荐和运行中的主要技术选型。精确版本以仓库内的 `pom.xml`、`dc3-web/package.json` 和 +`docs/package.json` 为准；README 只保留面向新读者的摘要。 + +## 后端与中心服务 + +| 范围 | 技术 | 用途 | +|------|------|------| +| 语言与框架 | Java 21 · Spring Boot 4 · Spring Cloud 2025 | 网关、四个中心服务与驱动进程的运行基础 | +| AI 集成 | Spring AI 2.0 | Agentic Center 接入 OpenAI-compatible provider、Tool Calling 与 MCP 工作流 | +| Web 与 API | Spring WebFlux · Spring Security · springdoc-openapi | HTTP API、认证鉴权、聚合 API 文档 | +| 服务协作 | gRPC · Protobuf · Facade 接口 | 中心服务之间的强类型调用契约 | +| 构建 | Maven 3.9+ | 多模块构建、测试、打包和依赖版本管理 | + +## 数据、消息与调度 + +| 范围 | 技术 | 用途 | +|------|------|------| +| 主存储 | PostgreSQL | 业务数据、租户、资源、设备模型与运行数据 | +| 时序与扩展 | TimescaleDB · AGE · pgvector | 位号历史、图能力和向量能力扩展 | +| ORM / 数据访问 | MyBatis-Plus | DO 层持久化访问与分页查询 | +| 消息总线 | RabbitMQ | 驱动与数据中心之间的异步值上报、命令下发与削峰 | +| 缓存与调度 | Caffeine · Quartz | 进程内缓存、定时任务与调度 | + +## 前端、文档与自动化 + +| 范围 | 技术 | 用途 | +|------|------|------| +| Web 前端 | Vue 3 · TypeScript 6 · Vite 8 · Element Plus | `dc3-web/` 下的管理控制台 | +| 可视化 | AntV G2/G6 | 仪表盘图表与关系可视化 | +| 文档站 | VitePress · Mermaid | 当前 `docs/` 文档站、架构图和流程图 | +| CLI 自动化 | TypeScript · pnpm · Vitest | sibling `dc3-cli/` 项目，面向 Gateway 的命令行客户端 | +| 容器部署 | Podman · Docker Compose | 本地依赖、开发栈、应用栈和可选观测栈 | + +## 继续阅读 + +- [从源码本地开发](../quickstart/) — 启动依赖、加载环境变量、构建与验证 +- [前端开发](../frontend/) — `dc3-web/` 的运行、目录和测试命令 +- [系统架构总览](../architecture/) — 网关、中心服务、驱动、消息总线和存储如何协作 +- [模块地图](../architecture/modules) — Maven 模块、部署单元和依赖关系 diff --git a/docs/zh/operation/index.md b/docs/zh/operation/index.md index 772a74cdd..cd6660a8a 100644 --- a/docs/zh/operation/index.md +++ b/docs/zh/operation/index.md @@ -70,11 +70,10 @@ flowchart LR | Swagger UI | `http://localhost:8000/swagger-ui.html` | 开发环境查看网关聚合后的 API（生产环境一般关闭） | | 各中心直连调试 | Auth `8300` / Manager `8400` / Data `8500` / Agentic `8600` | 单独调试某个中心时直连其 HTTP 端口，绕过网关 | | MCP / OAuth 入口 | `POST /mcp`、`GET /.well-known/oauth-protected-resource` | 供 AI Agent 经 OAuth 2.1 访问 MCP 工具（均在网关根路径，不经 `/api/v3`），见 [Agentic 中心](../ai/agentic) | -| Web UI | 前端源码在独立的 `iot-dc3-web` 仓库 | 图形化操作界面，后端接口同样通过 Gateway 访问 | +| Web UI | 前端源码在本仓库 `dc3-web/` 目录 | 图形化操作界面，后端接口同样通过 Gateway 访问 | -::: info Web UI 不在本仓库 -本仓库（`iot-dc3`）只含后端与文档；图形界面是独立的 `iot-dc3-web` 仓库里的 Vue 前端工程，它通过 Gateway 调用同一套 API。本手册以 -API / curl 为准描述操作，UI 上的对应入口与之一一对应。 +::: info Web UI 与 API 共用同一入口 +图形界面位于本仓库 `dc3-web/` 目录，通过 Gateway 调用同一套 API。本手册以 API / curl 为准描述操作，UI 上的对应入口与之一一对应。 ::: ## 从登录到一条命令：最小可跑示例 diff --git a/docs/zh/quickstart/index.md b/docs/zh/quickstart/index.md index a0659ff93..b98dfca7c 100644 --- a/docs/zh/quickstart/index.md +++ b/docs/zh/quickstart/index.md @@ -18,7 +18,7 @@ JDK/构建工具，外加一个容器运行时。 - **JDK 21** —— 平台强制 Java 21，低版本编译会直接失败。 - **Maven 3.9+** —— 仓库内置 `.mvn/settings.xml` 与并行构建配置；多模块打包用它。 -- **pnpm** —— 前端 `iot-dc3-web` 与 `dc3-cli` 都用 pnpm（不要用 npm/yarn）。仅做后端开发可跳过。 +- **pnpm** —— 前端 `dc3-web/` 与同级目录 `dc3-cli/` 都用 pnpm（不要用 npm/yarn）。仅做后端开发可跳过。 - **Podman** —— 本仓库容器操作一律用 `podman`（`make` 默认 `podman compose`）。 ## 在 JetBrains IDEA 中开发