# Nonmotor 前端开发入门：从需求到交付

正式阅读稿见 [Nonmotor 前端开发指南](./nonmotor-development-guide.md)。本文件保留分享时长、演示安排和备课建议。

> 面向后端工程师的分享编排稿。目标：听完后能够定位代码、判断改动方式，并在评审支持下完成一个小型前端需求。
>
> 依据：用户提供的《admin后端开发流程》页面 HTML，以及 nonmotor_h5 当前工作区源码。核对日期：2026-10-09。本文是培训设计，示例需求尚未实施，本地启动和部署步骤尚未实跑。

## 1. 编排思路

沿用参考文档的「项目介绍、环境搭建、开发流程、部署、配套工具」骨架，把最多时间放在一个需求如何完成。

建议采用两层材料：

- 分享主线：60 分钟讲解与演示，围绕一个小需求走完闭环，另留 15 分钟答疑。
- 配套手册：环境安装、命令、平台入口、分支约定、排障清单和基础语法，供实际开发时查阅。

开场可直接使用：

> 这次分享面向已经熟悉保险后端业务的同学。我们从一个投保页需求出发，看它如何落到 Journey 配置、React 页面、接口和数据流，再完成联调、自测和提测。学完之后，希望大家能够接下一个范围明确的小需求，并知道哪些地方需要进一步评审。

完成培训的可观察目标：给定市场、产品和页面 URL，学员能找到入口；能判断修改配置还是代码；能追踪一个字段从展示到请求的路径；能提交包含验证证据和发布物料的 MR。

## 2. 分享顺序与时间

| 章节 | 时间 | 学员要回答的问题 | 推荐展示材料 |
| --- | --- | --- | --- |
| 认识业务与系统边界 | 5 分钟 | nonmotor 在整条投保链路中负责什么？ | 产品详情 → 投保信息 → 确认 → 收银台的页面截图 |
| 从 URL 找到代码 | 7 分钟 | 我拿到页面后，第一份代码在哪里？ | 市场入口配置、index.tsx、App.tsx、一次接口调用 |
| 跑起目标页面 | 6 分钟 | 如何确保自己在改正确的市场、应用和环境？ | 一次启动演示、目标 URL、Network 面板 |
| 需求分析与方案选择 | 8 分钟 | 改配置、复用组件，还是新增能力？ | 需求分类表、字段与接口矩阵 |
| 一个小需求的完整实现 | 18 分钟 | 每一步具体改哪里，如何证明正确？ | Journey 前后差异、代码差异、请求体与页面效果 |
| 联调、自测与排障 | 7 分钟 | 页面有问题时如何逐层定位？ | Network、Console、配置与缓存检查 |
| 提测、发布与上线检查 | 5 分钟 | 除了代码，还有哪些东西要交付？ | MR、测试证据、翻译/图片/Journey 发布清单 |
| AI 协作与第一个练习 | 4 分钟 | 如何借助现有工具接下一个需求？ | 完整输入示例、练习验收要求 |

## 3. 各章节展开方式

### 3.1 认识业务与系统边界

先展示一条目标产品的实际链路，讲清每页输入、输出与用户操作。以当前仓库已有的 Factory V2 路径为讲解候选：PDP → Purchase → Confirmation → Checkout；实际顺序和步骤以演示产品为准。

重点解释：

- 页面负责交互、展示、输入校验、临时状态和接口调用；最终业务合法性仍由后端校验。
- 页面运行在浏览器或 App WebView，登录、返回、打开页面等能力通过项目 Bridge 与宿主交互。
- 当前是多入口多页面工程，先从 HTML 入口找对应代码。页面内部是否有步骤切换，再看具体实现。
- 同一套页面组件可以服务多个市场、产品；最终页面同时受代码、Journey、翻译、接口数据和环境影响。

用后端熟悉的职责作对照，避免机械套用后端分层名称：

| 后端已有认知 | 前端需要建立的认知 |
| --- | --- |
| 请求入口 | HTML entry / index.tsx 是页面启动入口，用户事件会触发后续处理 |
| 业务编排 | App、业务组件和 Hook 组织页面状态及交互，不是一条只执行一次的请求链 |
| 下游客户端 | service/model 封装接口，通过统一 request 发出请求 |
| 配置中心 | PFC 和 Journey 等配置参与页面行为；Journey 还能决定页面有哪些区块与字段 |
| 请求上下文 | props、state、Context 与页面缓存各有生命周期，不能当作同一种存储 |
| 服务日志 | Console、Network、IDAP 与后端请求日志共同构成排查依据 |

### 3.2 从 URL 找到代码

现场追踪一个市场的真实入口，例如 MY 的 purchase5：

1. 在 `config/nonmotor/my.json` 找到 `purchase5.html`，通过 chunks 找到 entry。
2. entry 指向 `src/pages/factoryV2/purchase5/index.tsx`。
3. index.tsx 挂载 BaseComponent 和 App，并初始化页面埋点。
4. `App.tsx` 请求 Journey，按 block/组件名组织页面与步骤。
5. 沿 import 找到 model、组件、表单与缓存处理，再在 Network 核对实际响应。

只介绍日常定位需要的目录：

| 位置 | 什么时候查 |
| --- | --- |
| `config/nonmotor/{region}.json` | 找目标市场的页面入口、新增入口 |
| `src/pages/factory/`、`src/pages/factoryV2/` | 找产品工厂页面与业务组件；以入口引用确定版本 |
| `src/pages/checkoutV2/` | 查收银台相关实现 |
| `src/service/`、页面内 `model/` 或 `service/` | 查请求封装、类型和响应转换 |
| `src/common/request.ts` | 查公共请求行为 |
| `src/InsEntry/` | 查动态表单、字段及校验能力 |
| `src/MoneeDesign/`、`src/components/` | 查现有 UI 控件和业务组件 |
| `src/bridge/`、`src/locales/` | 查宿主交互和国际化 |
| `runbooks/`、`docs/automation/` | 查现有回归用例、执行规则和证据要求 |

注意：仓库仍包含历史 ins_h5 名称和其他业务目录，目录存在并不代表它属于当前 nonmotor 构建。以 APP_NAME、REGION 和入口配置共同确定范围。

### 3.3 跑起目标页面

配套手册列明仓库权限、公司 npm 源、网络、测试账号、目标产品、有效页面参数以及本地联调方式。

已核对的入口：

- `.nvmrc` 当前为 `v20`；旧 package.json 的最低版本声明不能作为完整安装指南。
- 依赖安装脚本使用 `npm install --registry https://npm.shopee.io --legacy-peer-deps`。
- `npm run dev` 打开交互菜单，选择开发、目标环境、目标市场、服务 `nonmotor` 和适用构建环境。
- 启动后使用该市场已登记的页面和完整业务参数验证，不把服务启动成功当作业务页面验证通过。

现场要证明：页面能展示、接口请求打到预期环境、目标产品正确、登录态可用。需要 PFB 时还应验证请求确实进入目标后端分支；单纯设置前端 ENV 不足以证明后端 PFB 正确。

正式文档已补充 ZeroOmega → Whistle → 本地开发服务的代理链路、安装与证书步骤、市场规则和验收方式。分享时重点演示原业务域名加载本地代码，以及 API 经开发代理请求后端的区别；TH/SG/PH 的浏览器域名与源码 API 目标差异需实测确认。登录与 PFB 操作仍待补齐。浏览器演示之后，涉及 App 能力的需求仍需在目标 WebView 验证。

iOS 模拟器的安装步骤已补入正式文档第 2.10 节：安装 Xcode/runtime → 启动 Simulator → 获取对应市场的 Simulator App 包 → 解压安装 → 开启系统代理并配置信任证书 → 验证 App 内 H5。强调 Chrome 插件代理与模拟器系统代理的区别，以及调试后恢复代理设置。

### 3.4 拿到需求，先判断改动落点

先确认市场、产品、入口、PRD、设计稿、接口协议、异常分支与验收标准。需求分析的交付物是一张影响清单。

| 需求类型 | 先检查 | 可能交付物 |
| --- | --- | --- |
| 文案、图片、显隐和已有校验变化 | Journey、翻译和已有组件是否支持 | Journey / i18n / 图片资源及验证证据 |
| 已有字段或交互调整 | 当前字段配置、组件能力、缓存和接口映射 | 配置和必要代码改动 |
| 新业务区块或新交互能力 | 能否复用业务组件或 MoneeDesign；是否需要扩展表单能力 | 新增或扩展组件、配置接入与回归清单 |
| 新页面或新投保步骤 | 能否复用现有模板；入口、返回路径、状态传递是否完整 | 页面、入口配置、导航、缓存契约与埋点 |
| 接口字段变化 | 请求/响应类型、业务码、空值和展示规则 | 接口封装、数据转换与消费方调整 |

特别讲清：是否“只改配置”取决于现有能力。配置无法表达的新行为，需要代码支持；新增接口字段也可能同时影响确认页、报价和创单。

### 3.5 贯穿案例：投保信息新增一个字段

这是教学案例，具体字段和产品待选择。优先挑已有产品中范围小、能体现校验与数据传递的改动。

按七步演示，每步都展示一份产物：

1. **拆需求**：字段何时显示、是否必填、是否预填、如何报错、确认页如何展示、后端如何接收。
2. **查已有能力**：找到该产品 Journey 与对应组件，判断配置是否足够。
3. **列字段矩阵**：对齐 UI 文案、entry name、field_name、缓存路径、请求字段、类型、空值策略和展示格式。
4. **实现**：先复用字段组件和校验；确需扩展时，说明组件、页面、service 各自负责什么。展示修改前后差异。
5. **闭合数据流**：输入 → 校验 → 当前步骤写缓存 → 下一页读缓存 → 确认展示 → 最终请求，逐点核对。
6. **验证**：正确输入、空值、错误格式、返回修改、接口异常，以及其他复用产品的影响。
7. **交付**：提交代码/配置差异、截图、请求核对结果、回归范围和发布依赖。

现场字段矩阵模板：

| UI 字段 | Journey 标识 | 表单字段 | 缓存路径 | 接口字段/类型 | 确认页展示 | 校验与空值策略 |
| --- | --- | --- | --- | --- | --- | --- |
| 演示字段 | 从实际配置填写 | 从运行时表单核对 | 从步骤实现核对 | 从接口协议核对 | 从设计和 formatter 核对 | 从 PRD 和契约核对 |

当前 Journey 规范强调：Admin/O 端配置源是事实来源，可读 view 从它生成，本地 mock 从 view 生成；各步骤在本环节完成缓存读取、校验、转换和写回。正式讲稿应使用这一约定，避免把历史独立 mock 快照教成新的默认流程。

在这一步穿插最少的前端知识：TypeScript 对象和可选值、组件与 props、state 驱动渲染、事件、Effect 的依赖与清理、异步请求和 SCSS 布局。结合案例说明，不展开语言大全。

### 3.6 联调、自测与排障

采用固定定位顺序：

1. 页面入口是否正确：APP_NAME、REGION、HTML 与产品参数。
2. 资源是否正常：页面加载、JS/CSS、Console 错误。
3. 请求是否正确：实际 URL、参数、登录态、环境/PFB、HTTP 状态及业务码。
4. 数据是否正确：响应、Journey、翻译、组件注册、显隐和校验依赖。
5. 状态是否正确：表单值、缓存、上一步返回与再次进入。
6. 宿主行为是否正确：App 返回、页面跳转、支付等目标运行环境行为。

给学员一张提交前检查表：目标市场构建、类型与定向 lint/格式检查、需求验收路径、失败状态、返回/重进、公共组件受影响产品、移动端视觉和埋点。按仓库约定，不把新增前端单测文件作为默认交付要求；保留并按需执行已有相关测试。

展示现有 Runbook 能提供的步骤和证据。执行自动化时按 `runbooks/index.json` 的 executionOwner 选择执行链，遵守各自 session 和产物边界。

### 3.7 提测、发布与上线检查

复用后端同学熟悉的「代码 + 配套物料」表达，交付内容包括：

- MR：需求、改动范围、涉及市场/产品、验证结果。
- 配套物料：Journey、i18n、图片 CDN、PFC 配置和后端接口依赖，明确适用范围及先后顺序。
- QA 交接：入口、环境、账号获取方式、场景、预期和已知限制；不把凭证写进文档或仓库。
- 发布核对：前端包、配置和接口版本兼容；回退时同时考虑代码与配置的配套关系。
- 上线检查：目标页面、主链路、错误监控及关键行为数据。

源码能确认 nonmotor 有独立部署模块，构建读取 REGION/环境，产物目录为 `dist/nonmotor`，部署入口使用 `/nonmotor/`。因此必须说明市场维度，不能照搬参考后端文档中的“按机房部署一次覆盖全部市场”。

团队已确认：Casement 建立 `release-v1.x.xxx` 迭代，本地在 `dev-v1.x.xxx` 分支开发、提交 commit 和自测；完成后提交 MR 合入同版本 release，合入并发布后到 Casement 部署对应版本。分享时用正式文档中的 Casement 截图展示应用、迭代、环境、Region、版本/PFB 与部署状态的核对。Reviewer、部署负责人和审批细则仍待补充。

### 3.8 AI 协作与上手练习

将 AI 放在上述开发步骤中，演示如何提供充分上下文和核验结果。

推荐输入包含：市场、环境、应用、产品与页面、PRD/设计、接口契约、当前 Journey、可复用页面、验收标准和允许改动范围。输出要求包含：配置/代码判断、影响文件、实施结果、验证证据、剩余不确定项。

仓库已有需求分析、TD、代码生成、Journey 配置同步、UI 验证、mock、Runbook 和 Code Review 等 Skills。主讲时仅展示案例实际需要的能力，其余放工具索引。编码前需按 AGENTS.md 加载完整工程规范，AI 生成结果仍需开发者核验业务语义和运行效果。

建议逐级练习：

1. 修改已有文案或受支持的字段配置，完成展示验证。
2. 增加一个字段或简单交互，完成接口与回退路径验证。
3. 承接一个小型业务区块，完成实现、回归、MR 与提测物料。

## 4. 正式文档目录建议

1. Nonmotor 业务范围与系统架构
2. 项目环境搭建
3. 项目启动与第一个页面
4. 项目结构与代码定位
5. 分支规范与需求开发流程
6. 产品工厂 Journey 与配置开发
7. 页面、组件和接口开发规范
8. 需求实战：新增投保字段
9. 联调、自测与问题排查
10. 提测、部署与发布物料
11. 常用平台与 AI 工具
12. 前端基础知识速查和常见问题

## 5. 分享前需要补齐的材料

- 选定一个可演示产品：市场、产品 ID、完整入口、设计截图和可复现环境。
- 选定一份小型历史 MR 或准备教学改动，保证课堂上能展示明确的前后对照。
- 在干净环境验证 Node、依赖、登录、代理、页面启动和 PFB 步骤。
- 分支命名、MR 方向和 Casement 部署流程已确认；补齐 Reviewer、部署负责人、审批与版本/Tag 生成操作。
- 补齐目标团队可访问的 Journey、Transify、TMS、IDAP、部署平台入口与权限申请方式。

## 6. 本次核对的依据

- 参考文档：用户提供的《admin后端开发流程》HTML；原页面为 https://confluence.shopee.io/pages/viewpage.action?pageId=3269507138 。本次未依赖该页面中的其他外链。
- 运行与构建：`.nvmrc`、`package.json`、`scripts/prompt.js`、`config/bizConfig.js`、`config/paths.js`。
- 入口与部署：`config/nonmotor/my.json`、其他市场 nonmotor 配置、`deploy/nonmotor.json`、`deploy/space_build.sh`、`deploy/space_install.sh`。
- 页面链路：`src/pages/factoryV2/purchase5/index.tsx`、`App.tsx`、`src/pages/factory/model/queryProductFactoryJourney.ts`。
- 迁移边界：`src/common/nonmotor.ts`、`src/common/request.ts`；旧页面与 API 的改写受迁移白名单控制，不能假定所有旧地址都自动迁移。
- 工程约定：项目内 project-conventions、service-development、journey-development、monee-design、code-quality 等 Skill 与引用资料。

本稿只创建培训编排文档，未修改源码，未执行发布或真实业务操作。