zhaoyuxi/patbond-flutter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

新增：互动埋点与乐观更新视觉基建——字典 v3 互动八事件封装 + ToggleSync 成功上报与触点归因 + LikeButton 三层闪烁抑制动画（T3-16）

Browse Source 
- community_interaction_analytics：post_liked/unliked、post_favorited/unfavorited、
  comment_create_succeeded/failed、user_followed/unfollowed 强类型封装（22 号
  白名单键集逐一对齐；textLengthBucket 分桶、httpStatus 由五位码推导、
  会话失效不上报）；comment_create_started 锁死 unknown 不封装
- CommunityController：toggleLike/toggleBookmark 增 source 触点归因
 （feed / post_detail），成功响应后经注入的 interactionAnalytics 上报
 （乐观翻转与失败不报）；adjustCommentCount 评论计数同源写入
 （详情副本与 Feed 卡片一并更新）
- LikeButton 升 Stateful：点按激活 240ms 弹性缩放 + 120ms 图标淡入、
  取消仅颜色渐出；回滚/对账零动画直接跳变、计数与状态成对更新、
  激活动画未播完等播完再跳（05 号 §3.5/§4）；减弱动态设置降级瞬变

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Lixi20
2026-09-09 13:38:50 +08:00
parent 8aac8c52cc
commit 92524da8e2
5 changed files with 589 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/core/widgets/like_button.dart
+123 -13
View File
@@ -31,12 +31,21 @@ enum LikeButtonVariant {
final Color activeCountColor;
}
/// 点赞/收藏交互钮（05 号规范 §3.5 静态规格）：图标 20 + 计数 13/w600，
/// 未激活一律 `inkSoft`（6.59:1）。触控 44×44 由 padding 撑足。
/// 点赞/收藏交互钮（05 号规范 §3.5）：图标 20 + 计数 13/w600，未激活
/// 一律 `inkSoft`（6.59:1）。触控 44×44 由 padding 撑足。
///
/// T3-14 只做展示（[onPressed] 传 null 即禁用态，仍按正常色渲染计数与
/// 状态）；乐观更新动画与 ToggleSync 接线属 T3-15/16。
class LikeButton extends StatelessWidget {
/// 乐观更新视觉（§3.5/§4 三层闪烁抑制的 UI 半边，状态本体由持有方经
/// ToggleSync 驱动）：
///
/// - **点按驱动**的状态变化：激活播 240ms 弹性缩放（1→1.25→1）+ 图标
/// 120ms 淡入；取消仅 120ms 颜色渐出、无缩放。
/// - **非点按驱动**的状态变化（失败回滚 / 服务端对账）：零动画直接跳变；
/// 若激活动画未播完，等播完再跳（避免动画中途反转的抖动，§4.3a）。
/// - 计数变化一律直接替换，不做滚动动画（回滚时无二次滚动）。
/// - 系统「减弱动态效果」开启时全部降级为瞬变。
///
/// [onPressed] 传 null 即纯展示禁用态（仍按正常色渲染计数与状态）。
class LikeButton extends StatefulWidget {
const LikeButton({
required this.variant,
required this.active,
@@ -52,15 +61,106 @@ class LikeButton extends StatelessWidget {
final VoidCallback? onPressed;
final String? semanticLabel;
@override
State<LikeButton> createState() => _LikeButtonState();
}
class _LikeButtonState extends State<LikeButton>
with SingleTickerProviderStateMixin {
late final AnimationController _scaleController = AnimationController(
vsync: this,
duration: const Duration(milliseconds: 240),
);
late final Animation<double> _scale = TweenSequence<double>([
TweenSequenceItem(
tween: Tween<double>(
begin: 1,
end: 1.25,
).chain(CurveTween(curve: Curves.easeOut)),
weight: 40,
),
TweenSequenceItem(
tween: Tween<double>(
begin: 1.25,
end: 1,
).chain(CurveTween(curve: Curves.easeOutBack)),
weight: 60,
),
]).animate(_scaleController);
/// 当前展示态（回滚等待动画播完期间可短暂落后于 widget.active）。
late bool _displayActive = widget.active;
/// 展示计数与状态成对更新（§4.3c：回滚不出现「心已灭计数未减」中间帧）。
late int _displayCount = widget.count;
/// 最近一次点按的期望目标态；didUpdateWidget 以此区分「点按驱动」
/// （播动画）与「回滚/对账」（零动画跳变）。
bool? _expectedTarget;
/// 图标切换是否走 120ms 淡入淡出（点按驱动）；回滚跳变置 false。
bool _fadeSwap = false;
bool get _reduceMotion =>
MediaQuery.maybeOf(context)?.disableAnimations ?? false;
@override
void didUpdateWidget(LikeButton oldWidget) {
super.didUpdateWidget(oldWidget);
if (oldWidget.active == widget.active) {
// 状态未变的计数变化 = 服务端对账：静默替换、不播动画（§4.4）。
_displayCount = widget.count;
return;
}
final tapDriven = _expectedTarget == widget.active;
_expectedTarget = null;
if (tapDriven && !_reduceMotion) {
_fadeSwap = true;
_displayActive = widget.active;
_displayCount = widget.count;
if (widget.active) _scaleController.forward(from: 0);
return;
}
// 回滚 / 对账：零动画、计数与状态成对跳变。激活动画未播完则等
// 播完再跳（§4.3a，避免动画中途反转的抖动）。
_fadeSwap = false;
if (_scaleController.isAnimating) {
_scaleController.forward().whenComplete(() {
if (mounted) {
setState(() {
_displayActive = widget.active;
_displayCount = widget.count;
});
}
});
} else {
_displayActive = widget.active;
_displayCount = widget.count;
}
}
void _handleTap() {
_expectedTarget = !widget.active;
widget.onPressed!();
}
@override
void dispose() {
_scaleController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
final variant = widget.variant;
final active = _displayActive;
final iconColor = active ? variant.activeIconColor : AppColors.inkSoft;
final countColor = active ? variant.activeCountColor : AppColors.inkSoft;
return Semantics(
label: semanticLabel,
button: onPressed != null,
label: widget.semanticLabel,
button: widget.onPressed != null,
child: InkWell(
onTap: onPressed,
onTap: widget.onPressed == null ? null : _handleTap,
borderRadius: BorderRadius.circular(AppRadius.pill),
child: ConstrainedBox(
constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
@@ -69,14 +169,24 @@ class LikeButton extends StatelessWidget {
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(
active ? variant.activeIcon : variant.inactiveIcon,
size: 20,
color: iconColor,
ScaleTransition(
scale: _scale,
child: AnimatedSwitcher(
duration: _fadeSwap
? const Duration(milliseconds: 120)
: Duration.zero,
child: Icon(
active ? variant.activeIcon : variant.inactiveIcon,
key: ValueKey(active),
size: 20,
color: iconColor,
),
),
),
const SizedBox(width: 4),
// 计数直接替换（§3.5：不做滚动动画，避免回滚二次滚动）。
Text(
'$count',
'$_displayCount',
style: TextStyle(
color: countColor,
fontSize: 13,
lib/features/community/community_controller.dart
+48 -3
View File
@@ -1,5 +1,6 @@
import 'package:flutter/foundation.dart';
import 'package:patbond_flutter/core/network/api_exception.dart';
import 'package:patbond_flutter/features/community/community_interaction_analytics.dart';
import 'package:patbond_flutter/features/community/community_models.dart';
import 'package:patbond_flutter/features/community/community_repository.dart';
import 'package:patbond_flutter/features/community/toggle_sync.dart';
@@ -18,7 +19,7 @@ enum LoadMorePhase { idle, loading, error }
/// 评论列表只属详情页，按「页面级状态按页自建」纪律经 [repository]
/// 自取，不膨胀本控制器。服务端是唯一事实来源，内存副本仅作展示缓存。
class CommunityController extends ChangeNotifier {
CommunityController({required this._repository}) {
CommunityController({required this._repository, this._interactionAnalytics}) {
_likeSync = ToggleSync(
read: (id) {
final post = _postCache[id];
@@ -35,6 +36,11 @@ class CommunityController extends ChangeNotifier {
final state = target
? await _repository.likePost(id)
: await _repository.unlikePost(id);
// 成功响应后上报（06 §1.4 口径；乐观翻转与失败均不报）。
final source = _likeSources[id] ?? InteractionSource.feed;
target
? _interactionAnalytics?.postLiked(source: source)
: _interactionAnalytics?.postUnliked(source: source);
return ToggleOutcome(active: state.liked, count: state.likeCount);
},
generation: () => _generation,
@@ -62,6 +68,10 @@ class CommunityController extends ChangeNotifier {
final state = target
? await _repository.bookmarkPost(id)
: await _repository.unbookmarkPost(id);
final source = _bookmarkSources[id] ?? InteractionSource.feed;
target
? _interactionAnalytics?.postFavorited(source: source)
: _interactionAnalytics?.postUnfavorited(source: source);
return ToggleOutcome(
active: state.bookmarked,
count: state.bookmarkCount,
@@ -73,6 +83,12 @@ class CommunityController extends ChangeNotifier {
}
final CommunityRepository _repository;
final CommunityInteractionAnalytics? _interactionAnalytics;
/// 各帖最近一次 toggle 的触点来源（Feed 卡片 / 详情页共享同一实例，
/// 成功响应上报时按发起触点归因）。
final Map<String, InteractionSource> _likeSources = {};
final Map<String, InteractionSource> _bookmarkSources = {};
/// 页面级状态（评论列表、我的帖子、收藏页等）按页直接经仓库取数。
CommunityRepository get repository => _repository;
@@ -193,10 +209,34 @@ class CommunityController extends ChangeNotifier {
}
/// 点赞/取消点赞（乐观翻转，终态由 [ToggleSync] 对账收敛，不外抛）。
void toggleLike(String postId) => _likeSync.toggle(postId);
/// [source] 为触点来源（埋点归因），Feed 卡片缺省 feed、详情页传
/// post_detail。
void toggleLike(
String postId, {
InteractionSource source = InteractionSource.feed,
}) {
_likeSources[postId] = source;
_likeSync.toggle(postId);
}
/// 收藏/取消收藏（与点赞同构）。
void toggleBookmark(String postId) => _bookmarkSync.toggle(postId);
void toggleBookmark(
String postId, {
InteractionSource source = InteractionSource.feed,
}) {
_bookmarkSources[postId] = source;
_bookmarkSync.toggle(postId);
}
/// 评论创建/删除后的计数调整（详情页与 Feed 卡片同源写入，
/// 服务端 comment_count 由写侧同事务维护，本地只做展示对齐）。
void adjustCommentCount(String postId, int delta) {
final current =
_postCache[postId]?.commentCount ?? _cardOrNull(postId)?.commentCount;
if (current == null) return;
final next = current + delta;
_writeInteraction(postId, commentCount: next < 0 ? 0 : next);
}
/// 消费一次性 toggle 错误（SnackBar 展示后清除）。
void clearToggleError() => _toggleError = null;
@@ -215,6 +255,8 @@ class CommunityController extends ChangeNotifier {
_loadMoreError = null;
_toggleError = null;
_postCache.clear();
_likeSources.clear();
_bookmarkSources.clear();
_likeSync.reset();
_bookmarkSync.reset();
_notify();
@@ -234,6 +276,7 @@ class CommunityController extends ChangeNotifier {
int? likeCount,
bool? bookmarkedByMe,
int? bookmarkCount,
int? commentCount,
}) {
final post = _postCache[postId];
if (post != null) {
@@ -242,6 +285,7 @@ class CommunityController extends ChangeNotifier {
likeCount: likeCount,
bookmarkedByMe: bookmarkedByMe,
bookmarkCount: bookmarkCount,
commentCount: commentCount,
);
}
final index = _feed.indexWhere((card) => card.id == postId);
@@ -252,6 +296,7 @@ class CommunityController extends ChangeNotifier {
likeCount: likeCount,
bookmarkedByMe: bookmarkedByMe,
bookmarkCount: bookmarkCount,
commentCount: commentCount,
);
}
if (post != null || index != -1) _notify();
lib/features/community/community_interaction_analytics.dart
+137
View File
@@ -0,0 +1,137 @@
import 'package:patbond_flutter/analytics/page_view_tracker.dart';
import 'package:patbond_flutter/core/network/api_exception.dart';
/// 互动域埋点强类型封装（06 号规划 §1.4 字典 v3 互动八事件；后端白名单
/// 已随 api dev@8089c06 就绪，22 号报告 §1）。沿 pet/feed 域惯例：枚举
/// 编译期锁死，业务代码禁止手拼事件名与属性；只记行为不记内容
/// （隐私红线：postId/commentId 等内容 ID 一律不进 props）。
///
/// 点赞/收藏/关注**不埋失败**（06 §1.4 取舍：幂等写入单点交互，失败率
/// 靠服务端错误率观测）；`comment_create_started` 被字典锁死 unknown，
/// 不得上报（22 号 §1 末段）。
/// 互动触点来源（06 §1.4 source 枚举）。M3 接 feed / post_detail；
/// user_profile / follow_list 随后续页面启用。
enum InteractionSource {
feed('feed'),
postDetail('post_detail'),
userProfile('user_profile'),
followList('follow_list');
const InteractionSource(this.value);
final String value;
}
/// 评论创建失败原因（06 §1.4 失败枚举基底）。网络归并口径同 pet/feed 域：
/// 断网/超时/5xx 均并入 network_error，server_error 保留兜底。
enum CommentCreateFailureReason {
validationError('validation_error'),
notFound('not_found'),
rateLimited('rate_limited'),
networkError('network_error'),
serverError('server_error');
const CommentCreateFailureReason(this.value);
final String value;
}
/// 类型化异常 → 评论失败原因；会话失效返回 null（应用即将回登录页，
/// 不作为评论失败上报，feed 域同款口径）。
CommentCreateFailureReason? commentCreateFailureReasonOf(ApiException error) =>
switch (error) {
ApiNetworkException _ => CommentCreateFailureReason.networkError,
ApiRateLimitException _ => CommentCreateFailureReason.rateLimited,
SessionExpiredException _ => null,
ApiBusinessException(:final code) => switch (code) {
ApiCodes.paramError => CommentCreateFailureReason.validationError,
ApiCodes.postNotFound ||
ApiCodes.commentNotFound ||
ApiCodes.communityUserNotFound => CommentCreateFailureReason.notFound,
_ => CommentCreateFailureReason.serverError,
},
};
/// 正文规模分桶（06 §1.3 隐私红线 1：不报精确字数）。
/// empty / short(≤50) / medium(51–500) / long(>500)。
String textLengthBucketOf(int length) {
if (length <= 0) return 'empty';
if (length <= 50) return 'short';
if (length <= 500) return 'medium';
return 'long';
}
class CommunityInteractionAnalytics {
CommunityInteractionAnalytics(this._track);
/// 生产传 `AnalyticsService.trackEvent`，测试传录制桩。
final TrackEventFn _track;
/// 点赞成功响应后（乐观翻转本身不报；单飞合并链每个实际抵达服务端
/// 并成功的状态变更各报一条，与「成功响应后」的字典口径一致）。
void postLiked({required InteractionSource source}) {
_track('post_liked', {'source': source.value});
}
/// 取消点赞成功响应后。
void postUnliked({required InteractionSource source}) {
_track('post_unliked', {'source': source.value});
}
/// 收藏成功响应后。
void postFavorited({required InteractionSource source}) {
_track('post_favorited', {'source': source.value});
}
/// 取消收藏成功响应后。
void postUnfavorited({required InteractionSource source}) {
_track('post_unfavorited', {'source': source.value});
}
/// 评论提交成功响应后。
///
/// [durationMs]：本次输入会话（首个字符输入）→ 成功响应的耗时
/// （评论不设 started 事件，时长随成功事件带出）；
/// [textLength] 经 [textLengthBucketOf] 分桶后上报，精确字数不出端。
void commentCreateSucceeded({
required int durationMs,
required bool isReply,
required int textLength,
}) {
_track('comment_create_succeeded', {
'durationMs': durationMs,
'isReply': isReply,
'textLengthBucket': textLengthBucketOf(textLength),
});
}
/// 评论提交失败。
///
/// [errorCode] 为业务错误码（网络错误时缺席）；[httpStatus] 由五位
/// 业务码推导（`code ~/ 100`，pet 域同款口径）；[attemptSeq] 为本次
/// 输入会话内第几次提交尝试（从 1 起，成功或清空输入后重置）。
void commentCreateFailed({
required CommentCreateFailureReason reason,
required int attemptSeq,
int? errorCode,
}) {
_track('comment_create_failed', {
'failureReason': reason.value,
'attemptSeq': attemptSeq,
'errorCode': ?errorCode,
if (errorCode != null && errorCode >= 10000)
'httpStatus': errorCode ~/ 100,
});
}
/// 关注成功响应后。
void userFollowed({required InteractionSource source}) {
_track('user_followed', {'source': source.value});
}
/// 取关成功响应后。
void userUnfollowed({required InteractionSource source}) {
_track('user_unfollowed', {'source': source.value});
}
}