216 lines
10 KiB
Markdown
216 lines
10 KiB
Markdown
# 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*
|