@code2rich/jpage 1.5.0

package/docs/design/005-custom-modal.md

@@ -0,0 +1,296 @@
+# 005 — 自定义 Modal 组件替代原生 prompt/confirm
+
+> 状态：设计完成，待实现
+> 关联：分析报告问题 #8（重命名 prompt）、#9（删除 confirm）
+> 优先级：P1
+
+---
+
+## 一、现状分析
+
+### 1.1 当前已实现
+
+重命名和删除**已经**使用了自定义 modal（非原生 `prompt`/`confirm`），但实现方式是「每个场景独立编写 HTML + JS」：
+
+| Modal | HTML 行数 | JS 逻辑 | 特点 |
+|---|---|---|---|
+| `rename-modal` | index.html:188-206 | app.js `doRename()` ~55 行 | 输入框 + 校验 + Promise 封装 |
+| `delete-modal` | index.html:209-223 | app.js `doDelete()` ~43 行 | 动态文案 + 危险操作样式 |
+| `skill-modal` | index.html:127-145 | app.js ~110 行 | 展示型，无表单 |
+| `mcp-config-modal` | index.html:150-165 | 少量 | 展示型，纯复制 |
+| `skills-list-modal` | index.html:167-184 | 少量 | 列表型 |
+
+### 1.2 存在的问题
+
+1. **代码重复**：每个 modal 的 open/close/cleanup 逻辑几乎一致（事件绑定、backdrop 点击、Escape 关闭、aria 属性切换），但各写一遍
+2. **无通用组件**：新增 modal 场景（如分享链接、文件上传进度）需要复制整套 boilerplate
+3. **事件泄漏风险**：手动 `addEventListener` / `removeEventListener` 配对，容易遗漏
+4. **样式不统一**：个别 modal 使用 inline style（`style="max-width:440px"`），而非 CSS class
+
+---
+
+## 二、设计目标
+
+1. **一个通用 Modal 工具函数**，覆盖三种场景：
+   - **Alert**：纯信息提示 + 确认按钮（替代未来可能的 `alert`）
+   - **Confirm**：确认/取消双按钮（替代 `confirm`，如删除确认）
+   - **Prompt**：输入框 + 确认/取消（替代 `prompt`，如重命名）
+2. **Promise 接口**，调用方式简洁：`const name = await modal.prompt({ title, value })` 
+3. **复用现有 CSS**，不新增框架依赖
+4. **向后兼容**：保留 skill-modal、mcp-config-modal 等展示型 modal 不变，仅重构交互型 modal
+
+---
+
+## 三、API 设计
+
+### 3.1 `modal.confirm(options)` → `Promise<boolean>`
+
+```js
+const ok = await modal.confirm({
+  title: '确认删除',
+  message: '确定要删除 <strong>report.html</strong> 吗？此操作不可撤销。',
+  // message 支持 HTML 字符串
+  confirmText: '删除',      // 默认 '确认'
+  danger: true,             // 确认按钮使用红色危险样式
+});
+// ok === true  → 用户点了确认
+// ok === false → 用户点了取消 / Escape / 点击遮罩
+```
+
+### 3.2 `modal.prompt(options)` → `Promise<string|null>`
+
+```js
+const name = await modal.prompt({
+  title: '重命名文件',
+  label: '文件名',          // input 上方的 label 文字
+  value: 'old-name.html',  // 输入框初始值
+  placeholder: '输入新文件名',
+  validate: (v) => {        // 可选校验函数
+    if (!v.trim()) return '文件名不能为空';
+    if (/[\/\\]/.test(v)) return '文件名不能包含 / 或 \\';
+    return null;             // 返回 null 表示通过
+  },
+  confirmText: '确认',      // 默认 '确认'
+});
+// name === string → 用户输入的值（已 trim）
+// name === null   → 用户取消
+```
+
+### 3.3 `modal.alert(options)` → `Promise<void>`
+
+```js
+await modal.alert({
+  title: '提示',
+  message: '复制失败，请手动复制以下链接',
+});
+// 用户点确认或关闭后 resolve
+```
+
+---
+
+## 四、实现方案
+
+### 4.1 HTML 结构
+
+在 `index.html` 中新增一个**通用 modal 容器**（替换现有的 `rename-modal` 和 `delete-modal`）：
+
+```html
+<!-- 通用交互 Modal -->
+<div class="modal-backdrop" id="dialog-modal" hidden aria-hidden="true"
+     role="dialog" aria-modal="true" aria-labelledby="dialog-modal-title">
+  <div class="modal-panel modal-panel-sm">
+    <div class="modal-header">
+      <h2 id="dialog-modal-title"></h2>
+      <button type="button" class="btn btn-small modal-close"
+              id="dialog-modal-close" aria-label="关闭">×</button>
+    </div>
+    <div class="modal-body">
+      <div class="dialog-message" id="dialog-modal-message"></div>
+      <label class="login-field dialog-field" id="dialog-modal-field" hidden>
+        <span id="dialog-modal-label"></span>
+        <input type="text" id="dialog-modal-input" autocomplete="off">
+      </label>
+      <div class="login-error" id="dialog-modal-error" role="alert" hidden></div>
+    </div>
+    <div class="modal-footer">
+      <button type="button" class="btn btn-small" id="dialog-modal-cancel">取消</button>
+      <button type="button" class="btn btn-primary" id="dialog-modal-confirm">确认</button>
+    </div>
+  </div>
+</div>
+```
+
+要点：
+- `dialog-message`：confirm/alert 场景显示消息，prompt 场景可隐藏或共存
+- `dialog-field`：仅 prompt 场景显示（通过 `hidden` 切换）
+- `dialog-modal-cancel`：alert 场景隐藏该按钮（只留确认）
+- 现有的 `rename-modal` 和 `delete-modal` 两个 HTML 块将被移除
+
+### 4.2 CSS 新增
+
+```css
+/* 小尺寸 modal（prompt / confirm / alert） */
+.modal-panel-sm {
+  max-width: 440px;
+}
+
+/* dialog body 内的消息文字 */
+.dialog-message {
+  font-size: 15px;
+  line-height: 1.6;
+  margin: 0;
+}
+
+/* dialog 输入区域的 label+input 间距 */
+.dialog-field {
+  margin-top: 12px;
+}
+```
+
+不再使用 inline style，统一用 `modal-panel-sm` class。
+
+### 4.3 JS 实现
+
+在 `app.js` 中新增 `modal` 对象（约 80 行），核心逻辑：
+
+```js
+const dialogModal = {
+  el: null, input: null, error: null,
+  msg: null, field: null,
+  confirmBtn: null, cancelBtn: null, closeBtn: null,
+  _resolve: null,
+  _mode: null,       // 'alert' | 'confirm' | 'prompt'
+  _validate: null,
+
+  init() {
+    // 缓存 DOM 引用，绑定一次性事件
+    this.el = document.getElementById('dialog-modal');
+    // ... 缓存其他元素 ...
+    this.closeBtn.onclick = () => this._dismiss();
+    this.cancelBtn.onclick = () => this._dismiss();
+    this.el.addEventListener('click', e => {
+      if (e.target === this.el) this._dismiss();
+    });
+    this.input.addEventListener('keydown', e => {
+      if (e.key === 'Enter') this._accept();
+      if (e.key === 'Escape') this._dismiss();
+    });
+    document.addEventListener('keydown', e => {
+      if (e.key === 'Escape' && !this.el.hidden) this._dismiss();
+    });
+  },
+
+  _open(mode, opts) {
+    this._mode = mode;
+    this._resolve = null;
+    // 设置 title、message、field 可见性、按钮文案等
+    // ...
+    this.el.hidden = false;
+    this.el.setAttribute('aria-hidden', 'false');
+    if (mode === 'prompt') { this.input.focus(); this.input.select(); }
+    else { this.confirmBtn.focus(); }
+    return new Promise(resolve => { this._resolve = resolve; });
+  },
+
+  _accept() {
+    if (this._mode === 'prompt') {
+      const val = this.input.value.trim();
+      if (this._validate) {
+        const err = this._validate(val);
+        if (err) { this.error.textContent = err; this.error.hidden = false; return; }
+      }
+      this._close(val);
+    } else {
+      this._close(true);
+    }
+  },
+
+  _dismiss() {
+    this._close(this._mode === 'prompt' ? null : false);
+  },
+
+  _close(result) {
+    this.el.hidden = true;
+    this.el.setAttribute('aria-hidden', 'true');
+    this.error.hidden = true;
+    this._resolve(result);
+  },
+
+  confirm(opts) { return this._open('confirm', opts); },
+  prompt(opts)  { return this._open('prompt', opts);  },
+  alert(opts)   { return this._open('alert', opts);   },
+};
+
+// 在 DOMContentLoaded 中调用 dialogModal.init()
+```
+
+### 4.4 调用方改造
+
+**`doRename` 改造前（~55 行）→ 改造后（~12 行）：**
+
+```js
+async function doRename(container, id, currentName) {
+  const name = await dialogModal.prompt({
+    title: '重命名文件',
+    label: '文件名',
+    value: currentName,
+    validate: v => {
+      if (!v.trim()) return '文件名不能为空';
+      return null;
+    },
+  });
+  if (name === null || name === currentName) return;
+  try {
+    await api(`/api/files/${id}`, { method: 'PUT', body: { name } });
+    toast('重命名成功');
+    loadFiles(container);
+  } catch (e) {
+    toast(e.message, 'error');
+  }
+}
+```
+
+**`doDelete` 改造前（~43 行）→ 改造后（~10 行）：**
+
+```js
+async function doDelete(container, id, fileName) {
+  const ok = await dialogModal.confirm({
+    title: '确认删除',
+    message: `确定要删除 <strong>${escapeHtml(fileName)}</strong> 吗？此操作不可撤销。`,
+    confirmText: '删除',
+    danger: true,
+  });
+  if (!ok) return;
+  try {
+    await api(`/api/files/${id}`, { method: 'DELETE' });
+    toast('删除成功');
+    loadFiles(container);
+  } catch (e) {
+    toast(e.message, 'error');
+  }
+}
+```
+
+---
+
+## 五、影响范围
+
+| 文件 | 变更类型 | 说明 |
+|---|---|---|
+| `public/index.html` | 修改 | 移除 `rename-modal` 和 `delete-modal` 两个 HTML 块，新增通用 `dialog-modal` |
+| `public/css/style.css` | 修改 | 新增 `.modal-panel-sm`、`.dialog-message`、`.dialog-field` 样式 |
+| `public/js/app.js` | 修改 | 新增 `dialogModal` 对象（~80 行），精简 `doRename` / `doDelete`（共减少 ~60 行） |
+
+**不影响的文件**：`server.js`、`mcp-server.js`、`skills-registry.js`、展示型 modal（skill / mcp-config / skills-list）
+
+---
+
+## 六、验收标准
+
+1. 重命名流程：点击重命名 → 弹出 modal → 输入新名称 → 校验不通过显示错误 → 确认后调用 API → 成功 toast + 刷新列表
+2. 删除流程：点击删除 → 弹出确认 modal → 确认按钮为红色 → 确认后调用 API → 成功 toast + 刷新列表
+3. Escape 键 / 点击遮罩 / 点取消 → 关闭 modal，不触发任何操作
+4. 回车键（prompt 场景）→ 等同于点确认
+5. 无 `window.prompt` / `window.confirm` / `window.alert` 调用残留
+6. 深色模式下 modal 显示正常
+7. 移动端 modal 居中显示，不被截断

package/docs/design/013-file-version-history.md

@@ -0,0 +1,324 @@
+# 013 — 文件版本历史
+
+> 状态：设计完成，待实现
+> 关联：问题 21（版本历史）
+> 复杂度：★★★★★（DB + API + JS + CSS）
+
+---
+
+## 一、目标
+
+为每个文件维护版本链。上传同名文件自动覆盖并保留历史版本；支持查看、恢复、删除历史版本。
+
+---
+
+## 二、数据库变更
+
+### 2.1 `files` 表新增 `updated_at`
+
+```sql
+ALTER TABLE files ADD COLUMN updated_at DATETIME DEFAULT CURRENT_TIMESTAMP;
+```
+
+回填：`UPDATE files SET updated_at = created_at WHERE updated_at IS NULL;`
+
+语义：
+- `created_at` = 首次上传时间，创建后不变
+- `updated_at` = 最后一次覆盖上传的时间，每次覆盖刷新
+
+文件列表排序改为 `ORDER BY updated_at DESC`。
+
+### 2.2 新增 `file_versions` 表
+
+```sql
+CREATE TABLE IF NOT EXISTS file_versions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id INTEGER NOT NULL,
+  version INTEGER NOT NULL,
+  stored_name TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  uploaded_by INTEGER,
+  UNIQUE(file_id, version),
+  FOREIGN KEY (file_id) REFERENCES files(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_fv_file_ver ON file_versions(file_id, version DESC);
+```
+
+规则：
+- `files.stored_name` 始终指向**当前版本**文件
+- 覆盖上传时，先把旧 `stored_name` 写入 `file_versions`，再更新 `files` 主记录
+- `version` 从 1 递增，不设上限
+- 删除文件时 CASCADE 清理版本记录 + 遍历删磁盘文件
+
+### 2.3 迁移策略
+
+在 `db.serialize()` 块中顺序执行：
+
+```
+1. PRAGMA table_info(files) → 检查并 ADD COLUMN updated_at
+2. 回填 updated_at
+3. CREATE TABLE IF NOT EXISTS file_versions
+4. CREATE INDEX IF NOT EXISTS idx_fv_file_ver
+```
+
+无需数据迁移，对现有文件透明。
+
+---
+
+## 三、同名文件自动覆盖逻辑
+
+### 3.1 触发条件
+
+`POST /api/files/upload` 和 `POST /api/files/upload-json` 中，写入数据库前检查：
+
+```js
+const existing = await dbGet(
+  'SELECT id, stored_name, size, uploaded_by FROM files WHERE original_name = ?',
+  [decodedName]
+);
+```
+
+- **存在同名文件** → 执行覆盖流程（§3.2）
+- **不存在** → 保持原有新建逻辑不变
+
+### 3.2 覆盖流程
+
+```
+1. 计算 version 号：
+   SELECT COALESCE(MAX(version), 0) + 1 FROM file_versions WHERE file_id = existing.id
+   → nextVer
+
+2. 备份当前版本到 file_versions：
+   INSERT INTO file_versions (file_id, version, stored_name, size, uploaded_by)
+   VALUES (existing.id, nextVer, existing.stored_name, existing.size, existing.uploaded_by)
+
+3. 新文件写入磁盘（新 stored_name）
+
+4. 更新 files 主记录：
+   UPDATE files SET stored_name = ?, size = ?, updated_at = CURRENT_TIMESTAMP
+   WHERE id = existing.id
+
+5. 返回覆盖结果（含 version 信息）
+```
+
+**响应变化**：覆盖时返回 `{ overwritten: true, id, version: nextVer + 1, ... }`，前端据此提示「已更新为第 N 版」而非「上传成功」。
+
+### 3.3 文件类型校验
+
+同名覆盖时仍需校验扩展名一致。如果同名但扩展名不同（如已有 `a.html` 又上传 `a.md`），拒绝覆盖并提示「文件类型不匹配」，走新建流程。
+
+---
+
+## 四、API 设计
+
+### 4.1 新增端点
+
+| 方法 | 路径 | 鉴权 | 说明 |
+|---|---|---|---|
+| `GET` | `/api/files/:id/versions` | 需登录 | 列出版本历史 |
+| `GET` | `/api/files/:id/versions/:ver/content` | 需登录 | 获取历史版本原文 |
+| `GET` | `/api/files/:id/versions/:ver/render` | 需登录 | 渲染历史版本 |
+| `POST` | `/api/files/:id/versions/:ver/restore` | 需登录 | 恢复到指定版本 |
+| `DELETE` | `/api/files/:id/versions/:ver` | 需登录 | 删除指定历史版本 |
+
+### 4.2 修改现有端点
+
+| 端点 | 变更 |
+|---|---|
+| `POST /api/files/upload` | 上传前查同名 → 覆盖流程 |
+| `POST /api/files/upload-json` | 上传前查同名 → 覆盖流程 |
+| `GET /api/files` | 返回字段增加 `version_count`；排序改为 `updated_at DESC` |
+| `DELETE /api/files/:id` | 删除前清理 `file_versions` 及对应磁盘文件 |
+
+### 4.3 响应格式
+
+**`GET /api/files/:id/versions`**
+
+```json
+{
+  "file_id": 42,
+  "current": {
+    "stored_name": "1749...html",
+    "size": 1234,
+    "updated_at": "2026-06-08T14:30:00Z"
+  },
+  "versions": [
+    {
+      "id": 7,
+      "version": 1,
+      "size": 1000,
+      "created_at": "2026-06-07T10:00:00Z"
+    },
+    {
+      "id": 8,
+      "version": 2,
+      "size": 1100,
+      "created_at": "2026-06-08T09:00:00Z"
+    }
+  ]
+}
+```
+
+**覆盖上传响应**
+
+```json
+{
+  "id": 42,
+  "overwritten": true,
+  "version": 3,
+  "original_name": "report.html",
+  "file_type": "html",
+  "size": 1234,
+  "is_public": 1,
+  "share_key": "abc12345"
+}
+```
+
+### 4.4 恢复版本流程
+
+`POST /api/files/:id/versions/:ver/restore`
+
+```
+1. 从 file_versions 取目标版本的 stored_name
+2. 读目标版本文件内容
+3. 写入新磁盘文件（新 stored_name）
+4. 当前版本备份到 file_versions（nextVer）
+5. 更新 files.stored_name / size / updated_at 指向新文件
+6. 返回成功
+```
+
+注意：restore 时复制文件内容到新 stored_name，这样 `file_versions` 中的记录可安全删除不影响当前版本。
+
+### 4.5 删除版本流程
+
+`DELETE /api/files/:id/versions/:ver`
+
+```
+1. 查 file_versions 获取 stored_name
+2. 删除磁盘文件
+3. DELETE FROM file_versions
+```
+
+---
+
+## 五、文件列表页变更
+
+### 5.1 SQL 查询
+
+```sql
+SELECT f.*,
+  (SELECT COUNT(*) FROM file_versions WHERE file_id = f.id) AS version_count
+FROM files f
+ORDER BY f.updated_at DESC
+```
+
+### 5.2 列表项展示
+
+`file-subline` 增加版本信息：
+
+```
+HTML | 公开 | 12.3 KB · v3 · 2 分钟前更新
+```
+
+- `v1` 不显示（无历史版本）
+- `v2+` 显示版本号
+
+### 5.3 前端变量
+
+`allFiles` 中每个文件对象增加 `version_count` 字段，`renderFileList()` 中根据 `version_count > 0` 决定是否渲染版本 badge。
+
+---
+
+## 六、预览页 — 版本历史面板
+
+### 6.1 布局
+
+在预览页顶栏扩展行新增两个按钮：
+
+```
+[上传新版本]  [历史 v3 ▾]
+```
+
+点击「历史」按钮，右侧滑出面板：
+
+```
+┌──────────────────────────────────────────────────────┐
+│ ← 返回  文件名.html  [渲染|源码] [下载] [上传新版本] [历史 v3 ▾] │
+├──────────────────────────────────┬───────────────────┤
+│                                  │ 版本历史           │
+│                                  │                   │
+│          iframe 预览              │ ● 当前 (v3)       │
+│                                  │   12.3 KB · 刚刚   │
+│                                  │                   │
+│                                  │ ○ v2              │
+│                                  │   10.1 KB · 2h前   │
+│                                  │   [查看] [恢复] [删除]│
+│                                  │                   │
+│                                  │ ○ v1              │
+│                                  │   8.2 KB · 昨天    │
+│                                  │   [查看] [恢复] [删除]│
+└──────────────────────────────────┴───────────────────┘
+```
+
+### 6.2 面板交互
+
+| 操作 | 行为 |
+|---|---|
+| **查看** | iframe 加载 `/api/files/:id/versions/:ver/render`，面板保持打开 |
+| **恢复** | 二次确认 → `POST /versions/:ver/restore` → 刷新版本列表 + iframe |
+| **删除** | 二次确认 → `DELETE /versions/:ver` → 从列表移除该行 |
+| **上传新版本** | 触发文件选择器 → 调用 `POST /api/files/:id/overwrite` → 刷新 |
+| **关闭面板** | 点击遮罩 / Escape / 再次点击「历史」按钮 |
+
+### 6.3 预览页「上传新版本」
+
+预览页增加隐藏 `<input type="file">`，点击「上传新版本」触发。
+
+调用新的 `POST /api/files/:id/overwrite` 端点（multipart），流程与首页上传类似，但目标是覆盖而非新建。
+
+---
+
+## 七、MCP 工具扩展
+
+### 7.1 修改现有工具
+
+`upload_file` 增加可选参数 `overwriteFileId`：
+
+- 提供 `overwriteFileId` → 调用覆盖上传 API
+- 不提供 → 保持原行为（同名自动覆盖逻辑在服务端生效，MCP JSON 上传也会触发）
+
+### 7.2 新增工具
+
+| 工具 | 参数 | 说明 |
+|---|---|---|
+| `list_file_versions` | `fileId: number` | 列出版本历史 |
+| `restore_file_version` | `fileId: number, version: number` | 恢复到指定版本 |
+
+---
+
+## 八、实现步骤
+
+| 步骤 | 内容 | 涉及文件 |
+|---|---|---|
+| 1 | 数据库迁移（`updated_at` + `file_versions` 表） | `server.js` |
+| 2 | 覆盖上传逻辑（同名自动覆盖 + `/overwrite` 端点） | `server.js` |
+| 3 | 版本 CRUD API（列表/内容/渲染/恢复/删除） | `server.js` |
+| 4 | 修改删除文件端点（清理版本） | `server.js` |
+| 5 | 修改文件列表 API（`version_count` + `updated_at` 排序） | `server.js` |
+| 6 | 前端：文件列表显示版本号 | `app.js` |
+| 7 | 前端：预览页版本面板 UI + 交互 | `app.js`, `index.html`, `style.css` |
+| 8 | MCP 工具扩展 | `mcp-server.js` |
+
+---
+
+## 九、边界情况
+
+| 场景 | 处理 |
+|---|---|
+| 同名文件但扩展名不同 | 拒绝覆盖，提示「文件类型不匹配」 |
+| 版本面板查看历史版本时又上传新版本 | 刷新版本列表，iframe 回到当前版本 |
+| 恢复已被删除的版本 | 404 |
+| 删除所有历史版本 | 面板显示「仅有当前版本」 |
+| 并发覆盖同一文件 | SQLite 写锁串行化，后到者基于最新版本号递增，不会丢版本 |
+| MCP 上传同名文件 | 与 Web 上传走同一套自动覆盖逻辑 |