feat(server,web,desktop,shared,deploy,plugin): 数据库管理模块 + 客户端深色模式/设置拆子路由/首启引导，版本统一 1.0.0

- 服务端新增 database 模块（/api/database/*，仅 ADMIN）：全库 JSON 快照（备份 / 恢复 / 导入导出 / 定时备份共用同一格式，14 张表按拓扑序导出、恢复时关外键检查）、连接测试与目标库校验、一键 SQLite ⇄ MySQL 切换（备份 → 导出 → 测试连接 → 校验空库 → 改 schema → 子进程 generate / tsc / db push → 写数据，全部成功才改写 .env，中途失败回滚 schema）；XML 快照与 SQLite 数据文件均可下载；打包形态随包带上 prisma CLI 与 typescript （prisma-client 生成物是 .ts，需再编进 dist/generated，安装包因之变大） - Web 管理端新增「数据库管理」页（仅管理员），并加首次登录新手引导（el-tour，可跳过、可随时重看，版本号写 localStorage，改版后老用户会再收到一次） - 客户端设置改版：侧边栏改为分组折叠菜单，设置拆成 6 个子路由（/settings/{general,appearance,island,reminder,account,about}），新增深色模式（主题持久化到主进程配置，主窗口底色跟主题走，避免"先白后黑"闪一下），新增「关于」页（应用信息 / 诊断信息） - 客户端新增首启六步引导（OnboardingWelcome，状态存主进程配置 onboardingDone） - 客户端主窗口初始尺寸与 ClassIsland 对齐（1242x582 / minHeight 540 / 居中） - 版本号统一提升到 1.0.0：5 个 package.json、部署配置与镜像标签（.env.example / docker-compose / Dockerfile）、服务端 /health 与首页、插件 manifest.yml 与 BridgeService.PluginVersion、文档里的安装包名 - 文档与验收同步：AGENTS.md 补第 37~51 条约定（深色主题实现边界、设置子路由、数据库管理三件事、侧栏与窗口尺寸、引导在自动化里的判据等），README 补「数据库管理 / 新手引导 / 设置改版」三节；verify:e2e 增补 13 条数据库管理用例，客户端冒烟与 Web UI 冒烟跟进子路由、深色主题、侧栏与引导验证：pnpm lint 0 error；pnpm typecheck 全过；verify:e2e 186/186；verify:classisland-plugin 68/68； build:desktop 通过（含产物凭据门禁）；verify:desktop 99/102（3 项为上课时段下的"真实通知链路"用例，客户端按产品规则暂存普通通知所致，见下）；插件 dotnet 编译 0 错误。注：verify:desktop 的「真实通知链路 / 标记已读」三项要求当前不在上课时段——本次运行时种子课表恰有「周五 10:55-11:40 生物」正在进行，客户端正确地暂存了普通通知（AGENTS.md 第 18 条），属时间相关用例，与本次改动无关。
2026-10-02 11:18:47 +08:00
1 parent 391e2c1591
commit 572295c297
@@ -0,0 +1,285 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue';
+import { ElMessage, ElMessageBox } from 'element-plus';
+import {
+  HOMEWORK_PHRASE_DEFAULTS,
+  HOMEWORK_PHRASE_MAX_COUNT,
+  HOMEWORK_PHRASE_MAX_LENGTH,
+  formatDate,
+} from '@classhelper/shared';
+import { pingHealth, setApiBaseUrl } from '../../api/http.js';
+import { normalizeServerUrl } from '../../config.js';
+import { useAppStore } from '../../stores/app.js';
+import { useAuthStore } from '../../stores/auth.js';
+import { useNotificationStore } from '../../stores/notifications.js';
+import { useOnboardingStore } from '../../stores/onboarding.js';
+import { useRealtimeStore } from '../../stores/realtime.js';
+
+/**
+ * 通用设置：服务器连接、离线缓存与作业录入短语。
+ * （外观 / 灵动岛 / 提醒 / 账号 / 关于 各自是独立子页，见侧边栏「设置」分组。）
+ */
+const appStore = useAppStore();
+const auth = useAuthStore();
+const onboarding = useOnboardingStore();
+const realtime = useRealtimeStore();
+const notifications = useNotificationStore();
+
+const serverInput = ref(appStore.serverUrl);
+const testing = ref(false);
+const saving = ref(false);
+
+const storeLabels: Record<string, string> = {
+  profile: '登录资料',
+  classes: '班级 / 学期',
+  schedules: '课表',
+  homeworks: '作业',
+  notifications: '通知',
+  grades: '成绩',
+};
+
+const cacheRows = computed(() =>
+  appStore.cacheStoreStats.map((item) => ({
+    label: storeLabels[item.store] ?? item.store,
+    store: item.store,
+    count: item.count,
+    updatedAt: item.updatedAt ? formatDate(item.updatedAt, true) : '—',
+  })),
+);
+
+async function saveServer(): Promise<void> {
+  const normalized = normalizeServerUrl(serverInput.value);
+  if (!normalized) {
+    ElMessage.error('服务器地址格式不正确，例如 http://127.0.0.1:4000');
+    return;
+  }
+  saving.value = true;
+  try {
+    await appStore.applyServerUrl(normalized);
+    serverInput.value = normalized;
+    ElMessage.success('服务器地址已保存');
+    await testConnection();
+    if (auth.token) realtime.connect(normalized, auth.token);
+  } finally {
+    saving.value = false;
+  }
+}
+
+async function testConnection(): Promise<void> {
+  testing.value = true;
+  try {
+    const result = await pingHealth();
+    if (result.ok) ElMessage.success('服务器连接正常');
+    else ElMessage.error('无法连接服务器，请检查地址与网络');
+  } finally {
+    testing.value = false;
+  }
+}
+
+async function manualSync(): Promise<void> {
+  setApiBaseUrl(appStore.serverUrl);
+  await appStore.ping();
+  if (appStore.offline) {
+    ElMessage.warning('当前无法连接服务器，已保留缓存数据');
+    return;
+  }
+  await notifications.load();
+  appStore.markSynced();
+  ElMessage.success('已同步最新数据');
+}
+
+async function clearCache(): Promise<void> {
+  await ElMessageBox.confirm('清空后离线时将无法查看历史数据，确认继续？', '清空离线缓存', {
+    type: 'warning',
+  });
+  await appStore.clearCache();
+  ElMessage.success('离线缓存已清空');
+}
+
+/* ------------------------------------------------------------ 作业录入快捷短语 */
+
+/**
+ * 作业快捷短语：录作业时点一下就把词追加到标题/内容里（P、大本、背诵…）。
+ *
+ * 存在客户端本地配置（这台教室机器自己的习惯），不占用服务端字段；
+ * 空数组是合法值 —— 老师把短语全删了就是"不想用快捷短语"。
+ */
+const phrases = ref<string[]>([...HOMEWORK_PHRASE_DEFAULTS]);
+const phraseInput = ref('');
+const savingPhrases = ref(false);
+
+async function loadPhrases(): Promise<void> {
+  const config = await window.desktop?.getConfig?.();
+  if (config?.homeworkPhrases) phrases.value = [...config.homeworkPhrases];
+}
+
+async function savePhrases(): Promise<void> {
+  if (!window.desktop?.saveConfig) return;
+  savingPhrases.value = true;
+  try {
+    const saved = await window.desktop.saveConfig({ homeworkPhrases: [...phrases.value] });
+    phrases.value = [...saved.homeworkPhrases];
+  } finally {
+    savingPhrases.value = false;
+  }
+}
+
+async function addPhrase(): Promise<void> {
+  const value = phraseInput.value.trim().slice(0, HOMEWORK_PHRASE_MAX_LENGTH);
+  if (!value) return;
+  if (phrases.value.includes(value)) {
+    ElMessage.warning('这条短语已经有了');
+    return;
+  }
+  if (phrases.value.length >= HOMEWORK_PHRASE_MAX_COUNT) {
+    ElMessage.warning(`最多 ${HOMEWORK_PHRASE_MAX_COUNT} 条快捷短语`);
+    return;
+  }
+  phrases.value = [...phrases.value, value];
+  phraseInput.value = '';
+  await savePhrases();
+  ElMessage.success('已添加');
+}
+
+async function removePhrase(value: string): Promise<void> {
+  phrases.value = phrases.value.filter((item) => item !== value);
+  await savePhrases();
+}
+
+async function resetPhrases(): Promise<void> {
+  await ElMessageBox.confirm('恢复为默认快捷短语？', '恢复默认', { type: 'warning' });
+  phrases.value = [...HOMEWORK_PHRASE_DEFAULTS];
+  await savePhrases();
+  ElMessage.success('已恢复默认');
+}
+
+onMounted(async () => {
+  await appStore.refreshCacheStats();
+  await loadPhrases();
+});
+</script>
+
+<template>
+  <div class="page">
+    <div class="page-header">
+      <div>
+        <h2 class="page-title">通用</h2>
+        <p class="page-subtitle">服务器连接、离线缓存与作业录入</p>
+      </div>
+      <!-- 重看初次启动引导（首启时由 App.vue 自动弹出过一次） -->
+      <el-button @click="onboarding.open()">
+        <el-icon><Guide /></el-icon>
+        使用引导
+      </el-button>
+    </div>
+
+    <el-row :gutter="12">
+      <el-col :xs="24" :md="12">
+        <el-card shadow="never">
+          <template #header><span>服务器连接</span></template>
+          <el-form label-position="top">
+            <el-form-item label="服务器地址">
+              <el-input v-model="serverInput" placeholder="http://127.0.0.1:4000">
+                <template #prefix>
+                  <el-icon><Link /></el-icon>
+                </template>
+              </el-input>
+            </el-form-item>
+          </el-form>
+          <div class="toolbar">
+            <el-button type="primary" :loading="saving" @click="saveServer">保存并测试</el-button>
+            <el-button :loading="testing" @click="testConnection">测试连接</el-button>
+            <el-button @click="manualSync">立即同步</el-button>
+          </div>
+
+          <el-descriptions class="mt-16" :column="1" border size="small">
+            <el-descriptions-item label="当前状态">
+              <el-tag :type="appStore.serverReachable ? 'success' : 'danger'" size="small">
+                {{ appStore.serverReachable ? '服务器可达' : '离线（显示缓存数据）' }}
+              </el-tag>
+              <el-tag class="ml-8" :type="realtime.connected ? 'success' : 'info'" size="small">
+                {{ realtime.statusText }}
+              </el-tag>
+            </el-descriptions-item>
+            <el-descriptions-item label="最近同步">{{ appStore.lastSyncText }}</el-descriptions-item>
+            <el-descriptions-item label="实时事件数">{{ realtime.eventCount }} 条</el-descriptions-item>
+          </el-descriptions>
+        </el-card>
+
+        <el-card shadow="never" class="mt-12">
+          <template #header><span>作业录入</span></template>
+          <p class="text-muted">
+            在教室电脑上录作业时，点一下短语就会追加到标题 / 内容里（例如 P、大本、背诵）。 最多
+            {{ HOMEWORK_PHRASE_MAX_COUNT }} 条、每条
+            {{ HOMEWORK_PHRASE_MAX_LENGTH }} 字；全部删掉即不在录入页显示。
+          </p>
+          <div class="phrase-row">
+            <el-tag
+              v-for="item in phrases"
+              :key="item"
+              closable
+              type="info"
+              effect="plain"
+              @close="removePhrase(item)"
+            >
+              {{ item }}
+            </el-tag>
+            <span v-if="phrases.length === 0" class="text-muted">（已清空）</span>
+          </div>
+          <div class="toolbar mt-12">
+            <el-input
+              v-model="phraseInput"
+              placeholder="新增短语，如 大本"
+              style="width: 200px"
+              :maxlength="HOMEWORK_PHRASE_MAX_LENGTH"
+              @keyup.enter="addPhrase"
+            />
+            <el-button type="primary" :loading="savingPhrases" @click="addPhrase">添加</el-button>
+            <el-button @click="resetPhrases">恢复默认</el-button>
+          </div>
+        </el-card>
+      </el-col>
+
+      <el-col :xs="24" :md="12">
+        <el-card shadow="never">
+          <template #header><span>离线缓存（IndexedDB）</span></template>
+          <el-table :data="cacheRows" size="small" empty-text="暂无缓存数据">
+            <el-table-column prop="label" label="数据类型" width="130" />
+            <el-table-column label="条目数" width="90">
+              <template #default="{ row }">{{ row.count }}</template>
+            </el-table-column>
+            <el-table-column label="最近更新" min-width="150">
+              <template #default="{ row }">{{ row.updatedAt }}</template>
+            </el-table-column>
+          </el-table>
+          <div class="toolbar mt-12">
+            <el-button :icon="'Refresh'" @click="appStore.refreshCacheStats()">刷新统计</el-button>
+            <el-button type="danger" plain @click="clearCache">清空缓存</el-button>
+          </div>
+          <el-alert
+            class="mt-12"
+            type="info"
+            :closable="false"
+            show-icon
+            title="离线可用"
+            description="断网后课表、作业、通知、成绩都会从本地缓存读取；恢复网络后自动向服务器同步最新数据。"
+          />
+        </el-card>
+      </el-col>
+    </el-row>
+  </div>
+</template>
+
+<style scoped>
+.phrase-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-top: 12px;
+}
+
+.ml-8 {
+  margin-left: 8px;
+}
+</style>