# 📱 核心 UI 翻新与重构体系 (UITask 原型车间) > **⚠️ 智能体请注意 (Agent Prompt & Protocol)**: > 如果您被唤醒并要求接手本目录的 UI 任务,**请不要一上来就盲目生成代码!** > 您必须充当“UI 架构师”的角色,严格按照以下的 **“一步一答 (Step-by-Step) 交互式协议”** 引导人类用户完成工作流。您的最终目标是集齐 **6 件标准物料**。 --- ## 🗂️ 零、开工前必读:本仓库的真实资产现状 **⛔ 严禁凭空假设文件名。** 请务必先 `ls` 目录看清楚再动手。本仓库有两条**必须记牢**的命名铁律: | # | 铁律 | 说明 | | :--: | :--- | :--- | | 1 | **原图 = `Screenshot*.png`** | 从安卓设备导出的原机截屏,保持出厂文件名。**仓库里不存在 `actual_ui.png`**,那是历史文档的错误约定。 | | 2 | **效果图 = `image.png`** | 方案定稿后,**由人类亲自截图**并命名为 `image.png` 放进页面目录。**不存在 `target_style.png` / `final_effect.png`**,这两个名字同样是历史遗留,已作废。 | ### 当前仓库的四类目录 | 目录 | 性质 | 说明 | | :--- | :--- | :--- | | `设置页面UI优化/<页面名>/` | **主工作台** | 11 个页面子目录,完工形态为 6 件物料(见下)。 | | `.preview/<模块英文名>/` | **候选渲染稿暂存区** | 竞标阶段的多版 HTML 草稿存放地,**已纳入版本管理留痕**,但**绝不进入页面目录**。 | | `<界面名>-/` | **早期工作台(旧形态)** | 例:`系统设置界面-20260816/`,一个目录打包多屏,新任务不再采用此形态。 | | `ui_baseline/EAPManageUI/` | **原始截图总仓库** | 全量安卓截屏归档,**只读**。页面目录里的原图即来源于此。 | ### 📌 页面清单 · 原图映射 · 完工状态(`设置页面UI优化/`) | # | 页面目录 | 原机截屏(唯一原图,只读) | `image.png` | 状态 | | :--: | :--- | :--- | :--: | :--- | | 1 | `语言设置/` | `Screenshot_20260812_143341.png` | ✅ | **已完工**(6 件齐) | | 2 | `版型切换/` | `Screenshot_20260812_143347.png` | ✅ | **已完工**(6 件齐) | | 3 | `心率区间设置/` | `Screenshot_20260817-135129.png` | ✅ | **已完工**(6 件齐) | | 4 | `自动连接配置/` | `Screenshot_20260812_143357.png` | ✅ | **已完工**(6 件齐) | | 5 | `手环配置/` | `Screenshot_20260812_143405.png` | ✅ | **已完工**(6 件齐) | | 6 | `DFU固件升级/` | `Screenshot_20260812_143413.png` | ✅ | **已完工**(6 件齐) | | 7 | `用户管理/` | `Screenshot_20260812_143424.png` | ✅ | **已完工**(6 件齐) | | 8 | `设备数据库管理/` | `Screenshot_20260812_143432.png` | ✅ | **已完工**(6 件齐) | | 9 | `数据上传/` | `Screenshot_20260812_143450.png` | ✅ | **已完工**(6 件齐) | | 10 | `版本信息/` | `Screenshot_20260812_143456.png` | ✅ | **已完工**(6 件齐) | | 11 | `Logo授权管理/` | `Screenshot_20260812_143502.png` | ✅ | **已完工**(6 件齐) | > ¹ **旧基准复用**:这 3 页(外加已完工的语言设置、版型切换)曾在 `系统设置界面-20260816/` 产出过 `baseline_ui.html` / `DESIGN_SPEC.md` / `implementation_plan.md`。接手时**必须先读旧物料再动手**,不要从零重写,避免与已交付的 Token 基准打架。 > **⚠️ 命名不统一警告**:第 3 项证明截屏文件名**没有统一格式**(`Screenshot_日期_时间` vs `Screenshot_日期-时间`)。 > 因此**严禁用写死的正则**(如 `Screenshot_\d{8}_\d{6}\.png`)去匹配,会漏掉心率区间设置页。 > **唯一正确做法**:列目录取实际文件,见 Step 2 的识别算法。 ### ⛓️‍💥 已知断链:两份「宪法级」文档目前不在本仓库 `系统设置界面-20260816/` 下的卡片与图纸把下面两份文件标为 **[必读]**,但**本仓库内并不存在它们**(已全库检索确认): | 被引用的文件 | 声称的作用 | 现状 | | :--- | :--- | :--- | | `UI_DEV_GUIDE.md` | Token 宪法(CSS → Android Token 映射依据) | ❌ 缺失 | | `BEAUTIFY_BASELINE_20260816.md` | 全局美化公约(字号阶梯、分段控件等) | ❌ 缺失 | **智能体遇到此情况的正确处理**:不要卡死在找文件上,也不要假装读过。请主动告知用户:“这两份约束文档不在仓库里,请提供,或确认我按 Material 3 默认规范推进。” 在拿到之前,`implementation_plan.md` 里的 Token 映射一律**标注为待校准**,不得声称已对齐宪法。 --- ## 🎨 全局 AppBar 顶部导航栏统一规范 (AppBar Global Standard) 为确保 11 个设置子页面的顶部导航栏在尺寸、间距、按钮样式上具备 100% 像素级一致性,所有页面的 AppBar 必须严格遵循以下规范: ```css /* ========================================================================= AppBar 顶部导航栏统一规范 (40dp 纯净透明触控槽 + Hover 微圆底) ========================================================================= */ .appbar { height: 60px; /* --appbar-height */ display: flex; align-items: center; justify-content: space-between; padding: 0 20px; border-bottom: 1px solid var(--divider); background: var(--color-surface); } .appbar-left { display: flex; align-items: center; } /* 返回箭头 (←) 与 更多操作 (⋮) 统一规范 */ .appbar-nav, .appbar-more { width: 40px; height: 40px; border-radius: 50%; display: inline-flex; align-items: center; justify-content: center; cursor: pointer; background: transparent; /* 默认纯净透明,严禁生硬方块/灰色边框背景 */ border: none; transition: all 0.15s ease; } .appbar-nav:hover, .appbar-more:hover { background: rgba(15, 23, 42, 0.06); /* 仅在 Hover/Active 时显现轻量微圆底 */ transform: scale(0.96); } .appbar-nav svg, .appbar-more svg { width: 22px; height: 22px; fill: var(--text-main); /* 统一跟随文字主色 */ } .appbar-title { font-size: 19px; font-weight: 700; margin-left: 10px; /* 统一标题左间距 */ letter-spacing: -0.01em; } ``` --- ## 🎨 全局核心主色蓝统一规范 (Global Primary Blue Standard) 为了彻底消除各页面蓝色色号不一致(如部分页面出现偏紫蓝 `#3949AB`、深藏青 `#1A237E` 等杂色)的问题,**所有 11 个设置子页面的所有蓝色元素必须 100% 严格统一使用以下唯一的极客科技蓝 Token 体系**: ```css /* ========================================================================= 全局核心主色蓝统一规范 (Global Primary Blue Token Standard) ========================================================================= */ :root { --color-primary: #2563EB; /* 核心主色蓝 (Royal Tech Blue) */ --color-primary-dark: #1D4ED8; /* 深蓝 / Hover 悬停态 */ --color-on-primary-container: #1E40AF; /* 选中深色文字 / 高亮标题 */ --color-primary-light: #EFF6FF; /* 极浅蓝背景 / 选中浅底容器 */ --color-primary-container: #EFF6FF; /* 选中卡片微底 */ --color-primary-border: #DBEAFE; /* 浅蓝边框 (Border / Chip) */ --color-primary-glow: rgba(37, 99, 235, 0.25); /* 蓝色弥散发光与阴影 */ --color-primary-gradient: linear-gradient(135deg, #2563EB 0%, #1D4ED8 100%); /* 渐变主按钮 */ } ``` ### 🎯 蓝色应用强制约束原则 1. **标题与分区卡片名**:所有卡片标题、分类标题、模块主文案一律使用 `--color-primary` (`#2563EB`); 2. **选中态组件**: - 单选框 Radio、复选框 Checkbox、滑动开关 Switch 开启态、滑块 Slider 游标与轨道; - 选中的卡片边框(`border-color: #2563EB`)、选中左侧光条(`background: #2563EB`)、选中底色(`background: #EFF6FF`); 3. **主操作按钮**:一律采用 `--color-primary` 或 `--color-primary-gradient`; 4. **普通强调蓝色文字与标签**:如 `BLE` 协议标签、时段读数、选中文本一律采用 `#2563EB`,浅底搭配 `#EFF6FF`。 --- 为了彻底杜绝大屏幕固定像素导致的不适配与留白失衡,所有设置页面实行统一的 **自适应动态页边距体系**,并按业务类型划分为两大栅格策略: ### 1. 动态自适应外层页边距体系 (所有页面 100% 统一) - **外层视口边距**:`padding: clamp(16px, 2.5vw, 32px);`(上下左右等距呼吸,小屏紧凑、超大屏大气); - **容器最大宽度**:`max-width: min(100%, 1160px);`(大屏居中,不拉伸变形); - **卡片内边距**:`padding: clamp(20px, 2.5vw, 30px);`; - **分栏间距 (Gutter)**:`gap: clamp(16px, 2vw, 24px);`; - **主容器圆角**:`border-radius: 20px;`。 ### 2. 页面类型与双栏比例策略 | 页面类型 | 代表页面 | 核心栅格策略 (Grid Columns) | 说明与设计意图 | | :--- | :--- | :--- | :--- | | **A 类:双栏选择型页面**
*(Dual-Column Selector)* | • **版型切换**
• **语言设置** | **统一锁死黄金比例:`360px 1fr`**
(左侧 360dp 概览岛屿 + 右侧 1fr 选项卡片) | **占比严格统一**,确保同类选择型页面在视觉层级、左右宽度比例上 100% 对齐,不再出现左右忽大忽小的问题。 | | **B 类:高密度复合型页面**
*(High-Density Multi-Zone)* | • **心率区间设置**
• **自动连接配置** | **内容自适应比例**:
• 心率区间:`1fr 360px` (左 5 区间 + 右 HUD)
• 自动连接:`430px 1fr` (左通道 + 右 Bento) | **按内容空间需求自适应比例,无需刻意统一左右占比**,但外层动态边距与 AppBar 必须严格遵循全局规范。 | --- ## 🔄 您的交互式工作流 (Step-by-Step Protocol) 当您(新手智能体)被人类协作者唤醒,并收到这张 README 时,请按顺序执行以下步骤。**每完成一步,必须停下来等待用户的回复,严禁抢跑**: > **🌟 AI 能力自检探针 (Capability Check)** > 在执行 Step 1 前,请 AI 评估自身当前具备哪些具体的 Tool/API 权限,并据此调整策略: > - **文件读写能力**:能否在后台静默创建文件/目录并打包 ZIP?(有则静默创建,无则转为纯对话指导模式) > - **图片读取能力**:能否**读取本地磁盘上的 PNG** 并真正“看见”内容?(这是 Step 2 / Step 3 的硬性前提;若不能,必须请人类口述信息槽位) > - **自动截图能力 (Headless Screenshot Pipeline)**:已配置 Google Chrome Headless 自动截图管线,方案定稿后**自动截取 `image.png` 落盘**,无需人类手动截图。 > - **浏览器渲染能力**:能否打开本地 HTML 预览?(决定候选稿是您截图呈现,还是给路径让人类自己看) > - **文件访问透明度**:人类能否直接在电脑上双击打开你写的文件?(本地 IDE 可以;云端沙盒则需你在聊天框打印 HTML 供其复制) ### 📁 Step 1: 确定界面归属与建仓 (防覆盖) - **您的动作**:先问用户:“请问本次重构属于哪个界面?” - **分支判断(关键,别建重复目录)**: - **若用户报出的页面已在上方清单中** → 该页面的工作台**已经存在**,直接进入 `设置页面UI优化/<页面名>/` 就地作业。 **⛔ 严禁**为它新建带日期后缀的目录,**严禁**移动或复制原图。 - **若该页状态已是「已完工」** → 先告知用户“此页 6 件物料已齐”,问清是要**修订**还是**误报页面名**,别直接覆盖已交付成果。 - **若是清单之外的全新界面** → 在 `设置页面UI优化/` 下新建 `<页面名>/`,并请人类把原机截屏放进去。 - **收尾**:把您确定的工作台**绝对路径**回报给用户,等待确认后再进入 Step 2。 ### 📷 Step 2: 精确识别原机截屏 (原图锁定) - **⛔ 绝对禁令**:不许假设文件名是 `actual_ui.png`;不许重命名、不许移动、不许覆盖原图。原图是唯一的“信息槽位保底凭证”,必须保持出厂文件名以便追溯。 - **识别算法(照做,别猜)**: 1. 列出工作台目录下的全部文件(`ls`),**不要**先入为主地过滤文件名。 2. 筛出图片扩展名(`.png` / `.jpg` / `.jpeg` / `.webp`)。 3. **先把 `image.png` 排除掉**——它是效果图,不是原图(详见 Step 3)。 4. 在剩下的图片里挑**原机截屏**:文件名以 `Screenshot` 开头(大小写不敏感,分隔符可能是 `_` 也可能是 `-`),或虽不叫这个名字但明显是设备导出的截图。 5. **命中 1 张** → 锁定为本页原图,把绝对路径回报给用户确认。 6. **命中多张** → **禁止自行拍板**。列出全部候选(文件名 + 尺寸 + 修改时间)问用户:“检测到 N 张截屏,请指认哪张是本页的原机截屏?” 7. **命中 0 张** → 向用户说明目录里没有原图,请其放入后再继续;同时可去 `ui_baseline/EAPManageUI/` 里按时间戳协助查找。 - **读图**:锁定后**必须真正读取这张 PNG**,逐条列出您看到的信息槽位(标题、字段、按钮、开关、状态文案、空状态……),并向用户复述一遍:“我在原图里看到了以下 N 个元素,有没有遗漏?” 这一步是后续“绝不丢字段”验收标准的基线,**不做完不许进 Step 3**。 ### 🖼️ Step 3: 效果图盘点 —— 有 `image.png` 就用它,没有就先竞标 > **📌 本仓库的效果图铁律**:定稿的目标效果图**固定叫 `image.png`**。 > 一旦人类用户确认方案定稿后,智能体将**通过无头浏览器自动截屏落盘为 `image.png`** 存入页面目录,集齐 6 件全量标准物料。 **先盘点**:工作台目录里是否存在 `image.png`? #### ✅ 情况 A:已有 `image.png`(人类已定稿) 1. **直接读取它**,逐条列出您看到的视觉决策:栅格宽度、卡片密度、圆角、强调色用法、分组方式、控件形态、状态表达…… 2. 与用户核对:“我从 `image.png` 里读到以下风格特征,理解对吗?” 3. **⛔ 跳过竞标流程**,风格已由人类拍板,您**不许**再自行发挥或提议换风格。 4. 直接带着 **原机截屏(信息保底)+ `image.png`(风格目标)** 双基线进入 Step 4。 #### 🎨 情况 B:没有 `image.png` → 强制进入「渲染图竞标」 **不许跳过、不许自己拍脑袋定一个风格就开写。** 1. **产出至少 3~5 个候选方案**:基于 Step 2 读到的信息槽位,写出 3~5 份**风格互相有明显区分度**的 HTML 渲染稿(不是 3 份换个色号的同一版)。建议维度:卡片密度(紧凑 / 舒展)、分组方式(分区卡片 / 通栏列表)、强调手法(描边 / 填色 / 徽章)、平板宽屏栅格策略等。 2. **⛔ 落盘纪律(核心红线)**:候选稿**一律不许写进页面目录**,必须放在 `.preview/<模块英文名>/` 下(snake_case 英文名,如 `language_settings`、`edition_selection`、`heart_rate_settings`、`auto_connect_settings`)。 目的:保持页面目录干净(只留 6 件物料),避免十几份废稿污染 `@coder` 的交付清单。 > 💡 候选稿**保留**在 `.preview/` 作为设计决策留痕,不必删除——但它们**永远不算物料**。 3. **呈现给用户**: - 给出每份候选 HTML 的绝对路径,请用户双击打开逐个查看;有渲染能力则可另做一个 `preview_bakeoff.html` 汇总页并排对比。 - 附一份对比说明:每版的取舍点是什么、各自适合什么场景。 4. **等待选择**:明确提问“请选择哪一版作为效果图基准,也可以指定‘要 2 号的布局 + 3 号的配色’做混合”。**⛔ 用户没回话之前不许进 Step 4。** 5. **自动定稿截屏落盘(核心升级)**:用户确认落实后,智能体将中选版本写入 `baseline_ui.html`,并**自动调用 Chrome Headless 截取高清 `image.png` 存入页面目录**,自动补齐第 6 件物料,免除人类手动截图操作。 ### 💻 Step 4: 编码 HTML 与循环调优 (防死锁) - **您的动作**:以“原机截屏 + `image.png`”为双基线,打磨 `baseline_ui.html`,写入页面目录。 - **交互**:告诉用户该 HTML 文件的本地绝对路径,让用户双击用浏览器打开。 - **循环**:询问用户哪里有问题,反复修改 HTML 直到用户确认满意。 - **⚠️ 防死锁警告**:HTML 原型的核心目的是敲定排版结构和颜色 Token。如果您在尝试还原复杂动画或生僻字体时遭遇挫折,请主动放弃像素级的死磕,向用户说明情况并以快速输出图纸为主,切勿陷入无限修改的死循环。 ### 📐 Step 5: 自动生成图纸与资产交付 (终局) - **您的动作**:提取 HTML 里的 CSS 逻辑,生成并保存以下 3 份标准文件: 1. `DESIGN_SPEC.md` (视觉边界手册) 2. `implementation_plan.md` (原生映射图纸) 3. `CARD-YYYYMMDD-UITask-<页面名>.md` (最终的重构卡片模板) - **⚠️ 引用图片时的硬性要求**: - 引用原图**必须写真实文件名**(如 `Screenshot_20260812_143341.png`),**不许写 `actual_ui.png`**。 - 引用效果图**一律写 `image.png`**,不许写 `target_style.png` / `final_effect.png`。 - **交付自检**:确认页面目录下 6 件物料齐全:`Screenshot*.png`、`image.png`、`baseline_ui.html`、`DESIGN_SPEC.md`、`implementation_plan.md`、`CARD-*.md`。 --- ## 📦 交付物清单 (6 件标准物料) ### 第一部分:视觉基线(2 张图) | # | 物料 | 来源 | 说明 | | :--: | :--- | :--- | :--- | | 1 | 📷 **`Screenshot*.png`** | 安卓设备导出 | 原机截屏,**保持出厂名、只读**。保底凭证,确保原有槽位绝不丢失。⛔ 不要重命名为 `actual_ui.png`。 | | 2 | 🖼️ **`image.png`** | **无头浏览器自动截屏生成** | 定稿目标效果图,兼任“风格目标”与“定妆照”。由智能体在定稿后自动渲染落盘。 | ### 第二部分:原型与图纸(4 份文件) | # | 物料 | 说明 | | :--: | :--- | :--- | | 3 | 🌐 **`baseline_ui.html`** | **[核心输出]** 手写的 HTML/CSS 源代码。所有排版、颜色、状态机的讨论都在此 HTML 上进行。 | | 4 | 📐 **`DESIGN_SPEC.md`** | 纯视觉说明手册(透明度、边界条件、空白状态、截断规则等)。 | | 5 | 🛠️ **`implementation_plan.md`** | 原生 Android 施工图纸。必须含严格的 **CSS-to-Android Token 映射字典**(绝对禁止 XML 硬编码颜色和尺寸)。 | | 6 | 📋 **`CARD-YYYYMMDD-UITask-<页面名>.md`** | 最终的重构任务卡片。简明标明改动文件,并声明严格遵守 `UI_DEV_GUIDE.md`。 | > **完工目录形态**(以已交付的 4 个页面为例): > > ```text > 设置页面UI优化/自动连接配置/ > ├── Screenshot_20260812_143357.png # ① 原机截屏(原名保留,只读) > ├── image.png # ② 自动渲染的定稿效果图 > ├── baseline_ui.html # ③ 核心 HTML 原型 > ├── DESIGN_SPEC.md # ④ 视觉边界手册 > ├── implementation_plan.md # ⑤ 原生落地图纸 > └── CARD-20260817-UITask-自动连接配置.md # ⑥ 重构任务卡片 > ``` --- ## 🛑 行动准则 - **只做设计,不碰原生**:您的工作止步于产出这 6 份物料。Android 端的实际修改,由后续的 `@coder` 根据这 6 份物料执行。 - **原图神圣不可侵犯**:原机截屏只读。不重命名、不移动、不覆盖、不修图。 - **自动截取 `image.png`**:定稿后智能体通过无头浏览器自动生成 `image.png`,确保 6 件物料一次性齐备。 - **统一 AppBar 视觉标准**:所有页面严格采用 40dp 纯净透明触控槽 + Hover 微圆底规范,杜绝大小不一和生硬框线。 - **无 `image.png` 必先竞标**:**必须**先出 3~5 版(上不封顶)渲染图让用户选,候选稿只进 `.preview/`。禁止自己选一版就闷头开写。 - **页面目录只放 6 件物料**:候选稿、临时文件、废弃版本一律不进页面目录。 - **文件名以实际磁盘为准**:任何时候引用图片,先 `ls` 确认,再写路径。 - **Token 宪法**:编写 `implementation_plan.md` 时对照 `UI_DEV_GUIDE.md`,把 HTML 里的 `#FFFFFF` 映射为 `?attr/colorSurface`,`12px` 映射为 `@dimen/corner_radius_md`。