docs(02-01): 完成 PERM+FIN+POLL 9项修复计划 PERM-01/02 FIN-01/02/03 POLL-01/02/03/04

2026-03-28 10:46:10 +08:00
parent 754bbcdf3b
commit e1ec024904
18 changed files with 5548 additions and 28 deletions
--- a/.planning/codebase/INTEGRATIONS.md
+++ b/.planning/codebase/INTEGRATIONS.md
@@ -0,0 +1,215 @@
+# 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*