junhong_cmp_fiber/.planning/codebase/INTEGRATIONS.md

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