# TrackingService

**Repository Path**: yak33/TrackingService

## Basic Information

- **Project Name**: TrackingService
- **Description**: ⚓️ 全场景物流跟踪平台。Vue 3 + Kotlin (Spring Boot) / Go (Gin) 双架构支持，高性能重构，极致资源优化，支持海/空/港全口径动态追踪。
- **Primary Language**: Kotlin
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TrackingService

[![Kotlin](https://img.shields.io/badge/Kotlin-2.1.0-blue.svg?style=flat&logo=kotlin)](https://kotlinlang.org)
[![Go](https://img.shields.io/badge/Go-1.21+-00ADD8.svg?style=flat&logo=go)](https://go.dev)
[![Vue](https://img.shields.io/badge/Vue-3.0-4FC08D.svg?style=flat&logo=vuedotjs)](https://vuejs.org)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.9-6DB33F.svg?style=flat&logo=spring)](https://spring.io/projects/spring-boot)

**TrackingService** 是一个**全场景货物跟踪系统**，提供海运、空运、港口箱货的全链路物流追踪能力。

项目采用**一前双后**的现代化架构：
- **统一前端**: 基于 Vue 3 + TypeScript 构建。
- **双选后端**:
    - **Standard (Kotlin)**: 功能健全、集成 Spring Cloud 生态，适合标准企业级环境。
    - **High Performance (Go)**: 极致性能、极低内存占用，专为 2h2g 等低配置服务器重构。

---

## 🏗️ 架构概览

```mermaid
graph TD
    Client[Vue 3 前端] --> Gateway[Spring Cloud Gateway]
    Gateway --> K_Service[Kotlin Backend]
    Gateway --> G_Service[Go Backend]
    K_Service --数据持久化--> DB[(MySQL / Redis)]
    G_Service --数据持久化--> DB
```

---

## 📊 性能看板 (后端对比)

针对 **2h2g** 服务器环境的实测数据：

| 指标 | Kotlin (Spring Boot) | Go (Gin / GORM) | 建议选择 |
|------|---------------------|----------------|---------|
| **常驻内存** | ~800MB - 1.5GB | **~30MB - 100MB** | Go 版本节省 90%+ 内存 |
| **冷启动速度** | 15 - 30s | **< 1s** | Go 版本几乎秒开 |
| **二进制体积** | ~80MB (JAR) | **~15MB (Binary)** | Go 版本极其轻量 |
| **并发承载** | 高 (依赖线程/协程) | **极高 (基于 Goroutines)** | Go 版本更具伸缩性 |

---

## 📂 项目结构

```text
TrackingService/ (Mono-repo)
├── tracking-web/          # [Frontend] Vue 3, Vite, Naive UI
├── tracking-service/      # [Backend-Kotlin] 标准企业级实现 (DDD / Spring Cloud)
├── tracking-go/           # [Backend-Go] 极致性能重构版 (Gin / GORM)
├── tracking-common/       # [Shared] 共享逻辑与配置
├── gradle/                # Gradle 构建配置
└── scripts/               # 部署与运维脚本
```

---

## ✨ 核心业务场景

- **🚢 海运跟踪**: 支持提单号/箱号全流程订阅，集成船期动态追踪。
- **✈️ 空运跟踪**: 航空运单实时监控，支持航班动态与货站状态看板。
- **🏗️ 港口跟踪**: 统一宁波、上海、厦门、天津等主流港口查询接口。
- **🔐 租户权限**: 内置多租户架构，支持与外部 SSO (如 Sa-Token) 体系无缝对接。

---

## 🛠️ 后端方案选择

### 场景一：追求生态与快速扩展 (推荐 Kotlin)
如果您有充足的内存资源 (>= 4G)，且需要利用 Java/Kotlin 庞大的生态（如 Spring Cloud, MyBatis-Plus 高级特性）：
```bash
# 启动 Kotlin 后端
./gradlew :tracking-service:bootRun
```

### 场景二：追求低配运行与极速响应 (推荐 Go)
如果您的服务器是 **2h2g** 或更低配置，或者对 API 响应时延有极高要求：
```bash
# 进入 Go 项目
cd tracking-go
make run
```

---

## 🌐 统一前端

前端项目位于 `tracking-web`，支持响应式布局，完美适配 Web 与移动端浏览器。

```bash
cd tracking-web
pnpm install
pnpm dev
```

---

## 🛰️ 核心 API 定义 (双后端兼容)

| 功能 | 接口路径 | 备注 |
|------|---------|------|
| 海运列表 | `GET /tracking/ocean/list` | 支持分页与条件检索 |
| 空运列表 | `GET /tracking/airway/list` | 支持航班追踪 |
| 港口订阅 | `POST /tracking/portCtnr/subscribe` | 跨港口统一订阅 |
| 授权兑换 | `POST /internal/auth/exchange` | 跨系统 Token 桥接 |

---

## ⚖️ 许可证

本项目采用 **MIT** 许可证。

---

**Crafted with ❤️ by ZHANGCHAO**