完善项目文档并修复响应式布局
This commit is contained in:
+48
-8
@@ -1,5 +1,7 @@
|
||||
# Web Tools
|
||||
|
||||
[English](README.md)
|
||||
|
||||
一个匿名访问、自托管的浏览器本地工具箱。支持多人同时使用；除全局导航顺序外，文本、密钥、文件、图片和计算结果均只存在于各自浏览器中，不会发送到服务端。
|
||||
|
||||
当前应用版本：`0.0.6`。
|
||||
@@ -53,6 +55,20 @@ CHANGELOG.md 版本变更、修复和验证记录
|
||||
- `/setting` 是固定但不公开显示的管理入口；项目没有登录、收藏、赞助或用户系统。
|
||||
- 页面必须保持统一 UI，并兼容桌面端和移动端竖屏。
|
||||
|
||||
## 核心功能契约
|
||||
|
||||
以下行为属于已经发布的兼容性约束。修改时必须同步实现、页面提示、自动化测试和本文档，不能只调整界面文案。
|
||||
|
||||
- ASCII/Hex 工具按 UTF-8 字节转换文本；Hex 输入接受连续形式，或以空白、英文逗号、中文逗号分隔的片段，并允许每个片段使用可选的 `0x` 前缀。无效 UTF-8 字节必须报错，不能静默替换字符。
|
||||
- Base64 支持标准和 URL-safe 形式；解码结果可显示为严格 UTF-8、连续 Hex 或 `0x48, 0x9F, ...` 字节数组。无效字符、错误填充和非规范编码必须报错。
|
||||
- AES-128-CMAC 密钥必须恰好为 16 字节。密钥和 Hex 消息接受连续 Hex，或空格、换行、英文/中文逗号分隔，并允许片段使用可选的 `0x` 前缀；计算语义遵循 RFC 4493。
|
||||
- CRC 支持 BIN 和多 block Intel HEX，提供 CRC-8/16/32/64 预设，并允许自定义 `Width`、`Poly`、`Init`、`XorOut`、`RefIn` 和 `RefOut`。总 CRC 对按地址升序拼接的有效数据计算，不填充地址空洞，同时输出每个 block 的结果。
|
||||
- 固件 Hash 只接受 Intel HEX，输出 SHA-256 和 SHA-512。“有效数据”与“Block 校验头”模式的确切字节流见“固件 Hash 固定语义”；默认校验头字节序为 Big Endian。
|
||||
- RSA 只允许 2048、3072、4096 位密钥，公钥指数固定为 65537。优先使用 Web Crypto，必要时使用由 `crypto.getRandomValues` 提供随机种子的 `node-forge` 回退；公钥为 SPKI PEM，私钥为 PKCS#8 PEM，N/E 可分别显示为连续 Hex 或代码字节数组。
|
||||
- 安全随机数必须来自浏览器 `crypto.getRandomValues`，长度为 1 至 65,536 字节，支持连续 Hex、空格 Hex 和代码字节数组；切换显示格式不得重新生成随机数据。
|
||||
- JSON/XML 的格式化、压缩和校验均在浏览器本地完成。语法着色超过资源限制时只能降级为完整纯文本，不能截断结果。
|
||||
- 文件选择、文件更换、清空、模式切换和组件卸载都可能使异步任务失效。旧 Worker、旧图像解码和旧密钥生成结果不得覆盖当前输入或已清空状态。
|
||||
|
||||
## 多人使用与状态边界
|
||||
|
||||
- 每个浏览器标签页拥有独立的 Vue 组件状态、文件对象、图像对象和 Web Worker。不同用户、浏览器或标签页不会共享工具输入与结果。
|
||||
@@ -163,6 +179,21 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
|
||||
|
||||
脚本不会读取、覆盖或删除 `C:\ProgramData\WebTools\data`。PowerShell 窗口关闭后前台服务会停止；如使用 Windows 计划任务，应让任务执行 `web-tools.ps1 start`，更新时停止任务、运行 `web-tools.ps1 update -NoStart`，然后重新启动任务。
|
||||
|
||||
### Windows 单 EXE 交付状态
|
||||
|
||||
当前版本**不交付 Windows 单 EXE**。正式支持的部署方式仍是 Docker，或 Windows 上的 Node.js、Git 与 `web-tools.ps1`。对于自用 Windows Server，现有脚本更容易检查、更新和排障，因此单 EXE 不是必要条件。
|
||||
|
||||
若后续明确需要把程序交付给没有 Node.js 环境的 Windows 用户，建议采用 Node.js Single Executable Application（SEA），不要为本项目引入 Electron。实现时至少需要：
|
||||
|
||||
1. 增加专用的 EXE 启动入口，并把生产 `dist/`、工具目录和默认导航配置作为只读资源嵌入。
|
||||
2. 抽象静态资源读取方式，使 Node 服务既能读取开发时的文件系统，也能读取 EXE 内嵌资源。
|
||||
3. 增加 SEA 配置、注入工具（通常为 `postject`）、`build:exe` 脚本以及 Windows x64/ARM64 分架构构建。
|
||||
4. 继续把 `navigation.json` 放在 EXE 外部的可写数据目录，默认使用 `C:\ProgramData\WebTools\data`，升级 EXE 时不得覆盖它。
|
||||
5. 增加 Windows Server 启动、端口、静态资源、`/setting`、更新替换和杀毒软件兼容性冒烟测试。
|
||||
6. 正式对外分发时补充 EXE 图标/版本资源，并考虑 Authenticode 代码签名；未签名程序可能触发 SmartScreen 警告。
|
||||
|
||||
这项改造对源码体积影响不大，通常只是数十 KB 级的入口、资源适配和构建脚本，并增加少量开发依赖；真正明显的是发布产物。每个架构的 EXE 会包含 Node.js 运行时，常见为约 60-100 MB 未压缩、约 30-60 MB 压缩，具体随 Node 版本和资源大小变化。EXE 和中间产物必须保持在 `.gitignore` 或发布目录中，不提交到 Git，因此仓库不会明显膨胀；增加的主要成本是分架构构建、签名、测试和更新维护。
|
||||
|
||||
## 启动故障排查
|
||||
|
||||
- `ENOENT ... dist\\index.html`：当前目录只有源码或尚未生成生产前端。先执行 `npm.cmd ci --include=dev` 和 `npm.cmd run build`，再启动服务；直接执行 `node server\\index.mjs` 不会替代构建步骤。
|
||||
@@ -364,18 +395,27 @@ AI 不应仅修改 `dist/`；必须修改源码并重新构建。不得覆盖或
|
||||
|
||||
处理多人访问、文件工具或异步计算时，还必须检查本文档中的“多人使用与状态边界”和“资源限制”，避免重新引入共享状态、旧任务覆盖新输入或无上限解析。
|
||||
|
||||
完成任务后至少报告：修改的工具、数据格式选择、测试和构建结果、容器包路径及 SHA-256。涉及 UI 的改动还要进行桌面和移动端浏览器验收。
|
||||
完成任务后至少报告：修改内容、关键数据格式选择，以及实际执行的测试和构建结果。只有在任务要求制作发布包时，才需要报告容器包/ZIP 路径及 SHA-256。涉及 UI 的改动还要进行桌面、中间宽度和移动端浏览器验收。
|
||||
|
||||
## 版本与发布
|
||||
|
||||
应用版本的权威来源是 `package.json`。发布新版本时：
|
||||
应用版本的唯一权威来源是 `package.json`。`package-lock.json` 记录完整依赖树、下载地址和完整性摘要，供 `npm ci` 复现安装；其中项目自身的版本会在文件顶部和 `packages[""]` 中各出现一次，其余 `version` 都是第三方依赖版本，不应手工统一修改。
|
||||
|
||||
1. 使用 `npm version patch --no-git-tag-version` 或按兼容性选择 minor/major，使 `package.json` 与 `package-lock.json` 同步。
|
||||
2. 更新 `docker-compose.yml` 中的镜像标签。
|
||||
3. 更新本文档中的当前版本和离线镜像文件名。
|
||||
4. 在 `CHANGELOG.md` 记录用户可见变更、重要修复和验证结果。
|
||||
5. 运行测试、生产构建和依赖审计。
|
||||
6. 重新制作源码/容器部署 ZIP，并生成 SHA-256。
|
||||
使用 `npm version patch --no-git-tag-version`（或按兼容性选择 minor/major）可以同步更新 `package.json` 与 `package-lock.json`。按当前工程结构，一次完整版本发布需要更新以下 5 个已跟踪文件：
|
||||
|
||||
1. `package.json`
|
||||
2. `package-lock.json`
|
||||
3. `docker-compose.yml` 中的镜像标签
|
||||
4. `README.zh-CN.md` 中的当前版本和离线镜像文件名
|
||||
5. `CHANGELOG.md`
|
||||
|
||||
`README.md` 不硬编码版本号，而是指向 `package.json`，因此无需为每次版本升级修改。`AppSidebar.vue` 构建时直接读取 `package.json`，无需手工改其中的版本字符串。发布新版本时：
|
||||
|
||||
1. 先更新版本号，再同步镜像标签、本文档和 `CHANGELOG.md`。
|
||||
2. 运行 `npm run check` 和 `npm audit --audit-level=low`。
|
||||
3. 重新生成未跟踪的 `dist/` 生产构建。
|
||||
4. 重新制作源码/容器部署 ZIP，以及任务要求的可选 Docker 镜像 tar，并生成 SHA-256。
|
||||
5. 检查发布包不包含 `node_modules`、运行数据、令牌、`.env` 或其他本机文件。
|
||||
|
||||
版本号固定显示在左侧导航底部；版权信息 `Copyright © mid All Rights Reserved.` 固定显示在所有页面底部。第三方许可保留在 `THIRD_PARTY_NOTICES.md`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user