# External Integrations

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

## APIs & External Services

**Database / Cache Infrastructure:**
- PostgreSQL - 主业务数据库，GORM 通过 DSN 建连并配置连接池，见 `pkg/database/postgres.go`
  - Client: `gorm.io/gorm` + `gorm.io/driver/postgres`
  - Config: `pkg/config/config.go` 的 `database.*`
- Redis - Token、缓存、Asynq 后端、限流存储、微信配置缓存，见 `pkg/database/redis.go`、`pkg/queue/client.go`、`cmd/api/main.go`、`internal/service/wechat_config/service.go`
  - Client: `github.com/redis/go-redis/v9`
  - Config: `pkg/config/config.go` 的 `redis.*`

**Object Storage:**
- S3-compatible object storage - 文件直传、下载、导入任务临时落盘，见 `pkg/storage/s3.go`、`pkg/storage/service.go`
  - SDK/Client: `github.com/aws/aws-sdk-go`
  - Config: `storage.provider`、`storage.s3.*`、`storage.presign.*` in `pkg/config/config.go`
  - Used by: `internal/handler/admin/storage.go`、`internal/routes/storage.go`、`internal/task/iot_card_import.go`、`internal/task/device_import.go`

**WeChat ecosystem:**
- WeChat Official Account OAuth - 公众号登录与用户信息拉取，见 `pkg/wechat/official_account.go`、`internal/service/client_auth/service.go`
  - SDK/Client: `github.com/ArtisanCloud/PowerWeChat/v3`
  - Config source: `tb_wechat_config` via `internal/model/wechat_config.go`
- WeChat Mini Program login - `code2session` 换取 openid/session_key，见 `pkg/wechat/miniapp.go`、`internal/service/client_auth/service.go`
  - Transport: 标准 `net/http`
  - Config source: `tb_wechat_config`
- WeChat Pay - JSAPI/H5 下单、查单、关单、支付回调验签，见 `pkg/wechat/payment.go`、`pkg/wechat/config.go`、`internal/handler/callback/payment.go`
  - SDK/Client: `github.com/ArtisanCloud/PowerWeChat/v3`
  - Config source: `tb_wechat_config`

**Payment gateway:**
- Fuiou - 预下单、回调解析、签名与验签 SDK 已存在，见 `pkg/fuiou/client.go`、`pkg/fuiou/wxprecreate.go`、`pkg/fuiou/notify.go`
  - SDK/Client: repo-local `pkg/fuiou`
  - Config source: `tb_wechat_config` provider=`fuiou`，字段位于 `internal/model/wechat_config.go`
  - Callback endpoint: `internal/handler/callback/payment.go`
  - Current state: 回调处理存在 `TODO`，当前路径解析 XML 但未按配置创建客户端做验签，见 `internal/handler/callback/payment.go`

**SMS gateway:**
- SMS HTTP gateway - 验证码/消息发送，见 `pkg/sms/client.go`、`cmd/api/main.go`
  - Client: repo-local `pkg/sms`
  - Config: `sms.gateway_url`、`sms.username`、`sms.password`、`sms.signature` in `pkg/config/config.go`

**Business Gateway / IoT upstream:**
- Gateway API - 设备信息、卡状态、流量、实名链接、设备限速/切卡等外部接口，见 `internal/gateway/client.go`、`internal/gateway/device.go`、`internal/gateway/flow_card.go`
  - Auth: appId + appSecret，自定义 AES-128-ECB 加密 + MD5 签名，见 `internal/gateway/client.go`
  - Config: `gateway.base_url`、`gateway.app_id`、`gateway.app_secret`、`gateway.timeout` in `pkg/config/config.go`
  - Used by: `internal/service/iot_card/gateway_service.go`、`internal/service/device/gateway_service.go`、`internal/task/polling_handler.go`

## Data Storage

**Databases:**
- PostgreSQL
  - Connection keys: `JUNHONG_DATABASE_HOST`, `JUNHONG_DATABASE_PORT`, `JUNHONG_DATABASE_USER`, `JUNHONG_DATABASE_PASSWORD`, `JUNHONG_DATABASE_DBNAME`, `JUNHONG_DATABASE_SSLMODE`
  - Connection code: `pkg/database/postgres.go`
  - Runtime wiring: `cmd/api/main.go`, `cmd/worker/main.go`, `docker-compose.prod.yml`

**Redis:**
- Redis is shared across auth, cache, rate limiting, WeChat config cache, and Asynq
  - Connection keys: `JUNHONG_REDIS_ADDRESS`, `JUNHONG_REDIS_PORT`, `JUNHONG_REDIS_PASSWORD`, `JUNHONG_REDIS_DB`
  - Connection code: `pkg/database/redis.go`
  - Asynq reuse: `pkg/queue/client.go`, `pkg/queue/server.go`
  - Config cache key example: `wechat:config:active` in `internal/service/wechat_config/service.go`

**File Storage:**
- S3-compatible bucket storage
  - Provider implementation: `pkg/storage/s3.go`
  - Upload URL API: `internal/routes/storage.go`
  - Import consumers download to temp files before parsing: `internal/task/iot_card_import.go`, `internal/task/device_import.go`

**Local filesystem:**
- Logs are persisted to `/app/logs` inside containers and mounted by Compose, see `pkg/config/defaults/config.yaml`, `Dockerfile.api`, `Dockerfile.worker`, `docker-compose.prod.yml`
- OpenAPI runtime export writes to `logs/openapi.yaml`, see `cmd/api/main.go`, `cmd/api/docs.go`

## Authentication & Identity

**B-side auth:**
- Redis-backed token management and JWT manager initialization occur in `cmd/api/main.go`
  - Components: `pkg/auth`, Redis token manager, JWT manager

**C-side identity via WeChat:**
- 公众号 OAuth login path uses active config from `tb_wechat_config`, see `internal/service/client_auth/service.go`
- 小程序 login path uses WeChat `code2session`, see `internal/service/client_auth/service.go`, `pkg/wechat/miniapp.go`

## Monitoring & Observability

**Application logs:**
- Zap + Lumberjack app/access loggers, see `pkg/logger/logger.go`

**Request tracing:**
- Access logger captures request metadata and request/response bodies, see `pkg/logger/middleware.go`

**SQL observability:**
- GORM logger sends query errors and slow queries to Zap, see `pkg/database/postgres.go`

**Container health:**
- API health endpoint is used by Docker health checks and Compose dependency ordering, see `Dockerfile.api`, `docker-compose.prod.yml`

## Queue, Scheduling, and Runtime Integrations

**Asynq runtime:**
- Worker server consumes Redis-backed queues configured in `queue.*`, see `pkg/queue/server.go`, `cmd/worker/main.go`
- Task submission is wrapped in `pkg/queue/client.go`

**Registered task domains:**
- Email, data sync, SIM status sync, IoT card import, device import, commission stats, commission calculation, polling, package activation, order expiration, alert check, data cleanup, see `pkg/queue/handler.go`

**Schedulers:**
- Worker process starts an internal polling scheduler plus an Asynq Scheduler for recurring jobs, see `cmd/worker/main.go`
- Recurring jobs include order expiration, alert checks, and nightly cleanup, see `cmd/worker/main.go`

## Docs Generation Integrations

**OpenAPI generation:**
- Repo-local generator wraps `swaggest/openapi-go` and exports YAML, see `pkg/openapi/generator.go`
- Runtime generation during API boot writes `logs/openapi.yaml`, see `cmd/api/main.go`, `cmd/api/docs.go`
- Manual generation command writes `docs/admin-openapi.yaml`, see `Makefile`, `cmd/gendocs/main.go`
- Route registration for docs reuses production route registration, see `internal/routes/routes.go`, `pkg/openapi/handlers.go`

## CI/CD & Deployment

**Hosting / Runtime:**
- Dockerized API and Worker services are the deployment target, see `Dockerfile.api`, `Dockerfile.worker`, `docker-compose.prod.yml`

**Registry:**
- Images are pushed to a private registry declared in `.gitea/workflows/deploy.yaml`

**CI Pipeline:**
- Gitea workflow builds both images, pushes tag + SHA tags, copies `docker-compose.prod.yml`, and executes `docker compose pull/up -d`, see `.gitea/workflows/deploy.yaml`

**Migration tooling:**
- API image bundles `golang-migrate` and migration files, see `Dockerfile.api`
- Local migration shortcuts are defined in `Makefile`

## Environment Configuration

**Required env vars:**
- Database: `JUNHONG_DATABASE_HOST`, `JUNHONG_DATABASE_PORT`, `JUNHONG_DATABASE_USER`, `JUNHONG_DATABASE_PASSWORD`, `JUNHONG_DATABASE_DBNAME`
- Redis: `JUNHONG_REDIS_ADDRESS` plus optional Redis port/password/db tuning vars
- JWT: `JUNHONG_JWT_SECRET_KEY`

**Optional env vars by integration:**
- Storage: `JUNHONG_STORAGE_PROVIDER`, `JUNHONG_STORAGE_S3_*`
- SMS: `JUNHONG_SMS_*`
- Gateway: `JUNHONG_GATEWAY_*`
- Logging: `JUNHONG_LOGGING_*`

**Secrets location:**
- Default app config is embedded from `pkg/config/defaults/config.yaml`
- Most runtime secrets are expected through environment variables bound in `pkg/config/loader.go`
- WeChat / payment provider secrets are stored in database table `tb_wechat_config`, see `internal/model/wechat_config.go`
- Deployment wiring exists in `docker-compose.prod.yml` and `.gitea/workflows/deploy.yaml`; these files should be treated as sensitive and are not reproduced here

## Webhooks & Callbacks

**Incoming:**
- WeChat Pay callback: `POST /api/callback/wechat-pay`, handler in `internal/handler/callback/payment.go`
- Fuiou Pay callback: `POST /api/callback/fuiou-pay`, handler in `internal/handler/callback/payment.go`
- Alipay callback stub: `POST /api/callback/alipay`, handler in `internal/handler/callback/payment.go`

**Outgoing:**
- WeChat OAuth and payment API calls from `pkg/wechat/*.go`
- Gateway API calls from `internal/gateway/*.go`
- SMS API calls from `pkg/sms/client.go`
- S3 object storage calls from `pkg/storage/s3.go`

## 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/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/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/miniapp.go`
- `pkg/wechat/payment.go`
- `pkg/fuiou/client.go`
- `pkg/fuiou/wxprecreate.go`
- `pkg/fuiou/notify.go`
- `pkg/sms/client.go`
- `internal/gateway/client.go`
- `internal/gateway/device.go`
- `internal/gateway/flow_card.go`
- `internal/model/wechat_config.go`
- `internal/service/wechat_config/service.go`
- `internal/service/client_auth/service.go`
- `internal/service/client_order/service.go`
- `internal/routes/storage.go`
- `internal/handler/callback/payment.go`
- `internal/task/iot_card_import.go`
- `internal/task/device_import.go`
- `Makefile`
- `Dockerfile.api`
- `Dockerfile.worker`
- `docker-compose.prod.yml`
- `.gitea/workflows/deploy.yaml`

---

*Integration audit: 2026-03-27*