Article

蕉不焦前端架构与交付规划

2026年7月11日 · 11 分钟阅读

商业级前端真源:IA、页面契约、组件树、状态、动效映射、与 06/07 追溯、src 差距、迭代路线。

09 · 前端架构与交付规划

真源职责:移动端(及预留多端)如何实现 06 旅程与 07 呈现。
代码根:/src(Taro 4 + React 18 + 微信小程序)
呈现:07-product-presentation.md
故事:06-user-stories-journeys.md
参数:10-interaction-spec.md
后端:11-technical-spec.md


1. 技术基线

项选型说明
框架Taro 4.2 + React 18见 package.json
目标端微信小程序(主)build:weapp
次端H5 可调试dev:h5
样式Sass + CSS 变量styles/tokens.scss motion.scss
UI 库taro-ui 可选主路径尽量自研轻组件
状态React Context AppProviderMVP 足够;勿过早上重型状态库
存储本地 storage 封装services/storage.ts
AImockAgent 规则引擎可替换远程沉淀 API

1.1 约束与预算

约束目标
捕获反馈感知 ≤2s(mock 可模拟阶段)
包体主包控制;精灵 png/webp 按需
首屏打开即捕获,无重引导
减少动态尊重系统设置
不做日历页、四象限页、原生复杂手势依赖隐藏入口

2. 信息架构

2.1 三 Tab 哲学

捕获 Capture → 进(闪念)
聚焦 Focus → 做(一步)
复盘 Review → 放(释负)

为什么不是五 Tab: 列表/日历/我的会把产品拉回传统 Todo,破坏「只回来一步」。

2.2 路由(app.config.ts)

path标题文案建议职责
pages/capture/index捕获零字段闪念;M1/M2
pages/focus/index聚焦WIP=1;M3/M4
pages/review/index复盘M5

未来扩展(非 MVP 路由):线程详情、设置、账本导出——从复盘/状态条二级进入,不进 Tab。

2.3 全局壳

层实现
TabBar配置图标 assets/tab/*;选中色 primary
ToastToastHost 挂 App
RememberedRememberedFx 全局叠加 M4
ProviderAppProvider 包裹

3. 页面契约

3.1 Capture pages/capture

区块树

CapturePage
├── bg glow(B1 背景微光)
├── StatusStrip (visible 受下拉控制)
├── main
│ ├── AgentStatusLayer (phase, text, toneState)
│ └── hero
│ ├── SpriteStatus (idle-breath | capture-task | freeze-task)
│ ├── title / sub / hint
└── CaptureBar (text|voice|plus, busy, idleSlow)

状态机(页级)

本地 UI 状态来源
stripVisible下拉 dy>48
idleSlow10s timer → B2
agent.phaseProvider:idle/receiving/judging/done
currentNext用于 hint CAP-F11

事件

用户事件handler故事
提交文字/语音/图capture(text, source)US-C01/C02
下拉显示 StatusStrip 3–3.5sUS-C05
任意 touchresetIdleB1

空 / 错

态UI
空CAP-F0/F1 文案,无列表
busyCaptureBar disabled
失败Toast「没记下,请重试」

验收映射

  • M1:phase 流转 + 文案阶段
  • M2:toneState + reason 文案

3.2 Focus pages/focus

区块树

FocusPage
├── empty?
│ ├── SpriteStatus next-step
│ ├── empty title/sub
│ └── JellyButton → switchTab capture
└── filled
├── header 现在只做
├── SpriteStatus
└── ActionCard
├── reason / action / 原文
└── actions: complete split snooze important

事件 → Provider

UIAPI故事
完成✓completeCurrentF03
拆小splitCurrent + RememberedR01 M4
稍后snoozeCurrentR02
🔥markImportantR03

缺口(相对 07)

目标现状优先级
PendingConfirmCard FOC-F2无独立组件;pending 进 next 混用P0
稍后时段 chips可能一键 snoozeP1
原文展开部分无P1
完成 celebrate 精灵资产有,页未接P1

3.3 Review pages/review

区块树

ReviewPage
├── time
├── SpriteStatus sleep-shutdown
├── greeting / lead
├── learned notes(可选)
├── stats ×4 count-up
├── tomorrow action
└── actions: 上午别推 | 收到

事件

UIAPI
上午别推setPreference({ noPushAm }, remembered)
收到switchTab capture

缺口

目标现状
日终推送进页未接系统推送
动态「接住」等与全状态stats 字段已有,展示四项 OK

4. 组件架构

4.1 现有组件(保留)

组件职责07 关联状态
CaptureBar文字/语音/+ 面板捕获条状态机已有,可增强 Undo 出口
AgentStatusLayer判断文案+微光B3已有
StatusStrip今日统计下拉条已有
SpriteStatus帧动画精灵4.4 绑定已有
ActionCard一步+操作FOC-F1已有
JellyButton果冻主按钮B 果冻已有
RememberedFx记下了B4 M4已有
ThinkingDots思考点B3已有
ToastHostToast全局已有

4.2 目标新增组件

组件职责故事/帧Phase
UndoChip接住后 5s 撤销US-C08 CAP-F131
PendingConfirmCard一问+短按钮US-F05 FOC-F21
ReasonBanner可复用 reason 展示M21
SnoozeSheet傍晚/明天/下周US-R022
FragmentOrigin原文折叠US-F062
DeliveryHint「下午再回来」排程可见性2

4.3 组件 props 契约(关键)

CaptureBar

{
busy?: boolean
idleSlow?: boolean // B2
onCapture: (text: string, source: 'text'|'voice'|'image') => void
}

AgentStatusLayer

{
phase: 'idle'|'receiving'|'judging'|'done'
text: string
toneState?: FragmentState // 映射状态色
}

ActionCard

{
item: Fragment // action, reason, content, state
onComplete(): void
onSplit(): void
onSnooze(): void
onImportant(): void
}

RememberedFx

{
// 由 Provider remembered: { title, subtitle } 驱动
}

5. 状态管理

5.1 现有模型(types/models.ts)

FragmentState = raw | next_step | waiting | merged | snoozed
| frozen | pending | archived | done
Fragment { id, content, source, state, reason?, action?, createdAt, updatedAt }
PreferenceMap { splitFirst?, noPushAm?, conservativeTone?, preferImportant?, notes? }
DailyStats { date, caught, merged, frozen, waiting, done, snoozed, pending, archived }
AgentPhase = idle | receiving | judging | done

5.2 目标扩展(与 11 对齐,可渐进)

字段用途UI 暴露
urgency / importance内部启发否
threadId归并可选文案
deliverAt调度仅文案「稍后」
suppressUntil今天别推否

5.3 Provider API(目标)

方法说明
capture已有:阶段 timer + judgeFragment
completeCurrent已有
splitCurrent已有 + remembered
snoozeCurrent已有;增强时段
markImportant已有
setPreference已有
undoLastCapture新增 C08
confirmPending(id, choice)新增 F05
archive(id)新增 R04

5.4 持久化

  • loadSnapshot / saveSnapshot:fragments + preferences + stats
  • 日切:stats.date !== todayKey → emptyStats

5.5 乐观与撤销

capture → 立即 receiving UI → 异步/定时 judge → done
undoLastCapture → 删除 last id + 回滚 stats(若可)

6. 服务层

6.1 mockAgent.ts

规则state对应 US
URL/资料mergedS01
等待waitingS03
灵感frozenS02
客户+截止pendingS05
客户沟通next_stepS04
默认next_step + toNextStep/splitS04
prefs.splitFirstshrinkActionR01

增强清单:

  • 输出 stages[] 与 07 文案完全一致
  • 多意图语音:返回 primary action + side states(需模型支持多 fragment)
  • 记录 heuristic 不进 UI

6.2 haptics.ts

时机强度
接住/按钮light
完成/记下了medium

6.3 未来 api/sediment.ts

  • 接口形状对齐 11:POST /fragments
  • mock 与 remote 策略模式

7. 动效实现映射

07 态实现位置要点
B1 idle-breatheCaptureBar / JellyButton breathe3s scale
B2 rest-slowidleSlow prop5s
B3 judging-glowAgentStatusLayer + phase timers≤3s stages
B4 confirm-rippleRememberedFx波纹+文案
背景微光page-capture__glow8s 径向
果冻JellyButton0.34,1.56,0.64,1
count-upreview useCountUp已有
reduced-motionmotion.scss media需补全关呼吸

Token:styles/tokens.scss 与 07§3 对齐(已基本一致)。


8. 追溯矩阵(US × 帧 × 组件)

US07 帧页面组件埋点
C01CAP-F3–6captureCaptureBar, AgentStatuscapture_submit
C02CAP-F9–4captureCaptureBar voicecapture_voice_*
C08CAP-F13captureUndoChipcapture_undo
S01CAP-F5captureAgentStatus tone=mergedsediment_result
D02 F01FOC-F1focusActionCarddelivery_show
R01FOC-F4 B4focusActionCard, RememberedFxdelivery_action=split
V01REV-F1reviewstatsreview_open
V03REV-F3reviewJellyButton prefpreference_write

高光验收自动化(建议):

M手工半自动
M1提交见阶段文案timer mock 快进
M2reason 含不新增unit judgeFragment URL
M3仅一卡query next_step length≤1
M4拆小见记下了remembered non-null
M5复盘无「未完成」copy lint

9. 质量

9.1 测试

层范围
UnitjudgeFragment 各规则;splitSmaller;todayKey
ComponentCaptureBar 提交;ActionCard 四按钮回调
e2e(可选)最小:捕获→聚焦有下一步

现有:__tests__/index.test.js — 需扩展 agent 单测。

9.2 性能清单

  • 精灵图只加载当前 kind
  • 离开页停 interval(capture idle timer、review count-up)
  • 长列表禁止上捕获首页

9.3 无障碍

  • 主按钮可聚焦文案
  • reason 变化 aria-live(小程序能力内尽量)
  • 减少动态

10. 交付路线图

Phase 0 · 文档对齐(本文档库)

  • README / 06 / 07 / 09
  • 文案与 mockAgent stages 对齐 07

Phase 1 · 呼吸捕获(M1 M2)

项验收
阶段文案与 B3与 07 时间轴一致
UndoChipC08
reason 状态色M2
无强制跳转C04

Phase 2 · 聚焦纠偏(M3 M4)

项验收
WIP=1 硬约束D02
PendingConfirmCardF05
拆小 RememberedM4
SnoozeSheetR02

Phase 3 · 复盘释负(M5)

项验收
文案无羞辱V01
上午别推V03
空态 REV-F0JRN-08

Phase 4 · 硬化

  • 埋点字典落地
  • reduced-motion
  • remote sediment 接口
  • 多端预留(不进主包)

11. 现状差距表(诚实)

能力src 现状目标差距
三 Tab 页✅✅小
捕获文字/语音 mock✅✅文案/Undo
Agent 阶段 UI✅✅对齐 07 用词
状态规则引擎✅ 基础多意图/侧态中
聚焦单卡+四按钮✅✅待定卡、时段
记下了 Fx✅✅—
复盘四计数✅✅推送入口
呼吸 idleSlow✅✅reduced-motion
撤销捕获❌✅缺
Pending 专用 UI❌✅缺
排程 job 模型❌ 即时 nextdeliverAt中
四象限 UI❌(正确)禁止保持
日历页❌(正确)禁止保持
埋点❌字典缺
单测 agent弱强中

12. 目录与编码规范

src/
app.config.ts # 路由 Tab
app.ts / app.scss
pages/{capture,focus,review}/
components/{PascalCase}/index.tsx|scss
services/{mockAgent,storage,haptics}.ts
store/AppProvider.tsx
styles/{tokens,motion}.scss
types/models.ts
assets/{sprites,tab}/
规范要求
命名组件 Pascal;scss BEM block__elem--mod
颜色只用 CSS 变量,禁随意 hex 散落
文案对用户句来自 07 声线;禁开发者黑话
PR关联 US-ID 或帧 ID

13. 非目标(前端)

  • Eisenhower 矩阵页面
  • 日历 time-block
  • 桌面 Tauri 实现(可另库;契约同捕获原则)
  • 自动发微信
  • 重型状态管理迁移(无证据前不)

14. 开工第一周建议任务包

  1. 对齐 mockAgent stages 文案 → 07
  2. 实现 undoLastCapture + UndoChip
  3. currentNext 过滤保证 WIP=1
  4. Pending 态走 PendingConfirmCard
  5. 单测:URL→merged;拆小偏好
  6. 演示脚本:JRN-03 + M1–M5 录屏

15. 修订

日期说明
2026-07-11商业级前端架构首版:契约、差距、追溯、路线图