feat(maintenance): wire sysadmin ui.* whitelist settings to public site status

- sysadmin.Service.GetSettingValue: whitelist read-through (DB > env > default) - maintenance.Service: SiteSettingsProvider injection; StatusView carries notice/readOnly; new CurrentSiteStatus + GET /api/v1/maintenance/site-status - composition root wires ui.maintenance_notice / ui.read_only_mode into maintenance site settings - MaintenanceBanner: persistent notice banner + read-only mode strip - chore(web): drop dead 'dirty' var in EnvSettingsSection (baseline TS6133 build blocker) - KB ops actions: deferred out-of-repo (shared infra container side); documented in task record
2026-09-25 16:33:56 +00:00
parent cc998c05ce
commit 914d0aa39d
10 changed files with 283 additions and 3 deletions
@@ -0,0 +1,68 @@
+---
+title: "P9: web-sysadmin 残差收口"
+task_id: websysadmin-residual-r2-2026-09-25 (r1 cancelled: scope missed internal/app)
+status: in_progress
+created: 2026-09-25
+updated: 2026-09-25
+owner: cursor-auto
+task_type: implementation
+task_tier: small
+policy_revision: "agent-governance-2026-09-21-r1"
+branch: feature/websysadmin-residual-2026-09-25
+worktree: .worktrees/websysadmin-residual-2026-09-25
+base_dev_sha: "c5027788ea72bc9488247c2c22dc67c511241fd6"
+write_scope:
+  - internal/maintenance/
+  - internal/sysadmin/
+  - internal/server/
+  - internal/app/
+  - web/
+  - .doc/ops/short-term/
+  - .doc/test-reports/
+allowed_environments: []
+head_sha: ""
+mutex: web+sysadmin
+review_state: pending
+integration_state: pending
+deployment: not_required
+cleanup: pending
+cleanup_owner: independent maintainer after owner exit
+cleanup_trigger: acceptance green + owner exit
+remote_sync: not_requested
+---
+
+# P9: web-sysadmin 残差收口
+
+## 用户目标与授权
+
+- 用户目标：`/goal 把这些任务都进行规划，并推进至完成` → 总控 P9 批次。
+- 来源：MATRIX `web-sysadmin` 行尾注「剩余 deferred：Playwright 实跑、KB 运维动作、白名单项接消费方」。
+- 交付终点：三项残差处理完毕（做/不做+理由），验收绿。
+
+## 残差处置
+
+| 残差 | 处置 | 说明 |
+|---|---|---|
+| 白名单项接消费方 | **本批实施** | `ui.maintenance_notice` + `ui.read_only_mode` 接入维护状态公开端点与前端横幅 |
+| Playwright 实跑 | **本批实施（docker 镜像通道）** | 宿主缺 libatk 系统库且无 sudo，改用 `mcr.microsoft.com/playwright` 官方镜像跑 `admin-console.spec.ts`（自带全部依赖） |
+| KB 运维动作 | **登记不做** | KB 为纯只读检索客户端（`internal/kb` 无写路径），rebuild/index 属共享基础设施容器（`shuimu-kb-shared`）侧能力，超出本仓边界；一期只读口径维持，管理台 KB 分组补探活刷新即可 |
+
+## 实施内容（白名单消费方接线）
+
+1. `sysadmin.Service.GetSettingValue(key)`：白名单 key 只读解析（DB > env > default），供跨模块消费。
+2. `maintenance.Service`：新增 `SiteSettingsProvider` 注入位（装配根从 sysadmin 解析，避免业务包反向依赖）；`StatusView` 增加 `notice`/`readOnly` 字段；`CurrentStatus` 每次读取携带站点开关；新增 `CurrentSiteStatus`（无窗口时也可轮询）。
+3. 装配根（`app.go`）：`rt.Maintenance.SetSiteSettings(...)` 从 sysadmin 读 `ui.maintenance_notice`/`ui.read_only_mode`。
+4. 新公开端点：`GET /api/v1/maintenance/site-status`（无需登录，同 status 口径）。
+5. 前端 `MaintenanceBanner`：readOnly → 蓝色只读提示条；notice 非空且无窗口 → 黄色常驻公告横幅；类型 `MaintenanceStatus` 补两字段。
+6. 顺手修：`EnvSettingsSection.tsx` 死变量 `dirty`（dev 基线既有 TS6133 构建阻断，单行删除不改行为）。
+
+## 验证
+
+- Go：`go build ./...` + `go vet` + `go test -short ./internal/maintenance/ ./internal/sysadmin/ ./internal/server/` 全绿（新增 3 个 site settings 用例）。
+- Web：`npm test`（34/34）+ `npm run build` PASS。
+- Playwright：docker 镜像通道跑 `admin-console.spec.ts`（证据见测试报告）。
+
+## 非目标
+
+- 不做 KB 写路径/重建编排（超边界，见上表）。
+- 不改 `chat.default_session_role` 等其余白名单键（消费方属各自业务模块后续任务）。
@@ -305,6 +305,22 @@ func Assemble(cfg *config.Config, svc *bizdev.Service) (*Runtime, error) {
 	}
 	if pool != nil {
 		rt.Maintenance = maintenance.NewService(maintenance.NewPGStore(pool))
+		if rt.SysAdmin != nil {
+			// P9 白名单消费方接线：ui.maintenance_notice / ui.read_only_mode
+			// 经公开维护状态端点生效（横幅常驻 + 前端只读提示）。
+			sa := rt.SysAdmin
+			rt.Maintenance.SetSiteSettings(func(ctx context.Context) (string, bool) {
+				notice, _ := sa.GetSettingValue(ctx, "ui.maintenance_notice")
+				noticeStr, _ := notice.(string)
+				readOnly := false
+				if v, err := sa.GetSettingValue(ctx, "ui.read_only_mode"); err == nil {
+					if b, ok := v.(bool); ok {
+						readOnly = b
+					}
+				}
+				return noticeStr, readOnly
+			})
+		}
 	}
 	if instSvc != nil {
 		instSvc.SetAuthorOnlyPolicySource(&sysadminAuthorOnlyPolicyAdapter{svc: rt.SysAdmin})
@@ -11,11 +11,16 @@ import (
 // HandoffFunc 到点时调用：负责 spawn 公告进程并移交 listener。
 type HandoffFunc func(ctx context.Context, w Window) error

+// SiteSettingsProvider 提供站点级开关（ui.maintenance_notice / ui.read_only_mode
+// 的运行时生效值）。由装配根从 sysadmin 设置解析注入；nil 表示未接线。
+type SiteSettingsProvider func(ctx context.Context) (notice string, readOnly bool)
+
 // Service 维护窗口调度。
 type Service struct {
 	store   Store
 	now     func() time.Time
 	handoff HandoffFunc
+	site    SiteSettingsProvider

 	mu     sync.Mutex
 	timer  *time.Timer
@@ -30,6 +35,11 @@ func NewService(store Store) *Service {
 	}
 }

+// SetSiteSettings 注入站点开关提供方（装配根调用）。
+func (s *Service) SetSiteSettings(fn SiteSettingsProvider) {
+	s.site = fn
+}
+
 func (s *Service) SetHandoff(fn HandoffFunc) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -46,13 +56,21 @@ type StatusView struct {
 	ExpectedHours  float64    `json:"expectedHours,omitempty"`
 	WindowID       int64      `json:"windowId,omitempty"`
 	Status         string     `json:"status"`
+	// 站点级开关（sysadmin 白名单 ui.* 生效值）。
+	Notice   string `json:"notice,omitempty"`   // ui.maintenance_notice 非空时横幅常驻展示
+	ReadOnly bool   `json:"readOnly,omitempty"` // ui.read_only_mode 为 true 时前端进入只读提示
 }

 func (s *Service) CurrentStatus(ctx context.Context) (StatusView, error) {
+	siteNotice, siteReadOnly := "", false
+	if s.site != nil {
+		siteNotice, siteReadOnly = s.site(ctx)
+	}
 	w, err := s.store.GetOpen(ctx)
 	if err != nil {
 		if errors.Is(err, ErrNotFound) {
-			return StatusView{Status: "none"}, nil
+			view := StatusView{Status: "none", Notice: siteNotice, ReadOnly: siteReadOnly}
+			return view, nil
 		}
 		return StatusView{}, err
 	}
@@ -64,6 +82,8 @@ func (s *Service) CurrentStatus(ctx context.Context) (StatusView, error) {
 		ExpectedHours:  hours,
 		WindowID:       w.ID,
 		Status:         w.Status,
+		Notice:         siteNotice,
+		ReadOnly:       siteReadOnly,
 	}
 	switch w.Status {
 	case StatusActive:
@@ -74,6 +94,22 @@ func (s *Service) CurrentStatus(ctx context.Context) (StatusView, error) {
 	return view, nil
 }

+// CurrentSiteStatus 返回站点级开关（不依赖维护窗口）；site provider 未接线时为零值。
+func (s *Service) CurrentSiteStatus(ctx context.Context) StatusView {
+	view := StatusView{Status: "none"}
+	if s == nil || s.site == nil {
+		return view
+	}
+	notice, readOnly := s.site(ctx)
+	view.Notice = notice
+	view.ReadOnly = readOnly
+	if notice != "" {
+		// notice 自身驱动横幅（非维护窗口），状态标记为 site_notice 以便前端区分。
+		view.Status = "site_notice"
+	}
+	return view
+}
+
 type ScheduleInput struct {
 	Start     time.Time
 	End       time.Time
@@ -0,0 +1,90 @@
+package maintenance
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+// P9 白名单消费方接线：site provider 注入后 CurrentStatus 无窗口时也返回 notice/readOnly。
+func TestCurrentStatusCarriesSiteSettings(t *testing.T) {
+	svc := NewService(&fakeStore{err: ErrNotFound})
+	svc.SetSiteSettings(func(ctx context.Context) (string, bool) {
+		return "系统今晚 22:00 例行维护", true
+	})
+	view, err := svc.CurrentStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if view.Status != "none" {
+		t.Fatalf("status = %s, want none (no window)", view.Status)
+	}
+	if view.Notice != "系统今晚 22:00 例行维护" {
+		t.Fatalf("notice = %q", view.Notice)
+	}
+	if !view.ReadOnly {
+		t.Fatal("readOnly must carry through")
+	}
+}
+
+// CurrentSiteStatus：provider 返回非空 notice 时状态切 site_notice；未接线为零值。
+func TestCurrentSiteStatus(t *testing.T) {
+	svc := NewService(&fakeStore{err: ErrNotFound})
+	if v := svc.CurrentSiteStatus(context.Background()); v.Status != "none" || v.Notice != "" || v.ReadOnly {
+		t.Fatalf("unwired provider should zero, got %+v", v)
+	}
+	svc.SetSiteSettings(func(ctx context.Context) (string, bool) { return "公告", false })
+	v := svc.CurrentSiteStatus(context.Background())
+	if v.Status != "site_notice" || v.Notice != "公告" || v.ReadOnly {
+		t.Fatalf("site status = %+v", v)
+	}
+}
+
+// 有维护窗口时 notice/readOnly 同样随窗口状态返回。
+func TestCurrentStatusWindowPlusSite(t *testing.T) {
+	start := time.Now().Add(time.Hour).UTC()
+	svc := NewService(&fakeStore{w: &Window{
+		ID: 7, ScheduledStart: start, ScheduledEnd: start.Add(2 * time.Hour),
+		Message: "升级", Status: StatusScheduled,
+	}})
+	svc.SetSiteSettings(func(ctx context.Context) (string, bool) { return "横幅公告", false })
+	view, err := svc.CurrentStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !view.Scheduled || view.Message != "升级" {
+		t.Fatalf("window view = %+v", view)
+	}
+	if view.Notice != "横幅公告" {
+		t.Fatalf("notice lost: %+v", view)
+	}
+}
+
+type fakeStore struct {
+	w   *Window
+	err error
+}
+
+func (f *fakeStore) GetOpen(ctx context.Context) (*Window, error) {
+	if f.err != nil {
+		return nil, f.err
+	}
+	return f.w, nil
+}
+func (f *fakeStore) GetByID(ctx context.Context, id int64) (*Window, error) {
+	return f.w, nil
+}
+func (f *fakeStore) Insert(ctx context.Context, w Window) (Window, error) {
+	return w, nil
+}
+func (f *fakeStore) UpdateStatus(ctx context.Context, id int64, from, to string) (Window, error) {
+	if f.w != nil {
+		f.w.Status = to
+		return *f.w, nil
+	}
+	return Window{}, errors.New("no window")
+}
+func (f *fakeStore) ListRecent(ctx context.Context, limit int) ([]Window, error) {
+	return nil, nil
+}
@@ -32,6 +32,16 @@ func (s *Server) handleMaintenanceStatus(w http.ResponseWriter, r *http.Request)
 	writeJSONResponse(w, http.StatusOK, view)
 }

+// handleMaintenanceSiteStatus 只返回站点级开关（notice / readOnly），
+// 供无维护窗口时的横幅与只读提示轮询。
+func (s *Server) handleMaintenanceSiteStatus(w http.ResponseWriter, r *http.Request) {
+	if s.maintenance() == nil {
+		writeJSONResponse(w, http.StatusOK, maintenance.StatusView{Status: "none"})
+		return
+	}
+	writeJSONResponse(w, http.StatusOK, s.maintenance().CurrentSiteStatus(r.Context()))
+}
+
 func (s *Server) handleAdminMaintenanceList(w http.ResponseWriter, r *http.Request) {
 	if _, ok := s.requireSystemAdmin(w, r); !ok {
 		return
@@ -344,6 +344,7 @@ func (s *Server) Routes() http.Handler {
 	mux.HandleFunc("PUT /api/v1/admin/system/settings/{key}", s.handleAdminSystemSettingByKey)

 	mux.HandleFunc("GET /api/v1/maintenance/status", s.handleMaintenanceStatus)
+	mux.HandleFunc("GET /api/v1/maintenance/site-status", s.handleMaintenanceSiteStatus)
 	mux.HandleFunc("GET /api/v1/admin/maintenance", s.handleAdminMaintenanceList)
 	mux.HandleFunc("POST /api/v1/admin/maintenance", s.handleAdminMaintenanceSchedule)
 	mux.HandleFunc("POST /api/v1/admin/maintenance/{id}/cancel", s.handleAdminMaintenanceCancel)
@@ -214,6 +214,20 @@ func (s *Service) UpdateSettingEx(ctx context.Context, in SettingUpdate) (Settin
 	return setting, nil
 }

+// GetSettingValue 返回白名单 key 的当前生效值（PG 覆盖 → env 覆盖 → 默认）。
+// 供维护横幅 / 只读提示等运行时消费方只读使用；非白名单 key 返回 ErrUnknownSetting。
+func (s *Service) GetSettingValue(ctx context.Context, key string) (any, error) {
+	spec, ok := s.findSpec(key)
+	if !ok {
+		return nil, ErrUnknownSetting
+	}
+	setting, err := s.resolve(ctx, spec)
+	if err != nil {
+		return nil, err
+	}
+	return setting.Value, nil
+}
+
 // resolve 按 DB > env > default 解析单个设置的当前值。
 func (s *Service) resolve(ctx context.Context, spec SettingSpec) (Setting, error) {
 	setting := Setting{
@@ -148,7 +148,6 @@ export const EnvSettingsSection: React.FC = () => {
          </div>
          {g.items.map((s) => {
            const draft = drafts[s.key];
-            const dirty = s.writable && String(draft ?? '') !== '' && (!s.secret || String(draft) !== '');
            const secretDirty = s.secret && String(draft ?? '').trim() !== '';
            const plainDirty = !s.secret && draft !== s.value;
            const canSave = s.writable && (secretDirty || plainDirty);
@@ -39,7 +39,49 @@ export const MaintenanceBanner: React.FC<{ pollMs?: number }> = ({ pollMs = 4500
    };
  }, [pollMs]);

-  if (!status || (!status.scheduled && !status.active)) return null;
+  if (!status) return null;
+
+  // sysadmin 站点开关：ui.read_only_mode → 常驻只读提示条
+  if (status.readOnly) {
+    return (
+      <div
+        role="status"
+        style={{
+          padding: '10px 16px',
+          background: 'rgba(59, 130, 246, 0.14)',
+          borderBottom: '1px solid rgba(59, 130, 246, 0.35)',
+          color: '#1d4ed8',
+          fontSize: '13px',
+          lineHeight: 1.5,
+          textAlign: 'center',
+        }}
+      >
+        系统处于只读模式：写操作入口已暂停，请联系管理员恢复。
+      </div>
+    );
+  }
+
+  // sysadmin 站点开关：ui.maintenance_notice 非空 → 常驻公告横幅（无维护窗口也展示）
+  if (!status.scheduled && !status.active && status.notice) {
+    return (
+      <div
+        role="status"
+        style={{
+          padding: '10px 16px',
+          background: 'rgba(234, 179, 8, 0.16)',
+          borderBottom: '1px solid rgba(234, 179, 8, 0.35)',
+          color: '#a16207',
+          fontSize: '13px',
+          lineHeight: 1.5,
+          textAlign: 'center',
+        }}
+      >
+        {status.notice}
+      </div>
+    );
+  }
+
+  if (!status.scheduled && !status.active) return null;

  const hours = status.expectedHours ? status.expectedHours.toFixed(1) : '?';
  const text = status.active
@@ -10,6 +10,10 @@ export interface MaintenanceStatus {
  expectedHours?: number;
  windowId?: number;
  status: string;
+  /** sysadmin ui.maintenance_notice 生效值；非空时横幅常驻 */
+  notice?: string;
+  /** sysadmin ui.read_only_mode 生效值；true 时前端进入只读提示 */
+  readOnly?: boolean;
 }

 export interface MaintenanceWindow {