fix:pvx组件优化

Author: fifthThirteen

docs/agents/public-components-integration-2026-07-30.md

@@ -0,0 +1,145 @@
+# PVX 公共组件接入与页面回归记录（2026-07-30）
+
+## 1. 文档范围
+
+本文记录 2026-07-30 当前 PVX 工作区尚未提交的改动，覆盖：
+
+- `@jx3box/*` 公共库版本升级；
+- 公共组件新版样式和 i18n 能力接入；
+- 已由公共库承担的 PVX 本地深层覆盖清理；
+- 地图、Face/Body 数据组件的兼容修复；
+- 本轮用户检查中发现的页面级响应式问题。
+
+实施和后续回归同时遵循：
+
+- `docs/design/pvx-visual-style-guide.md`
+- `docs/design/responsive-adaptation-guide.md`
+- `docs/common/i18n-development-guide.md`
+
+## 2. 公共库版本
+
+| 公共库 | 调整前 | 当前接入 | 本轮用途 |
+| --- | --- | --- | --- |
+| `@jx3box/jx3box-ui` | `^2.3.21` | `^2.3.22` | Wiki surface variant、公共 Wiki 组件样式与 i18n |
+| `@jx3box/jx3box-map` | `^1.0.0` | `^1.1.12` | 响应式地图、聚焦模式、错误状态、可访问性和地图 i18n |
+| `@jx3box/jx3box-facedat` | `^2.7.6` | `^2.7.7` | Facedat/Bodydat 数据查看器公共样式 |
+| `@jx3box/jx3box-editor` | `^3.2.12` | `^3.2.13` | 跟进公共编辑器修订版本，本轮无新增业务改造 |
+
+`npm run update` 已补充 `@jx3box/jx3box-map@latest`，后续统一更新公共依赖时不会遗漏地图库。
+
+## 3. `@jx3box/jx3box-ui` 接入
+
+### 3.1 已完成
+
+- [x] `PvxUser` 向 WikiPanel、WikiRevisions、WikiComments 统一传递 variant。
+- [x] 普通 Web 使用 `surface`，机器人输出继续使用 `default`，避免改变抓图结构。
+- [x] 书籍、家具、坐骑、宠物、声望详情删除已由公共组件承担的 WikiPanel 深层结构覆盖。
+- [x] 删除的覆盖包括 panel head/body/title/actions、评论正文容器和移动端重复内边距。
+- [x] 保留真正属于 PVX 页面层的 Grid、区块间距、社区外框排布和业务按钮品牌色。
+
+### 3.2 i18n 边界
+
+- WikiPanel、WikiComments、WikiRevisions 的固定界面文案由 `jx3boxUi.*` 维护。
+- PVX 通过现有宿主 i18n 实例合并公共库词条，不创建第二套语言状态。
+- 用户正文、贡献说明、NPC、地图名和其他游戏源数据不由公共组件强制翻译。
+- 机器人场景继续使用公共组件默认 variant，普通 Web 的 PVX surface 不得改变机器人输出。
+
+### 3.3 后续
+
+- [ ] 统一评估各详情主题仍保留的 `.u-btn--link` 品牌色是否可以改用公共组件 CSS Variable。
+- [ ] 在公共组件 API 稳定后继续减少消费者对内部 class 的依赖。
+
+## 4. `@jx3box/jx3box-facedat` 接入
+
+### 4.1 已完成
+
+- [x] 删除 `FaceBodyDataViewer.vue` 中完整的 Facedat 主题副本。
+- [x] 删除 Face/Body 解析页中针对 Tab、贴花列表、参数、价格、Slider 和移动端滚动的深层覆盖。
+- [x] 删除普通 Web 详情页中重复的 Facedat Tab 内部修正。
+- [x] 保留页面预览区最小高度、详情模块间距等宿主布局职责。
+
+### 4.2 接入原则
+
+- Facedat/Bodydat 的字段、参数组、贴花结构和组件主题由 `@jx3box/jx3box-facedat` 维护。
+- PVX 不再复制公共库的完整内部 DOM 样式。
+- PVX 只处理公共组件所在页面的宽度、间距、模块顺序和终端分流。
+
+## 5. `@jx3box/jx3box-map` 接入
+
+### 5.1 公共能力确认
+
+- [x] 支持 `focus`、`overview`、`responsive` 模式。
+- [x] 使用 `ResizeObserver` 响应容器变化。
+- [x] 提供 resize/error 等事件和图片加载失败重试状态。
+- [x] 提供地图、点位可访问名称和键盘焦点。
+- [x] 地图加载、失败、重试、子地图切换等固定 UI 使用公共库四语言词条。
+
+地图名、NPC、坐标和点位说明仍属于业务源数据，由 PVX 传入，不由地图库猜测翻译。
+
+### 5.2 宠物详情
+
+- [x] 只有存在地图数据时才为宠物详情添加 `has-map`。
+- [x] 无地图宠物使用“宠物卡片 + 资料”双列，不再预留空白第三列。
+- [x] 竖屏平板及手机统一降为单列，避免宠物卡片和字段区横向溢出。
+- [x] 修复模板读取未定义 `petWiki` 的 Vue 警告，成就 ID 从宠物数据安全读取。
+- [x] 社区区块补充单列收缩约束，避免 Wiki surface 接入后撑宽页面。
+
+### 5.3 声望详情
+
+- [x] 声望商人点位优先使用 `Guides[0].map`，避免把 NPC 坐标绘制到错误的 `szMapIDs` 地图。
+- [x] 不再强制覆盖 `.c-map__inner` 的 1024 × 896 聚焦画布宽高。
+- [x] 声望商人地图并入“声望资料”卡片，不再作为顶层独立整行卡片。
+- [x] `>1440px` 时资料与地图在同一卡片内左右排列并顶部对齐。
+- [x] `≤1440px` 时地图在同一卡片内下移，整个商人模块与资料区左边缘对齐。
+- [x] 上下布局的商人模块限制为 960px 安全宽度。
+- [x] 聚焦地图画布在容器内水平居中，避免只在右侧露出空白背景。
+- [x] 地图在手机、平板、中等桌面和 2K 大屏均保留，不因适配困难隐藏业务内容。
+
+### 5.4 后续
+
+- [ ] 回归坐骑播报/详情和书籍详情的新版地图库表现。
+- [ ] 继续评估可以由 responsive/overview API 取代的固定高度和强制 resize 逻辑。
+
+## 6. 页面级响应式与视觉修复
+
+### 6.1 科举首页
+
+- [x] 移动端重排 Hero 图标、标题、说明和“补充题目”操作。
+- [x] 英文长标题和说明允许自然换行，不再把内容挤成窄竖列。
+- [x] 搜索、随机题目和空状态在手机安全宽度内展示。
+
+### 6.2 奇遇章节
+
+- [x] “加载更多”使用 PVX 主色软背景和可辨识文字色。
+- [x] 补充 Hover、Active、Loading 状态的背景、边框、阴影和位移反馈。
+- [x] Loading 状态不继承可点击 Hover 效果。
+
+### 6.3 伙伴详情
+
+- [x] 移动端取消详情容器和信息卡的固定最小高度。
+- [x] 双栏信息改为完整纵向排列，内部正文不再单独滚动。
+- [x] 属性表改为圆角字段卡，标签和值保持稳定双列和可换行能力。
+
+### 6.4 日常公告
+
+- [x] 移动端特殊坐骑卡片允许英文长文本自然增高。
+- [x] 刷新状态、时间和坐骑图标不再互相挤压或越界。
+
+## 7. 验证记录
+
+- [x] `npm run lint`
+- [x] `git diff --check`
+- [x] 宠物 190/429 的移动端、无地图和控制台警告检查。
+- [x] 声望 283 的地图资源、地图 ID、点位可见性和多尺寸布局检查。
+- [x] 科举、奇遇章节、伙伴、日常公告目标移动端页面检查。
+- [ ] 提交前按最终工作区运行 `npm run verify:legacy-js`。
+- [ ] 提交前按风险和时间运行必要构建。
+
+## 8. 提交前清单
+
+- [ ] 确认 package-lock 与 package.json 的四个公共库版本一致。
+- [ ] 搜索是否仍有可由新版公共组件替代的深层选择器。
+- [ ] 检查新增或修改文件中的固定界面文案是否进入对应 i18n 命名空间。
+- [ ] 检查英文、越南文长文本没有遮挡操作或制造页面级横向滚动。
+- [ ] 检查普通 Web 的 variant 没有改变机器人和小程序/App 输出。
+- [ ] 完成最终 lint、legacy JS 检查、必要构建和 `git diff --check`。

docs/design/responsive-adaptation-guide.md

@@ -140,6 +140,8 @@ Face / Body 当前分流如下：
 - 相关推荐采用横向卡片带时必须显示可滚动线索，并保证页面本身不横向滚动。
 - 弹窗、确认框、图片预览和下载提示均需单独验证触摸操作。
 - 图鉴详情的多阶段选择（如声望阶段奖励）在手机端可改为局部横向滑动卡片带，并使用 `grid-auto-flow: column`、稳定的可见卡片宽度和滚动吸附；奖励正文仍位于卡片带下方，不能让所有阶段纵向堆叠，也不能把横向滚动扩散到页面。
+- 声望详情的商人地图属于“声望资料”的补充信息，不单独占据顶层整行：大屏可在资料字段右侧并排，`1440px` 及以下在同一卡片内下移并与资料内容左边缘对齐。聚焦地图使用固定内部画布时，子模块应限制安全宽度，画布在容器内水平居中，避免单侧露出空白背景。
+- 宠物详情只有存在地图数据时才预留地图列；无地图数据时使用卡片与资料双列。竖屏平板及手机统一降为单列，不能因为桌面 `has-map` 状态保留多列定义。
 - 固定字段卡在英文、越南文等长语言下优先把标签和值改为上下排列，并对两者设置 `min-width: 0` 与 `overflow-wrap`；游戏源数据值不应因标签过长被截断。
 - 带胶囊标签的说明行必须使用明确的 Flex 垂直居中。标签、名称和短说明在单行时共享同一垂直中心；允许换行时应由内容自然增高，不能针对长语言统一改成顶部对齐而破坏常见单行状态。