koc-loop/design-qa.md

# KOC LOOP 数据回收标题跳转设计 QA

## 验证对象

- 用户参考截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-2296f03e-e79b-494c-b745-08e939fc20c6.png`
- 浏览器实现截图：`/private/tmp/koc-loop-recovery-title-link-focused.png`
- 参考与实现并排对照：`/private/tmp/koc-loop-recovery-title-link-comparison.png`
- 本地页面：`http://localhost:8080/`

## 环境与状态

- CSS 视口：1278 × 692，桌面布局
- 用户参考截图：2556 × 1384，按 2:1 密度归一为 1278 × 692
- 实现截图：1278 × 692
- 页面状态：数据回收 → 美团医美-备婚 → 数据回收队列
- 交互状态：已回填短链的第一条标题获得键盘焦点；两条未回填记录保持普通文本

## 完整画面对比

- 信息架构、侧栏、采集计划和数据回收表格继续沿用现有界面，没有新增路由或改变表格列宽。
- 已回填标题使用现有绿色交互色，聚焦时显示清晰但克制的描边；未回填标题仍为黑色普通文本。
- 参考图中的目标区域与实现截图在同一张并排对照图中检查，未发现遮挡、换行异常或列错位。

## 聚焦区域检查

- 字体与层级：标题字号、字重和省略规则保持不变，仅为可点击标题增加语义色和 hover/focus 状态。
- 间距与布局：链接仍受原有 310px 最大宽度约束，头像、账号副标题和相邻数据列未发生位移。
- 颜色与状态：绿色与现有按钮、成功状态色一致；键盘焦点轮廓可见。
- 图片质量：创作者截图缩略图未受本次改动影响，仍保持原比例显示。
- 文案内容：标题原文、账号名称、平台信息和采集数据均保持不变。

## 功能验证

- 当前任务中识别到 1 条可点击标题，`href` 为已回填的 `http://xhslink.cn/o/9qOYiD3Iu8K`，`target=_blank`。
- 点击标题后短链成功跳转并解析为小红书笔记详情页。
- 另外 2 条没有发布链接的标题不是链接，避免误导点击。
- 链接仅允许小红书正式域名和 `xhslink.cn` / `xhslink.com` 短链域名，其他协议或域名不会渲染为链接。
- 后台浏览器控制台无 warning/error。
- Docker 生产构建通过；相关静态验收测试 12 项全部通过。

## 迭代记录

1. 初次浏览器验收发现第一条发布链接为 `xhslink.cn`，而前端白名单只包含 `xhslink.com`，因此标题仍是普通文本。
2. 补充 `xhslink.cn` 及其子域名白名单，保留 HTTP/HTTPS 与小红书域名边界。
3. 重新构建后，浏览器识别到 1 条可点击标题；点击实际打开对应小红书页面，未回填行仍不可点击。

final result: passed

---

# KOC LOOP 任务筛选常驻搜索框设计 QA

## 验证对象

- 用户目标截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-67b0b080-8ea8-4504-82eb-348e8cf4ec19.png`
- 浏览器实现截图：`/private/tmp/koc-distributions-direct-search.png`
- CSS 视口：842 × 778，设备像素比 2
- 本地页面：`http://localhost:8080/?nav=distributions`

## 调整结果

1. 品牌/项目、内容类型、平台不再使用“先点下拉、再输入搜索”的两层结构，筛选栏直接展示三个可输入的搜索框。
2. 输入内容时立即进行模糊筛选；聚焦或输入后，下方仅展示匹配候选项，不再重复显示第二个搜索框。
3. 宽屏下四个搜索框保持同一行；当前窄视口下任务名称独占一行，三个分类搜索保持在下一行，不互相遮挡。
4. 保留键盘与无障碍语义，三个分类搜索均使用 `combobox`，候选项使用 `listbox` / `option`。

## 功能验证

- 默认展示 6 个任务。
- 品牌/项目直接输入“美团”后，候选项仅显示“美团”和“美团医美”，任务结果同步缩小为 2 个。
- 清空输入后恢复 6 个任务。
- 静态验收测试 14 项全部通过，正式构建通过；本地 Docker 应用已重新构建并加载新页面。

final result: passed

---

# KOC LOOP 任务筛选下拉遮挡设计 QA

## 验证对象

- 用户问题截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-bd2d14b7-472f-43a5-b997-1b6ff9528ba1.png`
- 浏览器实现截图：`/Users/wufp/Documents/koc-loop/design-qa-inline-filter.png`
- 修复前后并排对照：`/Users/wufp/Documents/koc-loop/design-qa-inline-filter-comparison.png`
- CSS 视口：1280 × 720，设备像素比 2
- 本地页面：`http://localhost:8080/?nav=distributions`

## 问题与调整

1. 之前仍使用浏览器原生 `select`，系统级下拉层会悬浮在页面上，因此即使搜索框本身布局正常，展开菜单仍会遮住搜索区或任务卡片。
2. 品牌/项目、内容类型、平台三个筛选器改为页面内选择面板，面板使用正常文档流布局，展开时把任务卡片向下推。
3. 同一时间只展开一个筛选器；选择选项后自动收起，并保留键盘焦点、`aria-expanded`、`listbox` 和 `option` 语义。

## 布局与功能验证

- 内容类型面板展开后：面板 `position: static`，搜索框底部为 379px，面板顶部为 388px，两者无重叠。
- 第一张任务卡片顶部为 480px，面板底部为 452px，任务卡片位于面板下方，未被覆盖。
- 选择“视频”后面板自动收起，任务数由 6 个缩小为 1 个；清空筛选后恢复 6 个任务。
- 浏览器实测搜索框、三个筛选按钮和任务卡片均可正常操作，交互过程中未出现页面报错。
- TypeScript 构建、静态验收及共 65 项测试全部通过；本地 Docker 服务已重新构建并通过健康检查。

final result: passed

---

# KOC LOOP 任务分发筛选栏设计 QA

## 验证对象

- 用户问题截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-4c32c7e3-58e0-4262-b625-c02b20ec4490.png`
- 浏览器实现截图：`/Users/wufp/Documents/koc-loop/design-qa-implementation.png`
- 修复前后并排对照：`/Users/wufp/Documents/koc-loop/design-qa-comparison.png`
- CSS 视口：1280 × 720
- 本地页面：`http://localhost:8080/?nav=distributions`

## 问题与调整

1. 全局 `label` 布局把搜索图标和输入框纵向堆叠，导致搜索框被拆成上下两层。
2. 搜索框现在显式使用横向布局，并清除继承的外边距；图标使用固定宽度居中对齐。
3. 品牌/项目下拉框加宽，选中值和下拉菜单锚点保持稳定，不再挤压搜索区域。

## 功能验证

- 输入“视频”后，结果从 6 个任务缩小为 1 个任务，筛选栏没有发生错位。
- 清空搜索后恢复展示 6 个任务。
- 浏览器控制台无错误。
- TypeScript、静态验收测试和正式构建均通过。
- 本地 Docker 服务已重建并通过健康检查。

final result: passed

---

# KOC LOOP 可搜索任务筛选浮层设计 QA

## 验证对象

- 参考截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-fc7ce949-d8ea-4a3b-afa6-04a778fdb8dc.png`
- 浏览器实现截图：`/Users/wufp/Documents/koc-loop/design-qa-current-filter.png`
- 参考与实现并排对照：`/Users/wufp/Documents/koc-loop/design-qa-filter-comparison.png`
- 本地页面：`http://localhost:8080/?nav=distributions`

## 布局与交互验证

- 品牌/项目、内容类型、平台均改为紧凑的页面内浮层，不再使用系统原生下拉，也不会把任务卡片整体向下推。
- 浮层锚定在当前筛选按钮下方，宽度与筛选控件协调，未遮挡任务名称搜索框及其他筛选按钮。
- 浮层顶部支持输入模糊查询；输入“医”后只显示“美团医美”，可继续点击完成筛选。
- 同一时间只展开一个筛选器，支持点击页面其他位置或按 Esc 收起。
- 浏览器实测筛选栏、任务卡片和按钮均保持稳定，没有布局跳动。

## 数据修复验证

- 抖音作品重新采集后获得点赞 5,684、收藏 565、转发 6,878、评论 332。
- 抖音主页链接改用短链跳转携带的真实 `sec_uid`，不再用数字内部用户 ID 拼接主页。
- MCP 的公开主页解析对当前账号仍返回资源不存在，因此公开抖音号、粉丝数和 IP 暂时保持待识别，不再写入错误数据。
- 相关自动化测试共 67 项全部通过，本地 Docker 服务已重建并通过健康检查。

final result: passed
# KOC LOOP 任务分发横向搜索框设计 QA

## 验证对象

- 用户问题截图：`codex-clipboard-252bf483-c3d1-4d70-abfb-d54587a300a2.png`
- 浏览器实现截图：`/private/tmp/koc-loop-distribution-filters-fixed.png`
- 本地页面：`http://localhost:8080/?nav=distributions`

## 问题与调整

1. 品牌/项目、内容类型、平台三个筛选框使用通用表单标签，继承了纵向排列样式，导致图标和提示文字上下分离。
2. 筛选框改为独立容器，并显式使用横向排列和垂直居中。
3. 保留原有模糊搜索、筛选逻辑及整体视觉规范。

## 布局与功能验证

- 三个筛选框内图标、输入文字与容器的垂直中心误差均为 0px。
- 四个搜索框保持同排展示，无相互遮挡、无异常换行、无额外浮层。
- 项目构建通过；页面渲染测试 14/14 通过；本地 Docker 运行版本已更新。

最终结果：通过。

---

# KOC LOOP KOC资源卡片密度优化设计 QA

## 验证对象

- 参考卡片：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-615400a6-0bd1-4110-b280-f7fdc29bf705.png`
- 原页面参考：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-5bf2bfb5-a50e-4c08-a407-192fdcf20b58.png`
- 第一轮实现截图：`/Users/wufp/Documents/koc-loop/design-qa-resource-cards-v2.png`
- 最终浏览器截图：`/Users/wufp/Documents/koc-loop/design-qa-resource-cards-final.png`
- 聚焦卡片并排对照：`/Users/wufp/Documents/koc-loop/design-qa-resource-card-comparison.png`
- 本地页面：`http://localhost:8080/`，KOC资源状态

## 环境与归一化

- CSS 视口：1280 × 720；设备像素比 2；浏览器截图按 1280 × 720 CSS 像素输出。
- 参考卡片像素：478 × 700；最终完整页面截图：1280 × 720。
- 聚焦对照将实现中的 304px 宽卡片等比放大到 478px，并与参考卡片并排查看；没有把两张独立截图当作同一对比证据。
- 桌面状态为三列卡片；同时验证 960px 两列、640px 一列。

## 完整画面对比

- 信息架构采用参考图的“头像 → 身份信息 → 简介 → 标签”顺序，同时保留 KOC LOOP 原有的粉丝、合作发布、合作来源和主页入口。
- 卡片高度由旧版的大块分区缩短到首屏实测约 274—278px；三列宽度均为 304px，页面没有横向溢出。
- 小红书使用粉红顶部识别线和柔和粉色标签，抖音使用深色顶部识别线，继续沿用现有平台标识。

## 聚焦区域检查

- 字体与层级：昵称 14px 并提高字重；账号号、属地、标签和数据从第一轮偏小的 8px 提升至 9—11px，信息仍紧凑但可读性更好。
- 间距与布局：圆形头像、昵称与性别保持同一视觉组；账号号、平台和属地收进头像右侧；粉丝、合作发布、最近合作合并为一条浅底数据栏。
- 颜色与视觉标记：标签颜色与平台呼应，状态对比足够；卡片 hover 只使用轻微位移和阴影，不改变布局。
- 图片与资产：当前账号数据没有头像 URL，因此保留现有首字母头像作为明确的数据缺失状态，没有伪造真人头像；平台标识继续使用项目已有资产。
- 文案与内容：真实简介最多展示三行；“未填写简介”“还没有简介”等占位内容统一折叠为“暂无简介”；无标签显示“待打标”；合作来源和主页入口合并到底部同一行。

## 交互与响应式验证

- 输入标签“美食探店”后，结果正确缩小为 3 个账号；清空后恢复完整列表。
- 主页入口保持可见并保留现有跳转目标；首屏六张卡片均检测到有效入口文案。
- 960px 视口为两列，640px 视口为一列，两个断点均无横向溢出。
- 浏览器控制台无 error；本地应用、MySQL、Nginx 均正常运行。
- 正式构建及完整自动化测试通过，共 82 项，无失败。

## 迭代记录

1. 第一轮已完成资料卡层级和高度压缩，但聚焦截图显示辅助文字偏小，无简介账号的底部留白仍较明显，记为 P2。
2. 第二轮提高辅助文字字号，移除固定最小高度，并把合作来源与主页入口合并为同一底栏。
3. 复查后卡片高度稳定在约 274—278px，关键内容可读，桌面与移动断点无溢出；先前 P2 已解决。

## 结论

- 没有遗留 P0、P1 或 P2 问题。
- P3 后续项：如果 MCP 未来提供可靠头像 URL，可将首字母头像替换成真实头像，进一步接近参考图。

final result: passed

---

# KOC LOOP KOC资源卡片底栏对齐设计 QA

## 验证对象

- 用户标注截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-fa2c031d-52ba-4ef5-bd70-2bf74adfa52d.png`
- 最终浏览器截图：`/Users/wufp/Documents/koc-loop/design-qa-resource-card-alignment-final.png`
- 归一化并排对照：`/Users/wufp/Documents/koc-loop/design-qa-resource-card-alignment-comparison.png`
- 本地页面：`http://localhost:8080/?nav=resources`

## 问题与调整

1. 不同账号的简介和标签数量不一致时，合作来源与主页入口会跟随前方内容上下浮动，导致同一排卡片的底部结构不齐。
2. 卡片保持纵向弹性布局，底栏改为自动占用剩余空间并贴住卡片底部；不增加固定高度，不改变数据或交互逻辑。
3. 三列桌面视口下实测前三张卡片高度均为 267.9px，底栏顶部均为 333.4px，底栏底部均为 365.9px，误差为 0px。

## 验证结果

- CSS 视口：1280 × 720；三列卡片状态。
- 不同简介、标签数量下，合作来源、来源标签和主页入口保持同一条水平基线。
- 浏览器控制台无 error；页面 hover 位移不会改变静止状态的布局基线。
- 页面渲染测试与 TypeScript 检查通过；本地 Docker 已重建。

final result: passed

---

# KOC LOOP KOC资源卡片数据栏对齐设计 QA

## 验证对象

- 用户标注截图：`/var/folders/0g/8yrmts9s7v5g_xc60sxx0__80000gn/T/codex-clipboard-78335120-710a-4a7b-96f9-b1046191c788.png`
- 双列实现截图：`/Users/wufp/Documents/koc-loop/design-qa-resource-card-metrics-alignment-two-column.png`
- 三列实现截图：`/Users/wufp/Documents/koc-loop/design-qa-resource-card-metrics-alignment-final.png`
- 归一化并排对照：`/Users/wufp/Documents/koc-loop/design-qa-resource-card-metrics-alignment-comparison.png`
- 本地页面：`http://localhost:8080/?nav=resources`

## 环境与归一化

- 用户截图为 1674 × 1180px；双列实现截图为 837 × 591px。
- 并排对照将用户截图归一化为 837 × 591px，与实现截图使用同一双列宽度和页面状态进行聚焦比较。
- 同时在 1280 × 720 三列桌面视口复测，确认调整不依赖双列断点。

## 问题与调整

1. 先前仅把合作来源底栏贴底，数据栏仍跟随简介和标签数量上下浮动，形成 P2 对齐问题。
2. 将弹性留白移动到标签区之后，数据栏与合作来源底栏作为一个完整结构贴住卡片底部；数据内容、标签和交互均未改动。

## 验证结果

- 双列第一排两张卡片的数据栏顶部均为 233.4px、底部均为 267.9px；底栏顶部均为 277.9px、底部均为 310.4px。
- 双列第二排两张卡片的数据栏顶部均为 525.3px、底部均为 559.8px；底栏顶部均为 569.8px、底部均为 602.3px。
- 三列前三张卡片的数据栏与底栏上下边界误差均为 0px。
- 字体、颜色、图片资产和文案未发生变化；浏览器控制台无 error。
- 页面渲染测试 14/14、TypeScript 检查和 Docker 构建均通过。

final result: passed