# FranklinWH Toolbox Service

Go 后端服务，整合了：

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

## 📁 项目结构

```bash
├── 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
凭据和验证码。