feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations
This commit is contained in:
134
docs/miniprogram-dev/api-audit/apply.md
Normal file
134
docs/miniprogram-dev/api-audit/apply.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# apply 页面数据来源排查
|
||||
|
||||
> 排查日期：2026-03-18
|
||||
> 页面路径：pages/apply/apply
|
||||
|
||||
## 概览
|
||||
|
||||
| 分类 | 数量 | 说明 |
|
||||
|------|------|------|
|
||||
| A. Mock 数据 | 0 | 无 mock 数据 |
|
||||
| B. 硬编码数据 | 5 | 表单校验规则、延时跳转、错误提示文案 |
|
||||
| C. 已对接 API | 2 | `/api/xcx/me`（GET）、`/api/xcx/apply`（POST） |
|
||||
| D. 前端计算/派生数据 | 2 | statusBarHeight、submitting 状态 |
|
||||
| E. 路由参数 | 0 | 无路由参数 |
|
||||
| F. WXML 硬编码文案 | 16 | 标题、欢迎语、步骤条、表单标签、placeholder、提示语 |
|
||||
|
||||
---
|
||||
|
||||
## 一、Mock 数据
|
||||
|
||||
无。页面未使用任何 mock 数据或本地假数据。
|
||||
|
||||
---
|
||||
|
||||
## 二、硬编码数据
|
||||
|
||||
| # | 位置（apply.ts 行号） | 内容 | 风险等级 | 说明 |
|
||||
|---|----------------------|------|----------|------|
|
||||
| B1 | L89 `!/^\d{11}$/.test(phone)` | 手机号正则：固定 11 位纯数字 | 🟡 低 | 仅适用于中国大陆手机号，若未来支持港澳台/海外号码需调整 |
|
||||
| B2 | L85 `maxlength="5"`（WXML） | 球房ID最大长度 5 | 🟡 低 | 与后端 site_code 长度约束需保持一致 |
|
||||
| B3 | L113 `setTimeout(() => {...}, 800)` | 提交成功后 800ms 延时跳转 | 🟢 无风险 | 纯 UX 延时，不影响业务逻辑 |
|
||||
| B4 | L117-123 错误码映射 | `409 → "您已有待审核的申请"`、`422 → "表单信息有误，请检查"` | 🟡 低 | 错误文案硬编码在前端，后端 detail 字段优先使用 |
|
||||
| B5 | L82-96 表单校验逻辑 | 4 条必填校验 + 手机号格式校验 | 🟢 无风险 | 标准前端校验，后端有独立校验 |
|
||||
|
||||
---
|
||||
|
||||
## 三、已对接 API
|
||||
|
||||
### API-1：获取当前用户状态
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 端点 | `GET /api/xcx/me` |
|
||||
| 调用位置 | `apply.ts` → `_checkAccess()` (L30) |
|
||||
| 调用时机 | `onShow` 生命周期 |
|
||||
| 请求参数 | 无（仅 Authorization header） |
|
||||
| 认证 | `needAuth: true`（自动附加 Bearer token） |
|
||||
| 响应字段 | `user_id`、`status`（new/pending/approved/rejected/disabled）、`nickname` |
|
||||
| 响应处理 | 写入 `app.globalData.authUser` + `wx.setStorageSync("userId"/"userStatus")`；根据 status 路由分发 |
|
||||
| 错误处理 | catch 静默忽略（允许用户继续填表） |
|
||||
|
||||
**路由分发逻辑：**
|
||||
|
||||
| status | 行为 |
|
||||
|--------|------|
|
||||
| `new` | 留在当前页（允许填写申请表） |
|
||||
| `rejected` | `reLaunch → /pages/no-permission/no-permission` |
|
||||
| `approved` | `reLaunch → /pages/mvp/mvp` |
|
||||
| `pending` | `reLaunch → /pages/reviewing/reviewing` |
|
||||
| `disabled` | `reLaunch → /pages/no-permission/no-permission` |
|
||||
|
||||
### API-2：提交入驻申请
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 端点 | `POST /api/xcx/apply` |
|
||||
| 调用位置 | `apply.ts` → `onSubmit()` (L99) |
|
||||
| 调用时机 | 用户点击"提交申请"按钮 |
|
||||
| 认证 | `needAuth: true` |
|
||||
| 请求参数 | 见下表 |
|
||||
| 成功处理 | Toast "申请已提交" → 800ms 后 `reLaunch → /pages/reviewing/reviewing` |
|
||||
| 错误处理 | 优先取 `err.data.detail`；409 → "您已有待审核的申请"；422 → "表单信息有误"；其他 → "提交失败，请稍后重试" |
|
||||
|
||||
**请求参数：**
|
||||
|
||||
| 字段 | 来源 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| `site_code` | 表单输入 `siteCode`（trim） | string | ✅ | 球房ID |
|
||||
| `applied_role_text` | 表单输入 `role`（trim） | string | ✅ | 申请身份（自由文本） |
|
||||
| `phone` | 表单输入 `phone` | string | ✅ | 11 位手机号 |
|
||||
| `employee_number` | 表单输入 `employeeNumber`（trim，空则 undefined） | string? | ❌ | 编号（选填） |
|
||||
| `nickname` | 表单输入 `nickname`（trim） | string | ✅ | 昵称 |
|
||||
|
||||
---
|
||||
|
||||
## 四、前端计算/派生数据
|
||||
|
||||
| # | 数据 | 来源 | 位置 |
|
||||
|---|------|------|------|
|
||||
| D1 | `statusBarHeight` | `wx.getWindowInfo().statusBarHeight` | `onLoad()` L14 |
|
||||
| D2 | `submitting` | 布尔状态锁，`onSubmit` 开始时设 true，finally 设 false | `onSubmit()` L98/L126 |
|
||||
|
||||
---
|
||||
|
||||
## 五、路由参数
|
||||
|
||||
无。`onLoad()` 未读取 `options` 参数。
|
||||
|
||||
---
|
||||
|
||||
## 六、WXML 硬编码文案
|
||||
|
||||
| # | 元素 | 文案内容 | 建议 |
|
||||
|---|------|----------|------|
|
||||
| F1 | navbar-title | `申请访问权限` | 可保留 |
|
||||
| F2 | welcome-title | `欢迎加入球房运营助手` | 可保留 |
|
||||
| F3 | welcome-desc | `请填写申请信息，等待管理员审核` | 可保留 |
|
||||
| F4 | step-label 1 | `提交申请` | 可保留 |
|
||||
| F5 | step-label 2 | `等待审核` | 可保留 |
|
||||
| F6 | step-label 3 | `审核通过` | 可保留 |
|
||||
| F7 | step-label 4 | `开始使用` | 可保留 |
|
||||
| F8 | form-label | `球房ID` | 可保留 |
|
||||
| F9 | form-label | `申请身份` | 可保留 |
|
||||
| F10 | form-label | `手机号` | 可保留 |
|
||||
| F11 | form-label | `编号` + `选填` | 可保留 |
|
||||
| F12 | form-label | `昵称` | 可保留 |
|
||||
| F13 | placeholder | `请输入球房ID` / `请输入申请身份（如：助教、店长等）` / `请输入手机号` / `请输入编号` / `请输入昵称` | 可保留 |
|
||||
| F14 | form-tip | `请认真填写，信息不完整可能导致审核不通过` | 可保留 |
|
||||
| F15 | submit-btn-text | `提交申请` | 可保留 |
|
||||
| F16 | bottom-tip | `审核通常需要 1-3 个工作日` | 🟡 若审核时效变化需同步更新 |
|
||||
|
||||
---
|
||||
|
||||
## 七、联调 TODO
|
||||
|
||||
| # | 类型 | 描述 | 优先级 |
|
||||
|---|------|------|--------|
|
||||
| T1 | 验证 | 确认 `GET /api/xcx/me` 返回字段与前端解构一致（`user_id`、`status`、`nickname`） | P0 |
|
||||
| T2 | 验证 | 确认 `POST /api/xcx/apply` 请求体字段名与后端 schema 一致（`site_code`、`applied_role_text`、`phone`、`employee_number`、`nickname`） | P0 |
|
||||
| T3 | 验证 | 确认后端 409 响应场景（重复申请）和 422 响应场景（参数校验失败）的 `detail` 字段格式 | P1 |
|
||||
| T4 | 验证 | 确认 `site_code` 最大长度（前端 maxlength=5）与后端约束一致 | P1 |
|
||||
| T5 | 优化 | `_checkAccess` 的 catch 静默忽略网络错误——考虑是否需要给用户提示网络异常 | P2 |
|
||||
| T6 | 优化 | `employee_number` 空值传 `undefined`（JSON 序列化时会被忽略）——确认后端是否接受缺省该字段 | P1 |
|
||||
| T7 | 确认 | `status` 枚举值完整性——前端处理了 `new/rejected/approved/pending/disabled`，确认后端不会返回其他值 | P1 |
|
||||
Reference in New Issue
Block a user