feat(common): expose docs_on appconfig toggle (#536)

## Background

A new `octo-docs-backend` module service is being introduced (not live
yet). Clients need a signal to decide whether to surface the docs module
entry. The client reads `/v1/common/appconfig`; without a dedicated
field it can only fall back to a hardcoded default. This PR exposes that
signal from appconfig.

## Changes

Adds a `docs_on` boolean to `GET /v1/common/appconfig`, mirroring the
existing `sticker_custom_enabled` toggle pattern exactly:

| File | Change |
|---|---|
| `modules/common/system_settings.go` | New getter `DocsEnabled()`
backed by `system_setting docs.enabled`, default `false` |
| `modules/common/system_setting_schema.go` | Register `docs.enabled`
(bool) so it is admin-tunable and converges across replicas via the
settings snapshot |
| `modules/common/api.go` | Add `DocsOn bool json:"docs_on"` to
`appConfigResp`; emitted in **both** return branches (including the
version short-circuit) |
| `modules/common/api_test.go` | Integration tests: default false / DB
true / version short-circuit |
| `modules/common/system_settings_test.go` | Getter unit tests: default
false / DB true |

## Design notes

- **Default `false`**: `octo-docs-backend` is not live, so the entry
stays hidden. Ops flips `docs.enabled` to `1` from the admin console for
a controlled rollout — no redeploy/restart required.
- **Decoupled from `app_config.version`**: the version short-circuit
branch also emits `docs_on`, otherwise clients that hit the
cached-version path would never receive the latest value. Same invariant
already applied to `LocalLoginOff` / `SearchEnabled` /
`StickerCustomEnabled`.
- **Presentation toggle only**: it gates client-side display of the docs
entry and carries no server-side authorization.

## Client adaptation

- Parse as a bool (not `0/1`); default to `false` (hidden) when the
field is absent.
- Always take the latest value from appconfig, even when a local version
cache is hit.

## Testing

Go toolchain not available locally; verified via a `golang:1.25`
container against the local module cache:
- `go build ./modules/common/...`
- `go vet ./modules/common/...`
- `go test -c` (test binary compiles)

Integration tests require MySQL/Redis/WuKongIM and were not run locally
— left to CI.

## Test plan

- [ ] CI Build / Test green
- [ ] `docs_on=false` when `docs.enabled` is unset
- [ ] `docs_on=true` after setting `docs.enabled=1` (including requests
carrying `version`)

Co-authored-by: an9xyz <an9xyz@users.noreply.github.com>

Author: an9xyz

modules/common/api.go

@@ -389,6 +389,7 @@ func (cn *Common) appConfig(c *wkhttp.Context) {
 			MessagesSearchOn:       searchEnabled,
 			StickerCustomEnabled:   cn.systemSettings.StickerCustomEnabled(),
 			StickerHandleRequired:  cn.systemSettings.StickerHandleRequired(),
+			DocsOn:                 cn.systemSettings.DocsEnabled(),
 		})
 		return
 	}
@@ -431,6 +432,7 @@ func (cn *Common) appConfig(c *wkhttp.Context) {
 		MessagesSearchOn:       searchEnabled,
 		StickerCustomEnabled:   cn.systemSettings.StickerCustomEnabled(),
 		StickerHandleRequired:  cn.systemSettings.StickerHandleRequired(),
+		DocsOn:                 cn.systemSettings.DocsEnabled(),
 	})
 }
 
@@ -781,6 +783,14 @@ type appConfigResp struct {
 	// 客户端命中 version 短路分支也必须拿到最新值，否则被本地缓存住失去实时性，故两个
 	// 分支都下发。
 	StickerHandleRequired bool `json:"sticker_handle_required"`
+
+	// DocsOn 告知客户端是否展示文档(docs)模块入口。值来源于 system_setting
+	// docs.enabled；默认 false —— 新增的 octo-docs-backend 服务尚未上线，先隐藏入口，
+	// 上线后由管理台切 docs.enabled 灰度放开。本字段只表达展示策略，不承担服务端鉴权。
+	//
+	// 与 app_config.version 解耦的原因同 LocalLoginOff / SearchEnabled：运维切展示
+	// 策略后老客户端命中 version 短路分支也必须拿到最新值，故两个分支都下发。
+	DocsOn bool `json:"docs_on"`
 }
 
 type oidcProviderResp struct {

modules/common/api_test.go

@@ -97,6 +97,22 @@ func setStickerCustomEnabledSetting(t *testing.T, ctx *config.Context, enabled b
 	require.NoError(t, EnsureSystemSettings(ctx).Reload())
 }
 
+// setDocsEnabledSetting upserts system_setting docs.enabled and reloads the
+// shared snapshot. This is the appconfig-facing display toggle for the docs
+// module (octo-docs-backend).
+func setDocsEnabledSetting(t *testing.T, ctx *config.Context, enabled bool) {
+	t.Helper()
+	v := "0"
+	if enabled {
+		v = "1"
+	}
+	_, err := ctx.DB().InsertInto("system_setting").
+		Columns("category", "key_name", "value", "value_type").
+		Values("docs", "enabled", v, "bool").Exec()
+	require.NoError(t, err)
+	require.NoError(t, EnsureSystemSettings(ctx).Reload())
+}
+
 func TestAddVersion(t *testing.T) {
 	t.Skip("OCTO migration TODO: see https://github.com/Mininglamp-OSS/octo-server/issues/17")
 	s, ctx := testutil.NewTestServer()
@@ -741,3 +757,52 @@ func TestGetAppConfig_StickerCustomEnabled_OnVersionShortCircuit(t *testing.T) {
 	assert.Equal(t, http.StatusOK, w.Code)
 	assert.Contains(t, w.Body.String(), `"sticker_custom_enabled":true`)
 }
+
+// appconfig 必须下发 docs_on：值来源于 system_setting docs.enabled。默认 false，
+// 客户端据此隐藏 docs 模块入口（octo-docs-backend 上线前）。
+func TestGetAppConfig_DocsOn_DefaultFalse(t *testing.T) {
+	s, ctx := testutil.NewTestServer()
+	f := New(ctx)
+	cleanAllTablesAndReloadSettings(t, ctx)
+	err := f.appConfigDB.insert(&appConfigModel{})
+	assert.NoError(t, err)
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("GET", "/v1/common/appconfig", nil)
+	req.Header.Set("token", testutil.Token)
+	s.GetRoute().ServeHTTP(w, req)
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Contains(t, w.Body.String(), `"docs_on":false`)
+}
+
+// system_setting docs.enabled=true → appconfig 下发 true，客户端展示 docs 模块入口。
+func TestGetAppConfig_DocsOn_True(t *testing.T) {
+	s, ctx := testutil.NewTestServer()
+	f := New(ctx)
+	cleanAllTablesAndReloadSettings(t, ctx)
+	setDocsEnabledSetting(t, ctx, true)
+	err := f.appConfigDB.insert(&appConfigModel{})
+	assert.NoError(t, err)
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("GET", "/v1/common/appconfig", nil)
+	req.Header.Set("token", testutil.Token)
+	s.GetRoute().ServeHTTP(w, req)
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Contains(t, w.Body.String(), `"docs_on":true`)
+}
+
+// version 短路分支同样要下发 docs_on：展示开关需与 app_config.version 解耦，
+// 避免 admin 切换后老客户端命中版本短路而继续使用旧值。
+func TestGetAppConfig_DocsOn_OnVersionShortCircuit(t *testing.T) {
+	s, ctx := testutil.NewTestServer()
+	f := New(ctx)
+	cleanAllTablesAndReloadSettings(t, ctx)
+	setDocsEnabledSetting(t, ctx, true)
+	err := f.appConfigDB.insert(&appConfigModel{})
+	assert.NoError(t, err)
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("GET", "/v1/common/appconfig?version=99999999", nil)
+	req.Header.Set("token", testutil.Token)
+	s.GetRoute().ServeHTTP(w, req)
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Contains(t, w.Body.String(), `"docs_on":true`)
+}

modules/common/system_setting_schema.go

@@ -147,6 +147,12 @@ var systemSettingSchema = []settingDef{
 	{Category: "sticker", Key: "handle_required", Type: settingTypeBool, Description: "新增自定义贴纸是否强制校验上传句柄 handle（关闭=兼容期放行缺失句柄并观测，开启=缺/伪造一律拒；需服务端配有效 OCTO_MASTER_KEY 才有校验能力）",
 		Effective: func(s *SystemSettings) string { return boolToCanonical(s.StickerHandleRequired()) }},
 
+	// docs 模块展示开关（客户端据此决定是否展示 docs 入口）。新增的 octo-docs-backend
+	// 服务尚未上线，默认关闭；上线后由管理台切 docs.enabled 灰度放量。仅表达展示策略，
+	// 不承担任何服务端鉴权。经 GET /v1/common/appconfig 的 docs_on 下发给客户端。
+	{Category: "docs", Key: "enabled", Type: settingTypeBool, Description: "是否向客户端展示文档(docs)模块入口（octo-docs-backend 上线前默认关闭）",
+		Effective: func(s *SystemSettings) string { return boolToCanonical(s.DocsEnabled()) }},
+
 	// Email server config — formerly yaml-only (Support.* in config.go).
 	{Category: "support", Key: "email", Type: settingTypeString, Description: "技术支持邮箱（发件人）",
 		Effective: func(s *SystemSettings) string { return s.SupportEmail() }},

modules/common/system_settings.go

@@ -776,3 +776,13 @@ func (s *SystemSettings) StickerCustomEnabled() bool {
 func (s *SystemSettings) StickerHandleRequired() bool {
 	return s.getBool("sticker", "handle_required", false)
 }
+
+// DocsEnabled reports whether clients should surface the docs module (backed by
+// the new octo-docs-backend service). This is a presentation toggle only: it
+// gates client-side display of the docs entry and does not itself grant or
+// enforce any server-side authorization. Default false so the module stays
+// hidden until octo-docs-backend is live and the admin flips docs.enabled for a
+// controlled rollout. Value source: system_setting docs.enabled (DB, hot-reloaded).
+func (s *SystemSettings) DocsEnabled() bool {
+	return s.getBool("docs", "enabled", false)
+}

modules/common/system_settings_test.go

@@ -682,3 +682,17 @@ func TestSystemSettings_StickerCustomEnabled_DBTrueWins(t *testing.T) {
 
 	assert.True(t, s.StickerCustomEnabled(), "DB true -> custom sticker management enabled")
 }
+
+func TestSystemSettings_DocsEnabled_DefaultsFalse(t *testing.T) {
+	s := newTestSystemSettings(t, nil)
+
+	assert.False(t, s.DocsEnabled(), "DB empty -> docs module hidden by default")
+}
+
+func TestSystemSettings_DocsEnabled_DBTrueWins(t *testing.T) {
+	s := newTestSystemSettings(t, nil)
+	require.NoError(t, s.db.upsert("docs", "enabled", "1", settingTypeBool, ""))
+	require.NoError(t, s.Reload())
+
+	assert.True(t, s.DocsEnabled(), "DB true -> docs module shown")
+}