# ami-docs

**Repository Path**: zzsvip/ami-docs

## Basic Information

- **Project Name**: ami-docs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AMI 水气信息采集系统

SaaS 多租户智能抄表 + VEE 数据校验 + DMA 漏损监控 + 受控远程阀控平台。

- 目标客户：中国城市级中小水务 / 燃气公司
- 远端：[gitee.com/zzsvip/ami-docs](https://gitee.com/zzsvip/ami-docs)
- 当前阶段：**项目脚手架已完成（F-000）**，进入业务功能点实现期（F-001 ~ F-211）

---

## 模块导览

| 模块 | 说明 |
|------|------|
| [ami-dependencies](ami-dependencies/) | BOM：Spring Boot 3.2 / PostgreSQL / Kafka / Redis 等版本锁定 |
| [ami-parent](ami-parent/) | 构建配置父 POM（Java 21 + 插件 + profile） |
| [ami-engine](ami-engine/) | 纯技术封装层（core / web / webflux / data / cache / mq / security / monitor / test） |
| [ami-context](ami-context/) | 业务上下文层（generic 通用 + supporting 支撑 + core 核心） |
| [ami-platform](ami-platform/) | 平台启动层（monolith 单体 + valve 阀控 + collector 协议接入） |

详细架构见：[docs/architecture/overview-design.md](docs/architecture/overview-design.md)

## 关键决策（ADR）

| ADR | 主题 |
|------|------|
| [ADR-0001](docs/adr/0001-modeling-paradigm-hybrid.md) | 建模范式混合（核心 DDD / 通用支撑 MVC） |
| [ADR-0002](docs/adr/0002-multi-tenant-isolation.md) | 多租户隔离（RLS_SHARED 默认 + 升级路径） |
| [ADR-0003](docs/adr/0003-timeseries-db-selection.md) | 时序库选型（**Proposed**，M1 PoC 决定） |
| [ADR-0004](docs/adr/0004-protocol-spi-abstraction.md) | 协议 SPI 抽象（EP-001） |
| [ADR-0005](docs/adr/0005-valve-security-flow.md) | 阀控六重防线 |
| [ADR-0006](docs/adr/0006-programming-model-hybrid.md) | 编程模型混合（WebFlux 采集 + MVC 业务） |
| [ADR-0007](docs/adr/0007-deployment-mode.md) | 部署模式（单体可切换 + 阀控/协议独立） |
| [ADR-0008](docs/adr/0008-interaction-style-hybrid.md) | 同步 + 事件驱动 Kafka |
| [ADR-0009](docs/adr/0009-service-comm-switch.md) | 服务通信切换（Conditional Bean） |
| [ADR-0010](docs/adr/0010-key-management-hsm.md) | 密钥管理（HSM 阀控签名 / KMS PIPL 信封） |
| [ADR-0011](docs/adr/0011-package-naming-and-project-structure.md) | 包根 `com.ami.zzsheng.*` + Maven 前缀 `ami-*` |

## 构建

```bash
mvn clean package -DskipTests           # 编译打包
mvn verify                              # 含测试 + Jacoco 覆盖率
mvn -pl ami-platform/platform-monolith -am package   # 仅构建单体启动器
```

## 配置：单一 .env 文件（开发期）

所有密码 / 主机 / 端口集中在根目录 `.env`（git ignore），同时 `docker-compose` 与 Spring Boot 都从中读取。**改密码只改 `.env` 一处 + 远程同步**。

| 文件 | 用途 | 入仓 |
|------|------|------|
| `.env.example` | 入仓模板（占位值 + 注释） | ✅ |
| `.env` | 本地真实值（含密码） | ❌（.gitignore） |

初次配置：

```bash
cp .env.example .env
# 编辑 .env 改成你部署的实际值
```

远端 Linux（`192.168.18.146`）按 `docker-compose.yml` 启动依赖时，把 `.env` 一同上传：

```bash
docker compose --env-file .env up -d
```

> **演进**：M3 预生产起将迁移到已部署的 Nacos Config Center（届时 `.env` 仅保留 NACOS_USERNAME / NACOS_PASSWORD 引导密码，其余配置从 Nacos 拉取） — 见后续 ADR-0012。

## 运行（远程依赖）

⚠️ **本地 Windows 不跑 docker** — 所有运行时依赖（PostgreSQL / Redis / Kafka / Nacos）在远程 Linux（`192.168.18.146`）上运行。

1. **远程 Linux 上**（一次性）：
   ```bash
   scp .env user@192.168.18.146:/path/to/ami/
   scp docker-compose.yml user@192.168.18.146:/path/to/ami/
   ssh user@192.168.18.146 "cd /path/to/ami && docker compose --env-file .env up -d"
   ```

2. **本地启动 Spring Boot**（加载 .env 为环境变量）：

   **方式 A：命令行**
   ```bash
   # Git Bash / Linux / macOS
   set -a && source .env && set +a
   mvn -pl ami-platform/platform-monolith -am spring-boot:run

   # Windows PowerShell
   Get-Content .env | ForEach-Object { if ($_ -match '^([^#=]+)=(.*)$') { Set-Item -Path "Env:$($matches[1])" -Value $matches[2] } }
   mvn -pl ami-platform/platform-monolith -am spring-boot:run
   ```

   **方式 B：IntelliJ IDEA**
   - 安装 [EnvFile 插件](https://plugins.jetbrains.com/plugin/7861-envfile)
   - Run Configuration → EnvFile → 勾选 `.env`

3. **健康检查**：`curl http://localhost:8080/actuator/health`

## 开发进度

见 [docs/plans/progress.md](docs/plans/progress.md)（212 个功能点）。

按推荐 5 批次实施：基础设施 → 底层主线 → 数据质量 → 业务功能 → 增值。

## 包名约定（ADR-0011 锁定）

- 包根：`com.ami.zzsheng`
- 模块包：`com.ami.zzsheng.<module>`
- 扩展点：`com.ami.zzsheng.<module>.ext`
- 共用基类：`com.ami.zzsheng.common.ext`