07 状态管理与数据流
  ├─ 前置：06 框架与组件化（useState / 响应式 / 渲染机制）
  ├─ 紧接：08 路由与渲染架构（URL 状态、水合后的状态恢复）
  ├─ 交叉：14 BFF（接口聚合与字段契约）、18 可观测性（状态变更埋点）
  └─ 长期：17 架构（模块边界与数据层分层）

/**
 * 同一个 UI，两条不同的「状态 → 视图」映射。
 * 关键：视图里不出现「先改 DOM 再记状态」的双写。
 */
function Counter() {
  const [count, setCount] = useState(0);

  // 视图 = f(count)，count 变了 React 自然会重画
  return <button onClick={() => setCount(count + 1)}>点了 {count} 次</button>;
}

// 反例：手动操作 DOM，状态和视图两份真相
let count = 0;
btn.addEventListener('click', () => {
  count += 1;
  btn.textContent = `点了 ${count} 次`; // 一旦还有别处改 count，这里就不同步
});

1. 只有这个组件用？           → 组件内部状态
2. 需要分享/收藏/刷新保留？    → URL 状态
3. 数据来自服务端？           → 请求库缓存
4. 多个不相干模块都要读？      → 全局 store（尽量小、按领域拆）
5. 需要跨会话保留？           → 持久化（注意版本与敏感信息）

/**
 * 列表页的状态分层示例。
 * 每一份状态都能回答「为什么放在这里」。
 */
function OrderListPage() {
  const [params, setParams] = useSearchParams();      // URL：可分享、可回退
  const page = Number(params.get('page') ?? 1);
  const keyword = params.get('keyword') ?? '';

  const { data, isFetching } = useQuery({             // 服务端：缓存 + 自动重验证
    queryKey: ['orders', { page, keyword }],
    queryFn: () => fetchOrders({ page, keyword }),
    staleTime: 30_000,
  });

  const [selected, setSelected] = useState<string[]>([]); // 组件：只影响本页
  const { user } = useAuth();                              // 全局：跨模块共享
  const [draft, setDraft] = useLocalStorage('order-draft', ''); // 持久化：跨会话

  return (
    <>
      <SearchBox value={keyword} onChange={(v) => setParams({ keyword: v, page: 1 })} />
      <OrderTable data={data?.list ?? []} loading={isFetching} selected={selected} onSelect={setSelected} />
    </>
  );
}

事件 → 更新状态 → 重新计算视图
  ↑                        │
  └──── 用户看到新视图 ←────┘

// 单向：数据只能从父流向子，子通过回调「请求」修改
function Parent() {
  const [value, setValue] = useState('');
  return <Child value={value} onChange={setValue} />;
}

function Child({ value, onChange }) {
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
}

/**
 * 1) 更新是异步批处理的：连续 set 不会立刻反映到当前闭包里的变量。
 * 2) 依赖旧值时必须用函数式更新。
 * 3) 对象/数组更新必须换新引用。
 */
function Counter() {
  const [count, setCount] = useState(0);

  const handleTripleWrong = () => {
    setCount(count + 1);
    setCount(count + 1); // 三次都基于同一个旧 count，最终只 +1
    setCount(count + 1);
  };

  const handleTripleRight = () => {
    setCount((c) => c + 1);
    setCount((c) => c + 1); // 每次拿到上一次的结果，最终 +3
    setCount((c) => c + 1);
  };

  return (
    <>
      <button onClick={handleTripleWrong}>错误：+1</button>
      <button onClick={handleTripleRight}>正确：+3</button>
    </>
  );
}

/**
 * 一个最小但完整的全局状态实现。
 * 结构：State + Action + reducer + Provider + 自定义 Hook。
 */
import { createContext, useContext, useReducer } from 'react';

/** @typedef {{ id: string, text: string, done: boolean }} Todo */
/** @typedef {{ todos: Todo[] }} State */
/** @typedef {{ type: 'add', text: string } | { type: 'toggle', id: string } | { type: 'remove', id: string }} Action */

const initialState = { todos: [] };

/**
 * 纯函数：给定旧状态和动作，返回新状态。不修改入参，不做副作用。
 * @param {State} state
 * @param {Action} action
 * @returns {State}
 */
function reducer(state, action) {
  switch (action.type) {
    case 'add':
      return { ...state, todos: [...state.todos, { id: crypto.randomUUID(), text: action.text, done: false }] };
    case 'toggle':
      return { ...state, todos: state.todos.map((t) => (t.id === action.id ? { ...t, done: !t.done } : t)) };
    case 'remove':
      return { ...state, todos: state.todos.filter((t) => t.id !== action.id) };
    default:
      return state;
  }
}

const TodoContext = createContext(null);

export function TodoProvider({ children }) {
  const [state, dispatch] = useReducer(reducer, initialState);
  return <TodoContext.Provider value={{ state, dispatch }}>{children}</TodoContext.Provider>;
}

/** 读取全局状态的唯一入口，便于以后替换实现。 */
export function useTodos() {
  const ctx = useContext(TodoContext);
  if (!ctx) throw new Error('useTodos 必须在 TodoProvider 内使用');
  return ctx;
}

const next = { ...state, user: { ...state.user, name: '新名字' } };

// 反例：直接修改
state.user.name = '新名字';

// 追加
const added = [...list, item];

// 删除
const removed = list.filter((x) => x.id !== id);

// 修改某一项
const updated = list.map((x) => (x.id === id ? { ...x, done: true } : x));

// 排序（注意 sort 会改原数组）
const sorted = [...list].sort((a, b) => a.order - b.order);

// 嵌套结构：改一个评论要穿过 4 层
const next = {
  ...state,
  posts: state.posts.map((p) =>
    p.id === postId
      ? {
          ...p,
          comments: p.comments.map((c) =>
            c.id === commentId ? { ...c, content } : c,
          ),
        }
      : p,
  ),
};

// ❌ 存两份：完成数量与实际列表可能不一致
const [todos, setTodos] = useState([]);
const [doneCount, setDoneCount] = useState(0);

// ✅ 每次渲染时算
const doneCount = todos.filter((t) => t.done).length;

const doneCount = useMemo(() => todos.filter((t) => t.done).length, [todos]);

/**
 * 受控表单：值是状态，改值走 onChange。
 * 优点：随时可校验、可联动、可重置；缺点：每次输入都触发渲染。
 */
function LoginForm({ onSubmit }) {
  const [form, setForm] = useState({ account: '', password: '' });
  const [errors, setErrors] = useState({});
  const [status, setStatus] = useState('idle'); // idle | submitting | success | error

  /** 字段级校验：返回错误对象，空对象表示通过。 */
  const validate = (values) => {
    const next = {};
    if (!values.account) next.account = '请输入账号';
    if (values.password.length < 6) next.password = '密码至少 6 位';
    return next;
  };

  const handleSubmit = async (e) => {
    e.preventDefault();
    const nextErrors = validate(form);
    setErrors(nextErrors);
    if (Object.keys(nextErrors).length > 0) return;

    setStatus('submitting');
    try {
      await onSubmit(form);
      setStatus('success');
    } catch {
      setStatus('error');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={form.account}
        onChange={(e) => setForm({ ...form, account: e.target.value })}
        aria-invalid={Boolean(errors.account)}
      />
      {errors.account && <p role="alert">{errors.account}</p>}
      <button disabled={status === 'submitting'}>{status === 'submitting' ? '提交中…' : '登录'}</button>
    </form>
  );
}

function SearchBar({ onSearch }) {
  const ref = useRef(null);
  return (
    <form onSubmit={(e) => { e.preventDefault(); onSearch(ref.current.value); }}>
      <input ref={ref} defaultValue="" />
    </form>
  );
}

// 筛选条件写进 query，刷新不丢、可分享、可回退
const [params, setParams] = useSearchParams();
const status = params.get('status') ?? 'all';

const changeStatus = (next) => {
  setParams({ status: next }, { replace: false }); // false：留一条历史记录，支持返回
};

UI 事件 → dispatch(action) → middleware 链 → reducer(prevState, action) → 新 state
                                                                          ↓
                                                              订阅者被通知 → 选择器算数据 → 重渲染

/**
 * 迷你 Redux：理解 store 只需要这 40 行。
 * 真实实现多了：订阅快照、批量通知、中间件组合、DevTools 协议。
 */
function createStore(reducer, preloadedState) {
  let state = preloadedState;
  const listeners = new Set();

  return {
    getState: () => state,
    dispatch(action) {
      state = reducer(state, action);
      listeners.forEach((l) => l());
      return action;
    },
    subscribe(listener) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
  };
}

// 中间件本质：把 dispatch 包装成可组合的高阶函数
const logger = (store) => (next) => (action) => {
  console.log('dispatch', action);
  const result = next(action);
  console.log('next state', store.getState());
  return result;
};

// ❌ 嵌套结构：更新深、易重复
const state = {
  posts: [{ id: 1, author: { id: 9, name: 'A' }, comments: [{ id: 2, author: { id: 9, name: 'A' } }] }],
};

// ✅ 规范化：实体扁平、引用只存 id
const norm = {
  posts: { byId: { 1: { id: 1, authorId: 9, commentIds: [2] } }, allIds: [1] },
  comments: { byId: { 2: { id: 2, postId: 1, authorId: 9, content: 'hi' } }, allIds: [2] },
  users: { byId: { 9: { id: 9, name: 'A' } }, allIds: [9] },
};

/** 组装：把 id 数组还原成对象数组。 */
const selectPostList = (state) =>
  state.posts.allIds.map((id) => ({
    ...state.posts.byId[id],
    author: state.users.byId[state.posts.byId[id].authorId],
  }));

import { createSelector } from 'reselect';

/**
 * 只有输入引用变化时才重算，否则返回上一次的结果（引用不变）。
 * 注意：如果 input 每次都是新数组，缓存永远不命中。
 */
const selectVisibleTodos = createSelector(
  [(state) => state.todos, (state) => state.filter],
  (todos, filter) => todos.filter((t) => (filter === 'all' ? true : t.done === (filter === 'done'))),
);

// ❌ 每次返回新对象 → Object.is 判定不等 → 每次都重渲染
const { name, age } = useStore((s) => ({ name: s.name, age: s.age }));

// ✅ 方案 1：分开选
const name = useStore((s) => s.name);
const age = useStore((s) => s.age);

// ✅ 方案 2：浅比较
import { useShallow } from 'zustand/react/shallow';
const { name, age } = useStore(useShallow((s) => ({ name: s.name, age: s.age })));

/**
 * TanStack Query 的核心模型。
 * queryKey 是缓存键：变了就是另一份数据。
 * staleTime：多久之内认为「新鲜」，不重新请求。
 * gcTime：没有组件使用后，多久从内存清除。
 */
const { data, error, isPending, isFetching, refetch } = useQuery({
  queryKey: ['order', orderId],
  queryFn: ({ signal }) => fetchOrder(orderId, { signal }),
  staleTime: 60_000,
  gcTime: 5 * 60_000,
  refetchOnWindowFocus: true,
  retry: 2,
});

时间轴（staleTime=60s, gcTime=5min）
0s     请求完成，写入缓存，状态 fresh
30s    组件重新挂载 → 命中缓存，不请求
61s    状态变 stale → 挂载/聚焦时后台重新请求（stale-while-revalidate）
5min   无组件使用 → 缓存被回收

// 写操作成功后，让相关缓存失效
await updateOrder(payload);
queryClient.invalidateQueries({ queryKey: ['orders'] });

// 精准更新某一个详情，避免多余请求
queryClient.setQueryData(['order', id], (old) => ({ ...old, ...payload }));

// 乐观更新（L3 详讲）
onMutate: async (next) => {
  await queryClient.cancelQueries({ queryKey: ['order', id] });
  const prev = queryClient.getQueryData(['order', id]);
  queryClient.setQueryData(['order', id], next);
  return { prev };
},
onError: (_err, _next, ctx) => queryClient.setQueryData(['order', id], ctx.prev),

/**
 * 竞态：先发的请求后到，覆盖了新结果。
 * 三种解法，从弱到强。
 */
function Search({ keyword }) {
  const [result, setResult] = useState([]);

  useEffect(() => {
    const controller = new AbortController();

    fetch(`/api/search?q=${encodeURIComponent(keyword)}`, { signal: controller.signal })
      .then((r) => r.json())
      .then((data) => setResult(data))
      .catch((err) => {
        if (err.name === 'AbortError') return; // 主动取消，不算错误
        setResult([]);
      });

    // 下一次 effect 执行前，取消上一次请求
    return () => controller.abort();
  }, [keyword]);

  return <List data={result} />;
}

// 忽略法：只接受最后一次请求的结果
let latestId = 0;
async function load() {
  const id = ++latestId;
  const data = await fetchData();
  if (id !== latestId) return; // 过期结果直接丢弃
  setData(data);
}

/**
 * 持久化的最小正确实现。
 * 1) 版本迁移：结构变了要能升级旧数据
 * 2) 容量与失败：写入可能抛 QuotaExceededError
 * 3) 敏感数据：token/身份证等不落明文本地
 */
const KEY = 'app-state';
const VERSION = 3;

const migrations = {
  1: (s) => ({ ...s, theme: 'light' }),
  2: (s) => ({ ...s, filters: {} }),
  3: (s) => ({ ...s, schema: 3 }),
};

function loadState() {
  try {
    const raw = localStorage.getItem(KEY);
    if (!raw) return null;
    let data = JSON.parse(raw);
    for (let v = data.version + 1; v <= VERSION; v++) data = migrations[v](data);
    return data;
  } catch {
    return null; // 解析失败就当没有，别让坏数据卡死应用
  }
}

function saveState(state) {
  try {
    localStorage.setItem(KEY, JSON.stringify({ ...state, version: VERSION }));
  } catch (err) {
    if (err.name === 'QuotaExceededError') {
      // 降级：清掉非关键字段，或改存 IndexedDB
      console.warn('本地存储已满，已跳过持久化');
    }
  }
}

/**
 * 动态字段数组：增删行时保持稳定 key，避免输入框错位。
 * 多步表单：把「当前步骤」放 URL，把「已填数据」放上层状态。
 */
function ContactsForm() {
  const [contacts, setContacts] = useState([{ key: crypto.randomUUID(), name: '', phone: '' }]);

  const update = (key, patch) =>
    setContacts((list) => list.map((c) => (c.key === key ? { ...c, ...patch } : c)));

  const remove = (key) => setContacts((list) => list.filter((c) => c.key !== key));

  return (
    <>
      {contacts.map((c) => (
        <div key={c.key}>
          <input value={c.name} onChange={(e) => update(c.key, { name: e.target.value })} />
          <input value={c.phone} onChange={(e) => update(c.key, { phone: e.target.value })} />
          <button onClick={() => remove(c.key)}>删除</button>
        </div>
      ))}
      <button onClick={() => setContacts((l) => [...l, { key: crypto.randomUUID(), name: '', phone: '' }])}>
        新增联系人
      </button>
    </>
  );
}

/**
 * 把 URL 当表单：解析、序列化、默认值、类型转换集中在一处。
 */
type ListQuery = { page: number; keyword: string; tags: string[]; sort: 'asc' | 'desc' };

function parseQuery(search: string): ListQuery {
  const p = new URLSearchParams(search);
  return {
    page: Math.max(1, Number(p.get('page')) || 1),
    keyword: p.get('keyword') ?? '',
    tags: p.getAll('tag'),
    sort: p.get('sort') === 'asc' ? 'asc' : 'desc',
  };
}

function toQuery(q: ListQuery): string {
  const p = new URLSearchParams();
  if (q.page !== 1) p.set('page', String(q.page));
  if (q.keyword) p.set('keyword', q.keyword);
  q.tags.forEach((t) => p.append('tag', t));
  if (q.sort !== 'desc') p.set('sort', q.sort);
  return p.toString();
}

// 用一个页面描述「加载中/成功/失败/空/重试中」
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const [data, setData] = useState(null);
const [retrying, setRetrying] = useState(false);

// 组合态有 2^4 = 16 种，其中大部分是非法的
// 例如：loading=true && error!=null && data!=null 同时成立

import { createMachine } from 'xstate';

/**
 * 下单流程状态机。
 * 每个状态只允许特定事件，非法事件被忽略（或走 error 分支）。
 */
const orderMachine = createMachine({
  id: 'order',
  initial: 'editing',
  context: { items: [], orderId: null, error: null },
  states: {
    editing: {
      on: {
        SUBMIT: { target: 'submitting', guard: 'hasItems' },
      },
    },
    submitting: {
      invoke: {
        src: 'createOrder',
        onDone: { target: 'paying', actions: 'saveOrderId' },
        onError: { target: 'failed', actions: 'saveError' },
      },
      on: { CANCEL: 'editing' },
    },
    paying: {
      on: { PAID: 'done', FAIL: 'failed' },
    },
    failed: {
      on: { RETRY: 'submitting', BACK: 'editing' },
    },
    done: { type: 'final' },
  },
});

/**
 * 乐观更新四件套：
 * 1) 取消在途查询，避免旧结果回写
 * 2) 立即写缓存（用户马上看到结果）
 * 3) 失败回滚（恢复到快照）
 * 4) 无论成败都重新验证（保证最终一致）
 */
function useToggleTodo() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, done }) => fetch(`/api/todos/${id}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': `${id}-${done}` },
      body: JSON.stringify({ done }),
    }).then((r) => r.json()),

    onMutate: async ({ id, done }) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });
      const prev = queryClient.getQueryData(['todos']);
      queryClient.setQueryData(['todos'], (old) =>
        old?.map((t) => (t.id === id ? { ...t, done } : t)),
      );
      return { prev };
    },

    onError: (_err, _vars, ctx) => {
      queryClient.setQueryData(['todos'], ctx.prev); // 回滚
    },

    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] }); // 最终一致
    },
  });
}

写入路径：用户操作 → 写本地库（立即成功）→ 入队 op-log → 有网时同步 → 服务端确认 → 清理队列
读取路径：读本地库（立即返回）→ 后台拉增量 → 合并 → 触发视图更新

/**
 * 操作日志（op-log）的极简结构。
 * 每条操作必须：可重放、可幂等、带时间戳与设备 id。
 */
type Op = {
  id: string;            // 幂等键
  entity: 'todo' | 'note';
  entityId: string;
  type: 'create' | 'update' | 'delete';
  payload: unknown;
  baseVersion: number;   // 基于哪个版本修改，用于检测冲突
  createdAt: number;
  deviceId: string;
};

/** 顺序同步：失败保留队列，下次继续；成功则按 id 去重后落库。 */
async function flush(queue: Op[]) {
  for (const op of queue) {
    try {
      const res = await fetch('/api/sync', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Idempotency-Key': op.id },
        body: JSON.stringify(op),
      });
      if (res.status === 409) {
        await resolveConflict(op, await res.json()); // 冲突交给策略处理
      }
    } catch {
      return; // 网络失败：保留剩余队列，等下次
    }
  }
}

副本 A：["买牛奶"]
副本 B：["买牛奶"]

A 在末尾加 "买面包" → ["买牛奶", "买面包"]
B 在开头加 "买鸡蛋" → ["买鸡蛋", "买牛奶"]

合并（按位置标识而非数组下标）→ ["买鸡蛋", "买牛奶", "买面包"]

/**
 * BroadcastChannel：同源标签页之间通信。
 * 用途：登录态同步、退出登录互踢、数据变更通知。
 */
const channel = new BroadcastChannel('app-sync');

// 发送
channel.postMessage({ type: 'logout', at: Date.now() });

// 接收
channel.onmessage = (e) => {
  if (e.data.type === 'logout') {
    clearSession();
    location.replace('/login');
  }
};

/**
 * 按路由懒加载 store：进入模块才创建，离开可保留或销毁。
 */
let orderStore = null;
export function getOrderStore() {
  if (!orderStore) orderStore = createStore(orderReducer);
  return orderStore;
}

/**
 * useSyncExternalStore：把外部 store 接入 React 的官方方式。
 * 它保证同一次渲染中，所有组件读到同一个快照。
 */
import { useSyncExternalStore } from 'react';

function useStoreSnapshot(store) {
  return useSyncExternalStore(
    store.subscribe,
    store.getSnapshot,
    store.getServerSnapshot, // SSR 时必须提供，否则水合不一致
  );
}

/**
 * 输入框必须即时响应（紧急更新），列表过滤可以被打断（过渡更新）。
 * 注意：不要把「输入框的值」也放进 transition，否则光标会卡。
 */
function SearchPage() {
  const [keyword, setKeyword] = useState('');
  const [list, setList] = useState([]);
  const [isPending, startTransition] = useTransition();

  const handleChange = (v) => {
    setKeyword(v); // 紧急
    startTransition(() => {
      setList(filterHugeList(v)); // 非紧急，可被打断
    });
  };

  return (
    <>
      <input value={keyword} onChange={(e) => handleChange(e.target.value)} />
      <List data={list} dimmed={isPending} />
    </>
  );
}

/**
 * 状态更新是纯函数 → 测试不需要渲染、不需要 mock 时间。
 * 这是 reducer / 状态机最大的工程价值。
 */
test('toggle 只影响目标项', () => {
  const before = { todos: [{ id: '1', done: false }, { id: '2', done: false }] };
  const after = reducer(before, { type: 'toggle', id: '1' });
  expect(after.todos[0].done).toBe(true);
  expect(after.todos[1].done).toBe(false);
  expect(before.todos[0].done).toBe(false); // 不可变
});

// ❌ 隐式依赖：谁发的？谁收的？顺序如何？无法静态分析
bus.emit('user-updated', user);
bus.on('user-updated', refreshList);
bus.on('user-updated', refreshHeader);
bus.on('user-updated', clearCache);

❌ pages/order/store.ts   （订单页一个 store）
   pages/user/store.ts    （用户页一个 store）
   → 同一份「订单」在两个 store 里各存一份

✅ domains/order/{model,api,selectors}.ts
   domains/user/{model,api,selectors}.ts
   页面只订阅需要的切片

┌──────────────┐   写    ┌──────────────┐
│  视图 / 交互  │ ──────▶ │  命令层       │──▶ API / BFF
└──────────────┘         └──────────────┘
        ▲                        │ 成功/失败/冲突
        │ 读                     ▼
┌──────────────┐         ┌──────────────┐
│  读模型缓存   │ ◀────── │  同步 / 失效  │
│ 内存→IDB→CDN │         └──────────────┘
└──────────────┘

/**
 * 增量同步的核心：游标（cursor）+ 变更集（changeset）。
 * 客户端只需拉「上次游标之后的变化」，避免全量传输。
 */
type PullResp = {
  changes: Array<{ entity: string; id: string; version: number; deleted?: boolean; data?: unknown }>;
  cursor: string; // 下次从这里继续
};

async function pull(cursor: string) {
  const res = await fetch(`/api/sync/pull?cursor=${encodeURIComponent(cursor)}`);
  const { changes, cursor: next } = await res.json();
  await applyChangesLocally(changes); // 幂等：同 version 重复应用无副作用
  await saveCursor(next);
}

设备A: {A:3, B:2}
设备B: {A:2, B:4}
→ B 没见过 A 的第 3 版，A 没见过 B 的第 3、4 版 → 存在并发修改，需要合并策略

/**
 * 每个操作都是一个命令：do / undo 成对存在。
 * 撤销栈只存命令，不存完整状态快照（省内存）。
 */
interface Command {
  do(): void;
  undo(): void;
}

class History {
  private undoStack: Command[] = [];
  private redoStack: Command[] = [];

  execute(cmd: Command) {
    cmd.do();
    this.undoStack.push(cmd);
    this.redoStack = []; // 新操作让重做失效
  }

  undo() {
    const cmd = this.undoStack.pop();
    if (!cmd) return;
    cmd.undo();
    this.redoStack.push(cmd);
  }

  redo() {
    const cmd = this.redoStack.pop();
    if (!cmd) return;
    cmd.do();
    this.undoStack.push(cmd);
  }
}

type Task = {
  id: string;
  title: string;
  status: 'todo' | 'doing' | 'done';
  order: number;
  version: number;   // 服务端版本，用于冲突检测
  updatedAt: number;
};

拖拽 → 本地立即改 order/status（乐观）
     → 生成 op（含 baseVersion）
     → 入队 IndexedDB
     → 在线则 flush
        ├─ 200：更新本地 version
        ├─ 409：拉最新 → 字段级合并 → 重放
        └─ 网络错误：保留队列，监听 online 事件重试

/**
 * 极简 store：支持选择器订阅、浅比较与批量通知。
 * @param {(state: any, action: any) => any} reducer
 * @param {any} initialState
 */
function createStore(reducer, initialState) {
  let state = initialState;
  /** @type {Set<{selector: Function, last: any, listener: Function}>} */
  const subscribers = new Set();
  let notifying = false;

  /** 浅比较，避免选择器返回新对象导致的无效通知 */
  const shallowEqual = (a, b) => {
    if (Object.is(a, b)) return true;
    if (typeof a !== 'object' || typeof b !== 'object' || !a || !b) return false;
    const ka = Object.keys(a);
    const kb = Object.keys(b);
    return ka.length === kb.length && ka.every((k) => Object.is(a[k], b[k]));
  };

  const getState = () => state;

  const dispatch = (action) => {
    const next = reducer(state, action);
    if (Object.is(next, state)) return;
    state = next;
    if (notifying) return;
    notifying = true;
    try {
      subscribers.forEach((sub) => {
        const value = sub.selector(state);
        if (!shallowEqual(value, sub.last)) {
          sub.last = value;
          sub.listener(value);
        }
      });
    } finally {
      notifying = false;
    }
  };

  /**
   * 订阅选择器结果。
   * @param {(s: any) => any} selector
   * @param {(value: any) => void} listener
   * @returns {() => void} 取消订阅
   */
  const subscribe = (selector, listener) => {
    const sub = { selector, listener, last: selector(state) };
    subscribers.add(sub);
    return () => subscribers.delete(sub);
  };

  return { getState, dispatch, subscribe };
}

/**
 * 撤销/重做历史：同类连续操作在时间窗内合并，避免每敲一个字都入栈。
 * @param {number} [windowMs=500] 合并时间窗
 */
function createHistory(windowMs = 500) {
  /** @type {Array<{state: any, tag: string, at: number}>} */
  let past = [];
  let present = null;
  let future = [];

  /**
   * 提交一次变更。
   * @param {any} next 新状态
   * @param {string} tag 操作类型，用于合并判断
   */
  const commit = (next, tag) => {
    const now = Date.now();
    const last = past[past.length - 1];
    const mergeable = last && last.tag === tag && now - last.at < windowMs;

    if (mergeable) {
      last.at = now; // 保留最早的状态，只更新时间窗
    } else if (present !== null) {
      past.push({ state: present, tag, at: now });
    }
    present = next;
    future = [];
  };

  const undo = () => {
    if (past.length === 0) return present;
    const prev = past.pop();
    future.push({ state: present, tag: prev.tag, at: Date.now() });
    present = prev.state;
    return present;
  };

  const redo = () => {
    if (future.length === 0) return present;
    const next = future.pop();
    past.push({ state: present, tag: next.tag, at: Date.now() });
    present = next.state;
    return present;
  };

  return {
    commit,
    undo,
    redo,
    get state() {
      return present;
    },
    get canUndo() {
      return past.length > 0;
    },
    get canRedo() {
      return future.length > 0;
    },
  };
}