nx-sk 0.9.2 → 0.10.0

package/src/modules/settings/view.jsx

@@ -1,23 +1,33 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { api } from '../../web/frontend/api/client.js';
 import { useStore } from '../../web/frontend/store.jsx';
 import { CliHints, Copyable, Empty, Tag } from '../../web/frontend/components/ui.jsx';
+import * as nav from '../../web/frontend/components/navModel.js';
+import NavManager from './navManager.jsx';
 
 export default function SettingsView() {
   const { boot, reload, toast, guard } = useStore();
   const [data, setData] = useState(null);
   const [form, setForm] = useState(null);
-  const [groups, setGroups] = useState([]);
+  const [navCfg, setNavCfg] = useState(nav.emptyConfig());
+  // 保存后的基准：脏值判断与「放弃改动」都以它为准，不靠逐项对比
+  const [baseline, setBaseline] = useState(null);
   // 面板地址不写死：直接取用户此刻访问的这个 origin，换端口/换 host 都自动跟上
   const panelUrl = typeof window === 'undefined' ? '' : window.location.origin;
   const panelPort = typeof window === 'undefined' ? '' : (window.location.port || '80');
 
+  const sections = useMemo(() => data?.sections || [], [data]);
+  const sectionIds = useMemo(() => sections.map((s) => s.id), [sections]);
+
   const load = useCallback(async () => {
     try {
       const d = await api('/api/settings');
+      const nextForm = { ...d.settings };
+      const nextNav = nav.configFromSettings(d.settings);
       setData(d);
-      setForm({ ...d.settings });
-      setGroups((d.settings.navGroups || []).map((g) => ({ title: g.title, sections: [...g.sections] })));
+      setForm(nextForm);
+      setNavCfg(nextNav);
+      setBaseline({ form: nextForm, navCfg: nextNav });
     } catch (e) {
       toast(e.message, 'bad');
     }
@@ -25,63 +35,40 @@ export default function SettingsView() {
 
   useEffect(() => { load(); }, [load]);
 
+  const problems = useMemo(() => (form ? nav.validate(navCfg, sectionIds) : []), [navCfg, sectionIds, form]);
+  const dirty = !!baseline && (nav.isDirty(navCfg, baseline.navCfg) || nav.isDirty(form, baseline.form));
+
+  // 一次保存全部设置：标量项 + 导航（分组 / 隐藏）。分成两块各存各的，
+  // 用户就得记住「刚才那块存了没」——统一保存 + 统一的脏值提示才是清晰的。
   const save = guard(async () => {
-    // 必须包在 `set` 里发：HTTP 的 body 会经 applySpec **只保留声明过的键**，
-    // 平铺的 `{exportDir: …}` 会被静默丢掉 → service 收到空 patch 报「至少要给一项」。
-    // `set` 是 setting.set 声明过的 kv flag，HTTP 形态就是 `{set: {k: v}}`。
-    const body = {
-      set: {
-        exportDir: form.exportDir,
-        exportFormat: form.exportFormat,
-        includeSecretsInExport: !!form.includeSecretsInExport,
-        defaultSection: form.defaultSection,
+    if (problems.length) { toast(`保存失败：${problems[0].message}`, 'bad'); return; }
+    const r = await api('/api/settings', {
+      method: 'PATCH',
+      body: {
+        set: {
+          exportDir: form.exportDir,
+          exportFormat: form.exportFormat,
+          includeSecretsInExport: !!form.includeSecretsInExport,
+          defaultSection: form.defaultSection,
+          ...nav.configToPayload(navCfg),
+        },
       },
-    };
-    const r = await api('/api/settings', { method: 'PATCH', body });
-    toast('设置已保存');
+    });
+    const nextForm = { ...r.set };
+    const nextNav = nav.configFromSettings(r.set);
     setData({ ...data, settings: r.set });
+    setForm(nextForm);
+    setNavCfg(nextNav);
+    setBaseline({ form: nextForm, navCfg: nextNav });
+    toast('设置已保存');
     await reload();
   });
 
-  // 头部导航分组：组顺序 = 头部显示顺序；组内栏目顺序 = 展开列表里的顺序（可上下移）
-  const patchGroup = (gi, patch) => setGroups((gs) => gs.map((g, i) => (i === gi ? { ...g, ...patch } : g)));
-
-  const addMember = (gi, sid) => setGroups((gs) => gs.map((g, i) => (
-    i === gi && !g.sections.includes(sid) ? { ...g, sections: [...g.sections, sid] } : g
-  )));
-
-  const removeMember = (gi, sid) => setGroups((gs) => gs.map((g, i) => (
-    i === gi ? { ...g, sections: g.sections.filter((x) => x !== sid) } : g
-  )));
-
-  const moveMember = (gi, si, delta) => setGroups((gs) => gs.map((g, i) => {
-    if (i !== gi) return g;
-    const to = si + delta;
-    if (to < 0 || to >= g.sections.length) return g;
-    const next = [...g.sections];
-    [next[si], next[to]] = [next[to], next[si]];
-    return { ...g, sections: next };
-  }));
-
-  const moveGroup = (gi, delta) => setGroups((gs) => {
-    const to = gi + delta;
-    if (to < 0 || to >= gs.length) return gs;
-    const next = [...gs];
-    [next[gi], next[to]] = [next[to], next[gi]];
-    return next;
-  });
-
-  const saveGroups = guard(async () => {
-    const naked = groups.find((g) => !String(g.title).trim());
-    if (naked) { toast('每个分组都要有组名', 'bad'); return; }
-    const empty = groups.find((g) => !g.sections.length);
-    if (empty) { toast(`分组「${empty.title}」还没有勾选栏目——要么勾一个，要么删掉这个分组`, 'bad'); return; }
-    const r = await api('/api/settings', { method: 'PATCH', body: { set: { navGroups: groups } } });
-    toast(groups.length ? `已保存 ${groups.length} 个导航分组` : '已取消分组，栏目恢复平铺');
-    setData({ ...data, settings: r.set });
-    setGroups((r.set.navGroups || []).map((g) => ({ title: g.title, sections: [...g.sections] })));
-    await reload();
-  });
+  const discard = () => {
+    if (!baseline) return;
+    setForm({ ...baseline.form });
+    setNavCfg(structuredClone(baseline.navCfg));
+  };
 
   if (!data || !form) return <div className="pad muted">加载中…</div>;
 
@@ -91,116 +78,35 @@ export default function SettingsView() {
         <strong>设置</strong>
         <span className="muted">本机配置与运行状态</span>
         <span className="grow" />
+        {dirty ? (
+          <span className="rowgap">
+            <span className="tag">有未保存的改动</span>
+            <button className="btn small" onClick={() => { void save(); }}>保存</button>
+            <button className="btn small ghost" onClick={discard}>放弃改动</button>
+          </span>
+        ) : <span className="muted">已保存</span>}
         <button className="btn small ghost" onClick={load}>重新读取</button>
       </div>
 
-      <div className="card">
-        <div className="colhead">存储与运行</div>
-        <div className="colbody">
-          <InfoRow label="数据目录" value={boot?.home} copy={boot?.home} />
-          <InfoRow label="store.json" value={boot?.storePath} copy={boot?.storePathRaw} />
-          <InfoRow label="栏目 / 条目" value={boot ? `${boot.counts.sections} / ${boot.counts.entries}` : ''} />
-          <InfoRow label="命令条数" value={boot ? String(boot.counts.commands) : ''} />
-          <InfoRow label="app / node" value={boot ? `v${boot.app.version} · node ${boot.app.node} · ${boot.app.platform}` : ''} />
-          <InfoRow
-            label="环境变量覆盖"
-            value={boot ? Object.entries(boot.envOverrides).filter(([, v]) => v).map(([k, v]) => `${k}=${v}`).join('　') || '（无）' : ''}
-          />
-        </div>
-      </div>
-
-      <div className="card">
-        <div className="colhead">密钥（密文落盘）</div>
-        <div className="colbody">
-          <InfoRow label="密钥来源" value={boot?.vault?.source === 'env' ? '环境变量 NX_SK_PASSPHRASE（口令不落盘）' : '本机密钥文件'} />
-          <InfoRow label="密钥文件" value={boot?.vault?.keyFile || boot?.vault?.saltFile || ''} copy={boot?.vault?.keyFile || boot?.vault?.saltFile} />
-          <div className="row">
-            <span className="desc">{boot?.vault?.note}</span>
-          </div>
-          <div className="row">
-            <span className="desc bad">删掉密钥文件或换掉口令后，已存的密文都解不开了——导出前先确认密钥可用。</span>
-          </div>
-        </div>
-      </div>
-
-      <div className="card">
-        <div className="colhead">面板与 CLI</div>
-        <div className="colbody">
-          <div className="row">
-            <span className="name">面板地址</span>
-            <span className="desc mono">{panelUrl}</span>
-            <span className="acts"><Copyable className="mono" text={panelUrl}>复制</Copyable></span>
-          </div>
-          <div className="row">
-            <span className="name">重启面板</span>
-            <span className="desc">面板本身就是 serve 提供的；改代码后重启它即可</span>
-            <span className="acts"><Copyable className="mono" text={`nx-sk serve --port ${panelPort}`}>{`nx-sk serve --port ${panelPort}`}</Copyable></span>
-          </div>
-        </div>
-      </div>
-
       <div className="card">
         <div className="colhead">
-          头部导航分组
-          <span className="right muted">{groups.length ? `${groups.length} 个分组` : '未分组（全部平铺）'}</span>
+          栏目管理
+          <span className="right muted">
+            头部显示 {sectionIds.length - navCfg.hidden.length} 个 · 隐藏 {navCfg.hidden.length} 个
+            {navCfg.groups.length ? ` · ${navCfg.groups.length} 个分组` : ''}
+          </span>
         </div>
         <div className="pad stack">
           <div className="hint">
-            把同域栏目收拢成一个头部入口：头部只显示组名，悬浮展开上下列表选具体栏目，
-            <b>列表顺序就是这里的顺序</b>（用上移 / 下移调）。不归组的栏目保持平铺；
-            组顺序 = 头部显示顺序；一个栏目只能属于一个分组。
-          </div>
-          {groups.map((g, gi) => {
-            const taken = new Set(groups.flatMap((o, oi) => (oi === gi ? [] : o.sections)));
-            const available = (boot?.sections || []).filter((s) => !g.sections.includes(s.id) && !taken.has(s.id));
-            const byId = (sid) => (boot?.sections || []).find((s) => s.id === sid) || null;
-            return (
-              <div className="stack" key={gi} style={{ borderTop: gi ? 'var(--border)' : 0, paddingTop: gi ? 8 : 0 }}>
-                <div className="rowgap">
-                  <input
-                    value={g.title}
-                    placeholder="组名，如「求职」"
-                    onChange={(e) => patchGroup(gi, { title: e.target.value })}
-                    style={{ minWidth: 160 }}
-                  />
-                  <button className="btn small ghost" disabled={gi === 0} onClick={() => moveGroup(gi, -1)}>上移</button>
-                  <button className="btn small ghost" disabled={gi === groups.length - 1} onClick={() => moveGroup(gi, 1)}>下移</button>
-                  <button className="btn small ghost" onClick={() => setGroups((gs) => gs.filter((_, i) => i !== gi))}>删除组</button>
-                  <span className="muted">已选 {g.sections.length} 个栏目</span>
-                </div>
-                <div className="colbody">
-                  {g.sections.length ? g.sections.map((sid, si) => {
-                    const s = byId(sid);
-                    return (
-                      <div className="row" key={sid}>
-                        <span className="mono muted">{si + 1}</span>
-                        <span className={`name ${s ? '' : 'bad'}`}>{s ? s.title : `栏目已删除（${sid}）`}</span>
-                        <span className="desc">{s ? `${s.entries} 条` : '保存前请移除'}</span>
-                        <span className="acts">
-                          <button className="btn small ghost" disabled={si === 0} onClick={() => moveMember(gi, si, -1)}>上移</button>
-                          <button className="btn small ghost" disabled={si === g.sections.length - 1} onClick={() => moveMember(gi, si, 1)}>下移</button>
-                          <button className="btn small ghost" onClick={() => removeMember(gi, sid)}>移除</button>
-                        </span>
-                      </div>
-                    );
-                  }) : <div className="muted">这个分组还没有栏目——从下面点一个加进来。</div>}
-                </div>
-                <div className="rowgap">
-                  {available.length ? available.map((s) => (
-                    <button className="btn small ghost" key={s.id} onClick={() => addMember(gi, s.id)}>
-                      + {s.title}<span className="count"> {s.entries}</span>
-                    </button>
-                  )) : <span className="muted">所有栏目都已归组</span>}
-                </div>
-              </div>
-            );
-          })}
-          {!groups.length ? <div className="muted">还没有分组——所有栏目都平铺在头部。</div> : null}
-          <div className="rowgap">
-            <button className="btn" onClick={saveGroups}>保存分组</button>
-            <button className="btn small ghost" onClick={() => setGroups((gs) => [...gs, { title: '', sections: [] }])}>新增分组</button>
-            {groups.length ? <button className="btn small ghost" onClick={() => setGroups([])}>清空（恢复平铺）</button> : null}
+            拖动就是把结构摆成你要的样子：栏目可以拖进分组、组内换位、拖回平铺区即移出；拖分组把手换分组顺序。
+            被隐藏的栏目只是头部不显示入口，用 <code>#/栏目id</code> 直达仍可用。
           </div>
+          <NavManager sections={sections} value={navCfg} onChange={setNavCfg} />
+          {problems.length ? (
+            <div className="stack">
+              {problems.map((p) => <div key={p.field} className="hint bad">· {p.message}</div>)}
+            </div>
+          ) : null}
         </div>
       </div>
 
@@ -236,8 +142,50 @@ export default function SettingsView() {
               </div>
             </div>
           </div>
-          <div className="rowgap" style={{ marginTop: 8 }}>
-            <button className="btn" onClick={save}>保存设置</button>
+        </div>
+      </div>
+
+      <div className="card">
+        <div className="colhead">存储与运行</div>
+        <div className="colbody">
+          <InfoRow label="数据目录" value={boot?.home} copy={boot?.home} />
+          <InfoRow label="store.json" value={boot?.storePath} copy={boot?.storePathRaw} />
+          <InfoRow label="栏目 / 条目" value={boot ? `${boot.counts.sections} / ${boot.counts.entries}` : ''} />
+          <InfoRow label="命令条数" value={boot ? String(boot.counts.commands) : ''} />
+          <InfoRow label="app / node" value={boot ? `v${boot.app.version} · node ${boot.app.node} · ${boot.app.platform}` : ''} />
+          <InfoRow
+            label="环境变量覆盖"
+            value={boot ? Object.entries(boot.envOverrides).filter(([, v]) => v).map(([k, v]) => `${k}=${v}`).join('　') || '（无）' : ''}
+          />
+        </div>
+      </div>
+
+      <div className="card">
+        <div className="colhead">密钥（密文落盘）</div>
+        <div className="colbody">
+          <InfoRow label="密钥来源" value={boot?.vault?.source === 'env' ? '环境变量 NX_SK_PASSPHRASE（口令不落盘）' : '本机密钥文件'} />
+          <InfoRow label="密钥文件" value={boot?.vault?.keyFile || boot?.vault?.saltFile || ''} copy={boot?.vault?.keyFile || boot?.vault?.saltFile} />
+          <div className="row">
+            <span className="desc">{boot?.vault?.note}</span>
+          </div>
+          <div className="row">
+            <span className="desc bad">删掉密钥文件或换掉口令后，已存的密文都解不开了——导出前先确认密钥可用。</span>
+          </div>
+        </div>
+      </div>
+
+      <div className="card">
+        <div className="colhead">面板与 CLI</div>
+        <div className="colbody">
+          <div className="row">
+            <span className="name">面板地址</span>
+            <span className="desc mono">{panelUrl}</span>
+            <span className="acts"><Copyable className="mono" text={panelUrl}>复制</Copyable></span>
+          </div>
+          <div className="row">
+            <span className="name">重启面板</span>
+            <span className="desc">面板本身就是 serve 提供的；改代码后重启它即可</span>
+            <span className="acts"><Copyable className="mono" text={`nx-sk serve --port ${panelPort}`}>{`nx-sk serve --port ${panelPort}`}</Copyable></span>
           </div>
         </div>
       </div>

package/src/web/frontend/App.jsx

@@ -17,28 +17,38 @@ export default function App() {
   const { boot, bootError, ui, patchUi, reload } = useStore();
   const view = LEGACY_VIEW[ui.view] || ui.view;
 
-  // 栏目 tab 是**数据驱动**的（bootstrap.sections）；分组来自 settings.navGroups（设置页可配）；
+  // 栏目 tab 是**数据驱动**的（bootstrap.sections）；分组与隐藏来自 settings（设置页可配）；
   // 静态 tab 来自前端注册表。渲染顺序：未分组栏目（按 order）→ 分组（按配置顺序）→ 工具（按 order）。
   const nav = useMemo(() => {
-    const sections = (boot?.sections || []).map((s) => ({
+    const all = (boot?.sections || []).map((s) => ({
       id: s.id, title: s.title, order: s.order, kind: 'section', count: s.entries,
     }));
-    // 分组是**显示配置**：成员栏目被删掉时优雅降级（过滤掉、配置保留），成员全没了就不显示这个组
+    // 隐藏**只隐藏入口**：`#/栏目id` 直达仍然渲染，所以 all 里保留全部栏目
+    const hidden = new Set(boot?.settings?.navHidden || []);
+    const visible = all.filter((s) => !hidden.has(s.id));
+
+    // 分组是**显示配置**：成员栏目被删掉时优雅降级（过滤掉、配置保留），成员全没了就不显示这个组；
+    // 被隐藏的成员在入口里同样不出现
     const groups = (boot?.settings?.navGroups || [])
       .map((g) => ({
         title: g.title,
         sections: (g.sections || [])
-          .map((sid) => sections.find((s) => s.id === sid))
+          .map((sid) => visible.find((s) => s.id === sid))
           .filter(Boolean),
       }))
       .filter((g) => g.sections.length);
     const grouped = new Set(groups.flatMap((g) => g.sections.map((s) => s.id)));
-    const flat = sections.filter((s) => !grouped.has(s.id)).sort((a, b) => (a.order ?? 50) - (b.order ?? 50));
+    // 平铺顺序：settings.navOrder 里显式排过的优先（按它的次序），其余按栏目自己的 order 跟在后面
+    const rank = new Map((boot?.settings?.navOrder || []).map((id, i) => [id, i]));
+    const rankOf = (s) => (rank.has(s.id) ? rank.get(s.id) : Number.MAX_SAFE_INTEGER);
+    const flat = visible.filter((s) => !grouped.has(s.id))
+      .sort((a, b) => rankOf(a) - rankOf(b) || (a.order ?? 50) - (b.order ?? 50));
     const stat = VIEWS.filter((v) => v.tab !== false)
       .map((v) => ({ id: v.id, title: v.title, order: v.order, kind: 'view', component: v.component }))
-      .filter((v) => !sections.some((s) => s.id === v.id))
+      .filter((v) => !all.some((s) => s.id === v.id))
       .sort((a, b) => (a.order ?? 50) - (b.order ?? 50));
-    return { flat, groups, tools: stat, all: [...flat, ...groups.flatMap((g) => g.sections), ...stat] };
+    const hiddenItems = all.filter((s) => hidden.has(s.id));
+    return { flat, groups, tools: stat, all: [...flat, ...groups.flatMap((g) => g.sections), ...stat, ...hiddenItems] };
   }, [boot]);
 
   // 没 boot 之前**不要**拿第一个 tab 兜底：那时动态栏目还没到，nav 里只有静态视图，

package/src/web/frontend/components/navModel.js

@@ -0,0 +1,226 @@
+// 头部导航配置的**纯模型**：分组 + 隐藏。零 React、零 IO，可单测。
+//
+// 为什么单独一层：这块的逻辑（增删改、排序、可用性、校验）比渲染多得多，
+// 混在 JSX 里既说不清也测不了。表现层只管画，动手改数据一律走这里——
+// 于是「管理逻辑」只有一份，前端拦一道、后端（settings service）再拦一道，两边同口径。
+//
+// 配置形状（与 settings.navGroups / navHidden / navOrder 一一对应）：
+//   { groups: [{ title, sections: [栏目id…] }], hidden: [栏目id…], order: [栏目id…] }
+// 组顺序 = 头部显示顺序；组内顺序 = 展开列表顺序；hidden = 入口不显示（直达仍可用）；
+// order = **平铺区的显示顺序**（没列进去的栏目按栏目自己的 order 跟在后面）。
+
+export const emptyConfig = () => ({ groups: [], hidden: [], order: [] });
+
+/** 从后端 settings 取一份**工作副本**（深拷贝，编辑不污染原数据）。 */
+export function configFromSettings(settings) {
+  return {
+    groups: (settings?.navGroups || []).map((g) => ({ title: String(g.title || ''), sections: [...(g.sections || [])] })),
+    hidden: [...(settings?.navHidden || [])],
+    order: [...(settings?.navOrder || [])],
+  };
+}
+
+/** 保存时发出去的形状（只带这两个键，其他设置项各自负责）。 */
+export function configToPayload(cfg) {
+  return {
+    navGroups: cfg.groups.map((g) => ({ title: g.title.trim(), sections: [...g.sections] })),
+    navHidden: [...cfg.hidden],
+    navOrder: [...(cfg.order || [])],
+  };
+}
+
+export const isDirty = (a, b) => JSON.stringify(a) !== JSON.stringify(b);
+
+// —— 分组：增删改 + 排序 ——
+
+export const addGroup = (cfg, title = '') => ({ ...cfg, groups: [...cfg.groups, { title, sections: [] }] });
+
+export const removeGroup = (cfg, gi) => ({ ...cfg, groups: cfg.groups.filter((_, i) => i !== gi) });
+
+export const renameGroup = (cfg, gi, title) => ({
+  ...cfg,
+  groups: cfg.groups.map((g, i) => (i === gi ? { ...g, title } : g)),
+});
+
+/** 上移 / 下移一个分组（delta = ±1）；越界原样返回。 */
+export const moveGroup = (cfg, gi, delta) => {
+  const to = gi + delta;
+  if (to < 0 || to >= cfg.groups.length) return cfg;
+  const groups = [...cfg.groups];
+  [groups[gi], groups[to]] = [groups[to], groups[gi]];
+  return { ...cfg, groups };
+};
+
+// —— 组成员：加入 / 移除 / 排序 ——
+
+/** 把栏目加进某个分组（已在该组或别的组里则原样返回）。 */
+export function addSection(cfg, gi, sid) {
+  const target = cfg.groups[gi];
+  if (!target || target.sections.includes(sid)) return cfg;
+  if (cfg.groups.some((g) => g.sections.includes(sid))) return cfg; // 一个栏目只能属于一个分组
+  return { ...cfg, groups: cfg.groups.map((g, i) => (i === gi ? { ...g, sections: [...g.sections, sid] } : g)) };
+}
+
+export const removeSection = (cfg, gi, sid) => ({
+  ...cfg,
+  groups: cfg.groups.map((g, i) => (i === gi ? { ...g, sections: g.sections.filter((x) => x !== sid) } : g)),
+});
+
+export const moveSection = (cfg, gi, si, delta) => {
+  const g = cfg.groups[gi];
+  const to = si + delta;
+  if (!g || to < 0 || to >= g.sections.length) return cfg;
+  const sections = [...g.sections];
+  [sections[si], sections[to]] = [sections[to], sections[si]];
+  return { ...cfg, groups: cfg.groups.map((x, i) => (i === gi ? { ...g, sections } : x)) };
+};
+
+/**
+ * 把栏目放到指定分组的指定位置（拖拽编排的主力原语）。
+ * `index === null` 表示追加到末尾；越界按边界处理。
+ * 来源可以是别的分组、也可以是「未归组」——两种情况都先摘掉再插入，
+ * 所以「拖动即等于移动」，不会出现同一栏目短暂存在两份。
+ */
+export function moveSectionTo(cfg, sid, gi, index = null) {
+  return moveToContainer(cfg, sid, { kind: 'group', gi }, index);
+}
+
+/**
+ * **容器**是这块的统一心智模型：一个栏目要么在「平铺」里、要么在某个分组里、要么在「隐藏」里。
+ * `{kind:'pool'} | {kind:'group', gi} | {kind:'hidden'}` —— 拖拽就是把栏目从一个容器挪到另一个。
+ */
+/**
+ * 栏目现在在哪个容器里，以及在该容器里的位置（拖拽预览要用它做索引换算）。
+ * 三种容器都有位置：平铺区的位置来自 order（没排过的按栏目 order 排），分组与隐藏各自是数组。
+ */
+export function containerOf(cfg, sid, allIds = []) {
+  if (cfg.hidden.includes(sid)) return { kind: 'hidden', index: cfg.hidden.indexOf(sid) };
+  const gi = cfg.groups.findIndex((g) => g.sections.includes(sid));
+  if (gi >= 0) return { kind: 'group', gi, index: cfg.groups[gi].sections.indexOf(sid) };
+  return { kind: 'pool', index: poolOrder(cfg, allIds).indexOf(sid) };
+}
+
+/**
+ * 平铺区的显示顺序：`order` 里显式排过的优先（按它的次序），
+ * 没排过的新栏目按传入的栏目顺序（= 栏目自己的 order）跟在后面。
+ * 于是「从没拖过」= 纯栏目 order（老行为不变），拖过之后以拖的为准。
+ */
+export function poolOrder(cfg, allIds) {
+  const ranked = (cfg.order || []).filter((id) => allIds.includes(id));
+  const rest = allIds.filter((id) => !ranked.includes(id));
+  return [...ranked, ...rest];
+}
+
+/**
+ * 悬停行索引 → 真正的插入位。
+ * 落点语义是「插到悬停行**之前**」，但被拖走的自身会让位：
+ * 同容器内往下拖时悬停行索引要减 1，否则实时预览会比实际落点差一格。
+ * `hoveredIndex === null` 表示拖在容器空白处 = 追加到末尾，原样返回。
+ */
+export function insertionIndex(cfg, sid, target, hoveredIndex, allIds = []) {
+  if (hoveredIndex === null || hoveredIndex === undefined) return null;
+  const from = containerOf(cfg, sid, allIds);
+  const sameContainer = target.kind === from.kind && (target.kind !== 'group' || target.gi === from.gi);
+  if (sameContainer && typeof from.index === 'number' && from.index < hoveredIndex) return hoveredIndex - 1;
+  return hoveredIndex;
+}
+
+/** 把栏目挪进目标容器（index = 在该容器里的插入位，null = 末尾）。 */
+export function moveToContainer(cfg, sid, target, index = null, allIds = []) {
+  // 先从所有容器里摘掉（分组 + 隐藏 + 平铺顺序），再放进目标——「移动」永远只落一处
+  const groups = cfg.groups.map((g) => ({ ...g, sections: g.sections.filter((x) => x !== sid) }));
+  const hidden = cfg.hidden.filter((x) => x !== sid);
+  const base = { ...cfg, groups, hidden, order: (cfg.order || []).filter((x) => x !== sid) };
+
+  if (target.kind === 'hidden') return { ...base, hidden: [...hidden, sid] };
+
+  if (target.kind === 'pool') {
+    // 平铺区的顺序就是 order：先算出「去掉自己之后」的序列，再插到目标位
+    const isPool = (id) => !groups.some((g) => g.sections.includes(id)) && !hidden.includes(id);
+    const seq = poolOrder(base, allIds).filter((id) => id !== sid && isPool(id));
+    const at = index === null ? seq.length : Math.max(0, Math.min(index, seq.length));
+    return { ...base, order: [...seq.slice(0, at), sid, ...seq.slice(at)] };
+  }
+
+  const gi = target.gi;
+  const cur = groups[gi];
+  if (!cur) return cfg;
+  const at = index === null ? cur.sections.length : Math.max(0, Math.min(index, cur.sections.length));
+  const sections = [...cur.sections.slice(0, at), sid, ...cur.sections.slice(at)];
+  return { ...base, groups: groups.map((g, i) => (i === gi ? { ...cur, sections } : g)) };
+}
+
+/** 把栏目移出分组（回到头部的平铺区）。 */
+export const ungroupSection = (cfg, sid) => moveToContainer(cfg, sid, { kind: 'pool' });
+
+/** 分组内相邻交换（键盘/触摸的兜底路径，拖拽之外的退路）。 */
+export const swapSection = (cfg, gi, i, j) => {
+  const g = cfg.groups[gi];
+  if (!g || i === j || i < 0 || j < 0 || i >= g.sections.length || j >= g.sections.length) return cfg;
+  const sections = [...g.sections];
+  [sections[i], sections[j]] = [sections[j], sections[i]];
+  return { ...cfg, groups: cfg.groups.map((x, k) => (k === gi ? { ...g, sections } : x)) };
+};
+
+// —— 隐藏：入口显不显示 ——
+
+export const toggleHidden = (cfg, sid) => ({
+  ...cfg,
+  hidden: cfg.hidden.includes(sid) ? cfg.hidden.filter((x) => x !== sid) : [...cfg.hidden, sid],
+});
+
+export const isHidden = (cfg, sid) => cfg.hidden.includes(sid);
+
+// —— 派生 ——
+
+export const groupedIds = (cfg) => cfg.groups.flatMap((g) => g.sections);
+
+/** 「平铺」容器里的栏目（既不在分组里、也没被隐藏），按平铺顺序。 */
+export const ungroupedIds = (cfg, allIds) => {
+  const skip = new Set([...groupedIds(cfg), ...cfg.hidden]);
+  return poolOrder(cfg, allIds).filter((id) => !skip.has(id));
+};
+
+/** 某个分组**还能**加入哪些栏目：不在本组、也不在别的组。 */
+export function availableFor(cfg, gi, allIds) {
+  const target = cfg.groups[gi];
+  if (!target) return [];
+  const others = new Set(cfg.groups.flatMap((g, i) => (i === gi ? [] : g.sections)));
+  return allIds.filter((id) => !target.sections.includes(id) && !others.has(id));
+}
+
+/**
+ * 前端先拦一道（后端 settings service 用同一套口径再拦一次）。
+ * 返回 [{ field, message }]，空数组 = 可以保存。
+ */
+export function validate(cfg, allIds) {
+  const known = new Set(allIds);
+  const problems = [];
+  const owner = new Map();
+
+  cfg.groups.forEach((g, i) => {
+    const label = g.title.trim() || `第 ${i + 1} 个分组`;
+    if (!g.title.trim()) problems.push({ field: `groups.${i}.title`, message: `${label}：每个分组都要有组名` });
+    if (!g.sections.length) problems.push({ field: `groups.${i}.sections`, message: `${label}：还没有栏目——加一个，或删掉这个分组` });
+    for (const sid of g.sections) {
+      if (!known.has(sid)) {
+        problems.push({ field: `groups.${i}.sections.${sid}`, message: `${label}：栏目 ${sid} 已不存在，请移除` });
+        continue;
+      }
+      const prev = owner.get(sid);
+      if (prev !== undefined) {
+        problems.push({ field: `groups.${i}.sections.${sid}`, message: `栏目 ${sid} 同时出现在「${prev}」与「${label}」里——一个栏目只能属于一个分组` });
+        continue;
+      }
+      owner.set(sid, label);
+    }
+  });
+
+  for (const sid of cfg.hidden) {
+    if (!known.has(sid)) problems.push({ field: `hidden.${sid}`, message: `要隐藏的栏目 ${sid} 已不存在` });
+  }
+  for (const sid of cfg.order || []) {
+    if (!known.has(sid)) problems.push({ field: `order.${sid}`, message: `平铺顺序里的栏目 ${sid} 已不存在` });
+  }
+  return problems;
+}

package/src/web/frontend/styles.css

@@ -435,3 +435,44 @@ a.file-name:hover { text-decoration: underline; }
   min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
 }
 .file-preview .file-preview-name:hover { text-decoration: underline; }
+
+/* ── 栏目管理（设置页）：拖拽编排 + 显隐 ─────────────────────
+   结构用版面表达、改结构用拖拽表达——所以这里只有把手、输入框与两个动作，
+   没有一排 上移/下移/移除 按钮（按钮越多越看不出「现在是什么结构」）。 */
+.grip {
+  width: 10px;
+  height: 14px;
+  flex: 0 0 auto;
+  cursor: grab;
+  background-image: radial-gradient(circle, var(--mid) 1px, transparent 1px);
+  background-size: 4px 4px;
+  opacity: .5;
+}
+.grip:active { cursor: grabbing; }
+.nav-title {
+  font: inherit;
+  font-size: var(--fs-core);
+  font-weight: 600;
+  min-width: 12ch;
+  padding: 2px 0;
+  background: none;
+  border: 0;
+  border-bottom: 1px dashed var(--soft-2);
+}
+.nav-title:focus { outline: none; border-bottom-color: var(--ink); }
+.nav-group .colhead { display: flex; align-items: center; gap: 8px; }
+.nav-pool { padding: 8px 10px; background: var(--paper); border: var(--border); border-radius: 8px; }
+/* 拖拽落点：一眼看出「松手会放到这儿」 */
+.nav-pool.drop-target, .nav-group.drop-target { outline: 2px dashed var(--ink); outline-offset: -2px; background: var(--soft); }
+.nav-row.dragging { opacity: .45; }
+/* 落点表达交给实时预览本身：被拖的行已停在新位置（.dragging 半透明），
+   再叠一条"悬停行高亮"反而会和预览里的位置对不上（索引不同源）。 */
+.nav-row.is-hidden .name { color: var(--mid); }
+
+/* 容器内的行列表：行本身已有 1px 底线，这里只做包裹 */
+.nav-list { display: flex; flex-direction: column; }
+/* 拖动分组时的落点提示（分组头也可以是落点：换顺序） */
+.nav-group .colhead.drop-target { background: var(--soft); }
+/* 「隐藏」与分组同构，只是语气更弱：它是"不显示"的容器 */
+.nav-hidden .colhead { color: var(--mid); }
+.nav-hidden .row .name { color: var(--mid); }

package/src/web/public/assets/{files-CJbQeKB4.js → files-CKVPmP4G.js}

@@ -1 +1 @@
-import{a as l}from"./index-VCOWbzUk.js";let r=null;function o(n=!1){return!n&&r||(r=l("/api/files").then(e=>e).catch(e=>{throw r=null,e})),r}function i(){return r=null,o(!0)}function u(n){return new Promise((e,a)=>{const t=new FileReader;t.onload=()=>e(t.result),t.onerror=()=>a(new Error("读取文件失败")),t.readAsDataURL(n)})}export{u as f,o as l,i as r};
+import{a as l}from"./index-kQO8dtPe.js";let r=null;function o(n=!1){return!n&&r||(r=l("/api/files").then(e=>e).catch(e=>{throw r=null,e})),r}function i(){return r=null,o(!0)}function u(n){return new Promise((e,a)=>{const t=new FileReader;t.onload=()=>e(t.result),t.onerror=()=>a(new Error("读取文件失败")),t.readAsDataURL(n)})}export{u as f,o as l,i as r};