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
@@ -8,19 +8,19 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
|
||||
)
|
||||
|
||||
// rbacRoute is one admin route plus the method needed to reach it. The name is
|
||||
// the subtest label, so a failure names the route without reading the path.
|
||||
// rbacRoute 是一条管理路由加上抵达它所需的方法。name 是
|
||||
// 子测试标签，因此失败时不必读路径就能指明是哪条路由。
|
||||
type rbacRoute struct {
|
||||
name string
|
||||
method string
|
||||
path string
|
||||
}
|
||||
|
||||
// viewerReadRoutes is the read-only monitoring tier: the exact admin route set
|
||||
// wired to viewerAuth in gateway/routes.go (owner/admin/viewer). It must stay in
|
||||
// lockstep with registerAdminRoutes — adding a route to viewerAuth without
|
||||
// adding it here leaves it untested, and moving one out of viewerAuth makes the
|
||||
// matching subtest fail (see the batch's mutation-verification records).
|
||||
// viewerReadRoutes 是只读监控层：gateway/routes.go 中接到 viewerAuth
|
||||
// 的确切管理路由集合（owner/admin/viewer）。它必须与
|
||||
// registerAdminRoutes 保持同步 —— 把一条路由加进 viewerAuth 而不
|
||||
// 加进这里会让它未被测试，而把一条移出 viewerAuth 会让对应
|
||||
// 子测试失败（见本批次的变异验证记录）。
|
||||
var viewerReadRoutes = []rbacRoute{
|
||||
{"personas", http.MethodGet, "/api/v1/admin/personas"},
|
||||
{"sessions", http.MethodGet, "/api/v1/admin/sessions"},
|
||||
@@ -36,10 +36,10 @@ var viewerReadRoutes = []rbacRoute{
|
||||
{"notifications", http.MethodGet, "/api/v1/admin/notifications"},
|
||||
}
|
||||
|
||||
// ownerAdminReadRoutes is the admin read tier that stays owner/admin: private
|
||||
// content, other accounts' data and the audit trail. A viewer must get 403; an
|
||||
// admin must pass the gate (the handler's own status is out of scope here, so
|
||||
// only "not 401/403" is asserted for admin).
|
||||
// ownerAdminReadRoutes 是仍保持 owner/admin 的管理读层：私有
|
||||
// 内容、其他账号的数据与审计链。viewer 必须得到 403；
|
||||
// admin 必须通过该门（handler 自身的状态在此不在范围内，因此
|
||||
// 对 admin 只断言「不是 401/403」）。
|
||||
var ownerAdminReadRoutes = []rbacRoute{
|
||||
{"memories", http.MethodGet, "/api/v1/admin/memories"},
|
||||
{"channels/messages", http.MethodGet, "/api/v1/admin/channels/messages"},
|
||||
@@ -52,10 +52,10 @@ var ownerAdminReadRoutes = []rbacRoute{
|
||||
{"rag/query", http.MethodPost, "/api/v1/admin/rag/query"},
|
||||
}
|
||||
|
||||
// ownerOnlyRoutes is every route reserved for the owner, including the
|
||||
// credential-acquiring channel endpoints (login-qr/login-status) and the
|
||||
// state-mutating writes. An admin must be rejected too, so the list doubles as
|
||||
// the owner>admin boundary test.
|
||||
// ownerOnlyRoutes 是保留给 owner 的每一条路由，包括
|
||||
// 获取凭据的渠道端点（login-qr/login-status）与
|
||||
// 改变状态的写操作。admin 也必须被拒绝，因此该列表同时用作
|
||||
// owner>admin 边界测试。
|
||||
var ownerOnlyRoutes = []rbacRoute{
|
||||
{"channels/{platform}/login-qr", http.MethodGet, "/api/v1/admin/channels/weixin-ilink/login-qr"},
|
||||
{"channels/{platform}/login-status", http.MethodGet, "/api/v1/admin/channels/weixin-ilink/login-status"},
|
||||
@@ -94,9 +94,9 @@ var ownerOnlyRoutes = []rbacRoute{
|
||||
{"system/restore", http.MethodPost, "/api/v1/admin/system/restore"},
|
||||
}
|
||||
|
||||
// newRBACEnv builds the gateway with a real JWT service, a capability registry
|
||||
// and an injected log ring buffer, so every viewer-readable route can answer
|
||||
// 200 (the log tail would otherwise be an honest 501).
|
||||
// newRBACEnv 用真实 JWT 服务、能力注册表
|
||||
// 与注入的日志环形缓冲构建网关，使每条 viewer 可读路由都能返回
|
||||
// 200（否则日志尾部会是诚实的 501）。
|
||||
func newRBACEnv(t *testing.T) *testEnv {
|
||||
t.Helper()
|
||||
env := newEnv(t, nil, true)
|
||||
@@ -104,10 +104,10 @@ func newRBACEnv(t *testing.T) *testEnv {
|
||||
return env
|
||||
}
|
||||
|
||||
// rbacBody returns a request body valid enough that the RBAC gate — not a
|
||||
// decoder error — decides the status. A failed decode still answers 4xx, which
|
||||
// never turns a 403 into a false pass, but a valid body keeps the assertions
|
||||
// honest about what each route expects.
|
||||
// rbacBody 返回一个足够合法的请求体，使决定状态的是 RBAC 门 ——
|
||||
// 而不是解码错误。解码失败仍返回 4xx，这绝不会把
|
||||
// 403 变成假通过，但合法请求体让断言对每条路由
|
||||
// 的预期保持诚实。
|
||||
func rbacBody(rt rbacRoute) any {
|
||||
switch rt.name {
|
||||
case "rag/query":
|
||||
@@ -117,9 +117,9 @@ func rbacBody(rt rbacRoute) any {
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdminRBAC_ViewerReadsMonitoringSurface locks the viewer tier: each of the
|
||||
// twelve read-only monitoring routes answers 200 for viewer, admin and owner
|
||||
// alike (owner>admin>viewer all satisfy viewerAuth).
|
||||
// TestAdminRBAC_ViewerReadsMonitoringSurface 锁定 viewer 层：十二条只读
|
||||
// 监控路由对 viewer、admin 与 owner 都返回 200
|
||||
// （owner>admin>viewer 都满足 viewerAuth）。
|
||||
func TestAdminRBAC_ViewerReadsMonitoringSurface(t *testing.T) {
|
||||
t.Parallel()
|
||||
env := newRBACEnv(t)
|
||||
@@ -140,9 +140,9 @@ func TestAdminRBAC_ViewerReadsMonitoringSurface(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdminRBAC_AnonymousIsUnauthorized proves every admin route (both tiers)
|
||||
// fails closed with 401 — not 403 and never a silent success — when no bearer
|
||||
// token is presented.
|
||||
// TestAdminRBAC_AnonymousIsUnauthorized 证明未出示 bearer token 时每条
|
||||
// 管理路由（两层）都以 401 失败关闭 —— 不是 403，也绝不是
|
||||
// 静默成功。
|
||||
func TestAdminRBAC_AnonymousIsUnauthorized(t *testing.T) {
|
||||
t.Parallel()
|
||||
env := newRBACEnv(t)
|
||||
@@ -162,10 +162,10 @@ func TestAdminRBAC_AnonymousIsUnauthorized(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdminRBAC_ViewerForbiddenOnRestrictedRoutes locks the exclusion list: a
|
||||
// viewer is 403 on every admin read that carries private content, other
|
||||
// accounts' data or audit records, and on every owner-only route (writes plus
|
||||
// the credential-acquiring channel endpoints).
|
||||
// TestAdminRBAC_ViewerForbiddenOnRestrictedRoutes 锁定排除列表：viewer 在
|
||||
// 每一条携带私有内容、其他账号数据或审计记录的
|
||||
// 管理读上都是 403，在每一条仅 owner 路由（写操作加上
|
||||
// 获取凭据的渠道端点）上亦然。
|
||||
func TestAdminRBAC_ViewerForbiddenOnRestrictedRoutes(t *testing.T) {
|
||||
t.Parallel()
|
||||
env := newRBACEnv(t)
|
||||
@@ -185,10 +185,10 @@ func TestAdminRBAC_ViewerForbiddenOnRestrictedRoutes(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdminRBAC_AdminPassesReadGateButNotOwnerGate separates the two upper
|
||||
// tiers: an admin passes the gate on the owner/admin read routes (its handler
|
||||
// may still answer 404/501 — only the gate's verdict is asserted) but is 403 on
|
||||
// every owner-only route, proving admin never leaks into owner.
|
||||
// TestAdminRBAC_AdminPassesReadGateButNotOwnerGate 区分上面两层：admin
|
||||
// 在 owner/admin 读路由上通过该门（其 handler 仍可能返回
|
||||
// 404/501 —— 只断言门的判定）但在每一条仅 owner 路由上
|
||||
// 是 403，证明 admin 绝不越入 owner。
|
||||
func TestAdminRBAC_AdminPassesReadGateButNotOwnerGate(t *testing.T) {
|
||||
t.Parallel()
|
||||
env := newRBACEnv(t)
|
||||
@@ -215,8 +215,8 @@ func TestAdminRBAC_AdminPassesReadGateButNotOwnerGate(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestAdminRBAC_ViewerForbiddenOnWrites pins the two write routes named in the
|
||||
// wiring brief so a future gate change cannot quietly hand a viewer a mutation.
|
||||
// TestAdminRBAC_ViewerForbiddenOnWrites 钉住接线说明中点名的两条写
|
||||
// 路由，使今后的门的改动无法悄悄把变更能力交给 viewer。
|
||||
func TestAdminRBAC_ViewerForbiddenOnWrites(t *testing.T) {
|
||||
t.Parallel()
|
||||
env := newRBACEnv(t)
|
||||
|
||||
Reference in new issue
Block a user