跳到主要内容

Web → App 基于 OpenSpec 的开发流程

· 阅读需 6 分钟
Quany
Quany
软件工程师

Web → App 基于 OpenSpec 的开发流程​

创建日期： 2026-02-04
适用范围： 线索 / 客户等 CRM 业务，从 Web 需求演进到 App 实现

1. 流程总览​

从一个功能/改动诞生，到 App 上线闭环，推荐遵循下面的主流程：

  1. 需求进入（通常先在 Web 上提出或实现）
  2. 统一业务到主 Spec（openspec/specs/*）
  3. 评估是否需要 App 跟进
  4. 为 App 创建 / 更新对应的 OpenSpec change（openspec/changes/app-*）
  5. 在 change 的 design.md 中完成 App UX 设计（信息架构 + 页面流程 + 布局）
  6. 从 design.md 拆分实施任务到 tasks.md
  7. 按任务开发、测试 App，并持续回填 Spec / 设计 / 任务
  8. 使用 openspec verify 验证，再 archive 完成变更归档

2. 需求进入 → 统一到主 Spec​

目标： 无论 Web 或 App，所有业务规则以 openspec/specs/* 为唯一真源。

  • 当有新需求或 Web 行为变更时，先检查：
    • 当前业务是否已经有对应 Spec（例如：lead-pool、personal-leads、customer-conversion 等）。
    • Web 实际行为与 Spec 是否一致。
  • 若不一致：
    • 创建一个小的业务同步 change（如 2026-02-xx-sync-lead-spec）。
    • 在该 change 中仅做两件事：
      • 修正/补充主 Spec：更新 openspec/specs/* 中的字段、状态流转、规则说明。
      • 记录原因：在 proposal.md / design.md 中说明“为什么要改 Spec（与历史实现的差异）”。

完成后，Web 与 App 后续均以更新后的主 Spec 为准。

3. 决定是否需要 App 跟进​

在业务 Spec 更新后，进行一次轻量评估：

  • 该改动是否影响移动端的核心场景？
    • 例如：线索列表字段调整、转化规则变化、客户关键信息修改等。
  • 评估结果：
    • 必须跟进：影响主流程或数据一致性，必须在 App 中同步。
    • 推荐跟进：改善体验，但不是硬性要求，可以合并到后续 App 迭代。
    • 暂不需要：仅 Web 端特有的桌面场景，可暂不做 App 支持。

当结论为“必须/推荐跟进”时，进入下一步，为 App 创建/更新 change。

4. 为 App 创建 / 更新 OpenSpec change​

命名建议：

  • openspec/changes/app-<模块>-<目标>，例如：
    • app-lead-mobile-list（线索列表移动端版本）
    • app-customer-conversion-flow（客户转化流程）

proposal.md 建议内容：

  • 背景： 关联哪些业务 Spec（链接到 openspec/specs/*）。
  • 目标用户： 例如一线销售 / 经理。
  • 业务目标： 希望这次在 App 上达成的业务效果（而非技术细节）。
  • 范围边界： 这次 App 改动包含/不包含哪些屏幕和操作。

5. 在 design.md 中完成 App UX 设计（先设计再开发）​

design.md 是这条 Web → App 变更在 App 侧的“设计真源”，推荐固定结构如下：

5.1 关联主 Spec 与场景​

  • 列出本次改动关联的业务 Spec：
    • 例如：[lead-pool](../../specs/lead-pool/spec.md)、[customer-conversion](../../specs/customer-conversion/spec.md)。
  • 用 1–2 句话说明本次在 App 上解决的核心场景：
    • 如：“让销售在移动端快速筛选高意向线索并发起跟进/转化”。

5.2 信息架构（App IA）​

  • 列出涉及的 App 屏幕及一句话职责，例如：
    • LeadListScreen：我的线索列表，帮助销售快速找到“现在最值得处理”的线索。
    • LeadDetailScreen：线索详情 + 跟进记录，集中展示决策所需信息。
    • LeadConvertScreen：转化流程，减少误操作，用最少步骤完成转客户。

5.3 用户流程（User Flow）​

  • 用步骤方式描述从入口到完成任务的路径，例如：
    • 首页 → 点“线索”入口 → 线索列表 → 筛选 → 详情 → 新增跟进 → 转为客户。
  • 对应线索/客户等核心流程可以只写 1–2 条“标准路径”，其余放到 tasks.md 验收里。

5.4 屏幕布局与组件粒度​

  • 对关键屏幕（例如线索列表、线索详情）写到组件级：
    • 顶部搜索、快捷筛选 Chips、列表卡片的字段排布、底部主按钮等。
  • 对次要屏幕可只写区块级：
    • 顶部标题区、中部表单区、底部操作区。
  • 不要求画高保真，只需说明信息密度、主次层级与主要交互。

5.5 状态与反馈​

  • 加载中、空数据、错误、权限不足时的表现：
    • 是否有 Skeleton 占位、空态文案、重试按钮等。
  • 哪些操作需要 Toast，哪些需要确认弹窗。

5.6 与 Web 的 UX 对齐与差异​

  • 明确哪些行为必须与 Web 一致（例如：校验规则、必填字段）。
  • 明确为移动端刻意做的差异（例如：字段裁剪、操作合并到底部按钮栏）。

6. 从 design.md 拆分到 tasks.md​

tasks.md 用于驱动实施与测试，建议按以下维度拆分：

  1. 屏幕与导航
    • 创建/调整相应的 Screen 与路由。
    • 配置 Tab / Stack 结构与入口位置。
  2. 组件与状态
    • 列表卡片、详情块、过滤组件、表单等 UI 任务。
    • 本地 UI 状态（loading/error/selected item 等）。
  3. API 与数据流
    • 调用哪些后端接口，如何与 shared API 连接。
    • 使用 Jotai / Zustand 管理哪些业务状态。
  4. 验收与测试
    • 从 design.md 的用户流程中抽取手工验收用例。
    • 设计 e2e 场景（登录 → 打开模块 → 执行核心路径）。

开发以 tasks.md 为 TODO 清单执行，过程中有变更应回填：

  • 业务规则问题 → 优先修改主 Spec（openspec/specs/*）。
  • 只是 UX/实现细节微调 → 更新 design.md / tasks.md。

7. 开发、验证与归档​

7.1 开发与自检​

  • 按 tasks.md 完成所有实现任务：
    • 屏幕/组件/导航/状态管理/API 调用。
  • 在 App 项目中执行基础自检：
    • npx tsc --noEmit
    • yarn lint
    • 关键路径的手工走查。

7.2 使用 openspec verify​

  • 在 verify 阶段对照以下内容逐条检查：
    • proposal.md 中的业务目标是否达成。
    • design.md 中的信息架构、流程、关键 UX 是否已实现。
    • tasks.md 中的实施任务与测试任务是否全部完成。
    • 与主 Spec 的行为是否保持一致，差异是否在设计中有记录。

7.3 archive 归档​

  • 验证通过后执行归档，将 change 移入 openspec/changes/archive。
  • 归档后的 change 就是这次 Web → App 能力同步的完整“变更记录”，便于后续审计与演进。

8. 推荐落地顺序（线索 / 客户试点）​

  1. 选择一条业务（推荐：线索列表 + 线索详情 + 转化）。
  2. 校准相关主 Spec（lead-pool、personal-leads、customer-conversion 等）。
  3. 新建 openspec/changes/app-<lead-module> change。
  4. 按本指南格式完善该 change 的 design.md 与 tasks.md。
  5. 驱动一次完整的 App 实施与验收闭环。

完成这条试点后，可以将本文件作为团队在其他模块（待办、机会、Dashboard 等）的共用开发流程规范。