FranklinWH-Toolbox/service

FranklinWH Toolbox Service

Go 后端服务，整合了：

• Fiber（Web 框架）
• GORM（ORM）
• Swagger（接口文档）
• 缓存（Redis）
• 任务 + 定时器（Cron）
• 日志（Zap 或 Logrus）
• 配置管理（Viper）

📁 项目结构

├── cmd/
│    └── main.go
├── config/             # 配置
├── cache/              # 缓存封装（Redis）
├── database/           # GORM 数据库相关
├── logger/             # zap Logger
├── scheduler/          # 任务调度
├── routes/             # Fiber 路由 & swagger   
├── controllers/        # 控制器
├── models/             # GORM 模型，数据结构定义（实体、DTO）
├── services/           # 业务逻辑（核心）
├── middleware/         # 中间件 (鉴权 / 日志 / 限流 / 恢复 panic)
├── repositories/       # 数据访问层（DB/Cache/外部 API）
├── dto/                # 请求/响应 DTO (Data Transfer Object) 对外接口类型
├── domain/             # 领域对象 Domain Model 对内/模型类型
├── utils/              # 工具函数
├── pkg/                # 自定义通用包
├── docs/               # Swagger 文档
├── .env                # 环境变量
├── go.mod
└── go.sum

♻️ 项目标准访问流

Notes:

• 带*为可选历程，可跳过
• 一般情况下不允许跳层级访问

Client (HTTP / gRPC / MQ)

│
▼

Route (Fiber 路由)

│
▼

Middleware* (鉴权 / 日志 / 限流 / 恢复 panic)

│
▼

Controller / Handler (解析请求，调用 service)

│
▼

Service (业务逻辑) ────────────────────────────────────────────┐

│                                                         ▼
│                                          Task (实时任务) / Scheduler (定时任务)
│                                                          │
│                                                          ▼
│                                                        Jobs* (繁琐事务)
▼                                                         

Repository / DAO (数据库 / 缓存 / API) ◀───────────────────────┘

│
▼

Database / Cache (Redis) / 外部服务 (FWH-API)

✅ 项目特点 & 核心依赖

• 配置: Viper（加载 .env、支持环境变量）
• ORM: GORM — 数据库操作 + AutoMigrate 自动建表
• 缓存: Redis（Go‑redis 客户端）
• 定时任务: robfig/cron
• 日志: Zap（结构化日志）
• 文档: swaggo + swagger UI 自动生成 Swagger 文档
• 任务调度: Cron 支持定时和任务计划

📌 源模板参考

• alpody/golang-fiber-realworld-example-app 项目提供了 Fiber + GORM + Swagger 等完整的实战案例
• Fiber 官方 recipes/gorm-example 示例展示了 GORM 和 Fiber 的集成方式

⚙️ 配置说明

项目可通过环境变量配置文件对软件的功能进行配置，配置文件支持的路径如下（读取优先级与路径列出顺序一致）：

• "./.env"
• "./config.env"

| 变量名 | 说明 | | - | --- | | APP_ENV | 运行环境，可选项："pro" - 生产环境、"dev" - 开发环境，默认"DEV" | | APP_PORT | 服务监听端口号，默认"8301" | | MYSQL_DSN | MYSQL数据库连接配置，DSN格式，连接FWH服务器的home_energy_storage_server数据库，用于查询站点信息。 | | POSTGRES_DSN | PGSQL数据库连接配置，DSN格式，本地保存数据信息。 | | MONGO_DSN | MONGO数据库连接配置，DSN格式，本地保存数据信息。 | | REDIS_ADDR | REDIS本地缓存服务器的域名或IP地址，默认"localhost" | | SIM_CARD_DINGTALK_WEBHOOK | SIM 卡每日流量统计的钉钉自定义机器人 HTTPS Webhook 地址；未配置时跳过日报统计和发送。 | | SIM_CARD_DINGTALK_SECRET | 可选；机器人开启“加签”安全设置时填写对应密钥。 |

SIM 卡采集任务在每天 23:00 UTC 启动。两平台的全部页面写入 MongoDB 后，服务会生成一份 UTC 日期对应的流量日报，保存在 SimCardDailyStatistics 集合，并通过钉钉机器人发送 Markdown 消息。总量为当日记录的本月累计用量；增量为当日累计用量减前一日累计用量，若月累计量重置，则以重置后的当日累计量计。缺少前一日记录的卡不参与增量统计。阈值均为严格大于，换算采用 1 MB = 1024 KB、1 GB = 1024 MB。钉钉机器人若使用“自定义关键词”安全设置，应包含“SIM 卡流量日报”或改用加签。

FWH 生产账号登录

FWH_PASSWORD 在配置中填写明文，后端会计算 MD5 摘要提交。后端先调用 /api-user/user/login：如果响应直接包含 正式 token，即完成密码登录；如果响应声明 mfaRequired，则需要配置 FWH_TOTP_SECRET，后端会用返回的 mfaToken 和当前六位验证码调用 /api-user/mfa/login/verify，再保存验证响应中的正式 token。账号要求 MFA 但未配置 密钥时，登录会明确失败。FWH_TOTP_FIELD 已不再使用。

FWH TOTP 验证码页面

在后端配置中设置 FWH_TOTP_SECRET、独立的 FWH_TOTP_VIEW_PASSWORD，并按需设置 FWH_TOTP_VIEW_PORT（默认 8303，必须与 APP_PORT 不同）。默认绑定地址由 FWH_TOTP_VIEW_HOST=127.0.0.1 指定。重启后访问 http://127.0.0.1:<FWH_TOTP_VIEW_PORT>/fwh-totp/。浏览器会要求输入 HTTP Basic Auth 凭据：用户名固定为 fwh，密码为 FWH_TOTP_VIEW_PASSWORD。页面显示当前六位验证码和 剩余秒数，并在验证码切换时自动更新。密钥或页面密码为空时，独立端口不会启动。

从其他电脑访问时，可以通过 HTTPS 反向代理或 SSH 端口转发接入；也可以把 FWH_TOTP_VIEW_HOST 改为服务器网卡地址。不要通过明文 HTTP 在公网传输 Basic Auth 凭据和验证码。