# 248 Admin：统一列表搜索区的清除按钮

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#15 / Admin 界面一致性
- 状态：已完成，待用户验收
- 日期：2026-08-15
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/248

## 背景与目标

顺运宝数据和档口入库码已经在搜索区提供常驻“清除”入口，蝦皮数据、PDD 商品、
采集采购、客户端列表和用户管理仍要手工清空输入框或等空状态出现后才能恢复默认列表。
本任务统一这 5 个 Tab 的搜索交互。

## 最终方案

- 5 个搜索表单均在“搜索”按钮前增加普通 GET“清除”链接，不增加 JavaScript。
- 清除链接不携带关键词、状态、类型、创建人和旧页码，因此恢复默认筛选并回到第 1 页；
  只保留当前归一化后的 `page_size`。
- 蝦皮回收站和“未登记商品”是独立查看范围，不属于普通搜索条件；蝦皮清除链接按当前
  页面继续携带 `deleted`、`unlinked`，避免清除关键词时意外离开当前范围。
- 新增一个集中式模板回归测试，逐页检查链接参数和“清除 → 搜索”的操作顺序。
- 界面规范补充常驻清除入口、参数保留和不依赖 JavaScript 的统一规则。

## 改了哪些

- `admin/templates/shopee/list.html`：增加保留当前查看范围的清除入口。
- `admin/templates/pdd/list.html`：增加 PDD 筛选清除入口。
- `admin/templates/task/list.html`：增加类型、状态、创建人和关键词的一次性清除入口。
- `admin/templates/client/list.html`：增加客户端名称清除入口。
- `admin/templates/user/list.html`：增加用户名和状态清除入口。
- `admin/filter_clear_template_test.go`：新增 5 个页面的链接参数和按钮顺序测试。
- `docs/admin/05-ui-specification.md`：更新工具条示例和统一清除规则。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 5 个目标 Tab 都在搜索前显示常驻“清除” | 通过 |
| 清除普通筛选并回到第 1 页 | 通过：链接不携带筛选参数和 `page` |
| 保留 `page_size` 及蝦皮独立查看范围 | 通过 |
| 不改变其他 Tab、数据库、接口和 Client | 通过 |
| 模板测试及固定 Go 1.23.0 验证通过 | 通过 |
| 界面规范与页面行为一致 | 通过 |

## 测试

- 执行的命令：
  - `GOTOOLCHAIN=go1.23.0 go test . -run TestListFilterTemplates -count=1`
  - `GOTOOLCHAIN=go1.23.0 go vet ./...`
  - `GOTOOLCHAIN=go1.23.0 go build ./...`
  - `GOTOOLCHAIN=go1.23.0 go test ./... -count=1`
- 结果：模板专项测试、vet、全量构建和全量测试均通过。
- **没验证到的部分**：未登录浏览器在 1366×768 分别人工点击 5 个清除入口；链接结构、
  参数边界和模板解析由自动化测试覆盖。本任务不涉及数据库、外部服务、Client 或真实业务动作。

## 相关提交

- `9f35419` 统一列表搜索清除入口。