# infrastructure (开发环境)

## 设计思想

开发环境在 **Windows** 宿主机直接运行所有服务：
- PostgreSQL 通过 Windows 原生安装运行
- Redis 7+ 通过 Windows 原生安装运行（可选，缺省时限流降级为 fail-open）
- 后端 Rust 服务通过 `cargo run` 快速重启
- 前端 Vite 热更新直接在宿主机
- PowerShell 脚本 (`dev.ps1`) 提供一键启动/停止

> Docker Compose 配置保留在 `docker/` 目录下，可供需要容器化环境的场景使用，但日常开发不依赖 Docker。

## 本机环境实际配置

> **重要：以下为当前开发机的实际配置，以本文件为准。**

| 组件 | 安装路径 | 配置 |
|------|---------|------|
| PostgreSQL 18 | `D:\postgreSQL\` | 服务名 `postgresql-x64-18`, 端口 5432 |
| Redis | 云端实例 | `redis://:redis_KBCYJk@129.204.154.246:6379`, 限流中间件已正常工作 |
| Rust | stable (cargo in PATH) | workspace 根目录编译 |
| Node.js + pnpm | in PATH | apps/web/ |

### 数据库连接

```
用户: postgres
密码: 123123
数据库: erp
连接串: postgres://postgres:123123@localhost:5432/erp
```

psql 路径: `D:\postgreSQL\bin\psql.exe -U postgres -h localhost -d erp`

### 后端启动命令

后端**必须**从 `crates/erp-server/` 目录启动（需要读取 `config/default.toml`），或通过环境变量覆盖：

```powershell
# 方式一：从 crates/erp-server 目录启动（使用 default.toml + 环境变量覆盖）
cd crates/erp-server
$env:ERP__DATABASE__URL = "postgres://postgres:123123@localhost:5432/erp"
$env:ERP__JWT__SECRET = "dev-secret-key-change-in-prod"
$env:ERP__AUTH__SUPER_ADMIN_PASSWORD = "Admin@2026"
cargo run -p erp-server

# 方式二：一键启动脚本（推荐）
.\dev.ps1
```

### 登录凭据

```
用户名: admin
密码: Admin@2026
```

## 服务端口

| 服务 | 端口 | 用途 |
|------|------|------|
| PostgreSQL 18 | 5432 | 主数据库 |
| Redis 7+ | 6379 (云端) | 缓存 + 限流 |
| erp-server (Axum) | 3000 | 后端 API |
| Vite dev server | 5174 | 前端 SPA（固定端口，--strictPort） |

### 连接信息（配置文件版本）
```
PostgreSQL: postgres://postgres:123123@localhost:5432/erp
Redis:      redis://:redis_KBCYJk@129.204.154.246:6379  (云端实例)
```

## 一键启动

```powershell
.\dev.ps1              # 启动后端 + 前端（自动清理旧进程 5174-5189）
.\dev.ps1 -Status      # 查看端口状态
.\dev.ps1 -Stop        # 停止所有服务
.\dev.ps1 -Restart     # 重启所有服务
```

> `dev.ps1` 会在启动前清理端口 5174-5189 范围内所有残留进程，并使用 `--strictPort` 确保 Vite 固定在 5174 端口。

### 环境变量

必须通过环境变量设置的值（`default.toml` 中为占位符）：

| 变量 | 说明 | 开发值 |
|------|------|--------|
| `ERP__DATABASE__URL` | 数据库连接串 | `postgres://postgres:123123@localhost:5432/erp` |
| `ERP__JWT__SECRET` | JWT 签名密钥 | 自定义字符串 |
| `ERP__AUTH__SUPER_ADMIN_PASSWORD` | admin 初始密码 | `Admin@2026` |
| `ERP__REDIS__URL` | Redis 连接串 | `redis://:redis_KBCYJk@129.204.154.246:6379` |

> 所有四个变量在 `default.toml` 中都是 `__MUST_SET_VIA_ENV__` 占位符，**必须**通过环境变量设置，否则服务拒绝启动。

## 关联模块

- **[[erp-server]]** — 连接 PostgreSQL 和 Redis
- **[[database]]** — 迁移在 PostgreSQL 中执行
- **[[frontend]]** — Vite 代理 API 到后端
- **[[testing]]** — 测试环境详细指南

## 关键文件

| 文件 | 职责 |
|------|------|
| `dev.ps1` | 一键启动/停止脚本（自动清理端口 5174-5189） |
| `docker/docker-compose.yml` | 可选的 Docker Compose 配置 |
| `crates/erp-server/config/default.toml` | 默认配置模板（密钥为占位符） |
| `D:\postgreSQL\bin\psql.exe` | PostgreSQL 客户端 |

## 常用命令

```powershell
# 一键启动（推荐）
.\dev.ps1

# 手动启动后端（从 crates/erp-server 目录）
cd crates/erp-server
$env:ERP__DATABASE__URL="postgres://postgres:123123@localhost:5432/erp"
$env:ERP__JWT__SECRET="dev-secret"
$env:ERP__AUTH__SUPER_ADMIN_PASSWORD="Admin@2026"
cargo run -p erp-server

# 手动启动前端（固定端口）
cd apps/web && pnpm dev -- --strictPort

# 连接数据库
D:\postgreSQL\bin\psql.exe -U postgres -h localhost -d erp

# 健康检查
curl http://localhost:3000/api/v1/health

# 登录测试
curl -s http://localhost:3000/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"Admin@2026"}'
```