feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

apps/DEMO-miniprogram/miniprogram/pages/notes/MIGRATION_NOTES.md

@@ -0,0 +1,185 @@
+# Notes 页面迁移说明
+
+## 迁移版本
+- **H5 原型基准**：`docs/h5_ui/pages/notes.html`
+- **桥文档版本**：v3.0
+- **迁移日期**：2026-03-14
+
+---
+
+## 样式调整清单
+
+### 1. 单位转换规则
+遵循桥文档 §2.3 的混合单位策略：
+- **主要使用 `px`**：因为notes页面的尺寸需要与H5原型1:1对齐
+- **换算基准**：H5 CSS px → 小程序 px（412宽设备验收基准）
+
+### 2. 导航栏（.custom-nav）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| height | 44px | 44px | 标准导航栏高度 |
+| padding | 0 16px | 0 16px | 左右内边距 |
+| border-bottom | 1px solid | 1px solid #eeeeee | 分割线 |
+
+**icon 尺寸调整**：
+- H5: `w-5 h-5` (20px)
+- 小程序: `size="24px"` (考虑小程序点击区域最小44px)
+
+### 3. 备注卡片（.note-card）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| border-radius | rounded-2xl (16px) | 16px | 圆角 |
+| padding | p-4 (16px) | 16px | 内边距 |
+| box-shadow | shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | 阴影 |
+| margin-bottom | mb-3 (12px) | 12px | 卡片间距 |
+
+### 4. 文本样式
+
+#### 备注内容（.note-content）
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| font-size | text-sm (14px) | 14px | 正文字号 |
+| line-height | leading-relaxed (1.625) | 20px | 行高（按附录B标准） |
+| color | text-gray-13 | #242424 | 正文颜色 |
+| margin-bottom | mb-3 (12px) | 12px | 下边距 |
+
+**line-height 设置规则**（附录B.2.3）：
+- 在外层 `<view>` 的 class 上设置 `line-height`
+- `<text>` 会自动继承，不需要额外设置
+
+#### 标签（.note-tag）
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| padding | px-2.5 py-1 (10px 4px) | 4px 10px | 标签内边距 |
+| font-size | text-xs (12px) | 12px | 标签字号 |
+| border-radius | rounded-lg (8px) | 8px | 圆角 |
+| border | 1px solid | 1px solid | 边框 |
+
+#### 时间戳（.note-time）
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| font-size | text-xs (12px) | 12px | 时间字号 |
+| color | text-gray-6 | #a6a6a6 | 次级文字颜色 |
+
+### 5. 列表容器（.note-list）
+
+| 属性 | H5 值 | 小程序值 | 说明 |
+|------|------|--------|------|
+| padding | p-4 (16px) | 16px | 列表外边距 |
+| gap | space-y-3 (12px) | 12px | 卡片间距 |
+
+### 6. 颜色映射（附录C）
+
+| 用途 | 色值 | 说明 |
+|------|------|------|
+| 主品牌色 | #0052d9 | primary |
+| 成功色 | #00a870 | success |
+| 背景色 | #f3f3f3 | gray-1 |
+| 正文色 | #242424 | gray-13 |
+| 次级文字 | #a6a6a6 | gray-6 |
+| 分割线 | #eeeeee | gray-2 |
+
+### 7. 标签渐变背景
+
+**客户标签**：
+```css
+background: linear-gradient(135deg, #ecf2fe, #e8eeff);
+color: #0052d9;
+border-color: #c5d4f7;
+```
+
+**助教标签**：
+```css
+background: linear-gradient(135deg, #e8faf0, #e0f7ea);
+color: #00a870;
+border-color: #b3e6d0;
+```
+
+---
+
+## 关键调整点
+
+### 1. 全局 line-height 设置
+```wxss
+page {
+  line-height: 1.5;
+}
+
+view {
+  line-height: inherit;
+}
+```
+**原因**：微信小程序 `<text>` 组件不能直接设置 `line-height`，必须在外层 `<view>` 设置（附录B.2.3）
+
+### 2. 单位统一为 px
+- 原小程序版本混用 `rpx` 和 CSS 变量
+- 调整为直接使用 `px`，确保与H5原型1:1对齐
+- 所有尺寸基于412宽设备验收基准
+
+### 3. 移除 CSS 变量依赖
+- 原：`var(--color-gray-2, #eeeeee)`
+- 新：直接使用 `#eeeeee`
+- 原因：确保样式独立，不依赖全局变量
+
+### 4. Icon 尺寸调整
+- 原：`size="48rpx"` (约88px)
+- 新：`size="24px"` (标准导航栏icon尺寸)
+- 原因：与H5原型中的 `w-5 h-5` 对齐
+
+### 5. 加载态 icon 尺寸
+- 原：`size="80rpx"` (约146px)
+- 新：`size="40px"` (适配小屏幕)
+
+---
+
+## 附录参考
+
+### 使用的附录
+1. **附录A**：Spacing 与尺寸字典 v3.0
+   - 间距换算：16px → 16px（px模式）
+   - 圆角：8px, 16px
+
+2. **附录B**：字体与文本字典 v3.1
+   - text-sm: 14px / 20px
+   - text-xs: 12px / 16px
+   - **关键规则**：line-height 必须在外层 view 上设置
+
+3. **附录C**：颜色字典 v3.0
+   - 项目自定义颜色表
+   - 透明度变体处理
+
+4. **附录D**：布局类映射字典 v3.0
+   - flex 布局
+   - gap 间距
+
+---
+
+## 验收清单
+
+- [x] 导航栏高度与H5对齐（44px）
+- [x] 卡片圆角与H5对齐（16px）
+- [x] 文字大小与H5对齐（14px/12px）
+- [x] 行高设置正确（在view上设置）
+- [x] 颜色值与H5对齐
+- [x] 间距与H5对齐（16px padding, 12px gap）
+- [x] 标签样式与H5对齐（渐变背景）
+- [x] 阴影效果与H5对齐（shadow-sm）
+
+---
+
+## 已知限制
+
+1. **安全区处理**：使用 `statusBarHeight` 动态计算，不使用 `env(safe-area-inset-*)`
+2. **AI 悬浮按钮**：bottom 值为 120px，需根据实际设备调整
+3. **页面滚动**：使用页面自然滚动，未使用 scroll-view
+
+---
+
+## 后续维护
+
+- 若真机测试发现尺寸偏差，优先检查 line-height 设置
+- 若需要调整间距，参考附录A的spacing表
+- 若需要调整字号，参考附录B的字体表
+- 颜色调整参考附录C的颜色字典