Skip to content

[1.5.2 Patch] 全页面功能说明增强并支持“下次默认折叠”,减少说明卡片遮挡主界面 #70

Description

@weidonglang

用户反馈 / 新需求

当前部分页面存在类似说明卡片,例如总览页:

总览
info
这个功能能做什么
只读展示当前环境和运行时状态。
确认级别:无需确认
只读或低风险操作通常不需要备份。
这个功能不会做什么
不会修改系统级设置,也不会删除用户数据。
不会静默请求管理员权限。

用户认为这类说明本身没有问题,尤其对新用户很有必要。但希望:

  1. 每个主要页面、每个页面下的重要子功能都应有更详细的说明。
  2. 说明不应该一直默认展开占用视野。
  3. 增加一个可勾选选项,例如“下次进入此页面默认折叠”。
  4. 勾选后,下次打开该子功能页面时说明卡片默认缩成一个小条,不影响主界面使用。
  5. 用户仍然可以随时手动展开查看。

问题判断

当前功能说明方向是对的,但需要从“固定说明卡片”升级为“可折叠、可记忆、分层展示的功能帮助系统”。

这属于 1.5.2 Patch 的体验增强和安全说明完善,不是新增业务功能。

修复目标

实现全页面功能说明增强:

首次进入页面:默认展开详细说明
用户勾选“下次默认折叠”:保存偏好
后续进入同一页面/子功能:默认折叠成小条
用户点击小条:随时展开查看

同时补齐每个主要页面及关键子功能的说明内容。

一、说明卡片内容要求

每个页面或关键子功能的说明至少包含:

这个功能能做什么
适合什么场景
第一步应该点哪里
确认级别
是否只读
是否需要备份
这个功能不会做什么
可能影响什么
失败后怎么办
相关安全建议

说明不应只写口号,例如“请谨慎使用”。必须说明具体风险和具体下一步。

二、折叠交互要求

说明卡片应有三种状态:

1. expanded

完整展开,展示详细说明。

2. collapsed

折叠成小条,只显示:

页面名称 + 风险等级 + 简短一句话 + 展开按钮

示例:

总览 · info · 只读展示当前环境状态。展开说明

3. dismissed-for-next-time

用户勾选:

下次进入此页面默认折叠

保存后,下次进入该页面默认 collapsed。

注意:不建议彻底隐藏说明,因为用户可能需要随时查看。

三、偏好保存要求

需要本地保存每个页面 / 子功能的说明展开偏好。

建议结构:

{
  "featureHelpPreferences": {
    "overview": "collapsed",
    "doctor": "expanded",
    "ports": "collapsed",
    "runtimes": "collapsed",
    "environment": "expanded",
    "project": "collapsed",
    "maintenance.cleanup": "collapsed",
    "toolbox.command": "collapsed"
  }
}

要求:

四、页面覆盖范围

至少覆盖以下主页面:

总览
环境医生
端口管理
版本管理
环境可靠性中心
项目启动向导
工具链
平台/镜像
C 盘急救
工具箱
命令面板
MySQL 修复中心
AI Agent / CLI 痕迹分析
C 盘扩容安全向导
版本更新
卸载本程序

五、关键子功能说明覆盖

每页下的重要子功能也要有说明或局部帮助,至少覆盖:

总览

  • 当前实际生效环境。
  • 系统快照。
  • 安装根目录。
  • 开源工具推荐。

环境医生

  • 一键诊断。
  • 安全修复。
  • 导出 Markdown / JSON。
  • 复制报告。

端口管理

  • 扫描端口。
  • 占用提醒。
  • 快捷筛选。
  • 端口详情。
  • 结束进程。
  • 最近 7 天历史。

版本管理

  • 本机环境发现。
  • JDK 管理。
  • Python 管理。
  • Python 环境分析。
  • Python 完整性检查。
  • 生成可审计修复计划。
  • Node.js 管理。
  • Maven / Gradle 构建工具。
  • 强验证所有运行时。

环境可靠性中心

  • 检查可靠性。
  • 导出报告。
  • Java 稳定修复计划。
  • 写入用户级 JAVA_HOME / PATH。
  • 环境备份与恢复。

项目启动向导

  • 选择项目文件夹。
  • 分析项目。
  • 生成 VS Code / IDEA 配置预览。
  • IDEA 配置只读读取。
  • Nacos / Nexus Java 验证。
  • 项目端口配置分析。

C 盘急救

  • 只读扫描。
  • 大文件分析。
  • 重复文件扫描。
  • 桌面归档计划。
  • 下载归档计划。
  • 空间搬家。
  • Junction。
  • 回滚记录。
  • 分区扩容检测。

工具箱

  • Docker / WSL 检查。
  • 数据库与本地服务。
  • MySQL 修复中心。
  • 网络诊断。
  • 下载缓存。
  • 命令面板。
  • AI Agent / CLI 痕迹。
  • 版本更新。
  • 卸载本程序。

六、说明详细程度要求

示例:总览说明可以扩展为:

这个页面用于只读查看当前 Windows 开发环境状态,包括默认安装根目录、已发现运行时、端口记录、PATH 警告和当前实际生效工具。适合你刚打开软件时先判断环境是否混乱。

第一步建议:先看“当前实际生效环境”,确认 java、python、node、maven、gradle、go 是否来自你预期的路径。

确认级别:无需确认。
风险等级:info / 只读。
是否需要备份:不需要。

这个页面不会修改系统级设置,不会删除用户数据,不会静默请求管理员权限,也不会自动修复环境变量。

七、UI 要求

  • 说明卡片默认不要过高。
  • 折叠状态要明显但不遮挡主内容。
  • “下次进入此页面默认折叠”放在说明卡片底部。
  • 提供“全部说明默认折叠 / 全部说明默认展开”设置入口,如实现成本低可加入。
  • 页面切换时保持用户偏好。
  • 不要用弹窗频繁打断用户。

八、与首次启动安全声明的关系

该功能说明系统不能替代 #68 首次启动安全声明弹窗。

两者关系:

九、测试要求

新增测试或手动验证:

  1. 首次进入页面,说明默认展开。
  2. 勾选“下次进入此页面默认折叠”后,切换页面再回来默认折叠。
  3. 重启软件后仍保持折叠偏好。
  4. 点击折叠小条可以重新展开。
  5. 配置损坏时回退为默认展开。
  6. 每个主页面都有说明。
  7. 关键子功能至少有简短帮助或局部说明。
  8. 折叠说明不影响主要按钮和表格使用。
  9. 首次启动安全声明 [1.5.2 Patch] 首次启动强制安全声明弹窗:阅读确认后才允许进入主界面 #68 仍然独立生效。

十、文档更新

更新:

  • docs/user-guide.md
  • docs/troubleshooting.md
  • docs/release-v1.5.2.md
  • docs/issues-57-70.md
  • 如有必要,更新 docs/software-copyright/04_用户操作手册.md

说明:

  • 页面功能说明可以折叠。
  • 如何恢复查看说明。
  • 为什么高风险功能仍需要单独确认。

十一、验收标准

  • 每个主要页面都有更详细的功能说明。
  • 关键子功能也有说明或局部帮助。
  • 用户可以勾选“下次进入此页面默认折叠”。
  • 折叠偏好本地持久化。
  • 折叠后说明缩成小条,不影响视野。
  • 仍可随时展开查看。
  • 不影响 [1.5.2 Patch] 首次启动强制安全声明弹窗:阅读确认后才允许进入主界面 #68 首次启动安全声明。
  • npm run build 通过。
  • cargo test --all-targets 通过。
  • release notes 记录该交互优化。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions