存了

.cursor/skills/kbone-miniprogram/reference.md

@@ -0,0 +1,110 @@
+# Next → 小程序 转化参考（详细步骤）
+
+与 `SKILL.md` 中「Next 项目 → 小程序 最优转化方式」对应，用于按步骤执行转化。
+
+---
+
+## 1. 架构与目录约定
+
+| 目录/产物 | 作用 |
+|-----------|------|
+| `newpp/` | Kbone 源码：多入口 React，构建输出到 `newpp/dist/mp/` |
+| `miniprogram/` | 小程序壳：`app.js`、`app.json`、`custom-tab-bar`、空白页面占位等 |
+| Next 根目录 `app/`、`components/` | Web 端页面与组件；可被 newpp 复制或通过 alias 引用 |
+
+构建后：将 `newpp/dist/mp/` 下的页面与 `common/` 合并进 `miniprogram/`，保留壳的 `app.js` 全局逻辑。
+
+---
+
+## 2. newpp 配置
+
+### 2.1 miniprogram.config.js
+
+- `router`：每个页面单独 key，对应 Next 路由，**不要使用 `other` 数组**。
+- 动态底部导航：`appExtraConfig` 中**不配置** `tabBar`，用自定义 React 组件 + `wx.reLaunch`。
+- `global`：建议 `rem: true`、`pageStyle: true`。
+- `pages`：为每个页面配置 `extra.navigationBarTitleText`。
+
+示例（按实际路由调整）：
+
+```javascript
+router: {
+  index: ['/', '/(index)?', '/index.html'],
+  chapters: ['/chapters', '/chapters.html'],
+  read: ['/read/:id', '/read.html'],
+  my: ['/my', '/my.html'],
+  match: ['/match', '/match.html'],
+},
+appExtraConfig: {
+  sitemapLocation: 'sitemap.json',
+  // 不配置 tabBar
+},
+```
+
+### 2.2 webpack.mp.config.js
+
+- `entry`：每个页面一个入口，例如 `index`、`chapters`、`read`、`my`、`match`，指向 newpp 内对应入口 JSX。
+- `isOptimize`：`const isOptimize = process.env.NODE_ENV === 'production'`，生产构建时再压缩。
+- `optimization.splitChunks`：中小型项目建议 `splitChunks: false`，避免 chunk 缺失；大型项目再考虑固定命名 cacheGroups。
+
+---
+
+## 3. 适配层（必须）
+
+在 newpp 内（或共享到根目录再被引用）实现：
+
+| 文件 | 职责 |
+|------|------|
+| `adapters/env.js` | `isMiniProgram()`：`typeof wx !== 'undefined' && wx.getSystemInfoSync` |
+| `adapters/request.js` | Web：`fetch`；小程序：`wx.request`，统一返回 Promise |
+| `adapters/storage.js` | Web：`localStorage`；小程序：`wx.getStorageSync`/`setStorageSync` |
+| `adapters/router.js` | Web：`window.location` 或 Next Router；小程序：`wx.navigateTo`/`wx.reLaunch`，路径用 `toMpPath(path)` 转成小程序页面路径 |
+
+业务代码**只**通过适配层访问请求、存储、路由，不直接使用 `window`、`document`、`localStorage`、`URLSearchParams` 等。
+
+---
+
+## 4. 功能控制一致
+
+与 Next 端保持一致：
+
+- 功能开关来自同一 API，例如 `/api/db/config` 的 `features.matchEnabled`。
+- 底部导航「找伙伴」等入口根据该配置条件渲染，不在小程序端写死。
+- 支付方式、营销二维码等同样由 API 配置驱动，两端逻辑一致。
+
+---
+
+## 5. UI 来源策略
+
+- **复制适配**：从 Next 的 `app/**/page.tsx`、`components/**` 复制到 newpp，改为 JSX，用适配层替代 `Link`/`useRouter`/`usePathname`/`fetch`。
+- **Alias 引用**：在 newpp 的 webpack `resolve.alias` 中指向项目根目录的共享组件目录，保证该目录内仅用 React + 适配层，无 Next 专属 API。
+
+---
+
+## 6. 样式兼容（与 Next 视觉一致）
+
+- **Grid → Flex**：所有 Grid 布局改为 Flex，并加 `boxSizing: 'border-box'`、必要时 `lineHeight`。
+- **backdrop-filter / sticky**：不支持则用纯色、渐变或占位，保证布局不错位。
+- **单位**：小程序侧可用 rpx，与 Web 的 rem/px 按设计稿统一换算。
+
+详见 `troubleshooting.md` 中的「样式问题」小节。
+
+---
+
+## 7. 构建与合并流程
+
+1. 在 newpp 执行：`NODE_ENV=production npm run build:mp`。
+2. 将 `newpp/dist/mp/` 下生成的页面目录及 `common/` 复制/合并到 `miniprogram/`。
+3. 保留 miniprogram 壳的 `app.js`（全局 data、onLaunch、onShow 等），仅覆盖或新增 Kbone 生成的页面与 common。
+4. 用微信开发者工具打开 `miniprogram/` 根目录，编译并测试。
+
+---
+
+## 8. 检查清单
+
+- [ ] miniprogram.config.js：每页单独 router，无 `other`；未配置原生 tabBar。
+- [ ] webpack.mp.config.js：每页有 entry；isOptimize 按 NODE_ENV；中小型项目 splitChunks 为 false。
+- [ ] 适配层：env、request、storage、router 已实现并在业务中统一使用。
+- [ ] 功能开关与 Next 一致，来自同一 API。
+- [ ] 样式：无 Grid，Flex 已加 boxSizing/lineHeight；不支持特性已替代。
+- [ ] 合并后 app.js 未被错误覆盖，页面路径与 app.json 一致。