docs: record pitfalls and sync progress

AGENTS.md

@@ -102,3 +102,10 @@
 - [业务进度管理.md](./业务进度管理.md)
 
 开发或接手任务前，先查看该文档确认已完成事项、进行中事项、待办事项与避坑记录。
+
+## 近期踩坑
+
+- `Validate::only()` 只限制校验字段范围，不会自动过滤请求参数；新增字段落库前，要同时检查 validate、logic、model、保存白名单和数据库列是否同步。
+- `adminapi/match.match/edit` 写入失败时，先查测试库或线上库表结构，确认 `la_match` 已补齐对应字段，不要只盯业务代码。
+- 世界杯专题页、比赛详情页这类前后端联动改动，要统一入口显示规则和跳转目标，避免只改一处导致入口不一致。
+- 构建产生的 `server/public/admin`、`server/public/mobile` 等产物不要混进提交，提交前先清理临时截图和生成文件。

docs/sql/alter_la_match_add_live_url.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `la_match`
+    ADD COLUMN `live_url` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '第三方直播链接' AFTER `stage`;

sbnews.sql

@@ -1,4 +1,4 @@
-/*
+/*
  Navicat Premium Dump SQL
 
  Source Server         : 世博头条测试数据库-亚马逊
@@ -960,6 +960,7 @@ CREATE TABLE `la_match`  (
   `league_name` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '联赛名称',
   `round_name` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT '' COMMENT '场次名称(第5轮/季前赛/半决赛等)',
   `stage` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT '' COMMENT '赛事阶段(小组赛/淘汰赛/常规赛等)',
+  live_url varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '第三方直播链接',
   `league_icon` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '联赛图标',
   `home_team` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '主队名称',
   `home_icon` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '主队图标',

业务进度管理.md

@@ -256,6 +256,40 @@
 
 ### 14. 世界杯专题新闻来源同步首页分类
 - 2026-05-23：`uniapp/src/pages/match/match.vue` 跳转世界杯专题页时携带首页解析到的 `世界杯` 分类 `cid`，`uniapp/src/packages_match/pages/worldcup.vue` 优先使用该 `cid` 拉取新闻，保证专题新闻来源与首页世界杯分类一致。
+
+### 15. 新闻资讯 AI 翻译
+- 2026-05-23：`server/app/api/controller/ArticleController.php` 新增 `/article/translate` 翻译接口，`server/app/api/logic/ArticleLogic.php` 复用 `AiService` 生成并缓存文章翻译结果到 `ext`。
+- 2026-05-23：`uniapp/src/pages/news_detail/news_detail.vue` 在新闻详情页新增 AI 翻译入口、加载态与翻译结果展示区，`uniapp/src/api/news.ts` 补充对应请求封装。
+
+### 16. 世界杯专题新闻列表 AI 翻译
+- 2026-05-23：`uniapp/src/components/news-card/news-card.vue` 增加可选 AI 翻译触发入口，世界杯专题新闻列表可在卡片内点按翻译按钮。
+- 2026-05-23：`uniapp/src/packages_match/pages/worldcup.vue` 接收翻译事件并以弹窗展示翻译结果，保持其他新闻列表默认不变。
+### 17. 社区首页特朗普分类 AI 翻译复用
+- 2026-05-23：`uniapp/src/packages_community/pages/index.vue` 继续复用 `post-card` 卡片渲染，社区首页无需单独拆分 AI 入口逻辑。
+- 2026-05-23：`uniapp/src/packages_community/components/post-card.vue` 将 `特朗普` 标签纳入 AI 翻译入口判断，沿用帖子翻译弹窗展示方式。
+### 18. 资讯 AI 翻译改为积分确认流程
+- 2026-05-23：`server/app/api/controller/ArticleController.php` 的 `/article/translate` 改为登录后可用，并支持 `article_id/id + confirm` 的积分确认参数。
+- 2026-05-23：`server/app/api/logic/ArticleLogic.php` 为资讯翻译补齐 `needs_payment` 探测、积分扣减、翻译缓存复用与已付费用户缓存读取。
+- 2026-05-23：`uniapp/src/api/news.ts`、`uniapp/src/pages/news_detail/news_detail.vue`、`uniapp/src/packages_match/pages/worldcup.vue` 改为与社区翻译一致的 `POST + confirm` 调用方式，翻译前先提示登录并在确认后扣积分。
+### 19. 赛事详情新增第三方直播入口
+- 2026-05-23：`server/app/api/controller/MatchController.php` 复用 `la_match_data.raw_data` 中的直播源文本，向详情接口补充 `living_tv` 字段，便于前端展示直播来源说明。
+- 2026-05-23：`uniapp/src/pages/match_detail/match_detail.vue` 新增“直播”入口卡片，点击后通过现有 `webview` 页面跳转到懂球帝第三方直播详情页。
+
+### 20. 管理端赛事直播链接编辑
+- 2026-05-23：`admin/src/views/match/lists/index.vue` 在赛事编辑弹窗中新增 `live_url` 输入项，用于维护第三方直播链接。
+- 2026-05-23：`server/app/adminapi/logic/match/MatchLogic.php` 允许赛事编辑写入 `live_url`，`uniapp/src/pages/match_detail/match_detail.vue` 优先读取该字段作为直播入口跳转地址。
+- 2026-05-23：新增 `docs/sql/alter_la_match_add_live_url.sql`，用于给 `la_match` 补充 `live_url` 字段。
+- 2026-05-23：已同步测试库 `sbnews.la_match.live_url` 字段，确认 `/adminapi/match.match/edit` 可正常落库。
+
+### 21. 赛事详情直播入口仅在有链接时展示
+- 2026-05-23：`uniapp/src/pages/match_detail/match_detail.vue` 将直播入口收敛为仅在 `match.live_url` 存在时展示，不再为无链接赛事自动兜底第三方直播地址。
+
+### 22. 世界杯专题比赛卡片跳转详情
+- 2026-05-23：`uniapp/src/packages_match/pages/worldcup.vue` 的赛程卡片和对阵图卡片统一支持点击跳转 `pages/match_detail/match_detail`，方便从世界杯专题直接进入比赛详情页。
+
+### 23. 近期踩坑与文档同步
+- 2026-05-24：将本次调试过程中确认的坑点同步到 `sport-era-project-dev` 技能文档和各级 `AGENTS.md`，补充 `Validate::only()` 不过滤请求参数、`la_match.live_url` 必须先补库、世界杯专题页入口一致性以及构建产物不要混入提交等注意事项。
+
 ## 二、进行中事项
 
 暂无。
@@ -311,6 +345,13 @@
 - 不通过 WSL `sshpass` / `scp` 上传业务代码。
 - 项目代码更新由用户通过 SFTP 等方式处理。
 
+### 6. 新增字段与联动入口排查
+
+- `Validate::only()` 只限制校验字段，不会过滤请求参数；新增字段必须同时核对 validate、logic、model、保存白名单和数据库列。
+- `adminapi/match.match/edit` 写入失败先看表结构，不要把测试库缺列误判成业务逻辑错误。
+- 世界杯专题页、比赛详情页的入口和显示规则要一起改，直播入口只在 `match.live_url` 有值时展示。
+- 构建产物如 `server/public/admin`、`server/public/mobile` 不要混进提交，提交前先清理临时截图和生成文件。
+
 ---
 
 ## 文档维护规范