first commit

doc/ci-auto-deploy.md

@@ -0,0 +1,57 @@
+# kkFileView master 自动部署
+
+当前线上 Windows 服务器的实际部署信息如下：
+
+- 部署根目录：`C:\kkFileView-5.0`
+- 运行 jar：`C:\kkFileView-5.0\bin\kkFileView-<当前项目版本>.jar`
+- 启动脚本：`C:\kkFileView-5.0\bin\startup.bat`
+- 运行配置：`C:\kkFileView-5.0\config\test.properties`
+- 健康检查地址：`http://127.0.0.1:8012/`
+
+当前自动部署链路采用服务器拉最新源码并本机编译的方式：
+
+1. 通过 WinRM 连接 Windows 服务器
+2. 在服务器上的源码目录执行 `git fetch/reset/clean`，同步到 `origin/$KK_DEPLOY_BRANCH`（默认 `master`）
+3. 使用服务器上的 JDK 21 和 Maven 执行 `mvn clean package -Dmaven.test.skip=true`
+4. 备份线上 jar，替换为新构建产物
+5. 使用现有 `startup.bat` 重启，并做健康检查
+6. 如果健康检查失败，则自动回滚旧 jar 并重新拉起
+
+## 需要配置的 GitHub Secrets
+
+- `KK_DEPLOY_HOST`
+- `KK_DEPLOY_USERNAME`
+- `KK_DEPLOY_PASSWORD`
+
+以下部署参数当前由 workflow 从 GitHub Secrets 读取；如果未单独配置，则使用脚本默认值：
+
+- `KK_DEPLOY_PORT=5985`
+- `KK_DEPLOY_ROOT=C:\kkFileView-5.0`
+- `KK_DEPLOY_HEALTH_URL=http://127.0.0.1:8012/`
+
+下面这些非敏感参数可以通过 workflow env 或 GitHub Variables 覆盖；未配置时会使用默认值：
+- `KK_DEPLOY_REPO_URL=https://github.com/kekingcn/kkFileView.git`
+- `KK_DEPLOY_BRANCH=master`
+- `KK_DEPLOY_SOURCE_ROOT=C:\kkFileView-source`
+- `KK_DEPLOY_JAVA_HOME=C:\Program Files\jdk-21.0.2`
+- `KK_DEPLOY_GIT_EXE=C:\kkFileView-tools\git\cmd\git.exe`
+- `KK_DEPLOY_MVN_CMD=C:\kkFileView-tools\maven\bin\mvn.cmd`
+- `KK_DEPLOY_MAVEN_SETTINGS=`
+
+如果服务器到 GitHub 的拉取速度不稳定，也可以把 `KK_DEPLOY_REPO_URL` 改成你自己的 Git 镜像地址。
+如果服务器访问 Maven Central 不稳定，也可以通过 `KK_DEPLOY_MAVEN_SETTINGS` 指向自定义 `settings.xml`，切换到就近镜像仓库。
+
+## 服务器前置环境
+
+服务器需要具备以下工具：
+
+- Git for Windows（推荐安装在 `C:\kkFileView-tools\git`）
+- Apache Maven 3.9.x（推荐安装在 `C:\kkFileView-tools\maven`）
+- JDK 21（当前线上已存在：`C:\Program Files\jdk-21.0.2`）
+
+## Workflow
+
+新增 workflow：`.github/workflows/master-auto-deploy.yml`
+
+- 触发条件：`push` 到 `master`，或手动 `workflow_dispatch`
+- 部署方式：WinRM + 服务器源码同步 + 服务器本机 Maven 编译 + jar 替换/回滚

doc/e2e-improvement-checklist.md

@@ -0,0 +1,44 @@
+# E2E 完善清单（基于 PR342 回归经验）
+
+## 背景
+本次手工回归已经验证了以下关键链路：
+- TXT
+- XLSX
+- ZIP
+- PDF
+- DOCX
+- MP4
+- CAD / DXF
+
+但当前 GitHub CI 中，自动化 E2E 仅覆盖了其中一部分，且大多只断言 HTTP 200，没有校验最终预览效果。
+
+## 本次落地目标
+
+### 1. 补齐缺失的关键链路
+- [x] PDF 预览 smoke
+- [x] MP4 预览 smoke
+- [x] CAD / DXF 预览 smoke
+
+### 2. 升级断言方式
+- [x] 不再只看 `status === 200`
+- [x] 增加标题/页面关键字断言，确认命中了正确预览模板
+- [x] 对 PDF / DOCX / CAD 增加“等待页 -> 最终页面”的轮询兼容
+
+### 3. 补齐 CI 所需 fixture
+- [x] `sample.pdf` 进入 required fixture 清单
+- [x] `sample.mp4` 进入 required fixture 清单
+- [x] `text.dxf` 进入 required fixture 清单
+- [x] 将 MP4 与 DXF fixture 作为仓库内静态样例纳入 CI
+
+### 4. 后续可继续增强（本次未全部落地）
+- [ ] 为 PDF / Office / CAD 增加截图型 nightly artifact
+- [ ] 为 `/picturesPreview` 增加独立 smoke
+- [ ] 为 OFD 增加稳定 fixture 和 smoke case
+- [ ] 为媒体预览增加更多格式（如 wav / mp3 / mov）
+- [ ] 为 CAD 增加第二份标准样例，避免单样例偏差
+- [ ] 将当前 HTML 测试报告模板收敛成 nightly 自动产物
+
+## 预期收益
+- 让 CI 覆盖这次 PR342 真正验证过的关键主链路
+- 避免未来出现“CI 绿了，但 PDF / MP4 / CAD 实际挂了”的情况
+- 让 E2E 更接近用户真实感知，而不是仅验证接口可达