本次整合将分散在 33+ 处核心代码和 10+ 个插件中的头像渲染统一到 avatar_component_from_data() 三层嵌套组件，新增 2 个 hook 点（badges/frame）和 avatar_shape 配置项，解决圆角不一致、尺寸碎片化、onerror 兜底混乱、用户组角标丢失、扩展点缺失 5 类问题。

阶段 1：核心组件升级

• [核心组件] 重构 lib/avatar_component.php 为三层嵌套结构（L1 avatar-wrap / L2 position-relative / L3 角标）

  • 必测: 帖子列表/回帖/用户主页头像正常显示

• [尺寸档位] 新增 xs(24px) 和 xxl(128px) 两档，共 6 档（xs/sm/md/lg/xl/xxl）

• [Hook 点] 新增 avatar_component_frame.php（头像框，L1 内，$frame_html = 覆盖模式）和 avatar_component_badges.php（角标，L2 内，$badges_html .= 累加模式）

• [配置项] 新增 avatar_shape 站点配置（rounded/circle/square 三档），通过 avatar_component_get_shape() 读取（带静态缓存）

• [函数签名] avatar_component_from_data() 新增第 6 参 $options，支持 extra_class/link_uid/show_group_icon/show_hooks/lazy/badge_position，旧 5 参数调用完全兼容

• [CSS] view/css/bootstrap-bbs.css avatar 区块重构：新增 .avatar-wrap / .avatar-shape-* / .avatar-badge / .avatar-frame 样式

• [后台设置] 新建 admin/view/htm/setting_avatar.htm 头像设置页（三选一单选 + 形状预览 + htmx 错误兜底）

• [后台路由] admin/route/setting.php 新增 setting_avatar 分支

• [后台菜单] admin/menu.conf.php 添加「头像设置」入口

• [多语言] zh-cn / zh-tw / en-us 三语言包同步新增 7 个 avatar 相关键

• [版本号] conf/conf.php static_version 递增 ?1.4.35 → ?1.4.36

阶段 2：核心 11 处迁移

• [前台模板] forum_members_block.htm 版块成员块迁移（sm 尺寸 + group 数据 + _uid）

• [前台模板] forum_followers.htm 版块关注者列表迁移（md 尺寸）

• [前台模板] forum.htm 版主列表迁移（sm 尺寸）

• [路由层] route/user.php 我的关注/粉丝列表迁移（md 尺寸）

• [路由层] route/notice.php 通知下拉迁移（xs 尺寸 + show_hooks=false + lazy=false）

• [后台模板] header_nav.inc.htm 顶部导航头像（保留字母兜底 + show_hooks=false + lazy=false）

• [后台模板] user_update.htm 用户编辑页头像预览（lg 尺寸 + show_group_icon=false）

• [后台模板] security_audit.htm 审核页头像对比（xs 列表 + lg 详情）

• [后台模板] audit.htm 另一处审核页同上

• [后台模板] admin_notice_list.inc.htm 后台通知列表（sm 尺寸 + flex-shrink-0）

• [后台模板] banned_user_list.htm 已迁移复核确认

阶段 3：插件迁移

• [xnx_verify] 新建 hook/avatar_component_badges.php 注入认证对勾到右下角（复用 ti-circle-check-filled 图标 + xnx_verify_status_approved 语言键 + VerifyService 静态缓存避免 N+1）

• [xnx_verify] view/htm/my_verify.htm 首字母兜底改用组件 + show_hooks=false + show_group_icon=false

• [xnx_medal] 新建 hook/avatar_component_badges.php 用勋章 icon 作为头像角标（最多 3 个，分布到 top-right/top-left/bottom-left 三角避开用户组图标）

• [xnx_medal] 新建 static/css/medal.css 覆盖 .avatar-badge 默认白底为透明

• [xnx_medal] 新建 hook/header_link_after.htm 引入 medal.css

• [xnx_medal] conf.json 递增版本 1.0.4→1.0.5，hooks_rank 新增两个 hook

• [xnx_avatar_ai] 确认 cache_delete(‘user-’.$uid) 已调用（双重保险），256x256 结果展示和 48x48 历史缩略图保留原生 img（特殊尺寸 + AI 生成图非用户头像）

• [xnx_checkin] 排行榜头像迁移（md + show_group_icon=false）+ 首页签到叠放迁移（xs + extra_class=border）

• [xnx_invite] 邀请记录列表迁移（sm + 完整 group 数据），16px 排行保留原生（过小）

• [xnx_fusers] 版块成员迁移（sm + link_uid 替代手动 a 标签 + show_group_icon=false）

• [xnx_lottery] 参与者迁移（xs + extra_class=border shadow-sm），移除首字母兜底

• [xnx_status] 后台贡献者迁移（sm + extra_class=me-2 + show_hooks=false + show_group_icon=false）

• [xnx_theme_moments] 朋友圈卡片头部迁移（md + flex-shrink-0）+ 侧栏推荐用户迁移（xs），60px 发帖按钮保留原生

• [xnx_hidden] JS 动态生成 + 不在 avatar-wrap 容器内，保留原生

• [xnx_feeds] JS 动态生成 + 特殊 toast 场景，保留原生

• [xnx_oauth] avatar_url 数据源兼容性验证通过（.png 保存 + user_format 查找 + time() 版本号）

• [xnx_need_avatar] 默认头像判断逻辑与组件 onerror fallback 一致

阶段 4：清理与规则沉淀

• [清理] 确认 xnx_verify 无 username_after hook 残留（Grep 验证通过）

• [规则] .trae/rules/bugfix_rules.md 新增「七、头像组件规范」章节，4 条规则：

  • 头像渲染必须用 avatar_component_from_data()，禁止原生 img

  • 头像形状通过 setting(‘avatar_shape’) 控制，禁止硬编码 rounded-1/rounded-circle

  • 头像角标/头像框扩展必须用 hook，禁止核心代码硬编码插件名

  • frame hook 用 = 覆盖，badges hook 用 .= 累加

• [审计] 代码层审查全部通过：

  • PC/移动端双模板 id 规则：两个 avatar_component hook 文件用 class 无 id 冲突

  • hook 文件无 return 语句：仅在注释中出现，无实际 return

  • 多语言包同步：zh-cn / zh-tw / en-us 三语言包均含 avatar 相关键