iotlcm/README.md

# iotLCM 物联网卡全生命周期管理平台

iotLCM 面向物联网 SIM 卡的全生命周期管理：卡片从运营商渠道入库 → 划拨给代理商 → 激活 / 续费 / 停机 → 流量与状态同步 → 销户。

平台对接**中国移动 OneLink**、**中国电信 5G CMP**、**中国联通 10646** 等运营商接口，支持以共享 Token 模式接入三方渠道商，并提供对外的 OpenAPI 服务。

## 文档

| 手册 | 内容 | 入口 |
| --- | --- | --- |
| **使用手册 · Web 管理端** | 查卡、智能诊断、业务受理、套餐与定价、库存出入库、通道管理、企业用户与角色、工单、API 凭证、常见问题 | [`docs/docs/manual/web/`](docs/docs/manual/web/index.md) |
| **使用手册 · 小程序端** | 首页公开查卡、卡片排查、客户管理与划拨、工单、批次执行日志、消息与个人中心 | [`docs/docs/manual/mini-program/`](docs/docs/manual/mini-program/index.md) |
| **部署手册** | 推荐环境、一键部署、配置说明、离线部署、拆分部署、自建镜像、运维与排错 | [`docs/docs/deploy/`](docs/docs/deploy/index.md) |
| **OpenAPI 合同** | 鉴权、V3 接口、旧版兼容接口、运营商能力代理 | [`docs/docs/openapi/`](docs/docs/openapi/index.md) |
| **共享 Token 接口** | 共享 Token 获取与白名单转发 | [`docs/docs/openapi/operator/`](docs/docs/openapi/operator/index.md) |

平台跑起来后，文档站随平台一起提供：`http://<平台地址>:8019/docs/`。

## 快速开始

需要 Docker 20.10+ 与 Docker Compose v2，单机 4 核 / 8 GB 起。预构建镜像已就绪，不需要编译：

```bash
git clone <仓库地址> iotlcm
cd iotlcm/deploy
docker compose up -d
```

首次启动自动完成建库建表、种子数据导入与时序库建表，约 1 分钟。启动完成后访问 `http://127.0.0.1:8009`。

默认账号口令、端口清单、可选服务（接口挡板 / 飞书通知 / 反向代理）、修改口令与上线检查，见 [`deploy/README.md`](deploy/README.md) 与[部署手册](docs/docs/deploy/index.md)。

> 业务端口默认只绑定 `127.0.0.1`。需要局域网或公网访问时，用 `--profile with-nginx` 起反向代理，或改用 `--profile with-gateway` 的单端口入口（默认 5051）。

## 功能概览

| 域 | 能力 |
| --- | --- |
| 卡资产 | 卡信息、批量导入、入库 / 库存 / 出库、批量开停复机、续费、变更套餐、达量断网 |
| 通信管理 | 通道与接入模板、运营商能力对接、共享 Token 接入三方渠道、通道缓存转发 |
| 资费 | 套餐与流量池、定价、生效与到期策略 |
| 代理商 | 代理商与分佣、划拨与回收 |
| 数据同步 | 流量 / 状态 / IMEI 全量同步与增量对齐、历史账期时序数据 |
| OpenAPI | V3 接口、旧版兼容接口、运营商能力代理（白名单转发 / 共享 Token） |
| 运营 | 工单、预警、执行日志、审计、智能诊断 |
| 端 | Web 管理端、小程序 / H5 用户端 |

## 服务构成

| 目录 | 说明 | 镜像 tag |
| --- | --- | --- |
| `admin-svr/` | 管理端后端（GoFrame） | `iotlcm-admin-svr` |
| `admin-ui/` | 管理端前端（Vue 3 + Vben Admin） | `iotlcm-admin-ui` |
| `openapi/` | 对外 API 网关 | `iotlcm-openapi` |
| `worker-svr/` | 异步执行（RabbitMQ 消费者、全量同步、批量任务） | `iotlcm-worker-svr` |
| `upstream-chan/` | 运营商 / 三方渠道对接层 | `iotlcm-upstream-chan` |
| `upstream-proxy/` | 通道缓存转发层 | `iotlcm-upstream-proxy` |
| `app/server/` | 用户端服务（GoFrame） | `iotlcm-app-server` |
| `app/app/` | 用户端前端（uni-app，基于 unibest） | `iotlcm-app-web` |
| `sms/` | 短信服务（HTTP / gRPC，阿里云 / 腾讯云） | `iotlcm-sms` |
| `bot/` | 飞书通知机器人（运维自用，可选） | `iotlcm-bot` |
| `docs/` | 文档站（VitePress）与 OpenAPI 合同 | `iotlcm-docs` |
| `onelink-mock/` | OneLink 接口挡板（联调 / 演示，可选） | `iotlcm-onelink-mock` |
| `deploy/` | Docker Compose 编排、数据库初始化、反向代理 / 单端口网关配置 | — |

各服务职责、配置项与本地运行方式见各自目录下的 `README.md`。

## 从源码构建

每个 Go 服务是独立模块，在对应目录内构建：

```bash
cd worker-svr && go build -o out/ .      # 其余 Go 服务同理
```

前端：

```bash
cd admin-ui/vue && pnpm install && pnpm build
cd app/app      && pnpm install && pnpm build
cd docs         && npm ci && npm run build
```

一键编译全部 Go 服务 / 本地构建全部镜像：

```bash
make build      # 编译检查
make images     # 构建镜像（REGISTRY / VERSION 可覆盖）
```

各服务的 Dockerfile 位置与构建上下文见[自建镜像](docs/docs/deploy/build-image.md)。

## 版本与镜像

镜像统一发布在同一个仓库，用 tag 区分服务与版本：

```text
<镜像仓库>/iotlcm/iotlcm:iotlcm-worker-svr-v1.0.4
                        └─ 仓库 ┘ └─ 服务名 ─┘└版本┘
```

| 服务 | 当前版本 |
| --- | --- |
| 除小程序线外 | `v1.0.4` |
| `iotlcm-app-server` / `iotlcm-app-web` | `v1.0.2`（小程序线独立版本线） |

升级时固定到具体版本，不要使用 `latest`。

## 反馈

问题与建议请提 Issue，或联系平台维护者。

## 许可

本仓整体采用 [Apache License 2.0](LICENSE)。以下子目录基于上游 MIT 项目衍生，保留其原始许可：

| 目录 | 上游 | 许可 |
| --- | --- | --- |
| `admin-ui/` | [Vben Admin](https://github.com/vbenjs/vue-vben-admin) | MIT，见 `admin-ui/LICENSE` |
| `app/app/` | [unibest](https://github.com/unibest-tech/unibest) | MIT，见 `app/app/LICENSE` |