root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

微信小程序页面迁移校验之前 P5任务处理之前

Browse Source
This commit is contained in:
Neo
2026-03-09 01:19:21 +08:00
parent 263bf96035
commit 6e20987d2f
1112 changed files with 153824 additions and 219694 deletions
Download Patch File Download Diff File Expand all files Collapse all files

404
apps/miniprogram - 副本/doc/h5-input-material-guide.md Normal file
View File

@@ -0,0 +1,404 @@
# H5 → 小程序转换：输入材料准备指南
> 本文档规范了每次将 H5 原型页面转换为微信小程序时，应提供的输入材料清单、格式要求和操作步骤。
> 目标：提高 AI 转换还原度，减少颜色/间距换算错误、交互逻辑遗漏、图标处理失误。
---
## 一、HTML 文件规范
### 问题背景
当前 H5 原型是 Tailwind CDN + 内联 SVG + 原生 JS 的单文件结构，存在以下转换障碍：
- Tailwind 工具类需逐个手动展开为 WXSS，容易遗漏或换算错误
- 内联 SVG 在小程序中完全不可用，但混在 HTML 里容易被"直译"
- JS 交互逻辑和 DOM 操作对小程序没有参考价值，反而干扰判断
### 推荐做法
1. **提供渲染后的最终 DOM**（而非模板源码）
- 浏览器中打开页面 → 右键 `<body>` → Copy → Copy outerHTML
- 原因：Tailwind `tailwind.config` 中自定义颜色/间距在源码中只是类名，无法确定最终计算值
- 保存为 `docs/h5_ui/rendered/<page-name>.html`
2. **去掉所有 `<script>` 标签**
- JS 交互逻辑应单独用结构化文本描述（见第三节"交互描述规范"）
- 不要让 AI 从 DOM 操作代码中反推意图
3. **内联关键样式**（二选一）
**方式 A：手动记录（少量元素时）**
```
Chrome DevTools 操作：
1. 打开 H5 页面
2. 右键目标元素 → 检查
3. 在 Styles 面板中，点击 Computed 标签
4. 勾选 "Show all"
5. 记录以下关键属性的计算值：
- width / height / padding / margin / gap
- font-size / font-weight / line-height / color
- background / border-radius / box-shadow
- display / flex-direction / align-items / justify-content
```
**方式 B：脚本批量导出（推荐）**
在 Chrome Console 中执行以下脚本，批量导出关键元素的计算样式：
```javascript
function exportStyles() {
const props = [
'width','height','padding','margin','gap',
'fontSize','fontWeight','lineHeight','color',
'background','backgroundColor','borderRadius',
'boxShadow','display','flexDirection','alignItems',
'justifyContent','position','opacity'
];
const elements = document.querySelectorAll('[class]');
const result = [];
elements.forEach((el, i) => {
const cs = getComputedStyle(el);
const styles = {};
props.forEach(p => {
const v = cs[p];
if (v && v !== 'none' && v !== 'normal' && v !== '0px' && v !== 'auto') {
styles[p] = v;
}
});
if (Object.keys(styles).length > 0) {
result.push({
tag: el.tagName.toLowerCase(),
classes: el.className,
text: el.textContent?.trim().slice(0, 30),
styles
});
}
});
console.log(JSON.stringify(result, null, 2));
}
exportStyles();
```
将输出追加到 `docs/h5_ui/computed-styles.json`（按页面名分 key 存放）
---
## 二、CSS / 样式规范
### 当前状况
CSS 分两部分：Tailwind 工具类（占 90%）+ 少量自定义 `<style>` 块。无 SCSS/LESS 预处理器。
### 设计 Token 文件（做一次，全局复用）
将 Tailwind 自定义主题提取为设计 Token，保存为 `docs/h5_ui/design-tokens.json`：
```json
{
"colors": {
"primary": "#0052d9",
"primary-light": "#ecf2fe",
"success": "#00a870",
"warning": "#ed7b2f",
"error": "#e34d59",
"gray-1": "#f3f3f3",
"gray-2": "#eeeeee",
"gray-3": "#e7e7e7",
"gray-4": "#dcdcdc",
"gray-5": "#c5c5c5",
"gray-6": "#a6a6a6",
"gray-7": "#8b8b8b",
"gray-8": "#777777",
"gray-9": "#5e5e5e",
"gray-10": "#4b4b4b",
"gray-11": "#393939",
"gray-12": "#2c2c2c",
"gray-13": "#242424"
},
"spacing": {
"comment": "Tailwind 默认 1 unit = 4px = 8rpx（基于 750rpx 设计稿）",
"base": 8,
"unit": "rpx"
},
"borderRadius": {
"sm": "8rpx",
"md": "16rpx",
"lg": "24rpx",
"xl": "32rpx",
"2xl": "32rpx",
"3xl": "48rpx"
},
"fontSize": {
"xs": "24rpx",
"sm": "28rpx",
"base": "32rpx",
"lg": "36rpx",
"xl": "40rpx",
"2xl": "48rpx"
},
"shadows": {
"lg": "0 8rpx 32rpx rgba(0,0,0,0.06)",
"xl": "0 16rpx 48rpx rgba(0,0,0,0.08)"
}
}
```
### 自定义动画标注
对 `<style>` 块中的自定义 CSS，需标注处理方式：
| CSS 特性 | 小程序支持 | 处理方式 |
|----------|-----------|----------|
| `@keyframes` + `animation` | ✅ 支持 | 直接迁移 |
| `transition` | ✅ 支持 | 直接迁移 |
| `linear-gradient` | ✅ 支持 | 直接迁移 |
| `backdrop-filter: blur()` | ❌ 不支持 | 改为半透明背景色 `rgba()` |
| `blur-xl`（Tailwind） | ❌ 不支持 | 去掉或改为纯色 |
| CSS 变量 `var()` | ✅ 支持 | 直接迁移（TDesign 大量使用） |
### 不需要做的事
- 不需要展开 SCSS/LESS（当前未使用预处理器）
- 不需要合并 CSS 文件（小程序每个页面有独立 `.wxss`）
---
## 三、交互描述规范
### 为什么需要单独描述
H5 原型中的 JS 交互（`addEventListener`、`classList.toggle`、`innerHTML` 等）在小程序中完全不可用。AI 需要从"用户意图"层面理解交互，而非从"DOM 操作"层面翻译。
### 格式模板
每个页面提供一份交互说明，保存为 `docs/h5_ui/interactions/<page-name>.md`：
```markdown
# 页面名：<page-name>
## 状态变量
| 变量名 | 类型 | 初始值 | 说明 |
|--------|------|--------|------|
| agreed | boolean | false | 协议勾选状态 |
| loading | boolean | false | 登录请求中 |
## 用户操作 → 响应
| 操作 | 触发条件 | 响应行为 | 目标状态 |
|------|----------|----------|----------|
| 点击协议勾选框 | 无 | 切换 agreed | agreed=!agreed |
| 点击"使用微信登录" | agreed=true | 调用登录API | loading=true → 跳转 |
| 点击"使用微信登录" | agreed=false | 无响应（按钮禁用态） | 不变 |
| 登录成功 | API返回 | 按用户状态跳转 | 见流程7.1 |
| 登录失败 | API报错 | Toast提示错误 | loading=false |
## 页面状态枚举
| 状态名 | 视觉表现 | 触发条件 |
|--------|----------|----------|
| 默认态 | 按钮灰色禁用 | agreed=false |
| 可登录态 | 按钮蓝色渐变+阴影 | agreed=true |
| 加载中 | 按钮显示loading | loading=true |
```
### 必须覆盖的状态（每个页面都要考虑）
| 状态 | 说明 | 视觉表现参考 |
|------|------|-------------|
| 正常态（有数据） | 页面主要功能正常展示 | 默认截图 |
| 空数据态 | 列表/卡片区域无数据 | 居中文案 `暂无数据` / `暂无任务` |
| 加载中态 | 数据请求中 | 区域文案 `加载中...` |
| 错误态 | 接口请求失败 | 文案 `加载失败，请点击重试` + 重试按钮 |
| 登录态差异 | 如果页面因登录状态有不同表现 | 按实际描述 |
---
## 四、视觉截图规范
### 截图是校验还原度的唯一视觉参考
### 分辨率
- 使用 iPhone 6/7/8 尺寸（375×667）
- 这是小程序 750rpx 设计基准的 1:1 对应
- Chrome DevTools → Toggle device toolbar → 选择 iPhone 6/7/8
### 每个页面至少截以下状态
| 状态 | 文件命名示例 | 说明 |
|------|-------------|------|
| 默认/正常态 | `login--default.png` | 有数据的主要展示 |
| 关键交互态 | `login--agreed.png` | 勾选协议后按钮变化 |
| 空数据态 | `task-list--empty.png` | 如果适用 |
| 弹窗/浮层 | `task-list--longpress-menu.png` | 弹窗打开状态 |
| 筛选展开 | `board-customer--filter-open.png` | 下拉筛选展开 |
### 命名规范
```
<page-name>--<state>.png
```
- 页面名用小写连字符：`board-customer`、`task-detail`、`my-profile`
- 状态名用小写连字符：`default`、`empty`、`loading`、`error`、`filter-open`、`longpress-menu`
### 存放目录
```
docs/h5_ui/screenshots/
```
### 长页面处理
如果页面有滚动内容，提供长截图：
- Chrome DevTools → Ctrl+Shift+P → 输入 "Capture full size screenshot"
### 不需要的截图
- 不需要暗色模式截图（PRD 无暗色模式需求）
- 不需要多设备截图（仅面向手机竖屏）
---
## 五、资源文件规范
### 当前状况
`docs/h5_ui/img/` 只有 2 张图片，大部分图标是内联 SVG。
### 图标处理优先级
1. **优先使用 TDesign 内置图标**（`<t-icon name="xxx">`），不需要提供文件
2. TDesign 没有的图标，提取为独立 SVG 文件
3. 复杂图形/Logo 使用 PNG/JPG 图片
### 图标文件规范
| 项目 | 规范 |
|------|------|
| 格式 | SVG（图标）、PNG（带透明图片）、JPG（照片类） |
| 命名 | `<category>-<name>.svg`，如 `icon-billiard.svg`、`icon-wechat.svg` |
| 目录 | `apps/miniprogram/miniprogram/assets/icons/`（图标） |
| | `apps/miniprogram/miniprogram/assets/images/`（图片） |
| 尺寸 | 图片提供 2x 版本（750px 宽设计稿对应的实际像素） |
### 图标映射表（每个页面提供）
```markdown
| H5 中的图标描述 | 处理方式 | 小程序引用 |
|----------------|----------|-----------|
| Logo 台球图标 | 自定义SVG | /assets/icons/icon-billiard.svg |
| 任务管理图标 | TDesign | <t-icon name="task" /> |
| 数据看板图标 | TDesign | <t-icon name="chart-bar" /> |
| 智能助手图标 | TDesign | <t-icon name="chat" /> |
| 微信图标 | 自定义SVG | /assets/icons/icon-wechat.svg |
| 返回箭头 | TDesign | <t-icon name="chevron-left" /> |
| 右箭头 | TDesign | <t-icon name="chevron-right" /> |
```
保存为 `docs/h5_ui/icon-mapping.md`，或在每个页面的交互说明中附带。
---
## 六、目录结构总览
准备完成后，`docs/h5_ui/` 目录结构应如下：
```
docs/h5_ui/
├── css/ # 原有：自定义 CSS 文件
├── img/ # 原有：图片资源
├── js/ # 原有：JS 文件
├── pages/ # 原有：H5 原型页面
│ ├── login.html
│ ├── board-customer.html
│ └── ...
├── rendered/ # 新增：渲染后的 DOM（可选）
│ ├── login.html
│ └── ...
├── computed-styles.json # 新增：计算样式（可选，按页面名分 key）
├── screenshots/ # 新增：页面截图（必须）
│ ├── login--default.png
│ ├── login--agreed.png
│ ├── task-list--default.png
│ ├── task-list--empty.png
│ └── ...
├── interactions/ # 新增：交互说明（必须）
│ ├── login.md
│ ├── task-list.md
│ └── ...
├── design-tokens.json # 新增：设计 Token（必须，做一次）
├── icon-mapping.md # 新增：图标映射表（必须，做一次）
└── index.html # 原有：入口页
```
---
## 七、操作步骤——"怎么喂料"
### 一次性准备（全局）
1. 创建 `docs/h5_ui/design-tokens.json`（从 `tailwind.config` 提取，见第二节）
2. 创建 `docs/h5_ui/icon-mapping.md`（全局图标映射表，见第五节）
3. 创建目录：`screenshots/`、`interactions/`、`rendered/`（可选）
### 每个页面的准备流程
#### Step 1：准备 HTML + 计算样式
1. 在 Chrome 中打开 `docs/h5_ui/pages/<page>.html`
2. 切换到 iPhone 6/7/8 设备模式（375×667）
3. 在 Console 中运行 `exportStyles()` 脚本（见第一节）
4. 将输出追加到 `docs/h5_ui/computed-styles.json`（以页面名为 key）
5. （可选）复制渲染后 DOM，保存为 `docs/h5_ui/rendered/<page>.html`
#### Step 2：截图
1. Chrome DevTools → Ctrl+Shift+P → "Capture screenshot"
2. 每个状态截一张，命名为 `<page>--<state>.png`
3. 放入 `docs/h5_ui/screenshots/`
#### Step 3：写交互说明
1. 按第三节格式模板，写出状态变量、操作→响应表、状态枚举
2. 保存为 `docs/h5_ui/interactions/<page>.md`
#### Step 4：标注图标/图片
1. 检查页面中的所有图标和图片
2. 在图标映射表中补充新图标的处理方式
3. 自定义资源放入小程序 `assets/` 对应目录
#### Step 5：喂给 AI
在对话中提供以下信息：
```
请将 <page-name> 页面转换为小程序。
- HTML：docs/h5_ui/pages/<page>.html
- 计算样式：docs/h5_ui/computed-styles.json（页面 key: <page>）
- 截图：docs/h5_ui/screenshots/<page>__default.png（拖入对话）
- 交互说明：docs/h5_ui/interactions/<page>.md
- PRD 参考：P<N> spec <章节号>
- 图标映射：全部使用 TDesign / 见 icon-mapping.md
```
---
## 八、最低限度清单
如果时间有限，以下三项是"必须提供"的底线：
| 优先级 | 材料 | 作用 | 频率 |
|--------|------|------|------|
| P0 | 截图（默认态，375px 宽） | 校验还原度的唯一视觉参考 | 每页 |
| P0 | 交互说明（状态变量 + 操作响应表） | 避免逻辑错误 | 每页 |
| P0 | 设计 Token JSON | 避免颜色/间距换算错误 | 一次 |
| P1 | 计算样式 JSON | 显著提高还原度 | 每页（可选） |
| P1 | 图标映射表 | 避免图标处理失误 | 一次 + 增量 |
| P2 | 渲染后 DOM | 复杂页面时有帮助 | 按需 |
---
## 附录：相关文档
- [H5 → 小程序转换避坑指南](./h5-to-miniprogram-pitfalls.md) — 标签映射、样式差异、事件系统、高频踩坑清单
- [小程序认证系统联调指南](./auth-integration-guide.md) — 前后端联调测试流程
- [产品需求文档](./prd.md) — 完整 PRD（页面级需求）
- PRD Specs — `docs/prd/specs/P1~P11`
- H5 原型 — `docs/h5_ui/pages/`