79 lines
6.0 KiB
Markdown
79 lines
6.0 KiB
Markdown
---
|
||
name: soul-miniprogram-dev
|
||
description: Soul 创业派对小程序开发规范。在 miniprogram/ 下编辑时必遵循。WXML/WXSS/JS、app.request、/api/miniprogram/*、scene、支付、权限。Use when editing miniprogram, 小程序, 微信原生.
|
||
---
|
||
# Soul 创业派对 - 小程序开发 Skill
|
||
|
||
当你在 **miniprogram/** 目录下新增、优化或编辑代码时，必须遵循本 Skill。本 Skill 与 soul-api、soul-admin 的边界约束见项目 Rules，防止与 API/管理端逻辑互窜。
|
||
|
||
---
|
||
|
||
## 1. 项目定位与边界
|
||
|
||
- **miniprogram**：微信原生小程序（WXML/WXSS/JS），面向 C 端用户。
|
||
- **唯一后端**：业务接口只请求 **soul-api**（Go），通过 `app.globalData.baseUrl` 配置。
|
||
- **禁止**：不得在 miniprogram 内实现或依赖 next-project 的 API 路由；不得调用 `/api/admin/*`、`/api/db/*` 等管理端路径。
|
||
|
||
---
|
||
|
||
## 2. API 调用规范（防互窜）
|
||
|
||
- **路径前缀**：所有请求**必须**使用 `/api/miniprogram/...`，与 soul-api 的 `miniprogram` 路由组一致。
|
||
- **发起方式**：统一通过 `getApp().request(url, options)`，禁止在页面里直接 `wx.request` 写死 baseUrl。
|
||
- **示例**：
|
||
- 正确：`app.request('/api/miniprogram/book/all-chapters')`、`app.request('/api/miniprogram/login', { method: 'POST', data: { code } })`
|
||
- 错误：`app.request('/api/book/all-chapters')`、`app.request('/api/admin/xxx')`、`/api/vip/status`（若 soul-api 未提供 miniprogram 下等价接口则视为错误，需统一走 miniprogram 组）。
|
||
- **静默请求**：不弹窗的请求（如推荐访问、统计）传 `silent: true`：`app.request(url, { ..., silent: true })`。
|
||
- **错误处理**：`request` 已统一处理 200 且 `success: false`、401、4xx/5xx 与网络错误；页面只需 `try/catch` 或 `.then/.catch`，用 `_getApiErrorMsg` 的文案即可，勿重复造轮子。
|
||
|
||
---
|
||
|
||
## 3. 代码风格与结构
|
||
|
||
- **入口**：`app.js` 内维护 `globalData`（baseUrl、userInfo、openId、bookData、purchasedSections、theme、推荐相关等），页面通过 `getApp().globalData` 读取。
|
||
- **页面**：每个页面一个目录，含 `*.js`、`*.wxml`、`*.wxss`、`*.json`；页面逻辑用 `Page({ data: {...}, onLoad, onShow, ... })`，数据用 `this.setData()` 更新。
|
||
- **工具**：公共方法放在 `utils/`（如 `util.js`、`scene.js`、`chapterAccessManager.js`、`readingTracker.js`、`payment.js`）；使用 `module.exports` 导出，页面内 `require`。
|
||
- **命名**：文件名小写短横线（如 `withdraw-records`）；JS 内变量/函数小驼峰；常量可全大写下划线。
|
||
- **注释**：文件头注明「Soul创业派对 - 模块名」及重要逻辑说明（如 scene 编解码、权限状态机）。
|
||
|
||
---
|
||
|
||
## 4. 业务逻辑约定（与 soul-api 对齐）
|
||
|
||
- **登录**：微信登录走 `POST /api/miniprogram/login`（code）；手机号用 `POST /api/miniprogram/phone-login` 或 `/api/miniprogram/phone`；token 存 `wx.setStorageSync('token', ...)`，请求头由 `app.request` 统一带 `Authorization: Bearer <token>`。
|
||
- **推荐码**：扫码/分享带 `ref` 或 scene 中 `ref`，由 `app.handleReferralCode` 统一处理；绑定调 `POST /api/miniprogram/referral/bind`，访问记录调 `POST /api/miniprogram/referral/visit`（可用 silent）。
|
||
- **书籍/章节**：目录与内容来自 `GET /api/miniprogram/book/all-chapters`、`/api/miniprogram/book/chapter/by-mid/:mid` 等；权限与购买状态用 `GET /api/miniprogram/user/purchase-status`，勿在端内臆造权限规则。
|
||
- **阅读进度**：使用 `utils/readingTracker.js` 与 `chapterAccessManager.js`；进度上报 `POST /api/miniprogram/user/reading-progress`。
|
||
- **支付**：下单/查单走 `POST/GET /api/miniprogram/pay`、回调由 soul-api 处理；支付前必须已有 openId（通过登录或 getOpenId 获得）。
|
||
- **提现**：申请/记录/确认等走 `/api/miniprogram/withdraw/*`；订阅消息模板 ID 在 `app.globalData.withdrawSubscribeTmplId`。
|
||
- **scene 编解码**：海报与扫码统一用 `utils/scene.js` 的 `buildScene`/`parseScene`，支持 mid、id、ref，分隔符与后端生成一致（如 `_`）。
|
||
|
||
---
|
||
|
||
## 5. 与 soul-api 的对接要点
|
||
|
||
- **响应格式**：成功为 `{ success: true, data: ... }` 或带 `message`；失败为 `{ success: false, error: "..." }` 或 `message`；`app.request` 已据此解析并 reject。
|
||
- **鉴权**：需登录的接口由 soul-api 校验 token；401 时 app 会清登录态并提示重新登录。
|
||
- **新增需求**：若 soul-api 尚未提供某能力，应在 soul-api 的 `miniprogram` 组下新增接口，小程序再调 `/api/miniprogram/...`，不得在 miniprogram 内写管理端路径或臆造接口。
|
||
|
||
---
|
||
|
||
## 6. 表单与输入框
|
||
|
||
- **input / textarea 边距**：**必须**用 `<view>` 包裹，padding/边距一律写在 view 上；内部 `<input>` 仅设 `width: 100%` 和字体样式。禁止在 input/textarea 自身上设 padding，否则会光标截断、布局异常。
|
||
- **口诀**：外边包 view，内部 input width 100%。
|
||
- **正确写法**：
|
||
- input：`<view class="form-input"><input class="form-input-inner" ... /></view>`，`.form-input { padding: 16rpx 24rpx; background: #1F2937; }`，`.form-input-inner { width: 100%; font-size: 28rpx; background: transparent; }`
|
||
- textarea：`<view class="form-textarea-wrap"><textarea class="form-textarea-inner" ... /></view>`，`.form-textarea-wrap { padding: 16rpx 24rpx; background: #1F2937; }`，`.form-textarea-inner { width: 100%; font-size: 28rpx; background: transparent; min-height: 160rpx; }`
|
||
|
||
---
|
||
|
||
## 7. 何时使用本 Skill
|
||
|
||
- 在 **miniprogram/** 下新增或修改页面、组件、utils 时。
|
||
- 在小程序内新增或修改任何网络请求路径时（必须保持 `/api/miniprogram/...`）。
|
||
- 做阅读、支付、推荐、提现等与 soul-api 对接的功能时。
|
||
- 做表单、input/textarea 样式时（遵循 §6，用 view 包裹，padding 写在 view 上）。
|
||
|
||
遵循本 Skill 可保证小程序只与 soul-api 的 miniprogram 路由组对接，避免与管理端或 next-project 接口混用。
|