nx-sk 0.3.4 → 0.6.0

package/src/modules/files/service.js

@@ -0,0 +1,276 @@
+// 附件（file）：统一附件库的业务编排。物理文件操作在 core/attachments.js，
+// 台账（store.files）的读写走 store.js——和 entries 一样的「两趟」结构：
+// 先在事务外完成文件移动/复制，再在 mutateStore 事务里改台账。
+import { loadStore, mutateStore, snapshotStore } from '../../core/store.js';
+import { displayPath, filesDir } from '../../core/paths.js';
+import { badInput, external, notFound } from '../../core/errors.js';
+import { nowIso } from '../../core/ids.js';
+import { openPath } from '../../core/open.js';
+import {
+  CATEGORY_IDS, collectFileSections, describeFile, fileReferences,
+  deletePhysical, fileRecordAbs, findFileRecord, importContent, importLocalFile,
+  relocateFile, restoreFile, streamRecord,
+} from '../../core/attachments.js';
+
+function mustFind(store, ref) {
+  const r = findFileRecord(store, ref);
+  if (!r) throw notFound(`找不到附件: ${ref}（用 'nx-sk file list' 看现有附件）`);
+  return r;
+}
+
+function assertCategory(cat) {
+  if (!cat) return null;
+  if (!CATEGORY_IDS.includes(cat)) {
+    throw badInput(`分类只能是 ${CATEGORY_IDS.join(' / ')}，收到 ${JSON.stringify(cat)}`);
+  }
+  return cat;
+}
+
+/**
+ * 列附件。组织方式**完全由栏目驱动**：`sections` 给出「哪些栏目在引用附件」，
+ * `section` 参数按栏目过滤（`none` = 只列没有任何条目引用的）。不预定义分类/槽位。
+ */
+export async function listFiles({ category, q, section } = {}) {
+  const store = await loadStore();
+  assertCategory(category);
+  const withRefs = store.files.map((rec) => ({ rec, usedBy: fileReferences(store, rec) }));
+  let list = withRefs;
+  if (category) list = list.filter((x) => x.rec.category === category);
+  if (section === 'none' || section === 'unlinked') {
+    list = list.filter((x) => !x.usedBy.length);
+  } else if (section) {
+    const sec = store.sections.find((s) => s.id === section);
+    if (!sec) throw notFound(`找不到栏目: ${section}`);
+    list = list.filter((x) => x.usedBy.some((u) => u.sectionId === sec.id));
+  }
+  if (q) {
+    const needle = String(q).toLowerCase();
+    list = list.filter((x) => [
+      x.rec.name, x.rec.note, x.rec.originalName, ...x.rec.tags,
+      ...x.usedBy.map((u) => `${u.sectionTitle} ${u.entryTitle} ${u.fieldLabel}`),
+    ].join('\n').toLowerCase().includes(needle));
+  }
+  list = list.slice().sort((a, b) => String(b.rec.createdAt || '').localeCompare(String(a.rec.createdAt || '')));
+  let totalBytes = 0;
+  for (const r of store.files) totalBytes += r.bytes;
+  // 分组素材：带 file 字段的栏目（栏目驱动）及其引用数
+  const sections = collectFileSections(store).map((s) => ({
+    ...s, count: withRefs.filter((x) => x.usedBy.some((u) => u.sectionId === s.id)).length,
+  }));
+  return {
+    count: list.length,
+    total: store.files.length,
+    totalBytes,
+    unlinked: withRefs.filter((x) => !x.usedBy.length).length,
+    root: displayPath(filesDir()),
+    rootRaw: filesDir(),
+    sections,
+    files: list.map((x) => describeFile(x.rec, store)),
+  };
+}
+
+export async function getFile(ref) {
+  const store = await loadStore();
+  // 带 store：顺带反查「被哪些条目引用」
+  return describeFile(mustFind(store, ref), store);
+}
+
+export async function addFile(patch = {}) {
+  const dryRun = patch['dry-run'];
+  assertCategory(patch.category);
+  const store = await loadStore();
+
+  let outcome;
+  if (patch.path) {
+    outcome = await importLocalFile(store, {
+      path: patch.path,
+      category: patch.category || undefined,
+      copy: patch.copy === true,
+      tags: patch.tags,
+      note: patch.note,
+      name: patch.name,
+      dryRun,
+    });
+  } else if (patch.content !== undefined) {
+    outcome = await importContent(store, {
+      content: patch.content,
+      name: patch.name,
+      category: patch.category || undefined,
+      tags: patch.tags,
+      note: patch.note,
+      dryRun,
+    });
+  } else {
+    throw badInput('导入附件需要：--path <本机路径>（默认移动，--copy 仅复制），或 Web 上传内容 --content <base64> --name <文件名>');
+  }
+
+  if (outcome.duplicate) {
+    return { status: 'ok', duplicated: true, id: outcome.record.id, ...describeFile(outcome.record) };
+  }
+  if (dryRun) return { status: 'skipped', dryRun: true, wouldAdd: describeFile(outcome.record) };
+
+  await mutateStore((s) => { s.files.push(outcome.record); });
+  return {
+    status: 'ok', created: true, moved: outcome.moved === true,
+    ...describeFile(outcome.record),
+  };
+}
+
+export async function updateFile(ref, patch = {}) {
+  const dryRun = patch['dry-run'];
+  assertCategory(patch.category);
+  const store = await loadStore();
+  const target = mustFind(store, ref);
+
+  const hasPhysicalChange = patch.category !== undefined || patch.name !== undefined;
+  const hasMetaChange = patch.tags !== undefined || patch.note !== undefined;
+  if (!hasPhysicalChange && !hasMetaChange) {
+    throw badInput('没有要改的内容：--name / --category / --tags / --note');
+  }
+  if (dryRun) {
+    return {
+      status: 'skipped', dryRun: true,
+      wouldChange: {
+        category: patch.category ?? target.category, name: patch.name ?? target.name,
+        tags: patch.tags ?? target.tags, note: patch.note ?? target.note,
+      },
+    };
+  }
+
+  const snapshot = await snapshotStore(`file-update-${target.id}`);
+  // 物理文件先改（失败即抛，台账不动）
+  const relocated = hasPhysicalChange
+    ? await relocateFile(store, target, {
+      category: patch.category ?? target.category,
+      name: patch.name ?? target.name,
+    })
+    : target;
+  await mutateStore((s) => {
+    const r = mustFind(s, target.id);
+    r.rel = relocated.rel;
+    r.name = relocated.name;
+    r.category = relocated.category;
+    if (patch.tags !== undefined) r.tags = patch.tags.map(String);
+    if (patch.note !== undefined) r.note = String(patch.note);
+    r.updatedAt = nowIso();
+  });
+  const after = await loadStore();
+  return { status: 'ok', id: target.id, ...describeFile(mustFind(after, target.id)), snapshot };
+}
+
+export async function removeFile(ref, patch = {}) {
+  const dryRun = patch['dry-run'];
+  const store = await loadStore();
+  const target = mustFind(store, ref);
+  if (dryRun) {
+    return { status: 'skipped', dryRun: true, wouldRemove: { id: target.id, name: target.name, category: target.category } };
+  }
+  const snapshot = await snapshotStore(`file-remove-${target.id}`);
+  // 先删物理文件（Windows 上文件被占用会直接抛错，台账保持不变）
+  await deletePhysical(target);
+  await mutateStore((s) => { s.files = s.files.filter((x) => x.id !== target.id); });
+  return { status: 'ok', removed: { id: target.id, name: target.name, category: target.category }, snapshot };
+}
+
+/** CLI 的 file content：给出物理路径与链接（不直接吐二进制，终端里没法看）。 */
+export async function contentInfo(ref, { download } = {}) {
+  const store = await loadStore();
+  return { ...describeFile(mustFind(store, ref)), download: !!download };
+}
+
+/** HTTP 原始流：由 api.js 在 action.raw 时直接委派。 */
+export async function serveRaw(ctx, { res }) {
+  const store = await loadStore();
+  const rec = mustFind(store, ctx.ref);
+  await streamRecord(res, rec, { download: ctx.download === true });
+}
+
+export async function restoreFileAction(ref, patch = {}) {
+  const dryRun = patch['dry-run'];
+  const store = await loadStore();
+  const target = mustFind(store, ref);
+  const exportCopy = patch.copy === true;
+  if (!target.sourcePath && !patch.to && !exportCopy) {
+    throw badInput('这是 Web 上传的附件、没有原始位置：给 --to <目标目录>，或加 --copy 只导出副本');
+  }
+  if (dryRun) {
+    return {
+      status: 'skipped', dryRun: true,
+      wouldRestore: { to: patch.to || (target.sourcePath ? displayPath(target.sourcePath) : ''), copy: exportCopy },
+    };
+  }
+  const snapshot = await snapshotStore(`file-restore-${target.id}`);
+  const r = await restoreFile(store, target, { to: patch.to, copy: exportCopy });
+  if (!exportCopy) {
+    await mutateStore((s) => { s.files = s.files.filter((x) => x.id !== target.id); });
+  }
+  // restored 标记：renderFileChange 靠它区分「还原」与「更新」——
+  // 两者的 payload 都带 path，只看 path 会把 update 误报成还原（旧 bug）。
+  return { status: 'ok', restored: true, exported: exportCopy, kept: r.kept, path: r.path, displayPath: r.displayPath, snapshot };
+}
+
+export async function openFileAction(ref) {
+  const store = await loadStore();
+  const rec = mustFind(store, ref);
+  const ok = await openPath(fileRecordAbs(rec));
+  if (!ok) throw external(`系统拒绝打开: ${rec.name}`);
+  return { status: 'ok', opened: rec.name, path: displayPath(fileRecordAbs(rec)) };
+}
+
+// —— CLI 人读渲染 ——
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function refLabel(u) {
+  return `${u.sectionTitle} / ${u.entryTitle || '（无名）'} / ${u.fieldLabel}`;
+}
+
+export function renderFileList(d) {
+  const lines = [`附件库 ${d.total} 个 · 共 ${fmtBytes(d.totalBytes)} · 目录 ${d.root}`];
+  lines.push(`被条目引用 ${d.total - d.unlinked} / ${d.total}（未引用 ${d.unlinked} 个）`);
+  if (d.sections.length) lines.push(`栏目：${d.sections.map((s) => `${s.title}(${s.count})`).join('　')}`);
+  for (const r of d.files) {
+    lines.push(`  ${r.id}  [${r.categoryLabel}] ${r.name}　${fmtBytes(r.bytes)}`);
+    if (r.usedBy?.length) lines.push(`      被引用: ${r.usedBy.map(refLabel).join('、')}`);
+    if (r.note) lines.push(`      备注: ${r.note}`);
+  }
+  lines.push('', '导入: nx-sk file add --path <文件>（默认移动）　链接: 在栏目条目的 file 字段填本附件 id');
+  return lines.join('\n');
+}
+
+export function renderFileGet(d) {
+  const lines = [
+    `${d.name}（${d.id}）· ${d.categoryLabel} · ${fmtBytes(d.bytes)}`,
+    `路径:   ${d.displayPath}`,
+    `链接:   ${d.url}`,
+  ];
+  if (d.usedBy?.length) lines.push(`被引用: ${d.usedBy.map(refLabel).join('、')}`);
+  else lines.push('被引用: （没有条目引用；在栏目的 file 字段里填本附件 id 即建立链接）');
+  if (d.sourceDisplay) lines.push(`原始:   ${d.sourceDisplay}（${d.mode === 'move' ? '移动导入' : '复制导入'}）`);
+  if (d.tags.length) lines.push(`标签:   ${d.tags.join('、')}`);
+  if (d.note) lines.push(`备注:   ${d.note}`);
+  return lines.join('\n');
+}
+
+export function renderFileChange(d) {
+  if (d.status === 'skipped') return `试运行（未落盘）：${JSON.stringify(d.wouldAdd || d.wouldChange || d.wouldRemove || d.wouldRestore)}`;
+  if (d.removed) return `已删除附件 ${d.removed.name}（${d.removed.id}）\n快照: ${d.snapshot}`;
+  if (d.duplicated) return `库中已有相同文件，未重复存储：${d.name}（${d.id}）`;
+  if (d.created) {
+    return `已导入附件 ${d.name}（${d.id}）· ${d.categoryLabel}${d.moved ? ' · 原件已移入（nx-sk file restore 可还原）' : ''}`;
+  }
+  if (d.restored && d.exported) return `已导出副本到 ${d.displayPath}（库中保留原件）`;
+  if (d.restored) return `已还原到 ${d.displayPath}（台账记录已撤销）${d.snapshot ? `\n快照: ${d.snapshot}` : ''}`;
+  return `已更新附件 ${d.name}（${d.id}）\n快照: ${d.snapshot}`;
+}
+
+export function renderContent(d) {
+  return `${d.name}（${d.id}）\n路径: ${d.displayPath}\n浏览器链接: ${d.url}${d.download ? d.downloadUrl : ''}`;
+}
+
+export function renderOpen(d) {
+  return `已用系统默认程序打开：${d.opened}　${d.path}`;
+}

package/src/modules/files/view.jsx

@@ -0,0 +1,342 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { api } from '../../web/frontend/api/client.js';
+import { fileToDataUrl, refreshAttachments } from '../../web/frontend/api/files.js';
+import { useStore } from '../../web/frontend/store.jsx';
+import { CliHints, Copyable, Empty, Modal, Tag } from '../../web/frontend/components/ui.jsx';
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+const refText = (u) => `${u.sectionTitle} / ${u.entryTitle || '（无名）'} / ${u.fieldLabel}`;
+
+/**
+ * 附件工作台：统一**展示与库存管理**（上传 / 本机路径导入、预览、下载、编辑、还原、删除）。
+ *
+ * 组织方式**完全由栏目驱动**——按「哪些栏目在引用附件」筛选，不预定义任何分类或槽位。
+ * 真正的「上传并挂到某条条目」发生在本栏目条目的 `file` 字段里；这里只是所有原件的总览。
+ */
+export default function FilesView() {
+  const { toast, guard, dialog, reload } = useStore();
+  const [data, setData] = useState(null);
+  const [err, setErr] = useState(null);
+  const [filter, setFilter] = useState(''); // '' 全部 | 'none' 未引用 | <栏目 id>
+  const [q, setQ] = useState('');
+  const [dragOver, setDragOver] = useState(false);
+  const [modal, setModal] = useState(null);
+  const pickerRef = useRef(null);
+  const dragDepth = useRef(0);
+
+  const load = useCallback(async () => {
+    try {
+      const params = new URLSearchParams();
+      if (filter) params.set('section', filter);
+      if (q) params.set('q', q);
+      const qs = params.toString();
+      const d = await api(`/api/files${qs ? `?${qs}` : ''}`);
+      setData(d);
+      setErr(null);
+    } catch (e) {
+      setErr(e.message);
+      setData(null);
+    }
+  }, [filter, q]);
+
+  useEffect(() => { load(); }, [load]);
+
+  const uploadFiles = useCallback(async (fileList) => {
+    const files = Array.from(fileList || []);
+    if (!files.length) return;
+    let ok = 0;
+    for (const file of files) {
+      try {
+        const content = await fileToDataUrl(file);
+        await api('/api/files', { method: 'POST', body: { content, name: file.name } });
+        ok += 1;
+      } catch (e) {
+        toast(`${file.name} 上传失败：${e.message}`, 'bad');
+      }
+    }
+    if (ok) toast(`已导入 ${ok} 个附件（到栏目条目里选它即可链接）`);
+    await refreshAttachments();
+    await load();
+    await reload();
+  }, [load, reload, toast]);
+
+  const onDrop = useCallback((e) => {
+    e.preventDefault();
+    dragDepth.current = 0;
+    setDragOver(false);
+    uploadFiles(e.dataTransfer.files);
+  }, [uploadFiles]);
+
+  const openPathImport = guard(async () => {
+    setModal({ kind: 'path', form: { path: '', copy: false } });
+  });
+
+  const submitPathImport = guard(async (form) => {
+    if (!form.path.trim()) { toast('请填本机文件的绝对路径', 'bad'); return; }
+    const r = await api('/api/files', { method: 'POST', body: { path: form.path.trim(), copy: form.copy } });
+    setModal(null);
+    toast(r.duplicated ? '库中已有相同文件' : (r.moved ? '已移动进附件库（可还原）' : '已复制进附件库'));
+    await refreshAttachments();
+    await load();
+    await reload();
+  });
+
+  const openEdit = guard(async (file) => {
+    setModal({
+      kind: 'edit',
+      id: file.id,
+      form: { name: file.name, tags: file.tags.join('、'), note: file.note },
+    });
+  });
+
+  const submitEdit = guard(async (id, form) => {
+    await api(`/api/files/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      body: {
+        name: form.name,
+        tags: form.tags.split(/[,，、;；]+/).map((x) => x.trim()).filter(Boolean),
+        note: form.note,
+      },
+    });
+    setModal(null);
+    toast('附件已更新');
+    await refreshAttachments();
+    await load();
+  });
+
+  const restore = guard(async (file) => {
+    const answer = await dialog({
+      message: `把「${file.name}」还原到哪？`,
+      detail: file.sourceDisplay
+        ? `默认移回原始位置并撤销台账：${file.sourceDisplay}`
+        : '该附件没有原始位置记录，请在下一步填写目标目录。',
+      input: file.sourceDisplay ? undefined : { placeholder: '目标目录绝对路径，例如 D:\\资料' },
+      confirmText: '移回并撤销台账',
+      cancelText: '取消',
+    });
+    if (answer === null) return;
+    const body = {};
+    if (answer && typeof answer === 'string') body.to = answer.trim();
+    const r = await api(`/api/files/${encodeURIComponent(file.id)}/restore`, { method: 'POST', body });
+    toast(`已还原到 ${r.displayPath}`);
+    await refreshAttachments();
+    await load();
+    await reload();
+  });
+
+  const exportCopy = guard(async (file) => {
+    const to = await dialog({
+      message: `导出「${file.name}」的副本到哪个目录？库中原件保留。`,
+      input: { placeholder: '目标目录绝对路径，例如 D:\\资料' },
+      confirmText: '导出副本',
+    });
+    if (!to) return;
+    const r = await api(`/api/files/${encodeURIComponent(file.id)}/restore`, {
+      method: 'POST',
+      body: { to: String(to).trim(), copy: true },
+    });
+    toast(`已导出到 ${r.displayPath}`);
+  });
+
+  const remove = guard(async (file) => {
+    const ok = await dialog({
+      message: `删除附件「${file.name}」？物理原件会一起删除，删除前自动留台账快照。`,
+      detail: '想保留原件、只撤销台账，请改用「还原」。',
+      danger: true,
+      confirmText: '删除',
+    });
+    if (!ok) return;
+    await api(`/api/files/${encodeURIComponent(file.id)}`, { method: 'DELETE' });
+    toast('已删除');
+    await refreshAttachments();
+    await load();
+    await reload();
+  });
+
+  if (err) {
+    return <div className="pad stack"><div className="bad"><strong>附件库读不到</strong></div><pre className="block">{err}</pre></div>;
+  }
+  if (!data) return <div className="pad muted">加载中…</div>;
+
+  const sections = data.sections || [];
+
+  return (
+    <div
+      className={`files-page ${dragOver ? 'drag-over' : ''}`}
+      onDragEnter={(e) => { e.preventDefault(); dragDepth.current += 1; setDragOver(true); }}
+      onDragOver={(e) => e.preventDefault()}
+      onDragLeave={(e) => {
+        e.preventDefault();
+        dragDepth.current -= 1;
+        if (dragDepth.current <= 0) { dragDepth.current = 0; setDragOver(false); }
+      }}
+      onDrop={onDrop}
+    >
+      <div className="toolbar rowgap pad">
+        <strong>附件</strong>
+        <span className="muted">{data.total} 个 · {fmtBytes(data.totalBytes)}</span>
+        <span className="hint" title="被栏目条目的 file 字段引用的附件数">被引用 {data.total - data.unlinked}/{data.total}</span>
+        <Copyable className="hint" text={data.rootRaw} title="点击复制附件库目录">{data.root}</Copyable>
+        <span className="grow" />
+        <input
+          style={{ width: 180 }}
+          placeholder="搜索名称 / 备注 / 标签 / 引用它的条目"
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+        />
+        <button className="btn small ghost" onClick={load}>刷新</button>
+        <button className="btn small ghost" onClick={openPathImport}>本机路径导入</button>
+        <button className="btn small" onClick={() => pickerRef.current?.click()}>上传文件</button>
+        <input
+          ref={pickerRef}
+          type="file"
+          multiple
+          style={{ display: 'none' }}
+          onChange={(e) => { uploadFiles(e.target.files); e.target.value = ''; }}
+        />
+      </div>
+
+      {/* 筛选按**栏目**驱动：栏目有 file 字段就会出现一个筛选片，不预定义任何分类 */}
+      <div className="rowgap pad file-filters">
+        <button className={`tab small ${!filter ? 'active' : ''}`} onClick={() => setFilter('')}>
+          全部<span className="count">{data.total}</span>
+        </button>
+        {sections.map((s) => (
+          <button
+            key={s.id}
+            className={`tab small ${filter === s.id ? 'active' : ''}`}
+            onClick={() => setFilter(s.id)}
+            title={`被「${s.title}」栏目引用的附件`}
+          >
+            {s.title}<span className="count">{s.count}</span>
+          </button>
+        ))}
+        <button className={`tab small ${filter === 'none' ? 'active' : ''}`} onClick={() => setFilter('none')}>
+          未引用<span className="count">{data.unlinked}</span>
+        </button>
+      </div>
+
+      {dragOver ? <div className="drop-hint">松开鼠标，文件直接导入附件库</div> : null}
+
+      {data.files.length ? (
+        <div className="file-grid pad">
+          {data.files.map((file) => (
+            <div key={file.id} className="file-card">
+              <a className="file-thumb" href={file.url} target="_blank" rel="noreferrer" title="在浏览器中预览">
+                {file.isImage
+                  ? <img src={file.url} alt={file.name} loading="lazy" />
+                  : <span className="ext-badge">{file.ext ? file.ext.slice(1).toUpperCase() : 'FILE'}</span>}
+              </a>
+              <div className="file-meta">
+                <a className="file-name" href={file.url} target="_blank" rel="noreferrer" title={file.name}>{file.name}</a>
+                <div className="rowgap" style={{ gap: 4 }}>
+                  <span className="hint">{fmtBytes(file.bytes)}</span>
+                  {file.mode === 'move' ? <Tag>移动导入</Tag> : null}
+                </div>
+                {file.usedBy?.length
+                  ? <div className="hint" title="条目的 file 字段引用了本附件">被引用：{file.usedBy.map(refText).join('、')}</div>
+                  : <div className="hint">未被任何条目引用（到栏目条目里选它即可链接）</div>}
+              </div>
+              <div className="file-acts">
+                <a className="btn small ghost" href={file.downloadUrl}>下载</a>
+                <button className="btn small ghost" onClick={() => exportCopy(file)}>导出副本</button>
+                <button className="btn small ghost" onClick={() => restore(file)}>还原</button>
+                <button className="btn small ghost" onClick={() => openEdit(file)}>编辑</button>
+                <button className="btn small ghost danger-ghost" onClick={() => remove(file)}>删除</button>
+                <span className="grow" />
+                <Copyable className="hint" text={file.path} title="点击复制物理路径">路径</Copyable>
+                <Copyable className="hint" text={file.url} title="点击复制链接">链接</Copyable>
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : (
+        <div className="pad">
+          <Empty>还没有附件。把文件拖到这里、点「上传文件」，或用「本机路径导入」把原件移动进库；随后到栏目的条目里选它。</Empty>
+          <div className="hint pad">CLI：nx-sk file add --path "D:\简历\张三-简历.pdf"（默认移动；--copy 仅复制）</div>
+        </div>
+      )}
+
+      <CliHints module="files" />
+
+      {modal ? (
+        <Modal title={modal.kind === 'edit' ? '编辑附件' : '从本机路径导入'} onClose={() => setModal(null)}>
+          {modal.kind === 'path' ? (
+            <PathImportForm
+              form={modal.form}
+              onChange={(f) => setModal((m) => ({ ...m, form: { ...m.form, ...f } }))}
+              onSubmit={() => submitPathImport(modal.form)}
+            />
+          ) : (
+            <EditForm
+              form={modal.form}
+              onChange={(f) => setModal((m) => ({ ...m, form: { ...m.form, ...f } }))}
+              onSubmit={() => submitEdit(modal.id, modal.form)}
+            />
+          )}
+        </Modal>
+      ) : null}
+    </div>
+  );
+}
+
+function PathImportForm({ form, onChange, onSubmit }) {
+  return (
+    <div className="stack">
+      <div className="field wide">
+        <div className="flabel"><span>本机文件的绝对路径</span></div>
+        <div className="fctrl">
+          <input
+            value={form.path}
+            placeholder='例如 D:\简历\张三-简历.pdf'
+            onChange={(e) => onChange({ path: e.target.value })}
+          />
+        </div>
+      </div>
+      <div className="field wide">
+        <div className="flabel"><span>导入方式</span></div>
+        <div className="fctrl">
+          <label className="inline">
+            <input
+              type="checkbox"
+              checked={form.copy}
+              onChange={(e) => onChange({ copy: e.target.checked })}
+            />
+            <span className="hint">仅复制、保留原件（默认把原件移动进库，可用「还原」撤销）</span>
+          </label>
+        </div>
+      </div>
+      <div className="rowgap">
+        <button className="btn" onClick={onSubmit}>导入</button>
+      </div>
+    </div>
+  );
+}
+
+function EditForm({ form, onChange, onSubmit }) {
+  return (
+    <div className="stack">
+      <div className="field wide">
+        <div className="flabel"><span>文件名</span></div>
+        <div className="fctrl"><input value={form.name} onChange={(e) => onChange({ name: e.target.value })} /></div>
+      </div>
+      <div className="field wide">
+        <div className="flabel"><span>标签</span><span className="fkey">多个用「、」分隔</span></div>
+        <div className="fctrl"><input value={form.tags} onChange={(e) => onChange({ tags: e.target.value })} /></div>
+      </div>
+      <div className="field wide">
+        <div className="flabel"><span>备注</span></div>
+        <div className="fctrl"><textarea rows={2} value={form.note} onChange={(e) => onChange({ note: e.target.value })} /></div>
+      </div>
+      <div className="rowgap">
+        <button className="btn" onClick={onSubmit}>保存</button>
+        <span className="hint">改文件名时，物理原件会随之移动。要链接到条目，请在栏目条目的 file 字段里选本附件。</span>
+      </div>
+    </div>
+  );
+}

package/src/modules/sections/index.js

@@ -87,6 +87,16 @@ export default {
       run: (ctx) => service.updateSection(ctx.ref, ctx),
       render: (d) => service.renderSectionChange(d),
     },
+    {
+      id: 'section.sync',
+      cli: ['section', 'sync'],
+      http: ['POST', '/api/sections/:ref/sync'],
+      summary: '按模板补齐字段：把模板新增、本栏目还缺的分组与字段补进来（只增不改不删）。模板演进不会回溯到已建栏目，用它追上',
+      args: ['ref'],
+      flags: { 'dry-run': { type: 'boolean', hint: '只列出会补哪些分组/字段，不落盘' } },
+      run: (ctx) => service.syncSection(ctx.ref, ctx),
+      render: (d) => service.renderSectionChange(d),
+    },
     {
       id: 'section.remove',
       cli: ['section', 'remove'],