csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
main
junhong_cmp_fiber/.planning/codebase/INTEGRATIONS.md

10 KiB
Raw Permalink Blame History

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

Reference in New Issue View Git Blame Copy Permalink