doc(readme): update readme to justify latest codebase

feat(controller): enhance message handling and user options for automatic notifications
feat(controller): update notification logic to respect event_status_notify settings for trusted groups and admins
2026-09-03 15:34:32 +08:00 · 2026-09-03 11:57:20 +08:00 · 2026-09-02 21:35:07 +08:00
8 changed files with 436 additions and 112 deletions
@@ -3,6 +3,7 @@ agent.md
 config.json
 bot_user_config.json
 *.exe
+nukumizu-linux-amd64

 # SQLite database files. They live on a network share (Y:), and git/cloud
 # sync touching them while a WAL database is open corrupts the WAL index and
@@ -2,94 +2,144 @@

 Remote server monitoring and command execution subsystem for [Komari](https://www.komari.wiki).

-## Overview
+Nukumizu connects to a Komari Dashboard instance, keeps an in-memory view of every monitored server, and pushes alerts to several notification channels. It also runs interactive bots on QQ (via [NapCat](https://napneko.github.io/), OneBot 11) and Telegram so operators can control servers from chat.

-Nukumizu connects to a Komari Dashboard instance to:
- Monitor server status in real-time via WebSocket
- Execute commands on remote servers via the Komari task API
- Provide Bot interfaces on QQ (via NapCat) and Telegram for interactive server control
- Send one-way status notifications via Email, Ntfy, and Webhook
+## Features

-## Project Structure
+- **Komari integration** — logs into the Komari Dashboard, refreshes the node list on startup and every 5 minutes, and polls each node's latest status through the Komari WebSocket every 5 seconds.
+- **Status tracking** — a thread-safe node tracker keeps the latest report and static info per server and detects `Online` / `Offline` transitions.
+- **Remote command execution** — dispatches commands through the Komari task API and polls the result (1s interval, up to 60s timeout).
+- **Interactive bots** — QQ (NapCat / OneBot 11) and Telegram bots for `/list`, `/status`, `/info`, `/run`, `/shutdown`, `/reboot`, and more, protected by an admin / trusted-group permission model.
+- **Notification channels** — server status changes are pushed to every enabled channel: QQ, Telegram, Email (SMTP), [ntfy](https://ntfy.sh), and Webhook.
+- **Network proxy** — a global proxy URL can be enabled per controller (`networkUseProxy`) for HTTP, WebSocket, and even SMTP (HTTP CONNECT tunnel).
+- **Customizable message templates** — every bot/notification message is rendered from a template in `config.json`.
+- **Storage** — SQLite (pure-Go driver) for `user.db` and `log.db`; safe on network shares (WAL disabled).
+- **Dashboard API** — token-authenticated REST API plus a live log-streaming WebSocket.
+
+## How it works
+
+1. On startup Nukumizu logs in to the Komari Dashboard. A failed login aborts the process.
+2. It fetches the node list (name → UUID, static info) and stores it in memory, then opens a WebSocket to poll live status every 5 seconds. If the connection drops it reconnects with exponential backoff; after 5 failed attempts it notifies and keeps retrying.
+3. The node tracker uses the first received snapshot as a baseline so a restart does not produce false "offline" alerts, then fires a status-change event for every real transition.
+4. Each status-change event is rendered through the `SERVER_STATUS_CHANGED` template and sent to all enabled controllers. QQ / Telegram additionally receive a startup welcome and the initial server list.
+5. Every 12 hours the Komari session is re-authenticated; the node list is refreshed every 5 minutes.
+
+## Project structure

 ```
 nukumizu-backend/
 ├── main.go                       # Entry point, startup sequence, graceful shutdown
 ├── router.go                     # HTTP route registration
 ├── config/
-│   └── config.go            # Configuration loading, defaults
+│   ├── config.go                 # Load config files, apply defaults
+│   └── variables.go              # Config schema structs + globals
+├── global/
+│   └── variables.go              # Software build metadata (name/version/developer)
 ├── handler/
-│   ├── user.go              # User login/register handlers
-│   ├── server.go            # Server list/status/exec handlers
-│   └── health.go            # Health check endpoint
+│   ├── user.go                   # /api/user/login, /api/user/register
+│   ├── server.go                 # /api/server/list, getStatus, exec
+│   └── health.go                 # /health
 ├── database/
-│   └── user.go              # SQLite user database
+│   └── user.go                   # user.db (SQLite) user store
 ├── utils/
-│   ├── auth.go              # Token management, authentication
-│   └── middleware.go        # Rate limit, CORS, XSS protection
+│   ├── auth.go                   # Token management, Auth middleware, JSON responses
+│   └── middleware.go             # Rate limit, CORS, XSS/security headers
 ├── postLog/                      # Logging subsystem
-├── internal/
-│   ├── komari/
-│   │   ├── client.go        # Komari HTTP API client
-│   │   └── ws.go            # Komari WebSocket client
-│   ├── qq/
-│   │   ├── qq.go            # QQ (Napcat) Bot controller
-│   │   └── napcat.go        # NapCat HTTP API + WebSocket client
-│   ├── node/
-│   │   └── tracker.go       # Thread-safe node state tracking
-│   ├── controller/
-│   │   ├── controller.go    # Controller interface & manager
-│   │   └── pipes/
-│   │       ├── telegram.go  # Telegram Bot controller
-│   │       ├── email.go     # Email notification controller
-│   │       ├── ntfy.go      # Ntfy notification controller
-│   │       └── webhook.go   # Webhook notification controller
-│   └── template/
-│       └── template.go      # Message template engine
+│   ├── postLog.go                # Leveled logger (stdout + broadcast)
+│   ├── database.go               # log.db (SQLite, one table per run)
+│   ├── logBroadcaster.go         # Fan-out to WebSocket clients
+│   └── logSocketHandler.go       # /api/system/getLogs WebSocket handler
+└── internal/
+    ├── komari/
+    │   ├── client.go             # Komari HTTP/JSON-RPC client (login, nodes, task exec/poll)
+    │   └── ws.go                 # Komari status WebSocket (poll + reconnect)
+    ├── node/
+    │   └── tracker.go            # Thread-safe server state, status-change detection
+    ├── netproxy/
+    │   └── netproxy.go           # Unified network proxy for controllers
+    ├── template/
+    │   └── template.go           # Message template renderer ({{ variables }})
+    └── controller/
+        ├── controller.go         # Manager, Controller / BotController interfaces
+        ├── trigger.go            # Command parsing, authorization, routing
+        ├── processor.go          # Command handlers
+        ├── utils.go
+        └── pipes/
+            ├── email.go          # Email notification pipe
+            ├── ntfy.go           # ntfy notification pipe
+            ├── webhook.go        # Webhook notification pipe
+            ├── qq_napcat/
+            │   ├── qq.go         # QQ (NapCat / OneBot 11) bot controller
+            │   └── napcat.go     # NapCat WebSocket + HTTP API client
+            └── telegram/
+                ├── telegram.go   # Telegram bot controller (go-telegram/bot, long polling)
+                └── send.go       # Message sending / splitting (Telegram Markdown)
 ```

+## Requirements
+
+- Go **1.25** or newer
+- A running [Komari](https://www.komari.wiki) Dashboard instance reachable from this host
+- For QQ: a [NapCat](https://napneko.github.io/) instance exposing an OneBot 11 WebSocket + HTTP endpoint
+- For Telegram: a bot token from [@BotFather](https://t.me/BotFather)
+
+Key dependencies: `github.com/go-telegram/bot`, `github.com/gorilla/websocket`, `gopkg.in/mail.v2`, `modernc.org/sqlite`.
+
 ## Configuration

-Copy and modify `config.json` at the project root:
+There are two configuration files, both read from the working directory unless overridden:
+
+| File | CLI flag | Default | Purpose |
+|---|---|---|---|
+| `config.json` | `-config` | `config.json` | Core settings: system, Komari, controllers, message templates |
+| `bot_user_config.json` | `-bot-user-config` | `bot_user_config.json` | Per-bot admins / trusted groups and their notification preferences |
+
+> Both files are in `.gitignore` because they contain credentials (Komari password, bot tokens, proxy auth). Start from the samples below and never commit real secrets.
+
+### `config.json`

 ```json
 {
    "system": {
        "debugMode": true,
        "listenAddr": "0.0.0.0",
-        "listenPort": "8080"
+        "listenPort": "8080",
+        "networkProxy": "http://127.0.0.1:7890"
    },
    "debug": {
        "showNapcatMsg": false,
-        "showTelegramMsg": false
+        "showNapcatAction": false,
+        "showTelegramMsg": false,
+        "showTriggerCmdEcho": true,
+        "showKomariTaskEcho": false,
+        "napcatIgnoreSelfMsg": false
    },
    "komari": {
-        "dashboardURL": "http://127.0.0.1:25774",
+        "dashboardURL": "https://status.example.com",
        "account": {
            "username": "admin",
-            "password": "admin"
+            "password": "CHANGE_ME"
        }
    },
    "controllerMethod": {
        "qq(napcat)": {
            "enabled": false,
+            "networkUseProxy": false,
            "napcatAddr": "127.0.0.1",
            "napcatPort": "3000",
            "napcatToken": "",
            "botQQID": 0,
-            "listenMethod": "global",
-            "admins": [],
-            "trustedGroups": []
+            "listenMethod": "global"
        },
        "telegram": {
            "enabled": false,
+            "networkUseProxy": false,
            "botToken": "",
-            "listenMethod": "global",
-            "admins": [],
-            "trustedGroups": []
+            "listenMethod": "global"
        },
        "email": {
            "enabled": false,
+            "networkUseProxy": false,
            "smtpHost": "",
            "smtpPort": 587,
            "username": "",
@@ -100,6 +150,7 @@ Copy and modify `config.json` at the project root:
        },
        "ntfy": {
            "enabled": false,
+            "networkUseProxy": false,
            "server": "https://ntfy.sh",
            "topic": "",
            "token": "",
@@ -107,6 +158,7 @@ Copy and modify `config.json` at the project root:
        },
        "webhook": {
            "enabled": false,
+            "networkUseProxy": false,
            "url": "",
            "method": "POST",
            "headers": {},
@@ -114,51 +166,202 @@ Copy and modify `config.json` at the project root:
        }
    },
    "controllerMessage": {
-        "SERVER_STATUS_CHANGED": "Server Status Changed Alert\n{{ serverName }} - {{ upStatus }}\nEvent: {{ event }}\nServer Name: {{ serverName }}\nMessage: {{ message }}\nTime: {{ time }}",
-        "SERVER_LIST": "All server list:\nOnline:\n{{ list.onlineServers }}\nOffline:\n{{ list.offlineServers }}",
-        "SERVER_EXECUTE_RESULT": "Command execute result:\nServer Name: {{ serverName }}\nCommand: {{ command }}\n***Result***\n\n{{ result }}\n\n************\nTime: {{ time }}"
+        "BOT_STARTED": "Nukumizu Alert Bot Started\nTime: {{ time }}\n- Software Version: {{ softwareVersion }}\n- Build Version: {{ softwareBuildVer }}\n- Commit Hash: {{ softwareCommitHash }}\n- Build Type: {{ softwareBuildType }}\n- Build Time: {{ softwareBuildTime }}\n- Developer: {{ softwareDeveloper }}",
+        "BOT_HELP": "Nukumizu Alert Bot Ver. {{ softwareVersion }}.{{ softwareBuildVer }}.{{ softwareCommitHash }}\nCommand Lists:\n- /help: Show this help message\n- /list: List all servers and show their status\n- /status <UUID>: Show specific server status\n- /info <UUID>: Show specific server info\n- /run <UUID> <command>: Execute command on specific server. If you type \"all\" in <UUID>, you will run the command on all servers.\n- /shutdown <UUID>: Shutdown specific server.\n- /reboot <UUID>: Reboot specific server.\n- /getip <UUID>: Get specific server IP address.",
+        "TG_BOT_START": "Welcome to use Nukumizu Alert Bot!\nUse `/help` to get command list.",
+        "SERVER_STATUS_CHANGED": "Server Status Changed Alert\n{{ serverName }} - {{ upStatus }}\n- Event: {{ event }}\n- Server Name: {{ serverName }}\n- Message: {{ message }}\n- Time: {{ time }}",
+        "SERVER_LIST": "All server list:\n- Online:\n{{ list.onlineServers }}\n- Offline:\n{{ list.offlineServers }}",
+        "SERVER_EXECUTE_RESULT": "Command execute result:\n- Server ID: {{ serverName }}\n- Command: {{ command }}\n-----**Result**-----\n\n{{ result }}\n----------\n\n- Time: {{ time }}"
+    },
+    "dataPath": "./data",
+    "dbPath": "./db"
+}
+```
+
+Field notes:
+
+- `system.networkProxy` is a **system-wide** proxy URL. A controller only uses it when its own `networkUseProxy` is `true`. Applied to Telegram HTTP polling, NapCat HTTP/WebSocket, ntfy and webhook requests, and Email SMTP (tunneled via HTTP CONNECT).
+- `controllerMethod.qq(napcat).listenMethod` / `telegram.listenMethod` — see [Bot recognition modes](#bot-recognition-modes).
+- `debug` toggles verbose per-channel message/action logging; these only matter in debug builds / `debugMode`.
+- `email.useTLS` is kept for configuration compatibility.
+- `dataPath` / `dbPath` default to `./data` and `./db`; `user.db` and `log.db` are created under `dbPath`.
+- Missing keys fall back to built-in defaults (host `0.0.0.0`, port `8080`, NapCat `127.0.0.1:3000`, ntfy server `https://ntfy.sh`, webhook method `POST`, etc.). Message templates have built-in fallbacks too.
+
+### `bot_user_config.json`
+
+Admins and trusted groups are defined **per bot channel** and map a member ID to that member's notification preferences:
+
+```json
+{
+    "qq(napcat)": {
+        "admins": {
+            "123456789": {
+                "event_status_notify": true,
+                "event_bot_started": true,
+                "event_reply": true
+            }
+        },
+        "trustedGroups": {
+            "987654321": {
+                "event_status_notify": true,
+                "event_bot_started": false,
+                "event_reply": true
+            }
+        }
+    },
+    "telegram": {
+        "admins": {
+            "user_handle": {
+                "event_status_notify": true,
+                "event_bot_started": true,
+                "event_reply": true
+            }
+        },
+        "trustedGroups": {
+            "-1001234567890": {
+                "event_status_notify": true,
+                "event_bot_started": false,
+                "event_reply": true
+            }
+        }
    }
 }
 ```

-## API Endpoints
+- **QQ**: member IDs are QQ numbers; group IDs are the numeric group number.
+- **Telegram**: member IDs may be `@username` (resolved to the numeric user ID once that user has messaged the bot) or the numeric user ID; group IDs are the numeric chat ID (supergroups are negative).
+- Per-member options:
+  - `event_status_notify` — receive server `Online`/`Offline` push notifications.
+  - `event_bot_started` — receive the automatic startup message (welcome + initial server list).
+  - `event_reply` — reserved for opting out of replies to that member's own commands.
+- Admins of a channel also appear in every trusted-group/private-chat context where the bot sends notifications.

-All API responses follow the format: `{"success": bool, "message": "..."}`
+### Message templates

-Authentication is via `X-Token` and `X-Timestamp` HTTP headers.
+`controllerMessage` templates are rendered before sending. Available variables (rendered through the Telegram pipe are additionally wrapped in Telegram legacy Markdown):

-| Endpoint | Method | Auth | Description |
+| Variable | Meaning |
+|---|---|
+| `{{ time }}` | Current server time |
+| `{{ serverName }}` | Targeted server name |
+| `{{ serverUUID }}` | Targeted server UUID |
+| `{{ upStatus }}` | `Online` / `Offline` |
+| `{{ event }}` | Status change event (`Online` / `Offline`) |
+| `{{ message }}` | Message accompanying a status event |
+| `{{ command }}` | The command that was executed |
+| `{{ result }}` | Command execution result |
+| `{{ list.onlineServers }}` | Formatted list of online servers (`- Name (uuid)`) |
+| `{{ list.offlineServers }}` | Formatted list of offline servers |
+| `{{ softwareVersion }}`, `{{ softwareBuildVer }}`, `{{ softwareCommitHash }}`, `{{ softwareBuildType }}`, `{{ softwareBuildTime }}`, `{{ softwareDeveloper }}`, `{{ softwareDescription }}` | Build metadata (commit hash and build time are injected at compile time) |
+
+## API
+
+All responses follow the envelope `{"success": true|false, "message": "...", ...data}`. `message` is empty on success unless noted.
+
+### Authentication
+
+Requests are authenticated with HTTP headers:
+
+| Header | Meaning |
+|---|---|
+| `X-Token` | Token returned by login/register. Held in memory only (lost on restart). |
+| `X-Timestamp` | Unix timestamp (seconds); rejected if more than ±30 minutes from server time. **Skipped entirely when `system.debugMode` is `true`.** |
+
+Tokens idle for more than 1 hour are expired (cleaned every 10 minutes); any authenticated call refreshes the timer. Permission levels: `None`, `bot`, `admin`. Endpoints requiring `bot` accept both `bot` and `admin` tokens. Currently registration/login always issue `admin`-level tokens.
+
+### Endpoints
+
+| Endpoint | Method | Permission | Description |
 |---|---|---|---|
-| `/api/user/login` | POST | None | User login |
-| `/api/user/register` | POST | None | First-time registration |
-| `/api/server/list` | GET | bot/admin | List all servers |
-| `/api/server/getStatus` | GET | bot/admin | Get server recent status |
-| `/api/server/exec` | POST | bot/admin | Execute command on server(s) |
-| `/health` | GET | None | Health check |
-| `/api/system/getLogs` | WS | None | Real-time log streaming |
+| `/api/user/login` | POST | None | Log in. Body `{username, password}`. Returns `{token, userID, username, level, registerDate}`. |
+| `/api/user/register` | POST | None | Register the first user. Body `{username, password}`. Only allowed while no user exists; otherwise `403`. Returns `{token, userID, username, level}`. |
+| `/api/server/list` | GET | bot / admin | List all monitored servers. |
+| `/api/server/getStatus` | GET | bot / admin | Recent live status for a server. Query `?uuid=<uuid>`. Returns `{uuid, report}` or `404`. |
+| `/api/server/exec` | POST | bot / admin | Execute a command. Body `{uuid: [<uuid>...], command}`. Dispatches a Komari task and polls until completion (or timeout). Returns `{taskID, results}`. |
+| `/health` | GET | None | Health check. Returns `{status, database}`. |
+| `/api/system/getLogs` | WebSocket | None | Streams logs. Sends the last 100 buffered entries, then live `{level, content, timestamp}` events. |

-## Bot Commands
+Middleware applied to the whole server:
+
+- **Rate limit** — token bucket, 100 requests/minute per client IP.
+- **CORS** — `Access-Control-Allow-Origin: *`, allows `Content-Type`, `X-Token`, `X-Timestamp`, `Authorization`.
+- **Security headers** — `X-XSS-Protection`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy`, a restrictive CSP.
+
+## Bots
+
+QQ (NapCat) and Telegram bots share one command engine and authorization pipeline, implemented in `internal/controller/`. NapCat speaks OneBot 11 (WebSocket event stream + HTTP actions); Telegram uses `go-telegram/bot` long polling.
+
+### Permission model
+
+- **Trusted group**: any command issued *inside a group* is only answered if that group is listed in `trustedGroups`. Messages in other groups are ignored.
+- **Admin commands**: `/shutdown`, `/reboot`, and `/run` additionally require the *sender* to be listed in `admins`.
+- **Private chat**: non-admin commands (`/help`, `/list`, `/status`, `/info`, `/getip`) are answered for any private sender; admin commands still require admin.
+
+### Bot recognition modes
+
+- `global` — the bot watches all messages in trusted groups and reacts to recognized commands without being mentioned. Unknown `/`-commands are silently ignored.
+- `at` — the bot only reacts when it is mentioned (QQ `@`, Telegram `@botname`). In this mode an unknown command produces an `Unknown command: /…` reply.
+
+### Commands

 | Command | Permission | Description |
 |---|---|---|
-| `/list` | None | List all server status |
-| `/shutdown <uuid>` | Admin | Shutdown specific server |
-| `/reboot <uuid>` | Admin | Reboot specific server |
-| `/status <uuid>` | None | Get server detailed status |
-| `/run <uuid\|all> <command>` | Admin | Run command on server(s) |
+| `/help` | All | Show the help message (`BOT_HELP` template). |
+| `/list` | All | List all servers with online/offline state (`SERVER_LIST` template). |
+| `/status <uuid>` | All | Live report for a server (CPU, RAM, disk, network, uptime, processes). |
+| `/info <uuid>` | All | Static info for a server (OS, kernel, CPU, RAM, swap, disk, billing, tags). |
+| `/getip <uuid>` | All | IPv4 / IPv6 address of a server. |
+| `/shutdown <uuid>` | Admin | Shut the server down via the Komari task API. |
+| `/reboot <uuid>` | Admin | Reboot the server via the Komari task API. |
+| `/run <uuid\|all> <command>` | Admin | Execute a command on one server or on all servers (`all`), then report the result (`SERVER_EXECUTE_RESULT` template). |
+| `/start` | All | Telegram only — sends the `TG_BOT_START` welcome message. |
+
+## Notification channels
+
+QQ and Telegram are *interactive* channels. Email, ntfy, and webhook are **status-only** channels — they receive server status-change alerts but cannot run commands. On startup, the welcome message and initial server list are delivered only to the bot channels (QQ / Telegram), honoring each member's `event_bot_started` preference.

 ## Building

+Requires Go 1.25+. Repo includes helper scripts that bake the current git commit and build time into the binary via `-ldflags`:
+
 ```bash
-go build -o nukumizu-backend .
+# Windows (cross-compile to Linux amd64)
+build-linux-x86_64.bat
+
+# Windows amd64
+build-win-x86_64.bat
 ```

+Equivalent manual builds:
+
+```bash
+# Linux / macOS
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+  go build -ldflags "-X main.CommitHash=$(git rev-parse --short HEAD) -X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  -o nukumizu-linux-amd64 .
+
+# Windows
+CGO_ENABLED=0 GOOS=windows GOARCH=amd64 \
+  go build -ldflags "-X main.CommitHash=<commit> -X main.BuildTime=<utc-time>" \
+  -o nukumizu-windows-amd64.exe .
+```
+
+`main.CommitHash` and `main.BuildTime` are surfaced in logs and in the `BOT_STARTED` message.
+
 ## Running

+Both `config.json` and `bot_user_config.json` must exist in the working directory (or be passed explicitly):
+
 ```bash
-./nukumizu-backend -config config.json
+# Development (uses go run, so config files must be in the CWD)
+run.bat
+
+# Or build first, then run a binary
+./nukumizu-linux-amd64 -config config.json -bot-user-config bot_user_config.json
 ```

+On startup the program logs in to Komari, loads node state, connects the status WebSocket, then starts each enabled controller and the HTTP server on `listenAddr:listenPort`. Press `Ctrl+C` for a graceful shutdown.
+
 ## License

 See [LICENSE](LICENSE).
@@ -121,6 +121,16 @@ type BotUserOptions struct {
 	// EventStatusNotify indicates whether this member is subscribed to node
 	// status change notifications.
 	EventStatusNotify bool `json:"event_status_notify"`
+
+	// EventBotStarted indicates whether this member receives the automatic
+	// messages the bot pushes on startup (welcome message and startup server
+	// list).
+	EventBotStarted bool `json:"event_bot_started"`
+
+	// EventReply indicates whether this member receives automatic replies to
+	// their commands (e.g. /status, /list). If false, the bot will not send any
+	// reply to this member's commands.
+	EventReply bool `json:"event_reply"`
 }

 // BotUserMembers maps a member ID (QQ number, Telegram @username or numeric
@@ -21,6 +21,37 @@ type Command struct {
 	SenderID int64    // User ID of the sender
 }

+// Message represents a message to be sent by a controller.
+type Message struct {
+	Source  string // The source pipe (e.g., "telegram", "qq", "napcat")
+	Content string // The message content
+	ChatID  int64  // Chat/group ID where the message should be sent
+	Type    string // Message type (see MessageType*), used for per-member opt-outs
+}
+
+// Message type labels. They let bot pipes apply per-member opt-out options from
+// bot_user_config.json (see MemberReceives) to automatic messages.
+const (
+	// MessageTypeBotStarted marks the automatic welcome/server-list messages the
+	// bot pushes on startup. Gated by BotUserOptions.EventBotStarted.
+	MessageTypeBotStarted = "event_bot_started"
+	// MessageTypeReply marks a direct reply to a user command. Reserved for the
+	// BotUserOptions.EventReply opt-out.
+	MessageTypeReply = "event_reply"
+)
+
+// MemberReceives reports whether a member whose bot_user_config.json options are
+// opts receives an automatic message of the given type. Only member-controllable
+// types are gated; anything else is always delivered.
+func MemberReceives(opts config.BotUserOptions, messageType string) bool {
+	switch messageType {
+	case MessageTypeBotStarted:
+		return opts.EventBotStarted
+	default:
+		return true
+	}
+}
+
 // Controller defines the interface for all notification/bot controllers.
 type Controller interface {
 	Name() string
@@ -38,7 +69,7 @@ type Controller interface {
 // pipes (email, ntfy, webhook) do not.
 type BotController interface {
 	Controller
-	SendMessage(message string) error
+	SendMessage(message Message) error
 }

 // Manager manages all controller instances and routes events.
@@ -72,14 +103,16 @@ func (m *Manager) Register(c Controller) {

 // ShowBotInitMessage sends the bot initialization message to all enabled
 // bot controllers (QQ/NapCat and Telegram). Notification-only pipes that do
-// not implement BotController are skipped.
+// not implement BotController are skipped. The message is typed
+// MessageTypeBotStarted so each controller can honor its members' per-recipient
+// EventBotStarted opt-out.
 func (m *Manager) ShowBotInitMessage() {
 	m.mu.RLock()
 	defer m.mu.RUnlock()

 	cfg := config.C_globalConfig
 	params := template.BuildBotInitializationMsgParams()
-	message := template.Render(cfg.ControllerMessage.BotStarted, params)
+	content := template.Render(cfg.ControllerMessage.BotStarted, params)

 	for _, ctrl := range m.controllers {
 		if !ctrl.IsEnabled() {
@@ -89,22 +122,29 @@ func (m *Manager) ShowBotInitMessage() {
 		if !ok {
 			continue // Notification-only pipe (email/ntfy/webhook), not a bot.
 		}
+		message := Message{
+			Source:  bot.Name(),
+			Content: content,
+			Type:    MessageTypeBotStarted,
+		}
 		if err := bot.SendMessage(message); err != nil {
 			postLog.Warning(fmt.Sprintf("Controller %s failed to send init message: %v", bot.Name(), err))
 		}
 	}
 }

-// ShowBotServerList sends the server list to all enabled bot controllers. The
-// message content is identical to the /list command (same template and
-// parameters).
+// ShowBotServerList sends the startup server list to all enabled bot
+// controllers. The message content is identical to the /list command (same
+// template and parameters). Like the init message it is typed
+// MessageTypeBotStarted so members who opted out of bot-started pushes do not
+// receive it.
 func (m *Manager) ShowBotServerList() {
 	m.mu.RLock()
 	defer m.mu.RUnlock()

 	cfg := config.C_globalConfig
 	params := template.BuildParamsFromServerList()
-	message := template.Render(cfg.ControllerMessage.ServerList, params)
+	content := template.Render(cfg.ControllerMessage.ServerList, params)

 	for _, ctrl := range m.controllers {
 		if !ctrl.IsEnabled() {
@@ -114,6 +154,11 @@ func (m *Manager) ShowBotServerList() {
 		if !ok {
 			continue // Notification-only pipe (email/ntfy/webhook), not a bot.
 		}
+		message := Message{
+			Source:  bot.Name(),
+			Content: content,
+			Type:    MessageTypeBotStarted,
+		}
 		if err := bot.SendMessage(message); err != nil {
 			postLog.Warning(fmt.Sprintf("Controller %s failed to send server list: %v", bot.Name(), err))
 		}
@@ -221,18 +221,29 @@ func (q *QQController) trustedGroupIDs() []string {
 	return nil
 }

-// SendMessage sends an arbitrary message (e.g. the bot initialization message)
-// to all QQ trusted groups and admins.
-func (q *QQController) SendMessage(message string) error {
+// SendMessage sends an automatic message (e.g. the bot initialization message
+// and the startup server list) to all QQ trusted groups and admins. Each
+// member's opt-out options in bot_user_config.json (e.g. EventBotStarted for
+// event_bot_started messages) are honored per recipient.
+func (q *QQController) SendMessage(message controller.Message) error {
 	if !q.cfg.Enabled {
 		return nil
 	}

-	for _, groupID := range q.trustedGroupIDs() {
-		q.sendGroupMessage(groupID, message)
+	// Only notify trusted groups and admins whose options allow this message type.
+	if uc := config.C_botUserConfig; uc != nil {
+		for groupID, opts := range uc.QQ.TrustedGroups {
+			if !controller.MemberReceives(opts, message.Type) {
+				continue
+			}
+			q.sendGroupMessage(groupID, message.Content)
+		}
+		for adminID, opts := range uc.QQ.Admins {
+			if !controller.MemberReceives(opts, message.Type) {
+				continue
+			}
+			q.sendPrivateMessage(adminID, message.Content)
 		}
-	for _, adminID := range q.adminIDs() {
-		q.sendPrivateMessage(adminID, message)
 	}
 	return nil
 }
@@ -247,15 +258,21 @@ func (q *QQController) SendStatusChange(change node.StatusChange) error {
 	params := template.BuildParamsFromStatusChange(change)
 	message := template.Render(cfg.ControllerMessage.ServerStatusChanged, params)

-	// Send to trusted groups.
-	for _, groupID := range q.trustedGroupIDs() {
+	// Only notify trusted groups and admins whose event_status_notify is true.
+	if uc := config.C_botUserConfig; uc != nil {
+		for groupID, opts := range uc.QQ.TrustedGroups {
+			if !opts.EventStatusNotify {
+				continue
+			}
 			q.sendGroupMessage(groupID, message)
 		}
-
-	// Send to admins via private message.
-	for _, adminID := range q.adminIDs() {
+		for adminID, opts := range uc.QQ.Admins {
+			if !opts.EventStatusNotify {
+				continue
+			}
 			q.sendPrivateMessage(adminID, message)
 		}
+	}

 	return nil
 }
@@ -6,6 +6,7 @@ import (

 	"github.com/go-telegram/bot"
 	"github.com/go-telegram/bot/models"
+	"nukumizu-backend/internal/controller"
 )

 // maxMessageLen is the safe chunk size for outbound messages. Telegram's hard
@@ -18,15 +19,16 @@ const maxMessageLen = 4000
 // rich text. Templates must stay valid under Telegram's legacy Markdown:
 // unpaired '*' or '_' characters (e.g. a lone '*Event: ...' label) make the
 // API reject the whole message.
-func (t *TelegramController) sendMessage(chatID int64, text string) error {
+func (t *TelegramController) sendMessage(message controller.Message) error {
 	if t.client == nil {
 		return nil
 	}
-	if strings.TrimSpace(text) == "" {
+	if strings.TrimSpace(message.Content) == "" {
 		return nil
 	}
-	for _, chunk := range splitMessage(text, maxMessageLen) {
-		if err := t.sendMessageChunk(chatID, chunk); err != nil {
+
+	for _, chunk := range splitMessage(message.Content, maxMessageLen) {
+		if err := t.sendMessageChunk(message.ChatID, chunk); err != nil {
 			return err
 		}
 	}
@@ -180,7 +180,14 @@ func (t *TelegramController) handleUpdate(_ context.Context, _ *bot.Bot, update
 		return
 	}

-	if err := t.sendMessage(msg.Chat.ID, response); err != nil {
+	message := controller.Message{
+		Source:  "telegram",
+		Content: response,
+		ChatID:  msg.Chat.ID,
+		Type:    controller.MessageTypeReply,
+	}
+
+	if err := t.sendMessage(message); err != nil {
 		postLog.Warning("Failed to send Telegram reply: " + err.Error())
 	}
 }
@@ -229,13 +236,30 @@ func (t *TelegramController) processCommand(cmd controller.Command) string {
 	return response
 }

-// SendMessage sends an arbitrary message (e.g. the bot initialization message)
-// to all Telegram trusted groups and admins.
-func (t *TelegramController) SendMessage(message string) error {
+// SendMessage sends an automatic message (e.g. the bot initialization message
+// and the startup server list) to all Telegram trusted groups and admins. Each
+// member's opt-out options in bot_user_config.json (e.g. EventBotStarted for
+// event_bot_started messages) are honored per recipient.
+func (t *TelegramController) SendMessage(message controller.Message) error {
 	if !t.cfg.Enabled || t.client == nil {
 		return nil
 	}
-	t.sendToGroupsAndAdmins(message)
+
+	// Only notify trusted groups and admins whose options allow this message type.
+	if uc := config.C_botUserConfig; uc != nil {
+		for groupID, opts := range uc.Telegram.TrustedGroups {
+			if !controller.MemberReceives(opts, message.Type) {
+				continue
+			}
+			t.sendGroupMessage(groupID, message.Content)
+		}
+		for admin, opts := range uc.Telegram.Admins {
+			if !controller.MemberReceives(opts, message.Type) {
+				continue
+			}
+			t.sendAdminMessage(admin, message.Content)
+		}
+	}
 	return nil
 }

@@ -249,7 +273,21 @@ func (t *TelegramController) SendStatusChange(change node.StatusChange) error {
 	params := template.BuildParamsFromStatusChange(change)
 	message := template.Render(cfg.ControllerMessage.ServerStatusChanged, params)

-	t.sendToGroupsAndAdmins(message)
+	// Only notify trusted groups and admins whose event_status_notify is true.
+	if uc := config.C_botUserConfig; uc != nil {
+		for groupID, opts := range uc.Telegram.TrustedGroups {
+			if !opts.EventStatusNotify {
+				continue
+			}
+			t.sendGroupMessage(groupID, message)
+		}
+		for admin, opts := range uc.Telegram.Admins {
+			if !opts.EventStatusNotify {
+				continue
+			}
+			t.sendAdminMessage(admin, message)
+		}
+	}
 	return nil
 }

@@ -368,14 +406,6 @@ func (t *TelegramController) resolvedAdminList() []string {
 	return result
 }

-// sendToGroupsAndAdmins sends a message to all trusted groups and admins.
-func (t *TelegramController) sendToGroupsAndAdmins(message string) {
-	t.sendToGroups(message)
-	for _, admin := range t.adminIDs() {
-		t.sendAdminMessage(admin, message)
-	}
-}
-
 // sendToGroups sends a message to all trusted groups.
 func (t *TelegramController) sendToGroups(message string) {
 	for _, groupID := range t.trustedGroupIDs() {
@@ -412,7 +442,13 @@ func (t *TelegramController) sendAdminMessage(admin string, message string) {

 // sendToChat sends a message to a chat ID, logging failures.
 func (t *TelegramController) sendToChat(chatID int64, message string) {
-	if err := t.sendMessage(chatID, message); err != nil {
+	messaged := controller.Message{
+		Source:  "telegram",
+		Content: message,
+		ChatID:  chatID,
+		Type:    controller.MessageTypeReply,
+	}
+	if err := t.sendMessage(messaged); err != nil {
 		postLog.Warning(fmt.Sprintf("Failed to send Telegram message to %d: %v", chatID, err))
 	}
 }
@@ -0,0 +1,10 @@
+package controller
+
+func Contains(slice []string, target string) bool {
+    for _, s := range slice {
+        if s == target {
+            return true
+        }
+    }
+    return false
+}
Author	SHA1	Message	Date
NanamiAdmin	0cedb51e50	doc(readme): update readme to justify latest codebase	2026-09-03 15:34:32 +08:00
NanamiAdmin	6c819f8c52	feat(controller): enhance message handling and user options for automatic notifications	2026-09-03 11:57:20 +08:00
NanamiAdmin	2a1f5e11f8	feat(controller): update notification logic to respect event_status_notify settings for trusted groups and admins	2026-09-02 21:35:07 +08:00