# Technology Stack

**Analysis Date:** 2026-03-27

## Languages

**Primary:**
- Go 1.25.x - 应用代码、API、Worker、OpenAPI 生成和基础设施脚本，依据 `go.mod`、`cmd/api/main.go`、`cmd/worker/main.go`、`cmd/gendocs/main.go`

**Secondary:**
- YAML - 配置与部署编排，见 `pkg/config/defaults/config.yaml`、`docker-compose.prod.yml`、`.gitea/workflows/deploy.yaml`
- Dockerfile - API/Worker 容器构建，见 `Dockerfile.api`、`Dockerfile.worker`
- Makefile - 本地构建、文档生成、迁移命令，见 `Makefile`

## Runtime

**Environment:**
- Go runtime；API 服务基于 Fiber HTTP 服务器，见 `cmd/api/main.go`
- 独立 Worker 进程处理异步任务与调度，见 `cmd/worker/main.go`
- 生产容器基础镜像为 Alpine，构建镜像使用 Go 1.25.6 Alpine，见 `Dockerfile.api`、`Dockerfile.worker`

**Package Manager:**
- Go Modules，见 `go.mod`
- Lockfile: `go.sum` present

## Frameworks

**Core:**
- Fiber v2.52.9 - HTTP 框架与路由宿主，见 `go.mod`、`cmd/api/main.go`
- GORM v1.31.1 + `gorm.io/driver/postgres` v1.6.0 - PostgreSQL ORM 与连接层，见 `go.mod`、`pkg/database/postgres.go`
- Viper v1.21.0 - 嵌入式默认配置 + 环境变量覆盖，见 `go.mod`、`pkg/config/loader.go`

**Queue / Scheduling:**
- Asynq v0.25.1 - 任务提交、Worker 消费、定时任务，见 `go.mod`、`pkg/queue/client.go`、`pkg/queue/server.go`、`cmd/worker/main.go`

**Serialization / Validation:**
- sonic v1.14.2 - Fiber JSON 编解码与任务载荷序列化，见 `go.mod`、`cmd/api/main.go`、`pkg/queue/client.go`
- validator/v10 v10.28.0 - DTO 校验依赖，见 `go.mod`

**Logging:**
- zap v1.27.1 - 应用日志与 SQL 日志，见 `go.mod`、`pkg/logger/logger.go`、`pkg/database/postgres.go`
- lumberjack.v2 v2.2.1 - 日志轮转，见 `go.mod`、`pkg/logger/logger.go`

**Docs tooling:**
- swaggest/openapi-go v0.2.60 - OpenAPI 3.0.3 文档生成，见 `go.mod`、`pkg/openapi/generator.go`

## Build / Dev / Deploy

**Build:**
- `Makefile` 定义 `build`、`run`、`run-worker`、`docs`、`migrate-*` 目标，见 `Makefile`
- API 与 Worker 使用多阶段 Docker 构建，编译产物分别来自 `./cmd/api` 与 `./cmd/worker`，见 `Dockerfile.api`、`Dockerfile.worker`

**Deploy:**
- 生产编排使用 Docker Compose，运行 `api` 与 `worker` 两个服务，见 `docker-compose.prod.yml`
- Gitea Actions 工作流构建镜像、推送私有镜像仓库并在主分支执行 `docker compose up -d`，见 `.gitea/workflows/deploy.yaml`

**Docs generation:**
- API 启动时会生成 `logs/openapi.yaml`，见 `cmd/api/main.go`、`cmd/api/docs.go`
- 手动文档命令 `make docs` 运行 `cmd/gendocs/main.go`，输出 `docs/admin-openapi.yaml`，见 `Makefile`、`cmd/gendocs/main.go`

## Storage, Data, Messaging

**Database:**
- PostgreSQL 是唯一检测到的主数据库；连接、连接池、GORM logger、Ping 校验位于 `pkg/database/postgres.go`

**Cache / KV:**
- Redis 用于认证、缓存、队列后端、限流存储和配置缓存，见 `pkg/database/redis.go`、`cmd/api/main.go`、`internal/service/wechat_config/service.go`

**Messaging / Queue:**
- Asynq 直接复用 Redis 连接配置作为消息后端，见 `pkg/queue/client.go`、`pkg/queue/server.go`
- Worker 内注册订单超时、告警检查、数据清理等调度任务，见 `cmd/worker/main.go`

**Object storage:**
- S3 兼容对象存储通过 AWS SDK v1 实现，支持上传、下载、预签名 URL、临时文件下载，见 `pkg/storage/s3.go`、`pkg/storage/service.go`

## Configuration

**Loading model:**
- 默认配置从嵌入文件 `pkg/config/defaults/config.yaml` 读取，见 `pkg/config/embedded.go`
- 运行时使用 `JUNHONG_` 前缀环境变量覆盖，见 `pkg/config/loader.go`
- 必填配置校验包括数据库、Redis、JWT，见 `pkg/config/config.go`

**Key config areas:**
- 服务与超时：`server.*`，见 `pkg/config/config.go`
- PostgreSQL：`database.*`，见 `pkg/config/config.go`
- Redis：`redis.*`，见 `pkg/config/config.go`
- Asynq：`queue.*`，见 `pkg/config/config.go`
- 日志：`logging.*`，见 `pkg/config/config.go`
- 短信：`sms.*`，见 `pkg/config/config.go`
- 对象存储：`storage.*`，见 `pkg/config/config.go`
- 外部 Gateway：`gateway.*`，见 `pkg/config/config.go`

**WeChat config exception:**
- 微信公众号/小程序/支付配置不走 Viper 主配置，业务侧从数据库表 `tb_wechat_config` 读取并缓存到 Redis，见 `internal/model/wechat_config.go`、`internal/service/wechat_config/service.go`、`pkg/wechat/config.go`

## Logging & Observability

**Application logs:**
- `pkg/logger/logger.go` 初始化 app/access 双 logger；生产模式写 JSON，开发模式 app logger 同时输出控制台

**Access logs:**
- `pkg/logger/middleware.go` 记录 method、path、query、status、duration、request_id、ip、user_agent、user_id、请求/响应 body

**SQL logs:**
- `pkg/database/postgres.go` 自定义 GORM logger，记录错误、慢查询和普通 SQL trace

**Health checks:**
- `Dockerfile.api` 与 `docker-compose.prod.yml` 均通过 `GET /health` 做容器健康检查

## Notable Dependencies

**HTTP / App:**
- `github.com/gofiber/fiber/v2` - API 服务核心框架，见 `go.mod`、`cmd/api/main.go`
- `github.com/google/uuid` - 请求 ID 生成，见 `cmd/api/main.go`

**Persistence / Cache:**
- `gorm.io/gorm`、`gorm.io/driver/postgres` - ORM 与 PostgreSQL 驱动，见 `go.mod`、`pkg/database/postgres.go`
- `github.com/redis/go-redis/v9` - Redis 客户端，见 `go.mod`、`pkg/database/redis.go`

**Queue / Async:**
- `github.com/hibiken/asynq` - 队列与调度器，见 `go.mod`、`pkg/queue/*.go`、`cmd/worker/main.go`

**Serialization / File processing:**
- `github.com/bytedance/sonic` - JSON 编解码，见 `cmd/api/main.go`、`pkg/queue/client.go`
- `github.com/xuri/excelize/v2` - Excel 导入处理依赖，见 `go.mod`; 任务消费方在 `internal/task/iot_card_import.go`、`internal/task/device_import.go` 调用 Excel 解析

**External SDKs:**
- `github.com/ArtisanCloud/PowerWeChat/v3` - 微信公众号与微信支付 SDK，见 `go.mod`、`pkg/wechat/official_account.go`、`pkg/wechat/payment.go`
- `github.com/aws/aws-sdk-go` - S3 兼容对象存储客户端，见 `go.mod`、`pkg/storage/s3.go`

## Platform Requirements

**Development:**
- 需要 PostgreSQL、Redis、JWT 密钥与 `JUNHONG_` 环境变量；`config.Load()` 在启动时强校验，见 `pkg/config/config.go`
- `make docs` 需要 Go 环境；`migrate-*` 目标需要系统安装 `migrate` 命令，见 `Makefile`

**Production:**
- 目标运行形态是 Docker 化 API + Worker 双进程部署，见 `Dockerfile.api`、`Dockerfile.worker`、`docker-compose.prod.yml`
- 镜像发布到私有仓库 `registry.boss160.cn`，见 `.gitea/workflows/deploy.yaml`

## Evidence

- `go.mod`
- `README.md`
- `cmd/api/main.go`
- `cmd/api/docs.go`
- `cmd/worker/main.go`
- `cmd/gendocs/main.go`
- `pkg/config/config.go`
- `pkg/config/loader.go`
- `pkg/config/embedded.go`
- `pkg/config/defaults/config.yaml`
- `pkg/database/postgres.go`
- `pkg/database/redis.go`
- `pkg/queue/client.go`
- `pkg/queue/server.go`
- `pkg/queue/handler.go`
- `pkg/logger/logger.go`
- `pkg/logger/middleware.go`
- `pkg/openapi/generator.go`
- `pkg/openapi/handlers.go`
- `pkg/storage/s3.go`
- `pkg/storage/service.go`
- `pkg/wechat/config.go`
- `pkg/wechat/official_account.go`
- `pkg/wechat/payment.go`
- `pkg/sms/client.go`
- `internal/gateway/client.go`
- `Makefile`
- `Dockerfile.api`
- `Dockerfile.worker`
- `docker-compose.prod.yml`
- `.gitea/workflows/deploy.yaml`

---

*Stack analysis: 2026-03-27*