# 快速开始

使用 Docker Compose 在 15 分钟内本地部署 Monetarie PIX。本指南介绍从零到运行系统并访问管理门户的最快路径。

## 前提条件

- 已安装 Docker 24+ 和 Docker Compose v2
- 可用 8 GB RAM
- 端口 4003、5432、6379、4222 和 8080 空闲
- 已安装 Git

## 步骤 1：克隆仓库

```bash
git clone https://github.com/MonetarieBR/pix.git
cd pix
```

## 步骤 2：配置环境

```bash
cp backend/.env.example backend/.env
```

默认 `.env` 文件包含开箱即用的开发设置：

```bash
# 数据库
DB_HOST=postgres
DB_PORT=5432
DB_USER=postgres
DB_PASS=postgres
DB_NAME=monetarie

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# NATS
NATS_HOST=nats
NATS_PORT=4222
NATS_ENABLED=true

# 安全
SECRET_KEY_BASE=dev-only-secret-key-base-replace-in-production-min-64-chars!!
MIX_ENV=prod

# 模拟器 (无需真实 BACEN 连接)
SIMULATOR_ENABLED=true
BACEN_ENABLED=false
```

## 步骤 3：启动服务

```bash
cd backend
docker compose up -d
```

这将启动 4 个容器：
- `postgres` -- PostgreSQL 16，端口 5432
- `redis` -- Redis 7，端口 6379
- `nats` -- NATS 2.10，JetStream，端口 4222
- `pix-backend` -- Monetarie PIX 后端，端口 4003

等待后端健康 (~30 秒)：

```bash
docker compose logs -f pix-backend
# 等待: "=== Starting Shared Application ==="
```

## 步骤 4：运行迁移

```bash
docker compose exec pix-backend bin/monetarie_pix eval "Shared.Release.migrate()"
```

预期输出：应用 25 个迁移。

## 步骤 5：填充种子数据

```bash
docker compose exec pix-backend bin/monetarie_pix eval "Shared.Release.seed()"
```

加载内容：
- 10 个参与者、7 个用户、369 个参考银行
- 277 个 PIX 密钥、15,442 个 DICT 操作
- 1,000+ 个真实交易 (30 天历史)
- 44 个 COSIF 账户、27 个 XSD schemas
- BACEN 模拟器场景

## 步骤 6：验证

```bash
# 健康检查
curl http://localhost:4003/health

# 登录 (返回 JWT cookie)
curl -X POST http://localhost:4003/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@2026!"}'
```

## 步骤 7：访问管理门户

如果在本地运行管理前端：

```bash
cd frontend/admin
npm install
npm run dev
# 打开 http://localhost:5173
```

登录凭据：

| 用户 | 密码 | 角色 |
|------|------|------|
| admin | Admin@2026! | 系统管理员 |
| operator | Operator@2026! | 交易操作员 |
| viewer | Viewer@2026! | 只读查看者 |

## 快速验证清单

| 检查项 | 命令 | 预期结果 |
|--------|------|----------|
| 后端健康 | `curl localhost:4003/health` | `200 OK` |
| Dict Service | `curl localhost:4001/api/health` | `200 OK` |
| SPI Service | `curl localhost:4002/api/health` | `200 OK` |
| 数据库 | `docker compose exec postgres psql -U postgres -d monetarie -c "SELECT count(*) FROM monetarie_spi.messages"` | 1000+ 行 |
| NATS | `docker compose exec nats nats stream ls` | 7 个流 |
| Redis | `docker compose exec redis redis-cli ping` | `PONG` |

## 停止环境

```bash
docker compose down        # 停止容器 (保留数据)
docker compose down -v     # 停止容器并删除卷
```

## 下一步

- [架构](./architecture.md) -- 了解系统设计
- [环境变量](../configuration/environment.md) -- 完整配置参考
- [Kubernetes 部署](../deployment/kubernetes.md) -- 生产级部署
- [管理门户](../administration/portal.md) -- 探索管理界面

## 预期结果

完成快速开始后：

- 所有 4 个后端服务正在运行且健康
- 数据库已填充种子数据，包括测试交易
- 您可以以管理员身份登录并探索 API
- BACEN 模拟器可用于测试 PIX 流程，无需真实 BACEN 连接