docs(gateway): gateway 剩余文件注释改中文（逐行 1:1，代码零字节改动）
主人 2026-10-03 拍板「注释一律中文」；gateway 至此整包注释中文化完成（本会话共 3 批： 已推库 16 个文件 + 本批剩余文件）。 校验：机械校验（非注释改动行）= 空；剥注释后代码文本逐行比对全等（不一致文件数 0）； 全树 go test ./... 58 包 ok / 0 FAIL；交叉编译绿。
This commit is contained in:
AskaEth committed
1 parent
91e8d7a029
commit
074ffc4ebf
73 files changed
+2529
-2529
No files matched your search
@@ -1,12 +1,12 @@
|
||||
package gateway
|
||||
|
||||
// This file adds the per-platform adapter panel endpoints (design/17 §2), owner
|
||||
// only and audited. They expose a platform's real account data (friends,
|
||||
// channels, guilds, private chats) via the adapter's REST surface and a single
|
||||
// controlled "test send" write. Only KOOK is wired; every other platform answers
|
||||
// an honest 501 rather than fabricated data (a project red line). The bot token
|
||||
// is never read or logged — the adapter owns the token and surfaces only its
|
||||
// normalized REST results.
|
||||
// 本文件新增按平台的适配器面板端点（design/17 §2），仅 owner
|
||||
// 且带审计。它们通过适配器的 REST 表面暴露某平台的真实账号
|
||||
// 数据（好友、频道、服务器、私聊），外加一个受控的
|
||||
// 「测试发送」写操作。目前只接线了 KOOK；其他平台一律
|
||||
// 返回诚实的 501 而不是编造数据（项目红线）。机器人 token
|
||||
// 绝不读取或记录 —— 适配器持有 token，只浮现其
|
||||
// 归一化后的 REST 结果。
|
||||
|
||||
import (
|
||||
"context"
|
||||
@@ -21,9 +21,9 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/plugins/channels/kook"
|
||||
)
|
||||
|
||||
// kookAdmin is the subset of the KOOK adapter's admin REST surface the gateway
|
||||
// panel endpoints invoke. It is implemented by *kook.Adapter and reached by
|
||||
// unwrapping the registration wrapper.
|
||||
// kookAdmin 是网关面板端点所调用的 KOOK 适配器管理 REST 表面的
|
||||
// 子集。它由 *kook.Adapter 实现，通过拆开注册包装器
|
||||
// 抵达。
|
||||
type kookAdmin interface {
|
||||
ListFriends(ctx context.Context, typ string) (kook.FriendList, error)
|
||||
HandleFriendRequest(ctx context.Context, id int64, accept bool) error
|
||||
@@ -37,7 +37,7 @@ type kookAdmin interface {
|
||||
SendTestMessage(ctx context.Context, targetID, content string) (kook.TestMessageResult, error)
|
||||
}
|
||||
|
||||
// adminKookView is the wire shape of GET /api/v1/admin/channels/{platform}/view.
|
||||
// adminKookView 是 GET /api/v1/admin/channels/{platform}/view 的线上结构。
|
||||
type adminKookView struct {
|
||||
Platform string `json:"platform"`
|
||||
AccountID string `json:"accountId,omitempty"`
|
||||
@@ -49,9 +49,9 @@ type adminKookView struct {
|
||||
Errors map[string]string `json:"errors,omitempty"`
|
||||
}
|
||||
|
||||
// kookAccountFor resolves the *kook.Adapter registered for a platform/account.
|
||||
// It is nil for a non-kook platform, an unknown account, or a wrapped adapter
|
||||
// that does not expose the admin surface.
|
||||
// kookAccountFor 解析为某平台/账号注册的 *kook.Adapter。
|
||||
// 对非 kook 平台、未知账号，或未暴露管理表面的
|
||||
// 包装适配器，它返回 nil。
|
||||
func kookAccountFor(caps CapabilityStore, platform, accountID string) (kookAdmin, bool) {
|
||||
if caps == nil {
|
||||
return nil, false
|
||||
@@ -75,11 +75,11 @@ func kookAccountFor(caps CapabilityStore, platform, accountID string) (kookAdmin
|
||||
return nil, false
|
||||
}
|
||||
|
||||
// asKookAdmin unwraps a registered channel value to its inner KOOK adapter. The
|
||||
// registration wraps the adapter in cmd/cyrene's namedAdapter (an unexported
|
||||
// struct embedding adapter.PlatformAdapter); the embedded field is exported, so
|
||||
// reflection reads it and type-asserts to the KOOK surface. A direct *kook.Adapter
|
||||
// value (tests) is also accepted.
|
||||
// asKookAdmin 把已注册的渠道值拆到其内层 KOOK 适配器。
|
||||
// 注册时会把适配器包进 cmd/cyrene 的 namedAdapter（一个内嵌
|
||||
// adapter.PlatformAdapter 的未导出结构体）；被内嵌的字段是导出的，
|
||||
// 因此反射可读取它并类型断言到 KOOK 表面。直接的
|
||||
// *kook.Adapter 值（测试）也被接受。
|
||||
func asKookAdmin(v any) (kookAdmin, bool) {
|
||||
if k, ok := v.(kookAdmin); ok {
|
||||
return k, true
|
||||
@@ -104,9 +104,9 @@ func asKookAdmin(v any) (kookAdmin, bool) {
|
||||
return nil, false
|
||||
}
|
||||
|
||||
// adminChannelPlatformView aggregates a KOOK account's friends, private chats and
|
||||
// guilds (with the first guild's channels). Each sub-fetch is best-effort; a
|
||||
// failing one is recorded in errors rather than aborting the whole view.
|
||||
// adminChannelPlatformView 聚合某 KOOK 账号的好友、私聊与
|
||||
// 服务器（含首个服务器的频道）。每次子拉取都是尽力而为；
|
||||
// 失败的那次记入 errors，而不中止整个视图。
|
||||
func (s *Server) adminChannelPlatformView(w http.ResponseWriter, r *http.Request) {
|
||||
platform := r.PathValue("platform")
|
||||
accountID := r.URL.Query().Get("accountId")
|
||||
@@ -136,8 +136,8 @@ func (s *Server) buildKookView(ctx context.Context, k kookAdmin, platform, accou
|
||||
} else {
|
||||
view.Guilds = guilds
|
||||
if len(guilds) > 0 {
|
||||
// Aggregate the first guild's channels and members so the panel has a
|
||||
// concrete server to render; deeper servers are a separate fetch.
|
||||
// 聚合首个服务器的频道与成员，使面板有具体的服务器
|
||||
// 可渲染；更深的服务器是另一次拉取。
|
||||
if channels, err := k.ListGuildChannels(ctx, guilds[0].ID, -1); err != nil {
|
||||
view.Errors["channels"] = err.Error()
|
||||
} else {
|
||||
@@ -153,8 +153,8 @@ func (s *Server) buildKookView(ctx context.Context, k kookAdmin, platform, accou
|
||||
return view
|
||||
}
|
||||
|
||||
// adminChannelPlatformFriends returns a KOOK account's friends/requests/blocked
|
||||
// list, filtered by the optional ?type= and ?accountId= params.
|
||||
// adminChannelPlatformFriends 返回某 KOOK 账号的好友/请求/黑名单
|
||||
// 列表，按可选的 ?type= 与 ?accountId= 参数过滤。
|
||||
func (s *Server) adminChannelPlatformFriends(w http.ResponseWriter, r *http.Request) {
|
||||
platform := r.PathValue("platform")
|
||||
accountID := r.URL.Query().Get("accountId")
|
||||
@@ -173,13 +173,13 @@ func (s *Server) adminChannelPlatformFriends(w http.ResponseWriter, r *http.Requ
|
||||
writeJSON(w, http.StatusOK, fl)
|
||||
}
|
||||
|
||||
// kookFriendHandleRequest is the POST /admin/channels/{platform}/friend/handle body.
|
||||
// kookFriendHandleRequest 是 POST /admin/channels/{platform}/friend/handle 的请求体。
|
||||
type kookFriendHandleRequest struct {
|
||||
ID int64 `json:"id"`
|
||||
Accept bool `json:"accept"`
|
||||
}
|
||||
|
||||
// adminChannelFriendHandle accepts or rejects a KOOK friend request (owner write).
|
||||
// adminChannelFriendHandle 接受或拒绝一个 KOOK 好友请求（owner 写）。
|
||||
func (s *Server) adminChannelFriendHandle(w http.ResponseWriter, r *http.Request) {
|
||||
platform := r.PathValue("platform")
|
||||
accountID := r.URL.Query().Get("accountId")
|
||||
@@ -207,14 +207,14 @@ func (s *Server) adminChannelFriendHandle(w http.ResponseWriter, r *http.Request
|
||||
writeJSON(w, http.StatusOK, map[string]any{"handled": true, "id": req.ID, "accept": req.Accept})
|
||||
}
|
||||
|
||||
// kookMessageTestRequest is the POST /admin/channels/{platform}/message/test body.
|
||||
// kookMessageTestRequest 是 POST /admin/channels/{platform}/message/test 的请求体。
|
||||
type kookMessageTestRequest struct {
|
||||
TargetID string `json:"targetId"`
|
||||
Content string `json:"content"`
|
||||
}
|
||||
|
||||
// adminChannelMessageTest sends one test message to a KOOK target channel (owner
|
||||
// write), so the panel can confirm the bot can reach the channel.
|
||||
// adminChannelMessageTest 向 KOOK 目标频道发送一条测试消息（owner
|
||||
// 写），使面板能确认机器人可以抵达该频道。
|
||||
func (s *Server) adminChannelMessageTest(w http.ResponseWriter, r *http.Request) {
|
||||
platform := r.PathValue("platform")
|
||||
accountID := r.URL.Query().Get("accountId")
|
||||
@@ -248,8 +248,8 @@ func (s *Server) adminChannelMessageTest(w http.ResponseWriter, r *http.Request)
|
||||
writeJSON(w, http.StatusOK, res)
|
||||
}
|
||||
|
||||
// kookTarget resolves the KOOK adapter for a platform/account, writing an honest
|
||||
// error and reporting found=false when it cannot.
|
||||
// kookTarget 解析某平台/账号的 KOOK 适配器；无法解析时
|
||||
// 写出诚实的错误并报告 found=false。
|
||||
func (s *Server) kookTarget(r *http.Request, w http.ResponseWriter, what, platform, accountID string) (kookAdmin, bool) {
|
||||
platform = strings.TrimSpace(platform)
|
||||
if platform != "kook" {
|
||||
|
||||
Reference in new issue
Block a user