更新小程序配置,重构页面结构,删除不再使用的地址管理和章节页面,优化项目结构以提升可维护性;调整全局样式,增强组件的可复用性和一致性。

This commit is contained in:
2026-02-03 11:35:38 +08:00
parent d74410cfb5
commit a7d781a25b
79 changed files with 10610 additions and 3518 deletions

View File

@@ -1,70 +1,65 @@
# Web 转小程序 - 完整流程提示词
> **用法**:在对话中 @ 本文件(`scripts/Web转小程序并上传-提示词.md`),请 AI 按本提示词把**整个流程**处理完:先按当前 Web 项目 100% 完整转为小程序代码到 `miniprogram/`,转换完成后打开微信开发者工具。
> **用法**:在对话中 @ 本文件(`scripts/Web转小程序并上传-提示词.md`),请 AI 按本提示词执行:**先枚举要转换的页面 → 按规则 100% 转为小程序 → 自检清单逐项通过 → 可选打开微信开发者工具**
---
## 一、你的任务(当被 @ 本文件时)
1. **转换**:将当前项目中的 **Web 端Next.js** 页面与功能,**完整、一致**地转为微信小程序代码,输出到 **`miniprogram/`** 目录。**转换必须完整,样式、按钮、布局、交互等不得有任何丢失**(见下方「完整性要求」)。
2. **检查**:转换完成后,自检 `miniprogram/` 是否可运行,并逐页对照 Web 端确认无遗漏必要文件、路由、API、样式、按钮、链接、交互一致
3. **打开微信开发者工具**:转换完成后,打开微信开发者工具并导入 `miniprogram/` 目录(可由 AI 代为执行 `start miniprogram``open miniprogram` 打开文件夹,用户将文件夹拖入微信开发者工具;或直接调用微信开发者工具 CLI 打开项目)。
按**顺序**执行:
若用户只要求「转换」,则只执行步骤 12若用户说「完整流程」或 @ 本文件且无特别说明,则执行上述三步
1. **枚举页面**:扫描 `app/` 下所有 `**/page.tsx`(排除 `app/api/``app/admin/`),得到需上小程序的页面列表及对应小程序路径(见二)
2. **转换**:将上述每个 Web 页面**完整、一致**转为小程序代码到 `miniprogram/`**样式、按钮、布局、交互、图标零丢失**(见三、四)。
3. **检查**:按「六、自检清单」逐项自检,确保可运行且与 Web 逐页对照无遗漏。
4. **打开微信开发者工具**(可选):若用户未说「仅转换」,则执行 `start miniprogram`Windows`open miniprogram`Mac或调用微信开发者工具 CLI 打开 `miniprogram/`
**触发约定**:用户只说「转换」或「只转」→ 只做 13用户说「完整流程」或仅 @ 本文件 → 做 14。
---
## 二、项目结构对照(按规则推导,不写死页面)
**转换时请扫描当前仓库的 `app/` 目录,按以下规则生成小程序结构;有新增页面时同样适用。**
**先扫描 `app/` 得到页面列表,再按规则生成小程序路径与四件套;新增 Web 页面时同样适用。**
1. **Web 路由 → 小程序页面路径**
- 规则`app/<path>/page.tsx` 小程序页面路径 `pages/<name>/<name>`其中 `<name>` 取该路由**最后一层目录名**(或约定名称,见下)
- 通用`app/<path>/page.tsx``pages/<name>/<name>``<name>` 取该路由**最后一层目录名**。
- 特例:
- `app/page.tsx`(根首页)`pages/index/index`
- `app/<a>/[id]/page.tsx` 等动态路由`pages/<a>/<a>`页面内通过 `onLoad(options)` `options.id`取参数
- 嵌套路由(如 `app/my/referral/page.tsx`)→ 小程序侧通常用单层页面名,如 `pages/referral/referral`(以功能命名,避免深层路径
- **新增页面**`app/`每增加一个需小程序展示的路由(如 `app/xxx/page.tsx`,就`miniprogram/pages/` 下新增 `pages/xxx/xxx` 四件套(.js/.json/.wxml/.wxss并在 `app.json``pages` 中追加 `"pages/xxx/xxx"`
- `app/page.tsx` `pages/index/index`
- 动态路由 `app/<a>/[id]/page.tsx``pages/<a>/<a>`参数在 `onLoad(options)` 中取 `options.id` 等。
- 嵌套路由(如 `app/my/referral/page.tsx`)→ 单层页面 `pages/referral/referral`,避免深层路径。
- **新增**:每增加一个需小程序 `app/xxx/page.tsx`,就在 `miniprogram/pages/` 下新增 `pages/xxx/xxx` 四件套(.js/.json/.wxml/.wxss并在 `app.json``pages` 中追加 `"pages/xxx/xxx"`
2. **如何枚举要转换的页面**
- 遍历 `app/` 下所有`page.tsx` 的路径(排除 `app/api/``app/admin/` 仅 Web后台用的路由,除非明确要上小程序)
- 对每个需上小程序的页面,按上面规则得到小程序页面路径,确保 `miniprogram/pages/` 存在对应目录及四件套,并`app.json``pages` 中注册。
2. **枚举要转换的页面**
- 遍历 `app/` 下所有含 `page.tsx` 的路径**排除**`app/api/``app/admin/` 仅 Web/后台用的路由。
- 对每个需上小程序的页面,按上条得到路径,确保 `miniprogram/pages/<name>/` 存在四件套且已`app.json``pages` 中注册。
3. **API**
- Web 的 `app/api/*` 不转为小程序代码;小程序通过 `wx.request`**同域名**接口(`https://soul.quwanzhi.com/api/...``miniprogram/utils` 或现有 baseURL 配置一致,不写死 localhost。
- `app/api/*` 不转为小程序代码;小程序 `wx.request` 调**同域名**接口(与 `miniprogram/utils`baseURL 一致),**不写死 localhost**。接口路径、参数、返回格式与 `app/api/` 保持一致
4. **tabBar**
-对需要在底部 tab 展示的页面(如首页、目录、找伙伴、我的)配置 `app.json``tabBar.list`;其余为普通页面。若项目后续新增 tab`tabBar.list` 中追加一项并在 `pages`注册该页
-首页、目录、找伙伴、我的等需底部 tab 的页面配置 `app.json``tabBar.list`;其余为普通页面。新增 tab`tabBar.list` `pages`同步追加
---
## 三、转换规则Web → 小程序)
### 完整性要求(零丢失)
**原则**:以 Web 为唯一真相来源,逐块对照,不猜测、不省略;无法 1:1 处用最接近实现并注释说明。
- **样式**颜色、字体、字号、行高、间距margin/padding、圆角、阴影、背景、边框等必须与 Web 一致,在 WXSS 中完整实现,不得省略或简化。
- **按钮与可点击元素**:每个按钮、链接、可点击区域都要保留,文案、图标、点击跳转/弹窗/提交等行为与 Web 一致;禁用态、加载态等状态也要体现。
- **布局与结构**:区块划分、顺序、折叠/展开、列表/卡片结构等与 Web 一致,不得漏掉任何一块内容或模块。
- **图片与图标**Web 中出现的图片、图标、占位图都要在小程序侧存在并正确引用;**菜单、列表项、统计项、标签、按钮等处的图标必须逐项对照补全**(可用 emoji 或图片),路径可用 `miniprogram/images/` 或 assets。
- **表单与输入**:输入框、选择器、校验、提交逻辑与 Web 一致,不丢字段、不丢校验。
- **若 Web 某块在小程序无法 100% 实现**(如复杂 CSS 或 DOM API用最接近的实现并在此处加注释说明差异不得直接删掉整块内容。
### 3.1 完整性要求(零丢失)
### 组件与语法
- **样式**:颜色、字体、字号、行高、间距、圆角、阴影、背景、边框与 Web 一致,在 WXSS 中完整实现。
- **按钮与可点击**:每个按钮、链接、可点击区域保留,文案、图标、跳转/弹窗/提交与 Web 一致;禁用态、加载态需体现。
- **布局与结构**:区块划分、顺序、折叠/展开、列表/卡片与 Web 一致,不漏模块。
- **图片与图标**Web 中出现的图片、图标、占位图在小程序侧存在并正确引用;**菜单、列表、统计、标签、按钮等处图标逐项对照补全**(可用 emoji 或图片),路径用 `miniprogram/images/` 或 assets。
- **表单**:输入框、选择器、校验、提交与 Web 一致,不丢字段与校验。
1. **组件与语法**
- React/JSX → WXML`wx:if``wx:for``bindtap` 等)。
- Tailwind/CSS 模块 → WXSS**逐条对照 Web 样式**,可保留 class 名,样式写到 `.wxss` 或页面/组件内,确保视觉效果一致)。
- `useState`/`useEffect` → 小程序 Page 的 `data``onLoad``onShow`
- 路由`useRouter`/`Link``wx.navigateTo``wx.switchTab`tab 页用 switchTab
2. **页面与路由**
- 新增/缺失的 Web 页面要在 `miniprogram/app.json``pages` 中注册,并在 `miniprogram/pages/` 下建立对应目录及四件套(.js/.json/.wxml/.wxss
- tabBar 页:保持与现有 `app.json``tabBar.list` 一致(首页、目录、找伙伴、我的)。
3. **接口与数据**
- 请求统一走 `wx.request`baseURL 用项目已有配置(如 `getApp().globalData.baseUrl``utils` 里封装的 request
- 与 Web 共用的接口:路径、参数、返回格式与 `app/api/` 保持一致。
4. **样式与资源**
- 图片:放 `miniprogram/images/` 或现有 assets 目录,引用路径用相对路径或 `/images/xxx`
- 主题色/字体:与 Web 的 `globals.css` 或设计一致,在 WXSS 中实现。
### 3.2 组件与语法
- **React/JSX → WXML**`wx:if``wx:for``bindtap` 等;**禁止在 WXML 中写 JS 方法**(见 4.1)。
- **Tailwind/CSS → WXSS**:逐条对照 Web 样式,可保留 class 名,视觉效果一致;主题色/字体与 `globals.css` 或设计一致
- **状态与生命周期**`useState`/`useEffect` → Page 的 `data``onLoad``onShow`
- **路由**`useRouter`/`Link``wx.navigateTo``wx.switchTab`tab 页用 switchTab
- **接口**`wx.request` + 项目 baseURL路径、参数、返回与 `app/api/` 一致。图片放 `miniprogram/images/` 或 assets引用用相对路径或 `/images/xxx`
---
@@ -74,8 +69,11 @@
### 4.1 WXML 禁止在模板里调用 JS 方法
- **问题**WXML 中不能写 `{{ (user.earnings || 0).toFixed(2) }}``{{ user.nickname.charAt(0) }}``{{ user.id.slice(-8) }}``{{ authorInfo.name.charAt(0) }}`,会报 WXML 编译错误。
- **做法**:在对应页的 `.js` 里(如 `onLoad``syncUser`、数据更新处)**先算好**需要展示字符串,写入 `data`(如 `earningsText``userInitial``userIdSuffix``authorInitial`WXML 只引用 `{{ earningsText }}``{{ userInitial }}` 等。
- **禁止**WXML 中不得出现任何 JS 方法调用,例如:`{{ (user.earnings || 0).toFixed(2) }}``{{ user.nickname.charAt(0) }}``{{ user.id.slice(-8) }}``{{ authorInfo.name.charAt(0) }}`,会报「unexpected token」等编译错误。
- **必须**:在对应页的 `.js` 中(`onLoad``onShow``syncUser`、数据更新处)**预先计算**展示字符串,写入 `data`WXML 只引用 data 变量。推荐命名示例:
- 金额两位小数 → `earningsText``balanceText` 等;
- 用户/作者首字 → `userInitial``authorInitial`
- 用户 ID 后几位 → `userIdSuffix`
### 4.2 启动不阻塞、不因网络报错导致模拟器启动失败
@@ -92,10 +90,11 @@
### 4.4 顶部安全区:状态栏 + 胶囊会遮挡,必须预留
- **问题**小程序使用 `navigationStyle: "custom"` 时,系统**状态栏**(时间、电池等)和右上角**胶囊按钮**会覆盖页面顶部,导致标题、返回、按钮被遮挡或点不到。
- **做法**
- **顶部占位高度**:不用固定 `statusBarHeight + 44`,改用 **`navBarHeight`**。在 `App.getSystemInfo` `wx.getSystemInfoSync()` `wx.getMenuButtonBoundingClientRect()` 计算 `navBarHeight`(状态栏 + 胶囊区域总高),无菜单按钮时回退 `statusBarHeight + 44`。每个页面的占位条/导航条高度设为 `{{ navBarHeight }}px`并在 `onLoad`/`onShow` `getApp().globalData``navBarHeight``statusBarHeight` 写入页面 `data`
- **头部右侧留白**导航栏、标题栏等头部内容需预留胶囊右侧空间,避免被胶囊遮挡。做法:在 `app.wxss` 中定义 `.safe-header-right { padding-right: 200rpx; box-sizing: border-box; }`,所有带标题/按钮的头部容器加上该类;或使用 `globalData.capsulePaddingRight`(由 `windowWidth - menuButton.left + 8` 计算)做内联样式
- **问题**`navigationStyle: "custom"` 时,**状态栏****胶囊按钮**会覆盖页面顶部,标题、返回、按钮被遮挡或点不到。
- **必须**
- **占位高度**统一使用 **`navBarHeight`**不用固定 `statusBarHeight + 44`。在 `App.getSystemInfo` `wx.getSystemInfoSync()` + `wx.getMenuButtonBoundingClientRect()` 计算 `navBarHeight`(状态栏 + 胶囊区域总高),无菜单按钮时回退 `statusBarHeight + 44`。每页占位条高度设为 `{{ navBarHeight }}px``onLoad`/`onShow``getApp().globalData``navBarHeight``statusBarHeight` 写入页面 `data`
- **头部右侧留白**所有带标题/按钮的头部容器加 `.safe-header-right``app.wxss` 中定义 `padding-right: 200rpx; box-sizing: border-box;`或使用 `globalData.capsulePaddingRight` 内联,避免被胶囊遮挡
- **占位页统一模板**:无复杂导航的页面(如 `address-edit``address-list``purchases``referral``settings`)必须使用**同一套**顶部安全区:顶部占位条高度 `navBarHeight`,其内 `padding-top: {{ statusBarHeight || 44 }}px`,导航容器使用 `display: flex; flex-direction: column; justify-content: flex-end; box-sizing: border-box;`,并加 `safe-header-right`,保证标题与返回按钮不被遮挡且右侧留白一致。
### 4.5 图标与样式逐页对照,不得遗漏
@@ -115,6 +114,10 @@
- **卡片内标题行**:若为 flex 布局(如左侧标题 + 右侧链接),给容器加 `gap``min-width: 0`;左侧标题区加 `flex-shrink: 0``min-width: 0`,标题与链接加 `white-space: nowrap`,右侧链接加 `flex-shrink: 0``white-space: nowrap`,防止挤压、换行或重叠错位。
- **全宽按钮**:卡片内的「全宽」按钮使用 `display: block``width: 100%``box-sizing: border-box`,保证与卡片内容区同宽、与上方内容左右对齐;不得因缺 box-sizing 或未 block 导致宽度计算错误而错位。
### 4.7 「我的」-「我的足迹」-「匹配记录」需随 matchEnabled 控制
- **要求**:与 Web 一致,当全局配置 `matchEnabled === false`「我的」页「我的足迹」Tab 下的「匹配记录」区块**不展示**;仅当 `matchEnabled === true` 时展示。小程序侧从 `getApp().globalData.matchEnabled` 读取,在 WXML 中用 `wx:if="{{ matchEnabled }}"` 控制该区块显隐,并在 `onShow` 或数据刷新时同步该值到页面 `data`
---
## 五、必须保留的小程序配置
@@ -128,14 +131,15 @@
## 六、转换完成后的自检清单
- [ ] `app.json` 中所有 `pages` `miniprogram/pages/`均有对应目录四件套。
- [ ] 每个页面的 `.json` `usingComponents` 与自定义组件引用正确(若有)。
- [ ] 无语法错误WXML 闭合、WXSS 合法、JS 中 Page() 注册正确**WXML 中无 `.toFixed()``.charAt()``.slice()` 等 JS 方法调用**均已改为 data 变量
- [ ] 接口 baseURL 为线上或配置项,非 localhost除非仅本地调试)。
- [ ] tabBar 与导航与 Web 一级入口一致;**「找伙伴」默认隐藏,仅配置返回 matchEnabled true 后显示**。
- [ ] **顶部安全区**:所有自定义头部的页面使用 `navBarHeight` 作为顶部占位高度,头部内容使用 `safe-header-right` 或等效右侧留白,避免被状态栏和胶囊遮挡
- [ ] **卡片与按钮对齐**:含标题行+链接+全宽按钮的卡片(如「我的」页我的收益)使用 `box-sizing: border-box`,标题行防挤压/换行,全宽按钮 `display: block``width: 100%``box-sizing: border-box`,与卡片内容区左右对齐无错位。
- [ ] **完整性**:逐页对照 Web确认样式颜色、间距、字体等、按钮、链接、图片、**图标**、表单、列表/卡片等无遗漏;若有无法 1:1 实现处,已用最接近方式实现并注释说明
- [ ] **页面注册**`app.json` `pages` `miniprogram/pages/` 下目录四件套一一对应,无缺页
- [ ] **组件引用**:各页 `.json` `usingComponents` 与自定义组件路径正确(若有)。
- [ ] **WXML 合规**无语法错误;**WXML 中无 `.toFixed()``.charAt()``.slice()` 等 JS 方法**展示用数值/字符串均已预先写入 data 并在模板中引用
- [ ] **接口**baseURL 为线上或配置项,非 localhost仅本地调试可例外)。
- [ ] **tabBar**与 Web 一级入口一致;**「找伙伴」默认 `hidden: true`,仅当接口返回 `matchEnabled === true` 后显示**(见 4.3
- [ ] **顶部安全区**:所有自定义头部使用 `navBarHeight` 占位,头部容器加 `safe-header-right`占位页address-edit、address-list、purchases、referral、settings使用统一顶部安全区模板见 4.4
- [ ] **卡片与按钮**:含标题行+链接+全宽按钮的卡片使用 `box-sizing: border-box`,标题行防挤压/换行,全宽按钮 `display: block``width: 100%``box-sizing: border-box`,与内容区左右对齐无错位(见 4.6
- [ ] **「我的足迹」-「匹配记录」**:该区块随 `globalData.matchEnabled` 显隐,`matchEnabled === false` 时不展示(见 4.7
- [ ] **完整性**:逐页对照 Web样式、按钮、链接、图片、**图标**、表单、列表/卡片无遗漏;无法 1:1 处已用最接近实现并注释说明。
---
@@ -152,11 +156,11 @@
## 八、参考文件位置
- Web 页面`app/**/page.tsx``components/`
- 小程序现有结构:`miniprogram/app.json``miniprogram/pages/``miniprogram/utils/``miniprogram/custom-tab-bar/``miniprogram/app.js`
- 上传脚本`scripts/autosysc-weixin.py`(项目根运行,需先配置 `miniprogram/private.key`
- 小程序配置说明:`miniprogram/小程序快速配置指南.md``miniprogram/小程序部署说明.md`
- **Web 对照**`app/**/page.tsx``components/`;接口路径、参数、返回格式参照 `app/api/`,保证与 Web 一致。
- **小程序结构**`miniprogram/app.json``miniprogram/pages/``miniprogram/utils/``miniprogram/custom-tab-bar/``miniprogram/app.js`
- **上传**`scripts/autosysc-weixin.py`(项目根运行,需先配置 `miniprogram/private.key`
- **配置说明**`miniprogram/小程序快速配置指南.md``miniprogram/小程序部署说明.md`
---
**当你被 @ 本文件时**:按「一、你的任务」执行完整流程(转换 → 检 → 打开微信开发者工具),并严格遵循二~六的对照、规则与踩坑必做项
**当你被 @ 本文件时**:按「一、你的任务」顺序执行(枚举页面 → 转换 → 检 → 可选打开开发者工具),并**严格遵循**二(结构对照)、三(转换规则)、四(踩坑必做项)、五(配置保留)、六(自检清单);四、六中的条目为必做项,不可省略