# 0.28.0 · 云岚 Web 成长手记

本次重做的是 **DSH 设置 → 内置插件 → 云岚养成**，不是原生桌宠的七页成长窗口。现有原生 helper、模型、存储格式及成长计算规则均不变。

## 信息架构

- **成长概览**：等级与阶段、真实升级进度、五阶段路线、连续天数/对话/工具调用、四维属性、习惯线索和最新回顾。
- **成长回顾**：按全部/阶段成长/日常回顾筛选本地最近 20 条记录。
- **数据与隐私**：详细计数、档案时间、隐私范围说明、统计摘要导出、独立的清零确认区。

设计采用低饱和岚青色、清晰标题、统一卡片间距和原创云朵矢量装饰。样式只作用于 `.ylg` 根元素；使用容器查询适应窄设置栏，提供宽屏双列、深浅色及减少动态效果规则。阶段与数字仍来自原来的本地数据接口，没有虚构趋势或展示用统计数字。

属性说明直接对应现有公式：体力来自有效会话时长，灵性来自工具与项目多样性，亲和来自对话/审批互动，定力来自已结束对话的成功占比。这是统计映射，不是心理测量、通用模型训练或真实能力评分。

## 分层与边界

| 层 | 入口 | 责任 |
| --- | --- | --- |
| 展示模型 | [model.js](../web/model.js) | 防御式规范化、阶段元数据、时间/进度/计数边界、导出白名单 |
| 网络 | [api.js](../web/api.js) | 同源 GET/POST、HTTP 与业务成功校验、超时/取消、安全错误文本 |
| 生命周期 | [hooks.js](../web/hooks.js) | 串行轮询、可见性暂停、卸载清理、并发与重置隔离 |
| 页面编排 | [App.jsx](../web/App.jsx) | 页签、加载/错误/陈旧数据/存储健康、键盘导航 |
| 展示组件 | [components](../web/components/Overview.jsx) | 概览、阶段、回顾、数据管理；不直接读写真实档案 |
| 视觉系统 | [styles.css](../web/styles.css) | 局部设计 token、容器查询、深浅色及可见焦点 |
| 宿主适配 | [index.jsx](../web/index.jsx) | 保持原有三个插件设置 slot；没有全局悬浮层 |
| 构建 | [build-client.mjs](../tools/build-client.mjs) | 将源码打包为宿主可执行工厂，React 由宿主提供 |

[生成产物](../lib/client.js) 仍处于原来的 `./client` 导出路径，保留 `window.__ModuleLoader__.load` 工厂契约。源码重构不要求修改 DSH 应用壳、插件启用状态或认证信息。JSX/CSS 固定 LF，构建不加入绝对路径、构建时间或用户信息。

## 网络、并发和操作安全

- 首次加载后，每轮请求完成才安排下一次轮询，默认间隔 15 秒；不叠加请求。
- 页面隐藏暂停普通轮询；恢复时再读取。已明确提交的清零不因页面隐藏而被重复提交。
- 请求有超时、取消与版本隔离；卸载会清理轮询、监听器和请求，旧响应不能覆盖清零后的新状态。
- 读取失败保留上次成功数据并提示陈旧；没有成功数据时显示错误/重试，而非用示例数字填充。
- 清零必须展开确认并准确输入「清零」，只有 HTTP 成功、`ok: true` 和有效的新 state 才显示成功。
- 清零超时不声称档案原封不动，也不自动重试；提醒先刷新核对。已有服务器备份/提交回滚逻辑保持不变。
- 档案健康异常会提示并禁用清零；不会把后端可能含本机路径的原始错误直接展示。
- 取消、Escape、完成清零后，在 React 提交完 UI 更新后恢复键盘焦点。

## 隐私范围

摘要导出使用明确白名单，仅有版本、经验、等级/阶段、连续天数、计数、四维属性和创建/更新时间；**不含项目名/ID、工具名、习惯原文、回顾、会话或任何任意后端扩展字段**。导出由浏览器下载到本机，不上传。下载请求不等于浏览器已落盘，界面文案要求在下载列表核对。

本页清零只处理成长档案，**不是**清除原生桌宠聊天、语音、记忆或所有 DSH 会话。页面已明确区分这些范围。没有变更云端、麦克风或记忆授权，测试不接触真实成长档案。

## 开发与验证

```powershell
npm ci
npm run build:client
npm run check:client
npm test
npm run preview:client
```

预览输出到已忽略目录 `native/verification/web-dashboard-preview.html`。它是单文件离线合成预览，React 与样式打包在文件内，无服务器、无远程字体、无真实档案读取；所有数据来自 [显式测试夹具](../test/fixtures/growth-view.js)。预览里的清零只重置演示对象。**这份预览不等于当前 DSH GUI 的实机验证。**

本轮 Node 测试 **61/61 通过**：保留原有后端/存储测试，新增规范化、接口、轮询控制器、真实 React StrictMode、实际生成客户端的 DOM 交互、键盘/焦点、HTML 转义、保护性清零和摘要导出测试。构建产物一致性校验通过。CI 已增加依赖安装与构建一致性检查。以上是本地验证记录，不等于后续 GitHub 发布提交的 CI 结果；远端状态应以该提交的 Actions 为准。

## 当前 GUI 验证边界

当前会话未发现同一 checkout 的 `dev:web` 监听器，不承诺修改后自动更新。安装版源码中存在已构建客户端文件变化通知机制，但是否在当前进程挂载、生效仍需实际验证。

验证时使用**现有 DSH 窗口**刷新后打开云岚养成页，核对页首「一起，慢慢长大。」和插件根元素 `data-ui-version="0.28.0"`，检查概览/回顾/数据页签及窄宽/深浅色布局。不可把新启动的替代服务器当作当前 GUI 已更新。

最初浏览器工具返回 `Target.createTarget` 路由失败且没有可用标签。经用户允许打开 Tabbit 窗口后，已在真实浏览器打开**离线合成预览**，检查了 320 / 360 / 623 / 1000px：均无横向溢出，1000px 下双列生效；深色背景与 color-scheme 生效，浅/深色截图已目视检查。回顾筛选、清零短语确认、Escape 焦点恢复、合成清零后的等级更新均通过。导出按钮已发起下载，但浏览器工具未观察到原生 download 完成事件，**不声称下载已落盘**。

用户表示已认证后，再次检查并刷新现有 DSH 标签，入口仍返回 401；也没有发现其他可访问的同端口 DSH 标签。因此 **当前 DSH 宿主是否实际加载新版仍未确认**，上述结果仅为离线合成预览的浏览器验证。没有绕过认证、读取密钥、启动替代服务、篡改应用壳或重启宿主。

打包检查另发现 npm 的显式 screenshots 目录清单可能重新包含 Git 忽略的五张本地运行截图；已在分发清单显式排除它们，并在 CI 添加隐私产物检查。`npm pack --dry-run` 最终通过（128 个文件），原始截图保留本地，没有上传。