# 君鸿卡管系统

Go/Fiber 后端，负责物联网卡与设备、套餐、订单、钱包、分佣、审批、轮询任务及第三方渠道协作。

## 前置条件

- Go 版本以 `go.mod` 为准。
- 可访问的隔离 PostgreSQL 与 Redis；仓库当前不提供本地依赖容器。
- `golang-migrate` 用于数据库迁移。
- 外部支付、Gateway、企业微信、短信和对象存储按需配置；不做对应操作时可保持未配置。

## 初始化配置

```bash
./scripts/setup-env.sh .env.local
```

脚本为交互式向导。启动前至少确认 PostgreSQL、Redis、JWT 和日志路径；本地日志建议写入仓库的忽略目录：

```bash
export JUNHONG_LOGGING_APP_LOG_FILENAME="$PWD/logs/app.log"
export JUNHONG_LOGGING_ACCESS_LOG_FILENAME="$PWD/logs/access.log"
```

不得复制 Makefile 中的历史数据库连接信息。

## 数据库迁移

`scripts/migrate.sh` 使用 `DB_*` 参数，与应用的 `JUNHONG_DATABASE_*` 前缀不同。只连接明确指定的隔离数据库：

```bash
DB_HOST=127.0.0.1 DB_PORT=5432 DB_USER=<USER> DB_PASSWORD=<PASSWORD> \
DB_NAME=<ISOLATED_DB> DB_SSLMODE=disable ./scripts/migrate.sh up
```

查看版本：

```bash
DB_HOST=127.0.0.1 DB_USER=<USER> DB_PASSWORD=<PASSWORD> \
DB_NAME=<ISOLATED_DB> ./scripts/migrate.sh version
```

## 构建与启动

```bash
go build ./cmd/api ./cmd/worker
./scripts/run-local.sh api       # API
./scripts/run-local.sh worker    # Worker
./scripts/run-local.sh both      # 两者
```

`run-local.sh` 会加载 `.env.local`。Worker 角色由 `JUNHONG_WORKER_ROLE=all|leader|consumer` 决定。

## Smoke

API 默认监听 `:3000`。启动后执行：

```bash
curl -fsS http://127.0.0.1:3000/health
curl -fsS http://127.0.0.1:3000/ready
```

预期统一响应的 `data.status` 分别为 `healthy` 与 `ready`。外部依赖或配置不完整导致进程启动失败时，先查看应用日志。

## 日志与定位

```bash
tail -f logs/app.log
tail -f logs/access.log
rg '<REQUEST_ID>|<CORRELATION_ID>' logs/app.log logs/access.log
```

实际路径由 `JUNHONG_LOGGING_APP_LOG_FILENAME` 与 `JUNHONG_LOGGING_ACCESS_LOG_FILENAME` 决定。API 与 Worker 共用应用日志配置；访问日志只记录 HTTP 请求。

## 重置隔离数据库

以下命令会删除并重建整个数据库，只允许显式指向可丢弃的隔离环境：

```bash
JUNHONG_DATABASE_HOST=127.0.0.1 \
JUNHONG_DATABASE_PORT=5432 \
JUNHONG_DATABASE_USER=<USER> \
JUNHONG_DATABASE_PASSWORD=<PASSWORD> \
JUNHONG_DATABASE_DBNAME=<DISPOSABLE_DB> \
./scripts/reset_db.sh
```

执行前人工核对主机、端口和库名；不得指向生产或共享环境。

## Context 验证

```bash
go run cmd/gendocs/main.go
openspec doctor --json
openspec validate --all
./scripts/context-health.sh
```

自动化测试当前为 N/A（用户决策）；当前验证依赖构建、OpenAPI、OpenSpec、结构检查、smoke、日志和独立审计。

## 文档入口

- Agent 导航：[`AGENTS.md`](AGENTS.md)
- 系统地图：[`ARCHITECTURE.md`](ARCHITECTURE.md)
- 当前行为：[`openspec/specs/`](openspec/specs/)
- 工程约束：[`docs/engineering/工程约束.md`](docs/engineering/工程约束.md)
- 第三方契约：[`docs/integrations/`](docs/integrations/)