君鸿卡管系统

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

前置条件

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

初始化配置

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

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

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_* 前缀不同。只连接明确指定的隔离数据库：

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

查看版本：

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

构建与启动

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。启动后执行：

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

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

日志与定位

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 请求。

重置隔离数据库

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

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 验证

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

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

文档入口

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