6.0 KiB
6.0 KiB
name, description
| name | description |
|---|---|
| soul-miniprogram-dev | 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; }
- input：
7. 何时使用本 Skill
- 在 miniprogram/ 下新增或修改页面、组件、utils 时。
- 在小程序内新增或修改任何网络请求路径时（必须保持
/api/miniprogram/...）。 - 做阅读、支付、推荐、提现等与 soul-api 对接的功能时。
- 做表单、input/textarea 样式时（遵循 §6，用 view 包裹，padding 写在 view 上）。
遵循本 Skill 可保证小程序只与 soul-api 的 miniprogram 路由组对接，避免与管理端或 next-project 接口混用。