跳到主要内容
Markdown DB Engine

设计系统

当前阶段

项目已经实现 CLI 与响应式数据库管理 Web UI。当前 Web UI 使用原生 HTML、CSS 与 JavaScript，采用 Cream Paper、Deep Green、Gold Focus 的管理工具视觉语言；没有引入组件库或图标库。

当前 Token 定义在独立 styles.ts 样式模块中：--ink、--muted、--paper、--panel、--line、--accent 和 --danger。页面在 720px 断点切换为单列与横向导航，键盘焦点使用 3px Gold Outline，状态同时使用文字和 aria-live，不只依赖颜色。

设计对象

产品包含四种交互体验：

  1. SDK 与 CLI：创建、打开、查询和事务修改 Runtime Database。
  2. 数据库 Web UI：像 phpMyAdmin 一样管理数据、Schema、索引、权限、事务与健康状态。
  3. Workspace：执行 update、查看本地修改状态和处理未提交内容。
  4. Merge：检查 Changeset、Schema 错误、删除影响、并发冲突和事务结果。

个人数字展示网站属于独立上层应用，不定义数据库核心交互。

体验原则

  • 中心明确：始终区分 Runtime Database 正式数据与 Workspace 编辑数据。
  • 自由编辑：Workspace 使用普通 Markdown，不要求用户理解数据库内部结构。
  • 提交可审查：Merge 前完整展示新增、修改、删除、移动、警告和冲突。
  • 结果可信：任何数据库修改都有明确的未执行、执行中、已提交或已回滚状态。
  • 数据安全：失败界面说明 Runtime Database 和 Workspace 是否发生变化，以及下一步怎样处理。
  • Agent 友好：CLI 与结构化输出具有一致语义，错误包含稳定代码和可执行建议。

信息架构原则

  • Runtime Database 状态、Workspace 状态和 Merge Plan 不能混成同一个“同步状态”。
  • 对象详情需要区分运行时值、Workspace 值、对象版本和冲突字段。
  • 删除操作展示受影响对象、关系和约束，不只显示文件路径。
  • 批量 Changeset 同时提供摘要和逐对象详情。
  • 内部 WAL、索引和 metadata 默认不暴露；完整性检查与诊断模式可以提供必要信息。
  • 多个 Workspace 不显示成 Branch 树；Web UI 只处理用户当前选择或提交的 Workspace。
  • Query Builder、Record 表格、Schema 结构和原始 Markdown 视图需要互相跳转。

交互状态

每个数据库操作至少设计：初始、执行中、成功、验证警告、硬性错误、并发冲突、事务回滚和恢复失败状态。

当前管理页面使用独立表单划分操作边界。Delete、Schema、Index Rebuild、Role Change、Transaction Commit、User Disable 和 Merge Apply 必须选中对应确认项；Transaction 提供 Changeset 影响预览，Merge Plan 在有冲突或删除时进入明确的 Conflict 或 Warning 状态。Restore 不允许在线覆盖 Writer Host，只显示停止 Server 后使用 CLI 恢复到新目录的操作说明。

Update

  • 明确数据方向是 Runtime Database 到 Workspace。
  • Workspace 存在未合并修改时，不允许无提示覆盖。
  • 更新结果列出新增、刷新、删除、跳过和冲突的文件。

Merge

  • merge --plan 或等价操作默认只检查，不修改 Runtime Database。
  • 提交前展示 Changeset、删除影响、Schema 错误和对象版本冲突。
  • Merge 失败时明确说明 Runtime Database 保持不变，Workspace 修改仍然存在。
  • 强制覆盖运行时新数据必须使用明确、高风险操作，不能隐藏在普通确认按钮中。

内容与可访问性

  • 使用明确动作名称，例如“更新 Workspace”“检查 Merge”“提交到 Runtime Database”，避免只写“同步”。
  • 状态不能只依赖颜色，必须配合文字、图标和机器可读状态。
  • 终端输出同时支持人类可读格式和结构化格式；错误信息不得只依赖终端颜色。
  • Web 界面的核心功能支持键盘操作、可见焦点和语义化标签，并满足 WCAG AA 对比度目标。
  • 对象身份、路径、版本、错误代码和事务标识允许复制。

动效原则

  • 使用轻量动效解释 Changeset 展开、状态切换和事务完成。
  • 尊重 prefers-reduced-motion。
  • 长时间检查、索引重建或 Merge 使用真实阶段状态，不展示虚假确定进度。
  • 成功反馈只能在事务已经提交后出现，不能掩盖仍在执行的索引或恢复工作。

Token 演进规则

现有 Token 是数据库管理器的正式基础。增加多个页面或可复用组件时，应当把颜色、字体、间距、网格、断点、圆角、阴影和组件尺寸移动到独立样式模块；每个 Token 继续使用语义名称，避免页面中散落未经约束的数值。