Files
EAP_Interface_html/README.md
T
2026-08-17 14:51:41 +08:00

185 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 📱 核心 UI 翻新与重构体系 (UITask 原型车间)
> **⚠️ 智能体请注意 (Agent Prompt & Protocol)**:
> 如果您被唤醒并要求接手本目录的 UI 任务,**请不要一上来就盲目生成代码!**
> 您必须充当“UI 架构师”的角色,严格按照以下的 **“一步一答 (Step-by-Step) 交互式协议”** 引导人类用户完成工作流。您的最终目标是集齐 7 件标准物料。
---
## 🗂️ 零、开工前必读:本仓库的真实资产现状
**⛔ 严禁凭空假设文件名。** 历史版本的本文档曾要求把原图命名为 `actual_ui.png`,但**仓库里根本不存在任何 `actual_ui.png`**。真实的原机截屏是从安卓设备直接导出的、以 `Screenshot` 开头的原始文件。请务必先 `ls` 目录看清楚再动手。
### 当前仓库的三类目录
| 目录 | 性质 | 说明 |
| :--- | :--- | :--- |
| `设置页面UI优化/<页面名>/` | **待办工作台(A 型)** | 已由人类预先建好 11 个页面子目录,每个目录内**只有 1 张原机截屏**,无任何效果图。 |
| `<界面名>-<YYYYMMDD>/` | **已完成工作台(B 型)** | 例:`系统设置界面-20260816/`,内含 `baseline_ui.html` + 3 份图纸。 |
| `ui_baseline/EAPManageUI/` | **原始截图总仓库** | 全量安卓截屏归档,**只读**。A 型目录里的图即来源于此。 |
### 📌 页面 → 原机截屏 精确映射表(`设置页面UI优化/`)
| # | 页面目录 | 原机截屏文件名(唯一原图) | 备注 |
| :--: | :--- | :--- | :--- |
| 1 | `语言设置/` | `Screenshot_20260812_143341.png` | ✅ 已有 B 型基准(见下) |
| 2 | `版型切换/` | `Screenshot_20260812_143347.png` | ✅ 已有 B 型基准 |
| 3 | `自动连接配置/` | `Screenshot_20260812_143357.png` | |
| 4 | `手环配置/` | `Screenshot_20260812_143405.png` | |
| 5 | `DFU固件升级/` | `Screenshot_20260812_143413.png` | |
| 6 | `用户管理/` | `Screenshot_20260812_143424.png` | |
| 7 | `设备数据库管理/` | `Screenshot_20260812_143432.png` | |
| 8 | `数据上传/` | `Screenshot_20260812_143450.png` | ✅ 已有 B 型基准 |
| 9 | `版本信息/` | `Screenshot_20260812_143456.png` | ✅ 已有 B 型基准 |
| 10 | `Logo授权管理/` | `Screenshot_20260812_143502.png` | ✅ 已有 B 型基准 |
| 11 | `心率区间设置/` | `Screenshot_20260817-135129.png` | ⚠️ **分隔符是短横线不是下划线**,日期也是 0817 |
### ⛓️‍💥 已知断链:两份「宪法级」文档目前不在本仓库
`系统设置界面-20260816/` 下的卡片与图纸把下面两份文件标为 **[必读]**,但**本仓库内并不存在它们**(已全库检索确认):
| 被引用的文件 | 声称的作用 | 现状 |
| :--- | :--- | :--- |
| `UI_DEV_GUIDE.md` | Token 宪法(CSS → Android Token 映射依据) | ❌ 缺失 |
| `BEAUTIFY_BASELINE_20260816.md` | 全局美化公约(字号阶梯、分段控件等) | ❌ 缺失 |
**智能体遇到此情况的正确处理**:不要卡死在找文件上,也不要假装读过。请主动告知用户:“这两份约束文档不在仓库里,请提供,或确认我按 Material 3 默认规范推进。”
在拿到之前,`implementation_plan.md` 里的 Token 映射一律**标注为待校准**,不得声称已对齐宪法。
> **⚠️ 命名不统一警告**:第 11 项证明截屏文件名**没有统一格式**(`Screenshot_日期_时间` vs `Screenshot_日期-时间`)。
> 因此**严禁用写死的正则**(如 `Screenshot_\d{8}_\d{6}\.png`)去匹配,会漏掉心率区间设置页。
> **唯一正确做法**:列目录取实际文件,见 Step 2 的识别算法。
> **♻️ 复用提示**:上表标 ✅ 的 5 个页面已在 `系统设置界面-20260816/` 产出过 `baseline_ui.html`、`DESIGN_SPEC.md`、`implementation_plan.md`。接手这 5 页时**必须先读旧物料再动手**,不要从零重写,避免与已交付的 Token 基准打架。
---
## 🔄 您的交互式工作流 (Step-by-Step Protocol)
当您(新手智能体)被人类协作者唤醒,并收到这张 README 时,请按顺序执行以下 6 个步骤。**每完成一步,必须停下来等待用户的回复,严禁抢跑**:
> **🌟 AI 能力自检探针 (Capability Check)**
> 在执行 Step 1 前,请 AI 评估自身当前具备哪些具体的 Tool/API 权限,并据此调整策略:
> - **文件读写能力**:能否在后台静默创建文件/目录并打包 ZIP?(有则静默创建,无则转为纯对话指导模式)
> - **图片读取能力**:能否**读取本地磁盘上的 PNG** 并真正“看见”内容?(这是 Step 2 的硬性前提;若不能,必须请人类口述原图信息槽位)
> - **附件提取能力**:能否将人类发在聊天框里的**多媒体图片附件**转化为本地磁盘文件?(⚠️ 绝大多数代码助手仅能读写文本,无法提取图片二进制流)
> - **浏览器渲染/截图能力**:能否打开本地 HTML 并截图存盘?(决定 Step 3 与 Step 5 的效果图是您自动产出,还是需人类手动截屏)
> - **文件访问透明度**:人类能否直接在电脑上双击打开你写的文件?(本地 IDE 可以;云端沙盒则需你在聊天框打印 HTML 供其复制)
### 📁 Step 1: 确定界面归属与建仓 (防覆盖)
- **您的动作**:先问用户:“请问本次重构属于哪个界面?”
- **分支判断(关键,别建重复目录)**:
- **若用户报出的页面已在上方映射表中** → 该页面的工作台**已经存在**,直接进入 `设置页面UI优化/<页面名>/` 就地作业。
**⛔ 严禁**为它新建带日期后缀的目录,**严禁**移动或复制原图。
- **若是映射表之外的全新界面** → 在仓库根目录创建 `<界面名>-<YYYYMMDD>/`(日期后缀防覆盖过往版本),并请人类把原机截屏放进去。
- **收尾**:把您确定的工作台**绝对路径**回报给用户,等待确认后再进入 Step 2。
### 📷 Step 2: 精确识别原机截屏 (原图锁定)
- **⛔ 绝对禁令**:不许假设文件名是 `actual_ui.png`;不许重命名、不许移动、不许覆盖原图。原图是唯一的“信息槽位保底凭证”,必须保持出厂文件名以便追溯。
- **识别算法(照做,别猜)**:
1. 列出工作台目录下的全部文件(`ls`),**不要**先入为主地过滤文件名。
2. 筛出图片扩展名(`.png` / `.jpg` / `.jpeg` / `.webp`)。
3. 在其中挑出**原机截屏**:文件名以 `Screenshot` 开头(大小写不敏感,分隔符可能是 `_` 也可能是 `-`),或虽不叫这个名字但明显是设备导出的截图。
4. **命中 1 张** → 锁定为本页原图,把绝对路径回报给用户确认。
5. **命中多张** → **禁止自行拍板**。列出全部候选(文件名 + 尺寸 + 修改时间)问用户:“检测到 N 张截屏,请指认哪张是本页的原机截屏?”
6. **命中 0 张** → 向用户说明目录里没有原图,请其放入后再继续;同时可去 `ui_baseline/EAPManageUI/` 里按时间戳协助查找。
- **读图**:锁定后**必须真正读取这张 PNG**,逐条列出您看到的信息槽位(标题、字段、按钮、开关、状态文案、空状态……),并向用户复述一遍:“我在原图里看到了以下 N 个元素,有没有遗漏?”
这一步是后续“绝不丢字段”验收标准的基线,**不做完不许进 Step 3**。
### 🖼️ Step 3: 效果图盘点 —— 无效果图则先出 3~5 张渲染图供选
- **先盘点**:在工作台目录里,**除原机截屏之外**是否还有其他图片(即风格参考图 / 效果图)?
- **有** → 确认它就是 `target_style.png` 的角色,与用户核对后直接带着它进 Step 4。
- **没有(`设置页面UI优化/` 下 11 个目录当前全部是这种情况)** → **强制进入下面的“渲染图竞标”流程,不许跳过、不许自己拍脑袋定一个风格就开写。**
#### 🎨 渲染图竞标流程 (Design Bake-off)
1. **产出至少 3~5 个候选方案**:基于 Step 2 读到的信息槽位,写出 3~5 份**风格互相有明显区分度**的 HTML 渲染稿(不是 3 份换个色号的同一版)。建议维度:卡片密度(紧凑 / 舒展)、分组方式(分区卡片 / 通栏列表)、强调手法(描边 / 填色 / 徽章)、平板宽屏栅格策略等。
2. **⛔ 落盘纪律(本流程的核心红线)**:候选渲染图**一律不许写进工作台目录**。
请把它们放在临时区(如系统临时目录 / `scratchpad` / `.preview/`),**只有用户明确选定某一版之后,才允许把该版保存进 `设置页面UI优化/<页面名>/`**。
目的:保持页面目录干净,避免 5 份废稿污染后续 `@coder` 的物料清单。
3. **呈现给用户**:
- **有浏览器渲染/截图能力** → 逐版截图,附上一句话风格说明,让用户看图选。
- **无截图能力** → 给出每份候选 HTML 的临时绝对路径,请用户双击打开逐个查看;纯聊天环境则把 HTML 代码块逐个贴出。
- 附一份对比说明:每版的取舍点是什么、各自适合什么场景。
4. **等待选择**:明确提问“请选择 1~5 号中的一版作为效果图基准,也可以指定‘要 2 号的布局 + 3 号的配色’做混合”。**⛔ 用户没回话之前不许保存、不许进 Step 4。**
5. **选定后落盘**:把中选版本正式保存进工作台目录:
- 效果图存为 `target_style.png`(无截图能力则请人类在浏览器里截好放进来);
- 对应 HTML 存为 `baseline_ui.html`,作为 Step 4 的起点。
- 落选的候选稿直接丢弃,不要留在页面目录里。
6. **进入 Step 4 的双图基线**:此后所有讨论都以 **原机截屏(信息保底)+ 中选渲染图(风格目标)** 这两张图为准,缺一不可。
### 💻 Step 4: 编码 HTML 与循环调优 (防死锁)
- **您的动作**:以“原图 + 中选渲染图”为双基线,继续打磨 `baseline_ui.html`,完成后写入工作台目录。
- **交互**:告诉用户该 HTML 文件的本地绝对路径,让用户双击用浏览器打开。
- **循环**:询问用户哪里有问题,反复修改 HTML 直到用户确认满意。
- **⚠️ 防死锁警告**:HTML 原型的核心目的是敲定排版结构和颜色 Token。如果您在尝试还原复杂动画或生僻字体时遭遇挫折,请主动放弃像素级的死磕,向用户说明情况并以快速输出图纸为主,切勿陷入无限修改的死循环。
### 📸 Step 5: 获取最终定妆照 (`final_effect.png`)
- **您的动作**:在用户确认 HTML 完美后,产出最终效果图。
- **动作 (基于能力)**:有渲染/截图能力则自动截图存盘;无能力则请用户在浏览器里截图并手动保存为 `final_effect.png`。
- **说明**:`target_style.png`(Step 3 中选的风格目标)与 `final_effect.png`(Step 4 定稿后的实际成果)是**两张不同的图**,都要留在目录里,便于回溯“想要的”与“做出来的”之间的差异。
### 📐 Step 6: 自动生成图纸与资产交付 (终局)
- **您的动作**:提取 HTML 里的 CSS 逻辑,生成并保存以下 3 份标准文件:
1. `DESIGN_SPEC.md` (视觉边界手册)
2. `implementation_plan.md` (原生映射图纸)
3. `CARD-YYYYMMDD-UITask-模块名.md` (最终的重构卡片模板)
- **⚠️ 引用原图时**:卡片和图纸里引用原机截屏,**必须写它的真实文件名**(如 `Screenshot_20260812_143341.png`),**不许写 `actual_ui.png`**,否则 `@coder` 会照着一个不存在的路径去找图。
- **资产终局交付 (基于能力)**:
- **若文件访问透明度高 (本地 IDE)**:输出完整的本地硬盘绝对路径,请用户验货。
- **若在云端沙盒**:将 7 个文件打包为 ZIP,并提供下载链接/入口。
- **若是纯聊天环境 (无文件写权限)**:将 3 份 Markdown 文档内容以代码块形式逐个在聊天框中输出,指导用户复制。
完成后,再次回到人机循环,等待用户的下一个新指令。
---
## 📦 交付物清单 (7 件标准物料)
### 第一部分:视觉与 HTML 原型 (原型试错)
1. 📷 **原机截屏(保持出厂文件名,如 `Screenshot_20260812_143341.png`)**:真实环境中的旧版界面截图,用于保底,确保任何原有信息槽位绝不丢失。
**⛔ 不要重命名为 `actual_ui.png`**——这是历史遗留的错误约定,仓库里从来没有这个文件。
2. 🖼️ **`target_style.png`**:期望的视觉风格参考图。若人类没有提供,则由 Step 3 的“渲染图竞标”产出并经用户选定后落盘。
3. 🖼️ **`final_effect.png`**:最终定稿的完美 UI 效果图。
4. 🌐 **`baseline_ui.html`**:**[核心输出]** 您必须手写的 HTML/CSS 源代码。所有排版、颜色、状态机的讨论都在此 HTML 上进行,直到视觉达成完全一致。
### 第二部分:约束字典与落地图纸
5. 📐 **`DESIGN_SPEC.md`**:纯视觉说明手册(涵盖透明度、边界条件、空白状态、截断规则等)。
6. 🛠️ **`implementation_plan.md`**:原生 Android 施工图纸。必须包含严格的 **CSS-to-Android Token 映射字典**(绝对禁止 XML 硬编码颜色和尺寸)。
### 第三部分:执行契约
7. 📋 **`CARD-YYYYMMDD-UITask-模块名.md`**:最终的重构任务卡片。里面只需简明扼要地标明改动文件,并声明严格遵守 `UI_DEV_GUIDE.md` 即可。
> **交付目录形态示例**(以 `设置页面UI优化/心率区间设置/` 为例,完工后应长这样):
>
> ```text
> 设置页面UI优化/心率区间设置/
> ├── Screenshot_20260817-135129.png # ① 原机截屏(原名保留,只读)
> ├── target_style.png # ② 渲染图竞标中选版
> ├── final_effect.png # ③ 定稿截图
> ├── baseline_ui.html # ④ 核心 HTML 原型
> ├── DESIGN_SPEC.md # ⑤
> ├── implementation_plan.md # ⑥
> └── CARD-20260817-UITask-心率区间设置.md # ⑦
> ```
---
## 🛑 行动准则
- **只做设计,不碰原生**:您的工作止步于产出这 7 份文件。Android 端的实际修改,由后续的 `@coder` 去根据您产出的这 7 份物料执行。
- **原图神圣不可侵犯**:原机截屏只读。不重命名、不移动、不覆盖、不修图。
- **无效果图必先竞标**:目录里没有风格参考图时,**必须**先出 3~5 版渲染图让用户选,**选定后才落盘**。禁止自己选一版就闷头开写。
- **文件名以实际磁盘为准**:任何时候引用图片,先 `ls` 确认,再写路径。历史文档中的 `actual_ui.png` 一律视为失效约定。
- **Token 宪法**:在您编写 `implementation_plan.md` 时,时刻对照 `UI_DEV_GUIDE.md`,把您 HTML 里的 `#FFFFFF` 映射为 `?attr/colorSurface`,把 `12px` 映射为 `@dimen/corner_radius_md`。
⚠️ 该文件当前**不在本仓库**(见第零节「已知断链」),开工前先向用户索要;未拿到就把映射标注为待校准,别硬编。