docs(#277 ): record sanitized pdd home evidence

fix(#277 ): fail image search tasks explicitly until automation is available
feat(#280 ): remember image search device
2026-09-15 10:07:27 +08:00 · 2026-09-15 09:59:56 +08:00 · 2026-09-15 09:57:17 +08:00 · 2026-09-15 09:51:39 +08:00 · 2026-09-15 09:45:50 +08:00 · 2026-09-15 09:42:25 +08:00
114 changed files with 6903 additions and 440 deletions
@@ -7,6 +7,8 @@
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
+    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />

    <queries>
        <package android:name="com.xunmeng.pinduoduo" />
@@ -38,6 +38,7 @@ class MainActivity : AppCompatActivity() {
        )
        setContentView(buildContent())
        requestNotificationPermission()
+        requestMediaPermission()
        if (AgentSettingsStore(this).serverUrl().isNotBlank()) AgentForegroundService.start(this)
        AgentAppUpdateManager.checkOnceAtStartup(this)
    }
@@ -127,6 +128,14 @@ class MainActivity : AppCompatActivity() {
        }
    }

+    private fun requestMediaPermission() {
+        val permission = if (Build.VERSION.SDK_INT >= 33) Manifest.permission.READ_MEDIA_IMAGES
+        else Manifest.permission.READ_EXTERNAL_STORAGE
+        if (checkSelfPermission(permission) != PackageManager.PERMISSION_GRANTED) {
+            requestPermissions(arrayOf(permission), MEDIA_PERMISSION_REQUEST)
+        }
+    }
+
    private fun applyScreenPolicy() {
        val keepScreenOn = cn.ilapage.goauto.agent.service.AgentStateStore(this).read().keepScreenOn
        if (keepScreenOn) {
@@ -145,5 +154,6 @@ class MainActivity : AppCompatActivity() {
        private const val TAB_PREFERENCES = "goauto_agent_ui"
        private const val LAST_SELECTED_TAB = "last_selected_tab"
        private const val STATE_SELECTED_TAB = "selected_tab"
+        private const val MEDIA_PERMISSION_REQUEST = 101
    }
 }
@@ -0,0 +1,44 @@
+package cn.ilapage.goauto.agent.automation
+
+import android.content.ContentValues
+import android.content.Context
+import android.net.Uri
+import android.os.Build
+import android.provider.MediaStore
+import cn.ilapage.goauto.agent.network.ImageSearchImage
+import java.security.MessageDigest
+import java.util.UUID
+
+data class PreparedImageSearchAsset(val uri: Uri)
+
+object ImageSearchAssetPolicy {
+    private const val MAX_BYTES = 10 * 1024 * 1024
+    fun valid(bytes: ByteArray, reference: ImageSearchImage): Boolean {
+        if (bytes.isEmpty() || bytes.size.toLong() != reference.sizeBytes || bytes.size > MAX_BYTES) return false
+        if (reference.mediaType != "image/jpeg" && reference.mediaType != "image/png") return false
+        return sha256(bytes) == reference.sha256.lowercase()
+    }
+    fun sha256(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256").digest(bytes).joinToString("") { "%02x".format(it) }
+}
+
+class PinduoduoImageSearchAssetStore(context: Context) {
+    private val resolver = context.applicationContext.contentResolver
+
+    fun prepare(bytes: ByteArray, reference: ImageSearchImage): PreparedImageSearchAsset? {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q || !ImageSearchAssetPolicy.valid(bytes, reference)) return null
+        val values = ContentValues().apply {
+            put(MediaStore.Images.Media.DISPLAY_NAME, "goauto-search-${UUID.randomUUID()}.jpg")
+            put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
+            put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/GoAutoSearch")
+            put(MediaStore.Images.Media.IS_PENDING, 1)
+        }
+        val uri = resolver.insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values) ?: return null
+        return try {
+            resolver.openOutputStream(uri)?.use { it.write(bytes) } ?: error("image output unavailable")
+            resolver.update(uri, ContentValues().apply { put(MediaStore.Images.Media.IS_PENDING, 0) }, null, null)
+            PreparedImageSearchAsset(uri)
+        } catch (_: Exception) { resolver.delete(uri, null, null); null }
+    }
+
+    fun delete(asset: PreparedImageSearchAsset?) { asset?.let { resolver.delete(it.uri, null, null) } }
+}
@@ -60,6 +60,14 @@ data class AgentTask(
    val status: String,
    val source: String,
    val replacementOriginType: String,
+    val imageSearch: ImageSearchImage?,
+)
+
+data class ImageSearchImage(
+    val imageUrl: String,
+    val mediaType: String,
+    val sizeBytes: Long,
+    val sha256: String,
 )

 data class CurrentPageIdentity(
@@ -584,6 +592,7 @@ class AgentApiClient(private val serverUrl: String) {
        status = data.getString("status"),
        source = data.optString("source", "admin"),
        replacementOriginType = data.optString("replacementOriginType"),
+        imageSearch = data.optJSONObject("imageSearch")?.let { image -> ImageSearchImage(image.getString("imageUrl"), image.getString("mediaType"), image.getLong("sizeBytes"), image.getString("sha256")) },
    )

    private fun purchaseTask(data: JSONObject) = PurchaseAgentTask(
@@ -708,6 +708,8 @@ class AgentForegroundService : Service() {
                ).collect(identity.goodsId, rule)
                if (!collection.successful) throw TaskFailure(collection.code, collection.message)
                CollectionExecution(requireNotNull(collection.payload), collection.colorImages)
+            } else if (task.source == "image_search") {
+                throw TaskFailure("IMAGE_SEARCH_AUTOMATION_UNAVAILABLE", "当前 Agent 版本尚未接入 PDD 图搜自动化，请使用普通采集任务")
            } else if (rule.schemaVersion == 2) {
                val trace: (String) -> Unit = { message -> Log.i("GoAutoCollector", message) }
                val collection = PddDetailEntryRunner(
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Project-Profile.-
-wiki_revision: 7468b9fbdd4d0bbbb9a73580c22ec868b3085753
-synchronized_at: 2026-09-05T07:16:39Z
+wiki_revision: 3b78360779ae520f1ff9e51be3118a04cd549f51
+synchronized_at: 2026-09-07T09:27:40Z
 <!-- gitea-wiki-mirror:end -->

 # 项目档案
@@ -61,6 +61,7 @@ GoAuto 默认采用轻量治理：文案、注释、格式、局部样式或布
 ## 环境与凭据

 - 服务端正式环境默认必须使用 HTTPS。仅当管理员接受 Device Token、任务内容和执行结果明文传输风险，并显式设置 `GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true` 时，Agent `/api/agent/v1/**` 可通过 HTTP；管理端和第三方服务不因此放宽。
+- #237 客户端密钥例外（用户 2026-09-07 明确接受风险）：提交 `71f7751` 起，管理员密钥管理及 `/api/client/v1` 默认兼容 HTTP/HTTPS，无开关；HTTP 明文传输密钥及业务数据，建议优先 HTTPS。实际迁移部署仍须单独授权；此例外不改变其他第三方服务的安全边界。
 - 每台设备使用独立 Device Token；Token 只存安全配置，不进入仓库。
 - PDD 账号密码、Cookie、验证码和用户个人数据不得进入日志。
 - 根目录 `gitea.env` 是本机工单访问配置，已被 Git 忽略。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.-
-wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
-synchronized_at: 2026-09-04T11:29:50Z
+wiki_revision: 029dc3e155e1828484c62efd0ac804616fcbc714
+synchronized_at: 2026-09-11T09:09:07Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -68,6 +68,8 @@ Android Portal/Agent
 | `pdd_account` | 可选的账号调度引用，只保存名称和状态，不保存凭据 |
 | `purchase_task` | 商品外键和不可变快照、执行模式、状态/租约 guard、价格边界、订单、人工支付复核、物流与回填事实 |
 | `purchase_task_attempt` | `task_id + attempt_id` 幂等执行记录、阶段、规则哈希、固化规格决策和结构化错误 |
+
+> #241 新增：`server/app/goauto/purchase/order_backfill.go` 与 `order_backfill_handler.go` 提供 `POST /api/agent/v1/purchase-tasks/order-backfill`（Device Token 鉴权，逐条事务、逐条结果）；`server/app/goauto/models/purchase_order_guard.go` 在 `PurchaseTask.BeforeSave` 上全局强制订单号唯一，以 `purchase_rule_setting` 单例行串行化订单号分配，避免新增唯一索引迁移；`purchasecontract.ParseAddressSuffix` 为 `AddressSuffix` 的反解，通过回比而非负向前瞻实现（Go RE2 不支持前瞻）。
 | `ai_matching_setting` | 唯一单例的启用状态、OpenAI-compatible Base URL、模型、超时、内部部署明文 API Key 和更新人；仅管理员设置接口可以读取该字段 |

 `collection_task` 的状态仅为 `pending`、`running`、`completed`、`completed_partial`、`failed`。设备身份和心跳表属于 Agent 领取任务的必要基础，不承载 PDD 业务数据。
@@ -333,3 +335,128 @@ PddProductDetailCollector
 - `GET /api/v1/sysjob/:id/execution-logs` 由 `server/app/jobs/service/execution_log.go`、`apis/execution_log.go` 和 `router/sys_job.go` 提供任务级分页、状态与开始时间过滤；沿用隐藏菜单 `JobLog` 的角色菜单绑定和精确 GET 权限。Web 入口为 `web/src/views/schedule/index.vue` 的单选“日志”按钮，详情页为 `web/src/views/schedule/log.vue`。
 - 执行历史明确不保存任务参数、AI Provider 地址或密钥、第三方原始响应和业务原始载荷；当前不提供删除、保留期限自动化、WebSocket 实时流或立即执行动作。
 - 追加迁移为 `server/cmd/migrate/migration/version-local/1788357000000_sys_job_execution_log.go`：创建执行历史表、登记只读 API、关联 `JobLog` 菜单，并只给迁移前已绑定该菜单的角色补充精确 Casbin 权限。
+
+## 客户端密钥访问架构（#237）
+
+代码基线 `71f7751`（含用户确认的默认 HTTP/HTTPS 兼容），2026-09-07 完成 Server/Web 代码与隔离测试；本机迁移、管理员菜单写入与 Server/Web 启动已于 2026-09-07 授权完成，真实 HTTP 管理列表和模块目录加载通过；线上仍未部署。
+
+- `server/app/goauto/clientkey` 管理独立密钥、授权及审计；`clientapi/routes.go` 的显式 Inventory 将 `/api/client/v1` 映射到既有业务处理器，绝不转发任意 Admin 路由。
+- `clientapi/gateway.go` 默认接受 HTTP 与 HTTPS，无协议开关或转发协议头门禁，按 Bearer 密钥、模块及能力顺序校验，每次请求读取数据库，无授权缓存。`common/clientprincipal` 传递独立客户端身份，不生成或伪装管理员 JWT。
+- `client_api_key` 保存名称、随机 256 位密钥的 SHA-256 摘要、前缀、授权 JSON、启用状态、版本、创建/修改人和最后使用时间；完整密钥仅创建响应一次返回。`client_api_key_audit` 保存管理变更和客户端请求元数据，不保存请求正文、查询参数、响应正文或凭据。
+- 编辑与停用采用启用状态和 version 条件更新，并与变更审计同事务提交；冲突返回 409。业务执行前先持久化请求审计意图，失败则不执行业务。完成后更新状态；更新失败或进程中断可能留下 status=0，表示结果待核对，不能据此自动重放。
+- 部分既有业务操作人字段使用该密钥最近授权管理员的 ID 兼容现有外键；实际调用方以独立审计的 key_id 为准，不能把业务字段当成人工操作证据。
+- Admin 页面 `web/src/views/goauto/client-keys/index.vue` 复用创建/编辑授权弹窗；菜单位于“采采管理”，仅管理员可见。新追加迁移 `1788798000000_client_api_key.go` 创建两表及管理员菜单，不改 Android。
+
+## 采购规格面板预滑动兼容（#238）
+
+代码基线 `58a6c1c`，Android 0.9.60 / versionCode 73（构建完成不等同于已安装/发布）。`PurchaseRehearsalExecutor.applyPostAction` 对 `openSpecPanel.swipeAfter` 只兼容解析、不执行机械预滑动，`waitAfterMs` 保留；首趟继续原 `probeSpecs` 遍历，第二趟继续原 `selectSpec` 精确查找与容器内有界滚动。其他动作的后置滑动仍沿用既有执行语义，失败不会被统一忽略。
+
+`GoAutoAccessibilityService.swipePurchase` 的失败分类由 `PurchaseSwipeFailureReason` 枚举提供；共享 `swipeNode` 仅增加可选分类回调，不改变手势目标、轨迹、1500ms 回调等待或其他调用者行为。`GoAutoPurchasePanel` 日志经 `AgentForegroundService` 关联 task、attempt、device 与规则快照哈希，新增预滑动跳过/必需滑动失败标量；不记录节点文字、坐标、原始控件树、截图或凭据。
+
+Server/Web、数据库和任务快照不变；旧 APK 仍有预滑动行为，必须更新 Agent 才生效。相关验证在 `PurchaseRehearsalExecutorTest`，Android 全量测试与 APK 构建入口不变。
+
+## SYB 逐页保存与部分成功（#239）
+
+实现绑定 c6a962d；代码已实现不代表当前线上已部署。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。
+
+同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。
+
+`orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。
+
+Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。
+
+入口为 `SyncWithShopSnapshot → loadDailyList → importSyncPage`；`server/app/goauto/sybimport/sync_page.go` 封装页事务和提交后计数；`import_handler.go` 判定终态，`sync_run.go` 保存及筛选，Web 复用 `web/src/views/goauto/syb-sync-runs/index.vue`。
+
+## Android 连续临时采集收尾（#250）
+
+当前实现绑定 `37e8b56`（Agent 0.9.72 / 85），用户确认 v5 按次数返回后切回 Agent。仅 Android，无 Admin/API/权限/数据库迁移；取代 v1～v4 首页导航。
+
+- `AgentSettingsFragment` 在采集间隔后复用卡片和 SwitchMaterial；仅开启显示“返回次数”按钮，Material 单选框选择 1～5 次（默认 3），立即保存或取消。成功无常驻反馈，错误/忙碌显示原因。任务忙碌禁用，弹窗选定时再检查。
+- `AgentSettingsStore` 在私有 `goauto_agent_settings` 保存 `continuous_collection`（false）与 `continuous_collection_return_count`（3）；次数越界或读取错误回落 3，写入失败恢复旧值，无网络加载。
+- `requestCurrentPageCollection` 保留原范围判断；`executeTask` 在采集开始固定次数。`executeTaskWhileAwake` 提交结果、结束图片上传后返回 resultStatus；`ContinuousCollectionPolicy.finish` 仅对完整确认成功调用新 `PddCollectionReturnNavigator`。失败/部分成功不导航。冷却间隔不变，连续模式不启动旧 idle-return。
+- 删除 `PddCollectionHomeNavigator` 和专属首页/搜索层判据。新导航器仅使用 capture/back、当前包名、openAgentPreservingTab；1～5 次 Back，每次后 500ms，前台离开 PDD 终止剩余 Back；保留风险场景停止。最后打开 Agent 并等待 500ms 验证包名，不验证 PDD 首页。仍在原任务互斥与唤醒锁范围内完成，结束后原 finally 释放。
+- `GoAutoCollector` 日志关联 taskId、attemptNumber、deviceId、规则快照 SHA-256；记录 continuousReturn、configuredBacks、固定 reason 和 actions。原因含 count_completed、left_pdd、back_failed、unsafe_page、agent_launch_failed、agent_not_confirmed、navigation_exception、invalid_count；actions 为 Back 尝试数，不代表最终页面。无节点文字、树、截图或个人数据落盘；不扩大采购诊断存储。
+- `ContinuousCollectionTest` 覆盖范围/终态、1～5 次、无变化仍按次数、前台变化、风险、动作/启动失败、包名确认和异常；`ContinuousCollectionSettingsTest` 覆盖开关与次数持久化、默认/越界/写入失败。`:app:testDebugUnitTest :app:assembleDebug` 376 项通过。旧首页专属测试随旧行为替换，新版未安装，UI 大字体/横屏、多设备和完整采集真机链路尚未验证。
+
+## SYB 存疑规格候选解析（#251）
+
+实现绑定 `64b4205`，仅 Server `app/goauto/sybimport`；无 API 字段、数据库迁移、权限、并发模式或 UI 变化。
+
+- `parse_candidates.go: ParseWithCandidates` 先运行原 `Parse`，仅 uncertain 时解码并校验已存 SpecsJSON；复用 `closedShopeeCandidates` 提取颜色/尺码封闭候选，拒绝未知有值角色/重复角色。完整候选组合与原文归一比较唯一时确认，其他情况返回原 ParseResult。
+- `ApplyDetail` 在加载既有蝦皮商品后、写入规格前调用；`Reparse` 在保留人工/AI 确认保护后加载关联候选调用。新增 ParseResult 私有 matchedCandidates 标记，使 `mergeParsedSpec` 对已经存在的候选直接返回，避免按维度名重复合并或改变映射。
+- #198 `ProcessSpecAIParseRun → Reparse` 自然接入确定性优化，仍需 AI 的记录沿用原后续步骤，不新增异步任务/Provider 调用/接口。
+- 验证 `go test ./app/goauto/sybimport ./app/goauto/aimatching ./app/goauto/shopeeproduct ./app/goauto/purchase` 和 `go build ./...` 通过；新增候选正反/格式/组合色/单维度、歧义/空值、同步重解析一致、人工保护及无需调用 AI 测试。AI 原有置信度/失败重试测试改用仍需语义理解的合成输入，继续验证原分支。
+- 本轮只使用本地测试数据与 httptest AI，未触发真实 SYB 同步、外部 AI、采购、数据库迁移或服务重启；线上及历史数据效果尚待授权验证。
+
+
+## 蝦皮详情匹配等待与回读（#254）
+
+实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。
+
+- Server `shopeeproduct.Service.DetailWithAutoMatchBudget` 为详情 GET 附加派生的整次匹配预算，不返回 Provider、Key 等配置。`AutoMatchMappings` 读取 AI 设置 T，使用 2T+10 秒的单个父 context；颜色、尺码、保存及结果回读共用剩余时间。初始配置读取也受有界 context 约束，读取耗时从后续预算扣除。
+- 批量定时匹配调用内部 `autoMatchMappings` 并继续使用原 MaxProviderTimeout=600 秒，不随本次详情入口调整；候选建议与其他 AI 功能不改。
+- Web `ShopeeProductDetailDrawer` 在提交前以普通 GET 刷新商品与预算，仅 auto-match POST 使用 (2T+20) 秒超时。准备失败/缺少预算时不发 POST；旧 Server 必须先更新，不能只发布新版 Web。
+- 加载状态同时绑定商品加载代次和操作序号。关闭/切换立即结束该页面等待状态；同商品重开读取详情，旧响应/旧 finally 不得污染新操作。匹配期间禁止在当前抽屉编辑映射，原人工草稿放弃确认保留。
+- POST 未正常返回时只回读详情及关联 PDD，不自动重发 POST；回读失败结束转圈并保留刷新入口。GET 沿用单请求10秒超时，完整结果回读最多两次串行 GET，不是无限等待。
+- 验证：Go shopeeproduct/aimatching/clientapi 测试与 go build；Web `node --test tests/unit/shopee-match-lifecycle.test.cjs`，Playwright shopee-match-lifecycle 与 shopee-pdd-picker，受影响 ESLint 与 build:prod。
+
+
+## SYB 行内一键关联最近采集（#253）
+
+实现绑定 `b1594dc`，2026-09-10；分支 feat/253-one-click-link，包含 #254 依赖。已完成合成数据测试及构建，未合并 main、未部署，不代表当前线上已具备此能力。
+
+- Web `syb-products/index.vue` 在“去关联”旁增加“一键关联＋下拉箭头”，共享 `quick-link.js` 页面级状态。`quick-link-device-preference.js` 按当前浏览器来源、API环境、用户ID保存设备ID，独立于批量采购偏好；不存密钥或商品数据。首次主动作选机继续原行，箭头选机只保存偏好。
+- Server `shopeeproduct/latest_collection.go` 复用 LinkPDD 的可选 Admin 模式。短事务核对 SYB→Shopee、未关联/规格版本、设备状态，选择并锁定最新 completed/completed_partial 的 agent_current_page 任务及其 PDD；仅完整采集、active且有可用颜色或尺码时更新，WHERE pdd_product_id IS NULL 不覆盖其他操作者的关联。响应保留该事务产生的规格版本及来源task/device/PDD，不能用后续GET替换冻结上下文再自动匹配。
+- 不新增表、迁移、路由或权限对账。原手动关联/替换请求不变；共享 Handler 明确拒绝 Client API 使用此跨模块模式，不能借 Shopee-only write grant 读取 SYB/设备上下文。来源任务原规则快照不改，taskId 可回溯既有采集证据。
+- 关联后读取现有采购准备；需要人工确认或不具备AI资格时停止自动链路并保留关联，其他情况调用原 AutoMatchMappings，沿用 #254 动态预算及原事务保存/上下文冲突保护。最后刷新实际处理阶段，不调用创建采购/订单接口。
+- 运行期间冻结行、商品、手机；前端重复主动作禁用，切换偏好仍只影响未来操作。卸载或 keep-alive deactivated 令旧操作失效，禁止旧回调继续下一步；不声称已经取消服务端在途写入。异常仅有限GET回读和刷新，不自动重发POST。
+- 验证命令：Server `go test -p 1 ./...`、`go build ./...`；Web `node --test tests/unit/syb-quick-link.test.cjs tests/unit/shopee-match-lifecycle.test.cjs`、`pnpm exec playwright test tests/e2e/syb-quick-link.spec.ts tests/e2e/shopee-match-lifecycle.spec.ts --workers=1`、受影响文件 ESLint、`pnpm build:prod`。SQLite 单连接并发测试不代替生产 MySQL 行锁验收；真实AI、生产数据、跨设备人工闭环待验证。
+
+## SYB 行内一键替换（#258）
+
+实现绑定 `2b01974`；部署与验收见 #258 发布证据。本节补充 #253，不改变原未关联入口。
+
+- `syb-products/quick-link.js` 复用分体按钮、设备偏好和匹配/回读流程；已关联且允许处理阶段时同位置显示一键替换。先只读预览，固定任务、目标商品及规格版本；不同商品一次确认，同商品不重绑。
+- `shopeeproduct/latest_collection.go` 在原 latestCollection 增加可选 replacement 模式。预览和提交均短事务锁定 SYB、Shopee、原PDD、设备、来源采集与目标PDD，核对旧关联及上下文。提交按预览 taskId 读取，不重新挑选后来采集的商品。
+- Admin 路由注入 `purchase.ValidateQuickReplacement`，在事务内复用采购准备数据集及处理阶段计算，不调用 AI。缺少校验函数拒绝替换；客户端密钥不注入且仍拒绝 latestCollection。无新路由、权限、表或迁移。
+- 关联完成后才执行现有 AI 匹配，不在数据库事务中等待 Provider；同一 SYB 正式采购创建与替换共用 SYB 行锁。历史采购快照不变。SQLite 合成测试覆盖冲突与串行并发请求，不能替代生产 MySQL 多连接锁验收。
+
+## 辅助信息缺失的采集关联（#259）
+
+实现绑定 `e467706`，仅 Server；部署/验收见 #259。替代 #253/#258 中“部分完成一律拒绝”的限制，不改变 completed 原有路径。
+
+- completed_partial 的 missing 必须是非空合法列表且仅包含 salesText、shopName、reviewCount，才进入辅助信息兼容检查；title、规格/价格缺失、遍历截断、SKU数量上限及未知原因仍拒绝。
+- `shopeeproduct/partial_collection.go` 核对本次 task 的维度和值、可售SKU的完整标记/规格引用/非负价格、本次颜色价格，以及当前档案可选值由本次有效SKU覆盖，不能借旧档案合并残留的规格或价格通过。真实单维度允许，不虚构另一维度；本次明确报告缺少规格仍拒绝。
+- 一键关联、替换预览及确认提交共用验证。失败沿用409 LATEST_COLLECTION_UNAVAILABLE及现有提示，不回退更早采集、不换手机。状态 completed_partial 和 missing 原样保留；辅助字段缺失仍可在任务详情查看。
+- 无接口字段、数据库迁移、Android/Web或权限变更；普通人工关联与采购/AI资格不变。不将“允许关联”视为“已匹配或已采购”。
+
+## 采购单标题面板与地址就绪等待（#260、#261）
+
+实现绑定 #260 `3c1ffa4`（执行器回归测试 `7de4318`）、#261 `5ea07f1`，Android 0.9.74 / versionCode87，基于0.9.73。安装及真实采购验收以工单证据为准；不代表 main 的 Android 已整合这些分支。
+
+- 采购仅在安全规格入口点击返回SUCCESS后，记录本次页面包名/Activity作为内存上下文；开始新执行或页面身份改变时清除。`PddScreenParser` 的新增 purchaseEntryContext 默认关闭，仅该采购执行器传入；普通解析和采集原判定保留。
+- 当前仍为同一PDD Activity、商品ID非空、没有页面风险、没有选中摘要，且唯一有标题规格滚动区、一个维度有值，同时具有关闭、数量、支付展示区域与下单操作证据时，单标题可识别为NORMAL_SCROLLABLE。只是允许进入既有精确规格探测/选择，不执行下单或付款，不全局认可UNKNOWN，不增加入口重复点击或滑动。
+- 地址入口点击原有1000ms保留；地址列表等待增加唯一修改目标要求。点击修改和保存由500ms改为1000ms，其他通用动作间隔不变，无新配置项。
+- 修改后不再只见“详细地址”文字就立即写入。最多50次、每次间隔200ms读取（不含读取耗时），检查PDD页面风险；唯一可见启用有内容的详细地址EditText，连续两次路径、边界、内容及Activity相同才继续原输入流程。始终零个/多个或不稳定时失败，不取第一个候选。
+- 输入内容生成、输入后回读、保存后退出及返回规格面板、最终复核和单次下单边界不变。新增本机脱敏诊断 addressEditorCandidates / addressEditorPolls 两个整数，与task/attempt/device/ruleHash关联；不记录地址内容、原始树或整屏截图。
+- 仅Android；无Server/Web、共享API字段、数据库迁移或权限变化。真实采购、地址写入及订单创建不作为自动安装验证，不执行付款。
+
+### v2 商品入口补点与地址返回等待（#260、#261）
+
+2026-09-10 实现绑定 #260 `713111d`、#261 `d0a82f3`，Android 0.9.75 / versionCode88；真实采购效果以工单验收为准，非 main 合并声明。
+
+- 入口恢复不再把全页面支付方式展示文案单独视为支付页。当前包名/Activity、商品标题和安全入口必须与点击前一致，入口唯一且可用；已打开面板、关闭控件、数量、选中摘要、订单操作、风险/评价页面仍拒绝恢复。支付 Activity 或明确支付、订单、地址文本继续阻止补点。仅允许既有一次重新定位后的规格入口中心手势，随后仍验证面板，不循环、不扩展到地址保存或下单。
+- 保存地址后的确认读取、必要时一次返回后的确认读取，增加最多50次、间隔200ms的有界就绪检查，页面捕获耗时另计。连续两次同一Activity满足原地址回读与确认面板条件后继续；完整信息不要求滚动区域。已明确到地址列表时保留原返回路径，不等待列表出现下单按钮；返回后增加1000ms缓冲。
+- 就绪检查不修改原地址回读和结构下单入口规则；超时后只对既有识别的面板、唯一可用滚动区域执行原有有限滚动。零/多个区域仍失败，不凭地址入口或未知底部节点授权下单。最终精确规格、数量、价格、地址与单次下单边界不变。
+- 私有采购诊断新增布尔 savedAddressMatched、savedPanelMatched；整数 savedLegacySubmitCandidates、savedAddressCards、savedAddressTargets、savedScrollCandidates、savedConfirmationPolls。只记录标量并绑定task/attempt/device/ruleHash，不保存地址、原始树或整屏图。
+- CG109 v1现场读取未达到空闲状态，不能确认原失败具体缺哪项证据；v2覆盖迟到确认节点及可观测性，不将合成测试通过冒充真机修复验收。无Server/Web/API/迁移/权限变化，不需要服务器重启。
+
+## 探测到正式采购的单次面板交接（#262）
+
+2026-09-10 实现绑定 `2ea32fd`，Android0.9.76/code89；基于#260/#261，未声明合并main或真实采购验收通过。
+
+- AgentForegroundService通过PurchaseProbeHandoff只在成功spec_probe且结束后新快照仍识别PDD规格面板时保留一次性内存交接。仅taskId/goodsId/ruleHash/deviceId、Activity、前台revision和单调时钟时间，不保留控件节点、地址或选中状态，不落盘；有效期180秒。
+- 正式阶段消费时检查同任务/商品/规则/设备、前台revision及时间，消费后即清除。失配/超时/无任务或采集任务调度/结果异常/进程重启均不能沿用；普通手动再试不会继承已消费交接。现有服务端租约、互斥和匹配等待策略不变。
+- 有交接时，执行器恢复限定的purchaseEntryContext，最多10次、间隔200ms新读取（捕获耗时另计）；连续两次相同PDD Activity且具备既有商品/面板证据才跳过openProduct。空树可有限等待，其他应用/Activity改变/页面风险立即拒绝复用。没有交接时保留原一次判断路径；不把UNKNOWN当成功，不跳过正式精确规格/数量/价格/地址或下单验证。
+- 私有诊断新增handoffPresent、productReused布尔值，reusePolls整数及reuseReason固定枚举legacy_evidence/page_problem/page_changed/handoff_ready/evidence_timeout。仍绑定task/attempt/device/ruleHash，无敏感文本。
+- 无Server/Web、共享API或数据库变化，不需重启服务器。只有合成测试验证；原CG107/108日志证实两阶段，但未记录旧版重开判断，不把上下文丢失假设宣称为唯一现场根因。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 670a5592a6db8301cd115295bf820f7f4b6e06d7
-synchronized_at: 2026-09-07T03:21:47Z
+wiki_revision: d8aeff02fba57cba0b53fb22cdb524fd5cc0cb3e
+synchronized_at: 2026-09-11T09:09:16Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -37,6 +37,8 @@ synchronized_at: 2026-09-07T03:21:47Z
 - PDD 重新采集或更换关联后，目标规格仍存在则映射继续有效；目标规格消失时详情标记“已失效”，服务端拒绝保存不存在的目标，采购预检和创建也拒绝使用失效映射并提示重新选择。
 - 批量软删除逐条校验引用（虾皮商品被 SYB 明细或采购任务引用时不可删除）并逐条返回结果；已删除商品默认不出现在列表，可筛选查看并恢复。

+- #257：蝦皮颜色与尺码建议/一键匹配先保留仍有效的已确认映射，再复用相同标准化比较：简体、空白、全半角与大小写统一。颜色标准化后仅命中一个当前可选 PDD 候选时，不调用 AI，建议标为 matched，一键匹配按既有流程保存 exact_match + confirmed；未命中或多个不同候选标准化后相同，仍走原 AI 与置信度/候选校验。只转换比较键，蝦皮/PDD 原规格名不改，映射目标保存 PDD 原始候选名称；不引入颜色同义词猜测、不自动重算历史映射。
+
 ## SYB 商品明细

 - 一行对应 SYB 一条明确的商品/颜色/尺码/数量明细；唯一键为「蝦皮订单号 `code` + 来源明细 `id`」组合，不是全局唯一 ID（未在多货运单样本中验证过全局唯一性）。
@@ -58,6 +60,13 @@ synchronized_at: 2026-09-07T03:21:47Z
 - 对采购人员展示的阶段固定为：待人工处理、未关联 PDD、PDD 待采集、PDD 采集中、PDD 采集失败、规格待匹配、可创建采购、已创建任务、采购成功、待人工核对。
 - 主阶段优先级为：待人工核对 → 采购成功 → 已创建任务 → 待人工处理 → 未关联 PDD → PDD 待采集/采集中/采集失败 → 规格待匹配 → 可创建采购。每行只显示一个阶段和对应下一步。
 - “待人工核对”表示订单结果不明确，必须先人工核查并禁止自动重试；“采购成功”表示已取得 PDD 订单号和下单时间，不代表已经支付。
+- 一个 PDD 订单号只能属于一个采购任务，该唯一性在采购任务保存路径上全局强制（#241）。人工处理结果未知、取消及 lifecycle 保存路径撞号时返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`，提示订单号已属于哪个任务，由采购员人工核对，不静默覆盖原值。
+- 不可逆边界之后的 `order_created` 结果回传是上述规则的例外：此时 PDD 真单已创建，发现订单号已属于其他任务时不回滚、不判失败，而是把任务降级为 `order_result_unknown`，冲突订单号以「读到订单号 X，但该号已属于任务 CG-yy」保存在任务与 attempt 的 `error_message`，`pdd_order_no` 留空以维持唯一性，保留下单时间与不可逆时间，进入既有人工处理结果未知通道。首要目标是保住「真单已存在」这一事实，不制造无记录的真实订单。
+- Agent 可按收货地址后缀 `_cg<任务号>` 批量回填订单号与下单时间（#241）。
+- Agent 侧回填为**人工触发的只读扫描**（#242）：入口在采购记录页搜索按钮右侧，输入天数（默认 2）后确认启动。天数口径为滚动 N×24 小时，基准是页面读到的下单时间。采集、采购、回填三者互斥，复用既有任务互斥锁并加原子防重入，忙碌时拒绝启动而不排队、不抢占。
+- 回填扫描不假设订单列表有序：只有连续观察到至少 5 单且下单时间严格递减、期间无缺失时间时，才允许「超过指定时间即停止」；一旦出现时间回升或缺失，改为扫至内部上限并明确标记「未完整扫描」，不得把不完整结果显示为已扫完。内部上限用于限制设备占用，不作为用户可配置的门禁。
+- 回填扫描全程只读：确认收货、申请退款、催发货、去支付、立即支付、提交订单、付款、退款、取消订单、再次购买、删除订单永久排除为点击目标；点击目标必须自身可点、子树不含上述词，且不与任何含上述词的可见控件几何重叠；不得按固定坐标盲点。遇登录、验证码或风控立即停止并报告。
+- 解析不出规范后缀的订单一律跳过，其订单数据不缓存、不上传、不入日志；上传载荷只含后缀、订单号与可选下单时间。本地缓存只采纳服务端确认的事实，并区分页面读到的真实时间与 `irreversible_at` 回落估算值。后缀只承载任务号，请求不含地址全文或收件人信息；只允许回填该设备自己的正式采购任务；页面下单时间优先，缺失时回落该任务的 `irreversible_at` 并标记时间来源，两者皆空则该条失败。
 - 已失败、已取消或演练完成的旧采购任务不单独占用主阶段；当前数据仍满足条件时恢复显示“可创建采购”，旧任务继续在采购管理留痕和按既有规则处理。
 - 未选择处理阶段时，商品列表仍先返回，当前页阶段和采购准备继续异步批量读取且不调用 AI Provider；选择阶段筛选时，服务端必须先对完整查询结果派生并筛选阶段，再计算总数和分页，不能只过滤当前页。

@@ -67,13 +76,13 @@ synchronized_at: 2026-09-07T03:21:47Z
 - 版本迁移会对历史存活店铺回填 `normalized_name = Normalize(display_name)`；回填只改匹配键且可重复执行。若两个存活店铺回填后会得到同一键，迁移必须整体失败并保留原数据，管理员先人工消除歧义后再执行，不能静默合并、删除或改变店铺启用状态。
 - 店铺可以从 SYB 真实货运单列表发现，也允许管理员手工补充。只有管理员可以新增、改名、启停和软删除，采购员等其他角色只读。
 - 没有任何启用店铺时，导入必须在读取凭据、建立会话、验证码 OCR 和任意 SYB 网络请求之前失败，并给出“请先启用店铺”的可读提示。
- 同步必须先拉取并校验当天原始全量列表的总数、分页和唯一 ID，再按本次同步开始时固定的启用店铺快照过滤；过滤不能降低完整性校验的请求范围或容量上限。
+- 同步先预检全范围总数及上限，每页校验原始列表条数、合法 ID 和重复，再按冻结店铺快照获取明细并页事务保存；整日结束核对总数。过滤不能降低完整性校验范围，已保存不能冒充整日完整（#239，c6a962d，已于 2026-09-08 随 d403f3b 部署线上）。
 - 只有列表与明细响应的店铺名都非空且命中启用快照时才允许写入。明细店铺名为空、变化为未启用店铺或无法匹配时跳过，并计入跳过数量。
 - 停用或软删除店铺只影响后续导入，不删除历史 SYB 商品、虾皮商品或任务数据。已有错误导入数据的清理必须先给出精确 SQL 和影响行数，再由用户单独确认。

 ## SYB 后台导入记录

- 导入由管理员创建，创建成功后立即转入后台执行；页面关闭不取消任务。采购员等其他已登录角色可以查看同步记录，不能开始导入。
+- 导入允许管理员和采购员（purchaser）创建，创建成功后立即转入后台执行；页面关闭不取消任务。其他已登录角色只能查看同步记录，不能开始导入（#236）。
 - 系统同一时刻只运行一个 SYB 导入任务。`syb_sync_run` 的唯一执行槽负责跨进程互斥，内存锁减少同一进程内的竞争；服务重启后遗留的执行中记录标记为“已中断”。
 - 导入失败或中断时保留已写入商品，记录明确的失败原因和已处理进度；重新导入相同范围按「订单号 + 明细 ID」覆盖，不产生重复商品。
 - 创建同步记录时冻结本次启用店铺的规范化匹配集合、展示名称快照及 SHA-256 哈希；后台执行必须只使用这一份快照，不得在开始后重新读取 `syb_shop`。同步详情保存并返回快照可用标记、快照店铺名称、哈希及各店铺“已导入/已跳过”数量。#212 之前的历史记录只有哈希和统计，明确标记为无完整快照。上述记录不保存账号、密码、Cookie、Token、验证码图片或 SYB 原始响应。
@@ -97,6 +106,8 @@ synchronized_at: 2026-09-07T03:21:47Z
 - PDD 完整规格选择器若无主滚动容器且尚未选择规格而没有已选摘要，仍可识别为非滚动规格面板，但必须同时出现至少两个已解析维度、至少两个可选项、唯一数量控件和唯一底部订单动作；缺少其中任一强证据时保持未识别。该订单动作仍仅作页面证据，永久禁止点击。
 - Agent 可扩展，但规则必须按任务类型授权：采集规则不能创建订单，采购规则只能使用独立审核的创建订单能力。当前项目不实现支付动作、入口或测试；支付、下单和订单相关文字可以作为只读页面证据配置，但不得成为点击目标。后续支付能力必须单独评估并至少具备显式能力位、服务端开关、单笔金额上限和人工授权。

+- #256（Android 0.9.73，实现 43703e0）：采集执行器可识别无“已选/请选择”摘要且当前仅一个规格标题的滚动规格面板。必须匹配 PDD 包名、任务详情 Activity 与选择器，无登录/验证等异常，并同时具备唯一有界规格滚动区域、唯一标题及非空候选、关闭、唯一数量输入/增减、支付区和唯一下方提交订单只读动作；缺失任一证据仍拒绝。此分支只由采集上下文启用，不生成虚假选中摘要，采购与其他解析调用维持原条件。订单动作仍仅作只读证据，采集绝不点击。
+
 ## 采集任务

 - 任务与结果共用 `collection_task` 主表，不建立独立 `collection_result` 主表。
@@ -168,7 +179,7 @@ synchronized_at: 2026-09-07T03:21:47Z

 - 管理端固定支持 `admin`（管理员）和 `purchaser`（采购员）两类业务角色；用户必须绑定一个存在且启用的角色，`role_id=0` 或停用角色不能创建或保存。
 - 采购员可读取设备状态，维护 PDD/虾皮商品和规格映射，查看与修正 SYB 商品，读取 SYB 店铺及同步记录，读取采集规则，创建/重置/删除采集任务，并创建、查看、重试及人工处理采购任务。
- 仅管理员可管理用户、角色、菜单、接口、部门和岗位；停用设备或吊销 Device Token；新增、改名、启停、删除或发现 SYB 店铺；手动启动 SYB 同步；新增、编辑或删除采集规则；保存或测试 AI Provider 配置。
+- 仅管理员可管理用户、角色、菜单、接口、部门和岗位；停用设备或吊销 Device Token；新增、改名、启停、删除或发现 SYB 店铺；新增、编辑或删除采集规则；保存或测试 AI Provider 配置。
 - AI 规格匹配菜单对采购员硬排除：采购员不显示该菜单，角色配置也不能为采购员选中该模块；既有 API 权限不变，仍只允许读取是否启用，不得读取 Provider 地址、模型、API Key，也不得保存或测试。
 - GoAuto 菜单由代码维护的模块定义幂等写入系统菜单和菜单/API 关联；迁移只为采购员追加首次引入且默认开放的模块，不会把采购员人工取消勾选的既有模块重新加回。
 - 采购员 Casbin API 白名单由代码权限矩阵全量重建，不从角色菜单勾选反推；减少权限时旧策略必须删除。菜单勾选只控制可见模块，不能扩大采购员 API 权限。
@@ -230,7 +241,7 @@ synchronized_at: 2026-09-07T03:21:47Z
 - 定时任务失败时明确记录失败原因，不自动重试。服务重启后由既有启动恢复逻辑处理遗留的运行中记录。
 - 单次同步内部的 SYB 只读请求（货运单总数、列表和明细）遇到暂时网络故障、5xx 或异常响应时最多执行 3 次，分别退避 1 秒、2 秒，单次 HTTP 总超时 60 秒；这不等于失败任务自动重试。明确未登录、业务失败、数据完整性错误以及任何写操作均不自动重试。
 - SYB 商品页不再提供“导入”和“同步记录”快捷按钮，也不查询、展示或轮询同步状态；后台同步成功、失败或中断均不在商品页弹出消息，商品数据由用户主动查询或刷新获取。
- 独立“SYB 同步记录”页面是同步结果的唯一 Web 展示位置，保留运行状态、进度、数量、失败原因和店铺统计；go-admin 定时任务中的 `GoAutoSYBHourlySync` 提供“执行记录”入口。管理员可在同步记录页人工发起覆盖昨天和今天的同步，采购员只读；人工与定时同步共用导入服务、执行记录和互斥，不排队、不并发，也不立即重试。
+- 独立“SYB 同步记录”页面是同步结果的唯一 Web 展示位置，保留运行状态、进度、数量、失败原因和店铺统计；go-admin 定时任务中的 `GoAutoSYBHourlySync` 提供“执行记录”入口。管理员和采购员可在同步记录页人工发起覆盖昨天和今天的同步，其他角色只读（#236）；人工与定时同步共用导入服务、执行记录和互斥，不排队、不并发，也不立即重试。


 ## cmautobuy 商品导入
@@ -397,7 +408,7 @@ synchronized_at: 2026-09-07T03:21:47Z

 - 规格入口与精确规格选择统一按“重新定位唯一目标 → 执行一次无障碍点击 → 读取新页面验证”执行；不得复用旧无障碍节点，不选择相近规格，也不在多候选时默认点击第一个。
 - 无障碍点击后页面完全无变化时，只允许对解析器已确认的安全规格入口或服务端下发且唯一命中的精确规格执行一次中心手势兜底。目标必须可见、启用、边界有效，手势后仍须以规格面板强证据或精确选中证据确认结果。
- 页面发生变化但规格面板强证据不足时，不再继续手势或猜测页面，明确失败并只记录面板类型、候选数量和证据布尔值等无敏感标量。原始控件树、节点文字集合和整屏截图仍不得保存或上传。
+- 页面发生变化但规格面板强证据不足时，默认明确失败；#243 的同商品页安全入口恢复是限定例外：确认包/Activity 未变、商品标题非空且未变、入口来源与语义未变，无面板、关闭、数量、已选、支付、订单或页面异常信号时，重新定位入口并最多执行一次受控手势。整页普通动态节点变化不单独阻断该恢复；入口缺失或显式/嵌套入口歧义仍拒绝。商品标题一致是当前上下文约束，不宣称已从页面核验 goods_id。诊断只记录入口来源、点击结果/原因、恢复结果和面板数量/布尔等无敏感标量。原始控件树、节点文字集合和整屏截图仍不得保存或上传。
 - 规格已处于精确选中状态时不得重复点击。规格查找只在解析器唯一识别的规格面板容器内有限滚动，每次滚动后重新定位容器与目标；容器缺失、歧义、到边或验证失败均 fail-closed。
 - 中心手势兜底不得用于修改/保存地址、创建或提交订单、订单详情入口以及任何支付/付款目标；正式创建订单的一次性不可逆门禁与永久禁止支付规则不变。
 ## PDD 商品反向关联与继续订单采购（#161）
@@ -444,3 +455,158 @@ synchronized_at: 2026-09-07T03:21:47Z
 - 弹窗打开后先按现有在线/可选/采购能力条件加载设备，再恢复选择并以相同设备预检。记忆设备当前不可用时保留偏好并提示用户重新选择或明确清空，不静默切换设备或自动领取。
 - 预检加载中、失败或记忆设备不可用时不能提交；过期预检结果不覆盖新的设备选择。服务端原有设备及采购资格校验不变。
 - 偏好只作用于此入口，不影响采集、其他创建入口和采购重试。浏览器存储失败时仍允许手动操作；刷新或关闭再打开浏览器可恢复，清理浏览器数据或沿用现有退出登录清理存储行为后需重新选择。
+
+## 客户端密钥与可编辑模块授权（#237）
+
+以下为提交 `71f7751` 已实现的规则；2026-09-07 本机已迁移并验证管理页面可用，2026-09-08 已随 d403f3b 完成线上迁移与部署，真实客户端密钥执行闭环尚未验证。
+
+- 仅管理员创建、查看、编辑授权或停用密钥。首版不提供密钥改名、到期、轮换、恢复启用、删除或任意接口授权。
+- 模块选择复用“采集采购/采采管理”现有 12 个业务模块；分组勾选只影响当前子模块，新菜单不会自动获得授权。客户端密钥管理、系统账号权限及支付不在可授权模块中。
+- 勾选模块默认只读，至少保留一个模块。读写仅开放清单中的普通写操作；同步、采集、采购、删除、导入、重解析、匹配、回写及切换当前采购规则分别独立授权，默认关闭。没有普通写接口的模块不允许勾选读写。
+- 编辑既有密钥不会更换密钥，名称和前缀只读；移除模块同时移除其动作。取消保留原授权；失败保留输入；版本冲突要求刷新重开。停用不可编辑或恢复。
+- 保存后新请求按最新授权校验，已经通过校验的在途请求可能完成，不追溯回滚。模块授权不是行级、店铺级或租户隔离，授予读取即允许读取该模块明确接口可返回的业务范围。
+- 用户于 2026-09-07 明确接受明文风险：密钥管理及客户端接口默认兼容 HTTP/HTTPS，无需开关。HTTP 会明文传输密钥与业务数据，建议优先使用 HTTPS；兼容不改变管理员身份与模块授权边界。
+- 客户端与 Admin 登录 JWT、Agent Device Token 独立。响应排除凭据及原始载荷字段；AI 设置只返回 enabled，不开放 Provider 配置读写或连接测试。设备仅开放列表，不开放身份重置、令牌或解锁接口。
+- 执行动作复用既有业务门禁、幂等参数及状态机；客户端采购 batch-retry 沿用 Admin 原有语义，不等同于 Agent 就地 reset。授权重采购、支付复核、取消订单等未列入接口不开放；永久禁止付款。
+- 创建响应丢失时不可找回完整密钥，应核对列表并停用可能已创建的记录，再明确创建新密钥，不能盲目自动重试。完整密钥只在创建结果弹窗内存中显示，关闭或离开页面清空，不写浏览器持久存储。
+
+## 打开采购规格面板后按需滚动（#238）
+
+- Android 0.9.60 / versionCode 73，代码 `58a6c1c` 起，规则 `openSpecPanel.swipeAfter` 保留格式校验与旧快照兼容，但不执行打开面板后的固定次数预滑动；不以“必须滑两次成功”作为进入规格探测/选择的条件。动作后的 `waitAfterMs` 仍生效。
+- 首趟规格探测和第二趟精确选择仍使用各自既有的按需横向/纵向、有界与稳定终止策略。取消预滑动不等于不探测隐藏规格，也不等于只看首屏。目标不存在、歧义、页面证据不足或必要的有界查找失败时仍明确失败。
+- 此调整覆盖所有已经安全识别打开的面板，不再仅特判 NON_SCROLLABLE_CONFIRMATION；不弱化面板验证、精确选中、地址、价格、任务租约、创建订单边界或禁止支付规则。
+- 其他动作的后置滑动沿用原行为，必需滑动失败仍返回 RULE_ACTION_FAILED。旧规则 JSON 不回写、不迁移；原任务 ID、历史 attempt、商品与规格快照不变。旧 APK 行为不变，需升级 Agent；本单未改线上规则或执行 CG68 真机采购。
+
+## SYB 逐页保存与部分成功（#239）
+
+实现绑定 c6a962d；2026-09-08 已随 d403f3b 部署线上，未手动触发真实同步验收；#240 上游尾页超时尚未修复。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。
+
+同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。
+
+`orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。
+
+Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。
+
+
+## 商品页动态变化下的采购入口恢复（#243）
+
+实现 ec8b14a，Android 0.9.61/versionCode 74；已构建、未安装或真机验收。规格探测和正式采购共用入口函数，面板已打开时不新增点击；仍在同一商品上下文且安全入口存在时，一次重新定位手势恢复不再依赖整页完全静止。手势后仍未打开则报告入口无效果，不循环点击。恢复不能用于地址、创建订单、支付或未知面板，不修改面板分类器及正式下单边界。CG82/CG85 原首次点击未生效的底层原因尚待新日志和授权真机验证。
+
+
+## 同一颜色卡片重复选中节点（#244）
+
+实现 93aab6a，Android 0.9.62/versionCode 75；已构建并授权覆盖安装，真实采购效果待验收。仅在颜色维度完整精确目标已选中、但存在非目标已选候选时，识别同一卡片重复表达：卡片必须是滚动容器直接子级的可点击非滚动 android.view.ViewGroup，节点父链明确、可见启用且边界包含；其他冲突节点仅可为该卡片自身或其中的 ImageView。另一文字选项、另一张卡片、多个精确目标、目标未选中、父链/边界不明均不适用例外。额外核对内存源节点以拒绝被解析器按同名去重隐藏的跨卡片目标；不保存原始树。
+
+不删除规格数字、不模糊匹配、不改变通用解析器、尺码确认、摘要兜底、入口/滚动/地址/价格/创建订单。没有非目标选中冲突时继续原判断；仅把同卡片容器/图片的重复选中表达从冲突中排除，不新增点击。
+
+
+## 精确规格不可用与入口恢复诊断（#245）
+
+实现 ca815c3，Android 0.9.63/versionCode 76；已通过单元测试并构建，未安装、未进行真实采购验收。入口恢复沿用 #243 条件，拒绝时通过 entryRecovery=rejected;reason=<固定原因码> 区分页面身份、商品上下文、面板/支付区域、数量/摘要、标题、入口来源/文案、歧义、规则别名及可用性；不放宽条件，不新增点击。
+
+在规格面板识别出唯一完整精确候选且 available=false 时，立即返回既有 PURCHASE_SPEC_SAFE_TARGET_MISSING，提示目标颜色/尺码已售罄或当前不可选，未创建订单；已选中目标同样不能绕过不可用检查。只记录 dimension 和 exact_target_unavailable 固定结构证据，不记录规格原文或原始树。原有纵向与横向定位在此条件下本就停止，不能将本改动描述为修复“已识别售罄仍继续搜索”。未识别精确候选时继续既有有界搜索，不推断售罄，不替换规格；解析器、匹配规则、滚动预算、地址与下单流程不变。
+
+## 改地址返回后的动态提交按钮（#248）
+
+实现绑定 `c80c746`，Android 0.9.66 / versionCode 79；已通过 353 项 Android 单元测试并构建，尚未安装或进行真实采购验收。
+
+- 地址回读与最终提交按钮定位分开判断。旧“提交订单”“现在买，仅”“确认购买”识别继续优先；存在旧文案候选但歧义时不使用结构补充选择其中一个。地址确实缺失时保留既有有限恢复；地址及采购面板上下文已确认后，不因底部按钮文字变化而滚动规格列表。按钮缺失或不唯一使用 `PURCHASE_SUBMIT_TARGET_AMBIGUOUS` 提示按钮问题，不误报地址保存超时。
+- 结构补充只属于当前执行器中已完成地址修改后的返回流程，不能由其他页面或旧执行的地址证明启用。当前须为 PDD、地址后缀按既有规则回读唯一、地址入口唯一，并存在唯一数量输入或已选摘要；通过地址入口与该证据的最近共同祖先确定整个采购弹层，不把颜色/尺码滚动区域当成弹层。排除全屏大祖先、地址编辑、已知支付 Activity 及订单结果/支付页面，后续定位要求 Activity 与地址返回时一致。
+- 旧文案无候选时，只接受弹层底部固定区域内一个独立、可见启用、非滚动的可点击容器；不在规格滚动区内选择按钮，不取控件树末项，不使用固定屏幕点击坐标。文字与人民币金额子节点合并为一个按钮；支持如“复购价，”及非支付展示文字变化，但单独价格、多个操作按钮或支付/付款/地址/返回等非提交动作均不放行。
+- 地址返回检查、最终复核和提交共用目标定位。结构路径保留原文字节点为重新定位锚点，由已有无障碍点击重新查找其可点击父级；不新增下单手势兜底。最终复核成功后才允许该结构路径提交；提交前再次检查路径、类别、文字与边界，发生变化即停止；复核失败清除本地结构提交锚点。
+- 既有规格、数量、价格和地址复核，任务租约、服务端/本地不可逆边界及单次提交规则不变。结构识别不支持支付，不增加采购员操作、配置或审批；不改变 Admin、接口、数据库、规则 JSON、通用解析器及滑动执行器。原始控件树、整屏截图、地址全文和凭据不得落盘或上传。
+
+## 临时采集连续模式（#250）
+
+当前实现绑定 `37e8b56`，Agent 0.9.72 / versionCode 85。2026-09-09 用户批准 v5：按配置次数返回后切回 Agent，替代此前“识别并停留 PDD 首页”的方案；不保证 PDD 最终停在首页。代码、376 项 Android 单测及 Debug 构建通过，新版设置与完整真机闭环待验收。
+
+- 连续采集默认关闭，本机即时保存，失败恢复原值；开启后显示返回次数选择，1～5 次、默认 3，取消不改，写入失败恢复旧值。任务忙碌时开关和次数均禁用，选择提交时再次检查；无新增权限。只用于本次人工新建普通临时采集（source=agent_current_page、attemptNumber=1、无替换来源），Admin 下发、重试、替代与采购不参与。
+- 单任务执行开始固定返回次数。完整 completed、服务端提交确认且既有图片上传流程结束后，执行有限 Back，每次后等待 500ms；不要求识别商品/搜索/相机/首页，也不要求画面发生变化。图片上传仍沿用既有非致命行为，不因收尾更改结果。
+- 每次 Back 前检查前台仍为 PDD，读取页面后再次检查；离开 PDD 则停止余下 Back。次数完成、离开 PDD 或 Back 动作失败后，尝试打开 Agent 保持原 Tab，等待 500ms 并验证前台包名。动作失败不重试，不把请求启动成功直接当作切回成功。
+- 沿用风险页安全边界：登录/验证码/风控、地址编辑、订单详情或支付等证据时保留现场，不发送 Back 或强行切回；Activity 缺失、读取异常明确停止。以上例外不引入首页门禁。
+- 导航在原任务互斥和唤醒锁内完成，不变更租约/调度。返回失败只显示人工处理提示，不把成功采集改为失败或自动重采。
+- 失败、部分成功、提交未确认保留现场，不运行返回步骤，也不触发旧空闲返回倒计时。关闭开关保持原流程，采集间隔不变。
+- 不自动拍照、搜索或创建下一任务，不涉及采购/订单/付款；不使用深链、浏览器、OCR/VLM 或坐标兜底。
+
+## SYB 存疑规格候选核对（#251）
+
+实现绑定 `64b4205`，基线 main `fdd26af`；2026-09-09 代码与本地测试/构建通过，未部署、未重跑生产历史数据。
+
+- 原 Parse 的成功与失败行为不变，仅 uncertain 明细增加既有蝦皮规格候选核对。比较完整原文，沿用【备注】清理，允许全角逗号、逗号两侧空白及连续空白归一；颜色尺码可正序或倒序，使用逗号或空白分隔，只有唯一完整组合才改为 success。返回既有候选标签，不改写标签，不删除加号、不截断体重说明、不做近似匹配。
+- 单规格只有在候选确实仅包含该角色时通过；有两个角色时不能用单值补猜另一个角色。空/损坏候选、校验不通过、同角色多维、未知有值维度、多种组合或归一化碰撞，均保留原结果。候选必须已存在，不能用本次待确认输入生成候选再自我证明。
+- 同步入库 ApplyDetail、手动 Reparse 共用；成功核对不再次合并规格，因此不新增重复维度、不覆盖已有映射。人工确认仍优先，默认 Reparse 跳过人工与 AI 已确认值；原文保留。
+- #198 批处理原本先 Reparse，所以可直接复用本优化：能确定的不用调用 AI；仍不确定的按原 AI 流程处理。没有新增调度、调用额度或同步等待，不自动开启已有任务。
+- 不取消 uncertain/failed 状态，不改变采购可信度/可采购规则，不实现一键关联 PDD。部署后新同步或显式重新解析会使用新逻辑；本次没有执行生产批量更新。
+
+
+## 蝦皮详情匹配等待与回读（#254）
+
+实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。
+
+- AI 设置中的 timeoutSeconds=T 仍是单次 Provider 请求的上限。详情一键匹配的整次预算为 2T+10 秒，浏览器 POST 等待上限为 2T+20 秒；例如 T=60 时130/140秒，T=180时370/380秒。只保留现有一个 AI 设置入口，不新增时间配置框，也不自动改变管理员已保存的 T。
+- 超时上限不是固定等待。颜色/尺码串行执行且共用整次预算；正常部分匹配仍按原事务保存合格结果，AI异常在保存前返回时不提交本轮新映射。既有置信度、候选、人工确认映射保护和采购资格不变。
+- 前端超时、关闭或切换详情不代表后端已取消、未保存或已回滚；必须以回读结果为准，无法回读显示结果未确认，不自动重复匹配、不自动创建采购。
+- 单商品详情的成功/失败/超时/关闭重开都必须结束失效的等待状态；旧请求不得覆盖新商品或新操作。匹配进行期间本抽屉不能人工改映射，已有未保存草稿仍按原确认流程处理。
+- UI匹配提示的等待上限仅指POST，不含提交前GET及结果核对GET；结果核对也有限时，不能让失败提示再次陷入无限转圈。
+
+
+## SYB 行内一键关联最近采集（#253）
+
+实现绑定 `b1594dc`，2026-09-10；分支 feat/253-one-click-link，包含 #254 依赖。已完成合成数据测试及构建，未合并 main、未部署，不代表当前线上已具备此能力。
+
+- 未关联 PDD 且既有处理阶段提供“去关联”的 SYB 行可用一键关联；原人工入口不删除。首次点击选择采集手机后继续当前行，后续使用记忆手机；小箭头查看/切换手机，保存只修改全行共用偏好。取消不改变偏好、不执行关联。与批量采购设备选择互不影响。
+- 以所选手机的临时采集 source=agent_current_page 为范围，从 completed、completed_partial 中按 finished_at DESC、id DESC 取最新一条；失败/待执行/执行中不参与。最新为部分成功或商品停用、无可用规格时明确停止，不回退更旧商品，不切换其他手机。离线手机允许使用已有成功结果，停用或已删除手机需要重新选择。
+- 主动作开始冻结行、蝦皮商品和设备；服务端关联事务固定来源采集任务、PDD商品与规格版本。仅未关联时自动写入，已有或被其他操作改变的关联不覆盖。关联作用于蝦皮商品，因此共用该蝦皮档案的其他 SYB 明细也受影响；切换手机不会重绑已有商品，也不会改变在途操作。
+- 先保存关联，再复用现有颜色/尺码自动匹配及保存。有效已确认映射保留；普通部分匹配保存合格结果，AI故障不提交本轮新映射，但已保存关联保留。后续可从“去匹配”或详情人工继续。failed 且无人工/AI确认时不能自动跳过人工解析；uncertain 不统一拦截，仍以原采购准备规则为准。
+- 操作完成不保证立即可采购，必须刷新现有处理阶段；缺规格、缺映射、解析需确认或其他原资格不满足时继续显示真实待处理阶段。不自动创建采购任务、不下单、不支付。
+- 请求超时/网络中断只做有限回读，不重复提交；读回失败明确结果未确认，避免无限转圈。离开页面不代表后端停止或回滚。普通用户沿用现有采购员权限，无新管理员专属开关。
+
+## SYB 已关联商品的一键替换（#258）
+
+实现绑定 `2b01974`；部署与验收见 #258 发布证据。
+
+- 复用一键关联及小箭头的位置，保留原查看 PDD 商品。PDD 待采集、采集失败、停用或缺价格的对应处理阶段可替换；采集中、已创建/运行采购、成功或结果未知不开放。服务端提交时再次检查，不能只相信按钮。
+- 复用每用户/浏览器/API环境的手机偏好；首次选择继续当前行，小箭头仅切换偏好。预览仅选所选手机最新 completed/completed_partial 临时采集，部分成功或不可用不回退旧商品。确认后固定来源任务和目标，不改用新采集；来源状态、设备、目标规格或旧关联改变时拒绝。
+- 不同商品显示一次确认，包含旧/新商品、手机和共享蝦皮档案影响；取消不写入。同商品不弹替换确认且不重写关联，只继续匹配。共享该蝦皮档案的 SYB 明细使用新关联，历史采购任务快照不改。
+- 沿用既有更换关联和有效映射检查，再复用自动匹配保存。部分匹配、AI失败或解析需人工处理时保留已保存关联，显示真实处理阶段，不保证立即可采购、不自动创建采购。
+- 网络异常只有限回读，区分目标商品、仍为原商品和其他关联，不把“已有某个关联”误报为本次替换成功；不自动重发写请求。没有新增后台作业、订单或付款操作。
+
+## 辅助信息缺失的采集关联（#259）
+
+实现绑定 `e467706`，仅 Server；部署/验收见 #259。替代 #253/#258 中“部分完成一律拒绝”的限制，不改变 completed 原有路径。
+
+- completed_partial 的 missing 必须是非空合法列表且仅包含 salesText、shopName、reviewCount，才进入辅助信息兼容检查；title、规格/价格缺失、遍历截断、SKU数量上限及未知原因仍拒绝。
+- `shopeeproduct/partial_collection.go` 核对本次 task 的维度和值、可售SKU的完整标记/规格引用/非负价格、本次颜色价格，以及当前档案可选值由本次有效SKU覆盖，不能借旧档案合并残留的规格或价格通过。真实单维度允许，不虚构另一维度；本次明确报告缺少规格仍拒绝。
+- 一键关联、替换预览及确认提交共用验证。失败沿用409 LATEST_COLLECTION_UNAVAILABLE及现有提示，不回退更早采集、不换手机。状态 completed_partial 和 missing 原样保留；辅助字段缺失仍可在任务详情查看。
+- 无接口字段、数据库迁移、Android/Web或权限变更；普通人工关联与采购/AI资格不变。不将“允许关联”视为“已匹配或已采购”。
+
+## 采购单标题面板与地址就绪等待（#260、#261）
+
+实现绑定 #260 `3c1ffa4`（执行器回归测试 `7de4318`）、#261 `5ea07f1`，Android 0.9.74 / versionCode87，基于0.9.73。安装及真实采购验收以工单证据为准；不代表 main 的 Android 已整合这些分支。
+
+- 采购仅在安全规格入口点击返回SUCCESS后，记录本次页面包名/Activity作为内存上下文；开始新执行或页面身份改变时清除。`PddScreenParser` 的新增 purchaseEntryContext 默认关闭，仅该采购执行器传入；普通解析和采集原判定保留。
+- 当前仍为同一PDD Activity、商品ID非空、没有页面风险、没有选中摘要，且唯一有标题规格滚动区、一个维度有值，同时具有关闭、数量、支付展示区域与下单操作证据时，单标题可识别为NORMAL_SCROLLABLE。只是允许进入既有精确规格探测/选择，不执行下单或付款，不全局认可UNKNOWN，不增加入口重复点击或滑动。
+- 地址入口点击原有1000ms保留；地址列表等待增加唯一修改目标要求。点击修改和保存由500ms改为1000ms，其他通用动作间隔不变，无新配置项。
+- 修改后不再只见“详细地址”文字就立即写入。最多50次、每次间隔200ms读取（不含读取耗时），检查PDD页面风险；唯一可见启用有内容的详细地址EditText，连续两次路径、边界、内容及Activity相同才继续原输入流程。始终零个/多个或不稳定时失败，不取第一个候选。
+- 输入内容生成、输入后回读、保存后退出及返回规格面板、最终复核和单次下单边界不变。新增本机脱敏诊断 addressEditorCandidates / addressEditorPolls 两个整数，与task/attempt/device/ruleHash关联；不记录地址内容、原始树或整屏截图。
+- 仅Android；无Server/Web、共享API字段、数据库迁移或权限变化。真实采购、地址写入及订单创建不作为自动安装验证，不执行付款。
+
+### v2 商品入口补点与地址返回等待（#260、#261）
+
+2026-09-10 实现绑定 #260 `713111d`、#261 `d0a82f3`，Android 0.9.75 / versionCode88；真实采购效果以工单验收为准，非 main 合并声明。
+
+- 入口恢复不再把全页面支付方式展示文案单独视为支付页。当前包名/Activity、商品标题和安全入口必须与点击前一致，入口唯一且可用；已打开面板、关闭控件、数量、选中摘要、订单操作、风险/评价页面仍拒绝恢复。支付 Activity 或明确支付、订单、地址文本继续阻止补点。仅允许既有一次重新定位后的规格入口中心手势，随后仍验证面板，不循环、不扩展到地址保存或下单。
+- 保存地址后的确认读取、必要时一次返回后的确认读取，增加最多50次、间隔200ms的有界就绪检查，页面捕获耗时另计。连续两次同一Activity满足原地址回读与确认面板条件后继续；完整信息不要求滚动区域。已明确到地址列表时保留原返回路径，不等待列表出现下单按钮；返回后增加1000ms缓冲。
+- 就绪检查不修改原地址回读和结构下单入口规则；超时后只对既有识别的面板、唯一可用滚动区域执行原有有限滚动。零/多个区域仍失败，不凭地址入口或未知底部节点授权下单。最终精确规格、数量、价格、地址与单次下单边界不变。
+- 私有采购诊断新增布尔 savedAddressMatched、savedPanelMatched；整数 savedLegacySubmitCandidates、savedAddressCards、savedAddressTargets、savedScrollCandidates、savedConfirmationPolls。只记录标量并绑定task/attempt/device/ruleHash，不保存地址、原始树或整屏图。
+- CG109 v1现场读取未达到空闲状态，不能确认原失败具体缺哪项证据；v2覆盖迟到确认节点及可观测性，不将合成测试通过冒充真机修复验收。无Server/Web/API/迁移/权限变化，不需要服务器重启。
+
+## 探测到正式采购的单次面板交接（#262）
+
+2026-09-10 实现绑定 `2ea32fd`，Android0.9.76/code89；基于#260/#261，未声明合并main或真实采购验收通过。
+
+- AgentForegroundService通过PurchaseProbeHandoff只在成功spec_probe且结束后新快照仍识别PDD规格面板时保留一次性内存交接。仅taskId/goodsId/ruleHash/deviceId、Activity、前台revision和单调时钟时间，不保留控件节点、地址或选中状态，不落盘；有效期180秒。
+- 正式阶段消费时检查同任务/商品/规则/设备、前台revision及时间，消费后即清除。失配/超时/无任务或采集任务调度/结果异常/进程重启均不能沿用；普通手动再试不会继承已消费交接。现有服务端租约、互斥和匹配等待策略不变。
+- 有交接时，执行器恢复限定的purchaseEntryContext，最多10次、间隔200ms新读取（捕获耗时另计）；连续两次相同PDD Activity且具备既有商品/面板证据才跳过openProduct。空树可有限等待，其他应用/Activity改变/页面风险立即拒绝复用。没有交接时保留原一次判断路径；不把UNKNOWN当成功，不跳过正式精确规格/数量/价格/地址或下单验证。
+- 私有诊断新增handoffPresent、productReused布尔值，reusePolls整数及reuseReason固定枚举legacy_evidence/page_problem/page_changed/handoff_ready/evidence_timeout。仍绑定task/attempt/device/ruleHash，无敏感文本。
+- 无Server/Web、共享API或数据库变化，不需重启服务器。只有合成测试验证；原CG107/108日志证实两阶段，但未记录旧版重开判断，不把上下文丢失假设宣称为唯一现场根因。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting
-wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
-synchronized_at: 2026-09-04T11:30:16Z
+wiki_revision: 18744477bfd17f396e8c76ec7a2fcc6720acdf6f
+synchronized_at: 2026-09-11T09:10:00Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -85,3 +85,22 @@ sqlite3 -readonly agent-diagnostics.db "SELECT task_id,reason,color_row_count,co
 ```

 读取时记录设备、Agent 版本、任务号和规则快照；工单只回写查询得到的脱敏聚合数值。读取完成后删除本地导出副本。正式 APK 若不允许 `run-as`，停止排查并确认安全的只读诊断出口，不通过放宽应用安全配置或上传完整数据库绕过。
+
+## Android 采购规格入口本地诊断（#249）
+
+实现绑定 `99faf5a`，Agent `0.9.67`（versionCode 80）。单元测试与 Debug 构建已通过，新增版本真机留存/读取尚待验证；本节不属于上文既有实测结论。
+
+采购执行器启动后，在应用私有 `files/purchase_diagnostics/<taskId>_<attemptId>.jsonl` 保存白名单结构化入口诊断。元数据包含 taskId、attemptId、deviceId、agentVersion、phase、ruleHash（当前任务规则快照 SHA-256）、timestamp 和 elapsedMs。现有任务接口只有 attemptId，没有 attemptNumber；用 attemptId 对照服务端历史，不推算重试序号。
+
+证据仅包含入口来源枚举、候选数、点击结果/原因枚举、等待轮数、面板结构布尔值/计数，以及受控恢复是否执行及固定拒绝原因。没有商品标题、规格原文、地址、手机号、Cookie、Token、链接、原始控件树或截图。entryWaitMillis 是该等待循环累计的计划等待量；elapsedMs 才是自本次采购执行器诊断起点计量的实际耗时，timestamp 是后台写入时间。
+
+复用现有单线程诊断队列异步写入，写入/排队失败不改变采购结果；不新增点击、滑动、等待或采购门禁。最多保留最近 5 个 attempt 文件、每文件最后 128 条事件，超过 7 天的文件在服务启动或下次写入时清理。异常断电或存储故障仍可能丢失诊断，不能将日志缺失当成动作未执行；不上传 Admin，不增加服务端接口。
+
+仅对允许 run-as 的 Debug APK，在设备已连接且选定准确序列号后只读提取：
+
+```powershell
+adb -s <device-serial> shell run-as cn.ilapage.goauto.agent ls files/purchase_diagnostics
+adb -s <device-serial> exec-out run-as cn.ilapage.goauto.agent cat files/purchase_diagnostics/<taskId>_<attemptId>.jsonl
+```
+
+先列出文件，再读取本次任务/attempt 的准确文件名；不得扩大为导出所有应用数据或完整数据库。新版安装前的失败不会补生成日志；需要用户授权后重试才能产生新证据。Release 若禁止 run-as 则停止，不更改权限绕过；首版没有导出界面。该功能用于确定拒绝分支，并不代表已经修复对应采购故障。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Android-Agent-API-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.-
-wiki_revision: f3242938de4ac55c47f5c6eebd69184024e6a0ea
-synchronized_at: 2026-09-05T09:04:42Z
+wiki_revision: ba259178cf6514d5b48ea425005dfd366ba803a3
+synchronized_at: 2026-09-12T03:09:46Z
 <!-- gitea-wiki-mirror:end -->

 # MVP 共享 API 契约
@@ -75,9 +75,9 @@ POST /api/admin/v1/syb-products/reparse-batch
 PATCH /api/admin/v1/syb-products/{productId}/correction
 ```

-`import` 仅允许管理员调用。请求体提交 `dateFrom`、`dateTo` 后创建持久化后台任务并立即以 `202` 返回 `runId` 和 `status=running`；关闭弹窗、刷新或离开页面不影响任务。没有启用店铺时必须在读取凭据、登录、验证码 OCR 和任意 SYB 网络请求之前返回 `422`。任意时刻只能有一条 `running` 记录，内存锁与数据库唯一执行槽共同阻止单进程和跨进程重复导入；冲突时返回正在执行任务的日期范围。
+`import` 允许已认证的管理员（admin）和采购员（purchaser）调用（#236），仍须通过 Casbin 权限校验；其他角色返回 403。采购员的 POST 权限由既有启动权限对账写入，不需要新增数据库迁移。操作人取已认证 claims，不接受客户端冒名。请求体提交 `dateFrom`、`dateTo` 后创建持久化后台任务并立即以 `202` 返回 `runId` 和 `status=running`；关闭弹窗、刷新或离开页面不影响任务。没有启用店铺时必须在读取凭据、登录、验证码 OCR 和任意 SYB 网络请求之前返回 `422`。任意时刻只能有一条 `running` 记录，内存锁与数据库唯一执行槽共同阻止单进程和跨进程重复导入；冲突时返回正在执行任务的日期范围。

-`sync-runs` 列表支持 `page`、`pageSize`、`status`、`dateFrom`、`dateTo`，详情返回日期范围、状态（`running` / `succeeded` / `failed` / `interrupted`）、处理天数、货运单/明细/新增/覆盖数量、店铺准入与跳过数量、店铺筛选快照哈希、按店铺的 `accepted` / `skipped` 统计、操作人和起止时间。列表和详情对已登录角色只读开放。服务启动时遗留的 `running` 任务改为 `interrupted`；中途失败或中断已经写入的数据保留，重新导入仍按唯一键覆盖。
+`sync-runs` 列表支持 `page`、`pageSize`、`status`、`dateFrom`、`dateTo`，详情返回日期范围、状态（`running` / `succeeded` / `partial_success` / `failed` / `interrupted`）、处理天数、货运单/明细/新增/覆盖数量、店铺准入与跳过数量、店铺筛选快照哈希、按店铺的 `accepted` / `skipped` 统计、操作人和起止时间。列表和详情对已登录角色只读开放。服务启动时遗留的 `running` 任务改为 `interrupted`；中途失败或中断已经写入的数据保留，重新导入仍按唯一键覆盖。

 列表返回结构化字段（`orderCode`、`shopeeItemId`、`productTitle`、`targetColor`、`targetSize`、`quantity`、`unitPriceCent`、`imageUrl`、`parseStatus`、`parseNote`、`manuallyConfirmed`），不含原始 JSON；`keyword` 匹配订单号、虾皮商品ID 或商品标题，`parseStatus` 筛选 `success`/`uncertain`/`failed`。详情额外返回 `rawJson`（原始 `details[]` 元素，未做任何改写）。

@@ -100,6 +100,33 @@ POST   /api/admin/v1/syb-shops/discover

 `discover` 提交日期范围，从 SYB 真实货运单列表发现店铺，返回 `shopName` 和 `status`（`new` / `exists`）；发现只读，不自动新增。店铺比较固定执行首尾去空白、全角/半角统一和忽略大小写。同步先完成原始列表完整性校验，再按一次性启用店铺快照过滤；明细响应中的店铺名为空或不在快照内时不得写入。

+## 管理端：SYB 商品过滤（#269）
+
+```http
+GET    /api/admin/v1/syb-product-filters
+POST   /api/admin/v1/syb-product-filters
+PATCH  /api/admin/v1/syb-product-filters/{id}/enabled
+DELETE /api/admin/v1/syb-product-filters/{id}
+```
+
+同步时按 `variationSku` 决定明细是否入库。规则分两类，由 `kind` 区分：`char` 是结构判据
+（`-`、`#`），`keyword` 是关键词清单。列表支持 `kind`、`keyword` 和分页，返回 `keyword`、
+`normalizedKeyword`、`enabled`、`lastHitCount`、`lastHitAt`、`note`，`char` 另有
+`lastChangedBy`、`lastChangedAt`。
+
+`[必须]` 服务端必须拒绝对 `kind=char` 行的 `POST` 新增与 `DELETE` 删除，分别返回
+`FORBIDDEN`（`结构过滤不可新增` / `结构过滤不可删除`），不得只依赖前端隐藏按钮。
+`kind=char` 的 `PATCH enabled` 允许，并记录操作人与时间。
+
+`[必须]` `lastHitCount` 是每条规则各自的命中数，由同步结束时回写；未命中的规则写 0，
+从未同步过为 `null`。停用 `kind=char` 的二次确认提示条数必须取该行实时的 `lastHitCount`，
+不得写死——写死的数字在数据变化后会给出错误警告。
+
+关键词归一化与店铺一致：去首尾空白、全角/半角统一、忽略大小写；**不做简繁转换**，SYB 数据
+为繁体。唯一性按 (`kind`, `normalizedKeyword`) 判定，重复添加返回
+`SYB_PRODUCT_FILTER_DUPLICATE`。写操作由 go-admin/Casbin 仅授权管理员，其他角色只读。
+删除为软删除，不清理已经入库的商品明细。
+
 ## 管理端：采集规则

 ```http
@@ -472,7 +499,7 @@ POST /api/agent/v1/tasks/{taskId}/fail
 |---|---:|---:|---:|---:|
 | `openProduct` | 是 | 是 | 是 | 否 |
 | `verifyProduct` | 是 | 是 | 否 | 否 |
-| `openSpecPanel` | 是 | 是 | 是 | 否 |
+| `openSpecPanel` | 是 | 是 | 兼容读取、不执行（0.9.60+，见 #238） | 否 |
 | `selectSpec` | 是 | 是 | 是 | 否 |
 | `setQuantity` | 是 | 是 | 否 | 否 |
 | `verifyUnitPrice` | 是 | 是 | 否 | 否 |
@@ -486,7 +513,7 @@ POST /api/agent/v1/tasks/{taskId}/fail
 - 文字候选按控件文字或内容描述**精确匹配**；候选合并后必须唯一命中。点击动作只允许点击唯一文字节点或其最近的可点击父容器，不允许模糊匹配、猜测相近候选、改点兄弟节点。
 - 动作 `textAliases` 不能包含地址修改、创建/提交订单、订单号或支付相关文字，防止用安全 action 绕过危险动作类型和能力门禁。只读识别字段使用独立校验：允许订单和支付证据，仍拒绝修改地址、收货地址，并沿用各字段声明的数量、长度、去重和空白限制。
 - `waitAfterMs` 表示动作成功后的等待时间，范围为 0～30000 毫秒；省略时为 0。
- `swipeAfter` 表示动作成功后执行一个有限滑动计划。`direction` 只能为 `up` / `down` / `left` / `right`，`count` 为 1～10，`durationMs` 为 100～2000，`intervalMs` 为 0～5000 且省略时为 0。
+- `swipeAfter` 通常表示动作成功后执行一个有限滑动计划；Android 0.9.60+ 的 `openSpecPanel` 例外，只兼容读取而不执行预滑动（见 #238）。`direction` 只能为 `up` / `down` / `left` / `right`，`count` 为 1～10，`durationMs` 为 100～2000，`intervalMs` 为 0～5000 且省略时为 0。
 - 未在矩阵中授权的 action/参数组合、未知字段、空候选和越界值一律拒绝。`updateShippingAddress`、`createOrder`、`readOrderResult` 等正式动作在其独立高风险契约完成前不接受上述参数。
 - 旧的仅含 `actions[].type` 的规则继续有效：候选使用 Agent 内置语义，等待为 0，不执行动作后滑动。
 - 服务端保存创建任务时收到的完整原始规则快照；规则后来更新为规则 B，不会改变已有任务中的规则 A 快照。
@@ -556,7 +583,17 @@ Android #42/#36 使用本地 SQLite 保存恢复与重传所需的任务、attem
 创建订单前先在本地事务保存 `order_submit_started`、不可逆时间、稳定的 `orderSubmitRequestId` 和脱敏最终确认快照，再调用服务端同名接口；只有两侧标记完成并重新校验商品、规格、数量、单价、地址后缀、PDD 包/Activity 与唯一创建订单按钮后，才点击一次。重启时重放同一标记请求并只读核单；无法取得唯一未付款订单号和 PDD 下单时间时提交 `order_result_unknown`。支付文字仅用于识别未付款/离开支付页，永不点击。服务端数据库仍是最终事实来源；双方均不保存原始控件树、截图、PDD 凭据或完整收货地址。

 创建订单后若出现 Android 多微信应用选择器，只读核单器必须同时确认前台包为 `android` / `com.android.intentresolver`、Activity 为白名单 `ChooserActivity` / `ResolverActivity`、页面出现已知系统选择器标题且至少一个候选以“微信”开头，才允许执行一次系统返回；不得点击任何微信候选。若前台已经是精确微信包 `com.tencent.mm`，只读核单器不得点击、输入、登录、支付或强制停止微信，只允许执行一次无参数 PDD 启动 Intent 并等待既有 PDD 任务栈回到前台；`startActivity()` 成功只表示恢复请求已发起。请求后在固定最多 15 次、每次 200ms 的宽限期内允许微信或空窗口短暂残留，不执行点击、返回、输入或滑动；观察到 PDD 后结束宽限，宽限超时、已经观察到 PDD 后再次进入微信或出现稳定未知应用时返回未知结果。随后若前台为 PDD `com.xunmeng.pinduoduo.app_pay.core.PayActivity` 或当前页面出现支付动作文字，最多再返回一次。返回后只读解析唯一订单号和下单时间；选择器或支付页重复出现、白名单不成立、恢复动作重复、无法到达订单详情、结果不唯一或超时均返回未知结果，禁止再次点击创建订单、取消订单或支付。
-`order_result_unknown` 保持订单号和下单时间为空，但允许携带创建订单前已经严格验证的 `actualUnitPriceCent`。Agent 同时提交脱敏稳定失败阶段，服务端只接受白名单并按错误码写入固定提示，不信任或保存页面原文；阶段覆盖空窗口超时、选择器返回失败、微信恢复失败/超时、未知应用、支付页返回失败/重复、订单上下文缺失、订单号缺失/歧义、下单时间缺失/无效和待付款证据缺失。任务与 attempt 保存同一错误阶段，Admin 和 Agent 历史读取数据库最终事实；旧 Agent 未提交阶段时归一为 `PURCHASE_ORDER_RESULT_UNKNOWN`。
+Agent 主动提交 `order_result_unknown` 时保持订单号和下单时间为空，但允许携带创建订单前已经严格验证的 `actualUnitPriceCent`。Agent 同时提交脱敏稳定失败阶段，服务端只接受白名单错误码，并按错误码写入固定提示作为面向人的主文案；不采信 Agent 文本作为权威描述，也不保存原始控件树或截图。阶段覆盖空窗口超时、选择器返回失败、微信恢复失败/超时、未知应用、支付页返回失败/重复、订单上下文缺失、订单号缺失/歧义、下单时间缺失/无效和待付款证据缺失。任务与 attempt 保存同一错误阶段，Admin 和 Agent 历史读取数据库最终事实；旧 Agent 未提交阶段时归一为 `PURCHASE_ORDER_RESULT_UNKNOWN`。
+
+#271 修订：`errorMessage` 的语义由「仅固定提示」改为「**固定提示 + Agent 诊断证据**」。固定提示仍由错误码唯一决定并排在最前，Agent 提交的脱敏诊断追加在其后。
+
+`[必须]` 追加前压平为单行：去除控制字符与零宽不换行空格、连续空白合并为一个空格；按 `error_message` 列宽 1000 截断，且**固定提示优先完整保留**，被截断的证据以 `…` 结尾。证据与固定提示相同时不重复拼接。Agent 文本为空或错误码不在白名单时行为不变，仍返回 `INVALID_REQUEST`。
+
+改动原因：原做法丢弃了 Agent 已经算出并上报的诊断。`#210` 为 `PURCHASE_ORDER_PAYMENT_REPEATED` 计算 `paymentBackAttempts` 与 `consecutivePaymentSamplesAfterBack`，但 2026-09-07 至 09-11 线上 61 次该错误的 `error_message` 无一携带这两个值，导致「返回动作未生效」「页面渲染慢于容忍窗口」「页面已是订单页但关键词未命中」三种情形无法区分。相邻的 `failed` 结果分支本就原样保存 Agent 文本，因此本修订不引入新的信任假设。
+
+`[必须]` `failed` 结果分支同样把错误码与消息写入 attempt，不再只写任务。此前该路径产生的 attempt 行 `error_code` 为 NULL，按 attempt 统计失败时这些记录是隐形的。
+
+#241 追加：全局订单号唯一性校验在人工处理结果未知、取消及 lifecycle 保存路径返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`（HTTP 409、`retryable=false`），提示“订单号已属于任务 CG-任务ID”；批量回填继续使用原有 `PURCHASE_BACKFILL_ORDER_ALREADY_USED`。不可逆边界后的 `order_created` 结果回传为例外：发现该号已属于其他任务时成功受理结果，将 `order_submit_started` 降级为 `order_result_unknown`，不回滚或自动重派。冲突订单号不写入 `pdd_order_no`，而以“读到订单号 X，但该号已属于任务 CG-yy”保存到任务和 attempt 的 `error_message`，两者 `error_code` 均为 `PURCHASE_ORDER_NUMBER_ALREADY_USED`；保留下单时间、不可逆时间及实际单价。attempt 以 failed 结束并保留原始 `order_created` 结果类型、请求 ID 和摘要，重复提交按原幂等协议返回；任务释放租约和运行槽，进入既有人工处理结果未知通道，权限不变。

 | 错误码 | 普通提示 |
 |---|---|
@@ -867,3 +904,268 @@ X-GoAuto-Device-Recovery-Code: <one-time-code>
 Agent 携带既有 Token（可已失效）及恢复码重新调用注册接口。服务端必须同时校验同一 `installId`、未停用状态、恢复码摘要、未过期和未使用；成功后使用原 `deviceId` 写入新 Token 摘要并返回一次新 Token，清除恢复码摘要和有效期。旧 Token 与恢复码都立即失效，已分配的 pending 采集或采购任务保持原 `deviceId`，不创建替代设备记录。缺少或错误恢复码仍为 `DEVICE_INSTALL_ID_CONFLICT`；过期码为 `DEVICE_RECOVERY_EXPIRED`；停用设备为 `DEVICE_DISABLED`。

 自 #223 起，新建 SYB 任务在保持 `mappedColor` / `mappedSize` 为空和首趟 `spec_probe` 不变的同时，把创建时与目标规格对应的 confirmed 商品映射冻结为仅供服务端决策的指导快照。服务端收到当次候选后按角色验证该快照：只有规范化后唯一对应当次候选时才复用，并固化当次候选原文；否则该角色继续执行确定性匹配，仍未解决才把该角色及其封闭候选交给 AI。已解决角色不得重复发送给 AI，最终颜色和尺码仍须逐字属于各自当次候选。任务决策快照通过 `roleSources` 记录每个角色的 `manual_mapping` / `exact_match` / `ai_match` 来源；任务级 `specSource` 使用现有枚举汇总，不新增 Agent 决策权限。
+
+## 客户端 API 与管理员密钥管理（#237）
+
+实现基线 `71f7751`；以下接口已通过隔离测试；2026-09-07 本机 MySQL 迁移及管理员通过 HTTP 读取列表、模块目录已验证，真实密钥创建/编辑/停用及业务访问仍未联调，线上尚未部署。Android 接口不变。
+
+### 管理接口
+
+前缀 `/api/admin/v1/client-keys`，要求 Admin JWT 和 admin 角色，默认接受 HTTP/HTTPS，响应 `Cache-Control: no-store`。
+
+| 方法与相对路径 | 输入 | 成功 data |
+|---|---|---|
+| GET 空路径 | page，固定每页 20 | items、total、page、pageSize |
+| GET /modules | 无 | 模块数组：key、title、group、writable、actions |
+| POST 空路径 | name（1～80 字符）、grants | key 元数据与仅本次返回的 secret |
+| PATCH /:keyId/grants | version、grants | 更新后的元数据 |
+| POST /:keyId/disable | version | 停用后的元数据 |
+
+授权示例：`{"module":"pdd_products","write":false,"actions":[]}`；grants 为非空数组。元数据包括 id、name、prefix、enabled、version、grants、createdBy、updatedBy、createdAt、updatedAt、lastUsedAt，不返回摘要或完整密钥。管理请求只接受单个 JSON 对象、拒绝未知字段、最大 64 KiB。成功 code=200；无效输入 422、不存在 404、授权版本冲突或已停用 409。
+
+### 客户端访问与错误语义
+
+- 前缀 `/api/client/v1`，只接受 `Authorization: Bearer <客户端密钥>`，不接受 Cookie 或 URL 凭据，不与 JWT、Device Token 通用。
+- 根据用户 2026-09-07 的明确确认，管理与客户端接口在所有环境默认接受 HTTP/HTTPS，不设置协议开关，也不依赖 X-Forwarded-Proto 或 GOAUTO_TRUST_FORWARDED_PROTO。HTTP 明文传输密钥及业务数据，优先使用 HTTPS；不影响其他接口各自的协议要求。
+- 不再因 HTTP 返回 426；401 为缺失、无效或停用密钥；403 为模块/动作未授权；400 为查询参数携带凭据；503 为认证或审计暂不可用。业务错误沿用各既有接口。
+- 一般请求体最大 16 MiB；响应只支持有限 JSON（32 MiB），递归过滤凭据与原始载荷字段。不支持直接流式/二进制文件接口。响应不可序列化或超限时返回 502；业务可能已执行，必须先核对结果，不要自动重试。
+- 通过密钥认证的请求由服务端生成 `X-Client-Request-Id` 关联审计；它不是业务幂等键，原业务接口要求的 requestId 等字段仍须提供。允许请求必须先落审计意图；完成状态更新失败可留下 status=0。无效密钥没有 key_id 关联审计；拒绝授权的 403 审计为尽力记录。
+- GET `/ai-matching-settings` 只返回 `data.enabled`。POST `/ai-matching-settings/resolve` 接受 targetColor、targetSize、colors、sizes；每组最多 200 项，每个值最多 255 字符，总请求最大 64 KiB；确定性优先，必要时使用当前 Provider，返回 mappedColor、mappedSize、source；不保存映射、不创建任务，无法可靠匹配返回 422 安全提示。
+
+### 明确开放的接口清单
+
+下表路径均相对 `/api/client/v1`；普通业务请求字段沿用本文对应 Admin 业务契约。read=选中模块，write=模块读写，其他值均需 actions 逐项授权。没有列出的 Admin 接口不能用客户端密钥调用；新增 Admin 路由不会自动开放。
+
+| 方法 | 路径 | 模块键 | 能力 |
+|---|---|---|---|
+| POST | `/ai-matching-settings/resolve` | ai_matching | match |
+| GET | `/devices` | devices | read |
+| GET | `/pdd-products` | pdd_products | read |
+| GET | `/pdd-products/:productId` | pdd_products | read |
+| POST | `/pdd-products` | pdd_products | write |
+| PATCH | `/pdd-products/:productId` | pdd_products | write |
+| GET | `/shopee-products` | shopee_products | read |
+| GET | `/shopee-products/:productId` | shopee_products | read |
+| POST | `/shopee-products` | shopee_products | write |
+| PATCH | `/shopee-products/:productId` | shopee_products | write |
+| POST | `/shopee-products/:productId/link-pdd` | shopee_products | write |
+| POST | `/shopee-products/:productId/specs/values` | shopee_products | write |
+| PUT | `/shopee-products/:productId/specs/mapping` | shopee_products | write |
+| DELETE | `/shopee-products/:productId/specs/values` | shopee_products | delete |
+| DELETE | `/shopee-products/:productId/specs/mapping` | shopee_products | delete |
+| POST | `/shopee-products/batch-delete` | shopee_products | delete |
+| POST | `/shopee-products/:productId/specs/mapping/auto-match` | shopee_products | match |
+| POST | `/shopee-products/:productId/specs/mapping/confirm` | shopee_products | match |
+| GET | `/syb-products` | syb_products | read |
+| GET | `/syb-products/:productId` | syb_products | read |
+| PATCH | `/syb-products/:productId/correction` | syb_products | write |
+| POST | `/syb-products/:productId/reparse` | syb_products | reparse |
+| POST | `/syb-products/reparse-batch` | syb_products | reparse |
+| GET | `/syb-products/sync-runs` | syb_sync_runs | read |
+| GET | `/syb-products/sync-runs/:runId` | syb_sync_runs | read |
+| POST | `/syb-products/import` | syb_sync_runs | sync |
+| GET | `/syb-inner-codes` | syb_inner_codes | read |
+| GET | `/syb-inner-codes/:recordId` | syb_inner_codes | read |
+| GET | `/syb-inner-codes/match-jobs/:jobId` | syb_inner_codes | read |
+| GET | `/syb-inner-codes/apply-batches/:batchId` | syb_inner_codes | read |
+| POST | `/syb-inner-codes/rematch` | syb_inner_codes | match |
+| POST | `/syb-inner-codes/import` | syb_inner_codes | import |
+| POST | `/syb-inner-codes/batch-delete` | syb_inner_codes | delete |
+| POST | `/syb-inner-codes/apply-preview` | syb_inner_codes | writeback |
+| POST | `/syb-inner-codes/apply` | syb_inner_codes | writeback |
+| POST | `/syb-inner-codes/:recordId/recheck` | syb_inner_codes | match |
+| GET | `/syb-shops` | syb_shops | read |
+| POST | `/syb-shops` | syb_shops | write |
+| PATCH | `/syb-shops/:shopId/name` | syb_shops | write |
+| PATCH | `/syb-shops/:shopId/enabled` | syb_shops | write |
+| DELETE | `/syb-shops/:shopId` | syb_shops | delete |
+| GET | `/collection-rules` | collection_rules | read |
+| POST | `/collection-rules` | collection_rules | write |
+| PATCH | `/collection-rules/:ruleId` | collection_rules | write |
+| DELETE | `/collection-rules/:ruleId` | collection_rules | delete |
+| GET | `/purchase-rules` | purchase_rules | read |
+| GET | `/purchase-rules/current` | purchase_rules | read |
+| POST | `/purchase-rules` | purchase_rules | write |
+| PATCH | `/purchase-rules/:ruleId` | purchase_rules | write |
+| DELETE | `/purchase-rules/:ruleId` | purchase_rules | delete |
+| PUT | `/purchase-rules/current` | purchase_rules | activate |
+| GET | `/collection-tasks` | collection_tasks | read |
+| GET | `/collection-tasks/:taskId` | collection_tasks | read |
+| POST | `/collection-tasks` | collection_tasks | collect |
+| POST | `/collection-tasks/batch` | collection_tasks | collect |
+| POST | `/collection-tasks/:taskId/reset` | collection_tasks | collect |
+| DELETE | `/collection-tasks/:taskId` | collection_tasks | delete |
+| GET | `/purchase-tasks` | purchase_tasks | read |
+| GET | `/purchase-tasks/:taskId` | purchase_tasks | read |
+| POST | `/purchase-tasks/batch-preview` | purchase_tasks | purchase |
+| POST | `/purchase-tasks` | purchase_tasks | purchase |
+| POST | `/purchase-tasks/batch` | purchase_tasks | purchase |
+| POST | `/purchase-tasks/batch-retry` | purchase_tasks | purchase |
+| POST | `/purchase-tasks/stock` | purchase_tasks | purchase |
+| GET | `/ai-matching-settings` | ai_matching | read |
+
+### openSpecPanel 后置滑动兼容与诊断（#238）
+
+版本边界：Android 0.9.60 / versionCode 73，代码 `58a6c1c`。不修改 JSON schema、能力标识、任务接口或已有快照哈希。`openSpecPanel.swipeAfter` 仍按 direction/count/durationMs/intervalMs 原约束校验；解析成功后不执行该准备性滑动，`waitAfterMs` 保留。其他动作后置滑动沿用旧执行语义。旧 Server 可继续下发原快照；旧 APK 仍按原策略执行，不能将本契约描述当作旧设备已获得兼容。
+
+规格探测与精确选择自行负责按需有界滚动，原始候选、精确点击和选中复核不变。跳过预滑动不作为规格探测成功或订单创建证据。
+
+本地 `GoAutoPurchasePanel` 脱敏结构日志关联 task、attempt、device、rule（规则 SHA-256），不上传原始页面。新增事件：`postSwipe=skipped;action=openSpecPanel;reason=spec_panel_on_demand;panel=<枚举>`；其他必需滑动失败为 `postSwipe=failed;action=<动作枚举>;direction=<方向枚举>;swipeIndex=<本动作内第几次滑动>;reason=<固定分类>`。
+固定失败分类：unknown、root_unavailable、no_scrollable、invalid_bounds、gesture_unsupported、gesture_rejected、gesture_cancelled、gesture_timeout。日志不含规格值、节点文本、坐标、地址、订单、凭据、原始树或截图；结果错误码仍为 RULE_ACTION_FAILED，现有结果提交字段不变。
+
+## SYB 逐页保存与部分成功（#239）
+
+实现绑定 c6a962d；代码已实现不代表当前线上已部署。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。
+
+同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。
+
+`orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。
+
+Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。
+
+## Agent 采购订单批量回填（#241）
+
+本节为 #241 服务端实现契约，2026-09-08 按用户授权直接更新本地镜像；线上 Wiki 与其他长期文档由审核阶段同步。本节不表示已经部署或完成真机验收。
+
+`POST /api/agent/v1/purchase-tasks/order-backfill`
+
+使用 `Authorization: Bearer <Device Token>`，沿用 `RequireAgentHTTPS`、`GOAUTO_ALLOW_INSECURE_AGENT_HTTP` 与既有可信转发协议策略。无需 Admin JWT、claim、start 或 attempt。设备号只从认证读取，请求不得指定 deviceId、地址全文、收件人、手机号或原始控件树；未知 JSON 字段拒绝。此接口只记录已观察到的订单事实，不执行设备动作、创建订单或付款。
+
+请求示例（页面时间先按 Asia/Shanghai 理解，再以带时区 RFC3339/RFC3339Nano 发送）：
+
+```json
+{
+  "requestId": "5826cdda-dcd6-442e-90c3-9b75ba6fb8d8",
+  "items": [
+    {"addressSuffix": "_cg7", "pddOrderNo": "EXAMPLE-ORDER-7", "orderSubmittedAt": "2026-09-08T20:30:00+08:00"},
+    {"addressSuffix": "_cg72", "pddOrderNo": "EXAMPLE-ORDER-72"}
+  ]
+}
+```
+
+- requestId 必须为 UUID；items 为 1～50 条，保持输入顺序；请求体上限沿用 1 MiB。
+- addressSuffix 只接受 `AddressSuffix(id)` 生成的完整字符串。任务号为非零 uint64，拒绝前导零、正负号、空格、尾随文本、多个后缀与溢出；`_cg7` 与 `_cg72` 分别定位任务 7 和 72。
+- pddOrderNo 必填，最多 100 个 Unicode 字符，不接受首尾空白、换行或制表符，不自动裁剪后覆盖旧值。
+- orderSubmittedAt 缺失或 null 时回落任务 irreversible_at；空字符串、无时区文本及非法时间是条目错误，不触发回落。存储统一 UTC。页面值与 irreversible_at 都缺失时该条失败。
+
+有效批次返回 HTTP 200，包括全部条目失败的批次；每条独立事务，失败不撤销其他条目已提交的数据。响应包裹为 `data`，并设 `Cache-Control: no-store`：
+
+```json
+{
+  "data": {
+    "requestId": "5826cdda-dcd6-442e-90c3-9b75ba6fb8d8",
+    "items": [
+      {"index": 0, "taskId": 7, "result": "backfilled", "code": "BACKFILLED", "status": "order_created", "statusVersion": 5, "pddOrderNo": "EXAMPLE-ORDER-7", "orderSubmittedAt": "2026-09-08T12:30:00Z", "timeSource": "page", "retryable": false},
+      {"index": 1, "taskId": 72, "result": "backfilled", "code": "BACKFILLED", "status": "order_created", "statusVersion": 4, "pddOrderNo": "EXAMPLE-ORDER-72", "orderSubmittedAt": "2026-09-08T12:31:00Z", "timeSource": "irreversible_at", "retryable": false}
+    ]
+  }
+}
+```
+
+index 从 0 开始；后缀无法解析时不返回 taskId。result 为 `backfilled`、`already_backfilled`、`conflict` 或 `failed`。已认证设备所属任务可返回提交后的状态、版本、已保存订单号及时间；拒绝条目尽可能返回当前已提交事实。跨设备任务和不存在任务不返回这些业务字段，事务回滚后的内存值绝不作为最终事实返回。
+
+timeSource 说明已保存时间的来源：`page` 为页面值，`irreversible_at` 为估算回落，`existing_unknown` 为原先已创建的历史订单且没有可证明的来源。没有已保存时间时省略 timeSource。客户端必须保留估算标记，不得把回落值或 unknown 宣称为页面真实时间。重复回填不会用新页面时间自动校正旧时间。
+
+| 条目 code | result | 含义 |
+|---|---|---|
+| `BACKFILLED` | backfilled | 本条完成回填 |
+| `ALREADY_BACKFILLED` | already_backfilled | 正式任务已为 order_created 且订单号相同，无写入 |
+| `PURCHASE_BACKFILL_SUFFIX_INVALID` | failed | 非法、非规范、零、溢出或歧义后缀 |
+| `PURCHASE_TASK_NOT_FOUND` | failed | 任务不存在 |
+| `PURCHASE_BACKFILL_DEVICE_MISMATCH` | failed | 未绑定设备或不属于认证设备 |
+| `PURCHASE_STATE_CONFLICT` | failed | 非正式采购，或状态不允许回填 |
+| `PURCHASE_INVALID_REQUEST` | failed | 订单号非法 |
+| `PURCHASE_ORDER_TIME_INVALID` | failed | 提供的页面时间无效 |
+| `PURCHASE_ORDER_TIME_MISSING` | failed | 页面时间与 irreversible_at 均无有效值 |
+| `PURCHASE_BACKFILL_ORDER_CONFLICT` | conflict | 任务已有不同订单号 |
+| `PURCHASE_BACKFILL_BATCH_CONFLICT` | conflict | 同批同任务出现多个不同订单号，该任务所有条目均拒绝 |
+| `PURCHASE_BACKFILL_ORDER_ALREADY_USED` | conflict | 同一订单号已对应其他任务 |
+| `INTERNAL_ERROR` | failed | 数据库失败、死锁等，retryable=true，可安全重放 |
+
+批级 JSON/UUID/数量错误为 HTTP 422 `PURCHASE_INVALID_REQUEST`；鉴权、停用设备和 HTTPS 限制复用既有错误（401 `DEVICE_TOKEN_INVALID`、403 `DEVICE_DISABLED`、426 `HTTPS_REQUIRED`）。批级失败使用既有 `{code,message,retryable}` 包裹，未开始条目写入。
+
+### 状态、幂等与并发
+
+新服务在事务中锁定任务并检查来源状态，仅允许当前设备的 `live + order_result_unknown` 首次写入；`live + order_created` 只在订单号相同时返回已回填。其他状态（包括 running、failed、cancelled 与演练）均拒绝。复用 SetStatus 同步占用字段，同一事务递增 statusVersion、设置 statusChangedAt、清空主任务当前错误及租约；原始 attempt、规则快照、支付与物流、SYB 回写字段不变。
+
+requestId 沿用 UUID 约定，不增加批次表或全局幂等缓存。既有 unknown_resolve_request_id 槽存储 `backfill:<page|irreversible_at>:<由 requestId 和后缀派生的 UUID>`（最多 61 字符），用于任务级关联和保留本功能时间来源。相同任务和订单号即使更换 requestId 也无写入；同 requestId 改内容仍重新执行设备、状态和订单冲突检查，不凭 requestId 直接放行。批内不同任务提交同一订单号时，先成功提交者占用，其余条目返回订单已被使用；已存在的历史重复订单号不自动修复。
+
+订单号尚无唯一索引，本实现不迁移数据库。共享模型保存钩子复用 `purchase_rule_setting.id=1` 行作短事务互斥锁，再以锁定读检查订单号归属，覆盖回填、原人工解除和旧结果提交路径；单例缺失时拒绝写入，数据库死锁时回滚失败事务。原 ResolveUnknown 与 Admin 鉴权代码保持不变。禁止通过跳过模型钩子的直接 SQL 写入宣称具备此保证。
+
+新回填路径禁用包含绑定参数的 SQL 日志，不记录请求正文、订单号、地址或原始树；任务号和认证设备号沿既有任务关联不可变 ruleSnapshot。此接口未新增日志载荷或任务/attempt。
+
+本地测试覆盖事务回滚、并发服务调用和旧写入路径，使用 SQLite；MySQL 8.4 多连接/多进程的实际行锁、生产数据和真机端到端回填尚待环境验收，不以单元测试替代。
+
+
+## 蝦皮详情匹配等待与回读（#254）
+
+实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。
+
+本节是 Admin 蝦皮详情接口补充，不修改 Android 请求或采购协议。
+
+- `GET /api/admin/v1/shopee-products/:productId` 的 `data` 增加 `autoMatchTimeoutSeconds` 整数，为后端详情一键匹配整次预算 `2 × AI timeoutSeconds + 10`，配置范围3～600对应16～1210秒。它是非敏感派生预算，沿用商品详情读取权限；不是开放 AI 管理配置读取，响应不包含 Key、Provider、BaseURL 或 Model。现有客户端路由若复用本 Handler 同样仅获得这个数字。
+- `POST /api/admin/v1/shopee-products/:productId/specs/mapping/auto-match` 请求字段、业务权限、版本核对与响应映射语义不变。服务端按收到请求时的 AI 配置确定整次父预算，读取配置耗时扣除；Provider 请求仍受自身超时及父 context 剩余时间中更短者约束。
+- Admin 点击前先GET新详情取得预算，POST timeout=(autoMatchTimeoutSeconds+10)×1000毫秒；缺字段、非整数或超范围时明确拒绝开始匹配，不猜配置。前后端需配套升级。
+- 准备后配置可能变化，浏览器仍可能先超时；不要据超时响应断言事务是否提交。POST失败/断连/超时只执行有限GET回读，不自动重发POST；失败回读显示结果未知。回读结果表示当前已保存状态，不保证这次请求已经永久不再写入，也不保证全部项目都匹配成功。
+- 普通GET默认10秒；本轮未修改建议接口610秒、其他AI功能或后台批量匹配600秒预算。T=60时130/140秒、T=180时370/380秒。
+
+
+## SYB 行内一键关联最近采集（#253）
+
+实现绑定 `b1594dc`，2026-09-10；分支 feat/253-one-click-link，包含 #254 依赖。已完成合成数据测试及构建，未合并 main、未部署，不代表当前线上已具备此能力。
+
+本节仅补充 Admin API；Android 和客户端密钥旧请求不变。
+
+`POST /api/admin/v1/shopee-products/{productId}/link-pdd` 新增与非零 pddProductId 互斥的可选模式：
+
+```json
+{"requestId":"UUID","latestCollection":{"sybProductId":1,"deviceId":2,"specContextVersion":"详情返回的未关联版本"}}
+```
+
+- 校验当前 SYB→Shopee、未关联、规格版本和设备存在/未停用；离线可用。短事务选择最新已结束成功或部分成功的临时采集，排序 finished_at DESC、id DESC；部分成功不跳过回退旧记录。只接受 completed、存在 finishedAt/PDD、PDD active 且存在可选颜色或尺码。
+- 成功返回原 `product`，及 `collectionSource: {taskId, deviceId, pddProductId, requiresSpecConfirmation}`。product.specContextVersion 是此次事务写入后的冻结版本；requiresSpecConfirmation 对应 failed 且没有人工或AI确认，完整资格仍由现有 batch-preview 派生。不得把后续其他人的商品版本当作本次自动匹配上下文。
+- 409 `PDD_LINK_CONFLICT` 表示已有关联；409 `LATEST_COLLECTION_UNAVAILABLE` 表示设备/最近采集/候选不可用；409 `SPEC_CONTEXT_VERSION_STALE` 沿用现有语义。非法参数422。重复请求不会覆盖已有关联，成功响应丢失后重发也会冲突，客户端应回读而非自动重试。last_update_request_id 保留本次请求标识；不承诺额外持久化完整重放响应。
+- `/api/client/v1/.../link-pdd` 带 latestCollection 时返回403 FORBIDDEN，不扩大API Key授权模块；原手动 pddProductId 模式行为不变。
+- Web 先GET详情及 #254 autoMatchTimeoutSeconds，再提交关联；关联响应中的冻结版本交给现有 auto-match。其匹配仍自动保存，无额外“保存修改”写请求。普通请求/回读每次10秒，auto-match 单独使用派生前端预算2T+20秒；业务拒绝直接提示，网络/匹配失败至多一次详情回读，再刷新准备状态，禁止自动POST重试。
+- Server/Web 需配套更新并包含 #254；无需迁移/Android升级。现有人工关联、匹配阈值、规格/采购资格、任务与支付边界不变。
+
+## Admin 一键替换最近采集候选（#258）
+
+实现绑定 `2b01974`；仅补充 Admin，Android/API Key 不变。沿用 `POST /api/admin/v1/shopee-products/{productId}/link-pdd` 和原权限，不新增路由或迁移。
+
+先请求只读预览（仍需 UUID requestId）：
+
+```json
+{"requestId":"UUID","latestCollection":{"sybProductId":1,"deviceId":2,"specContextVersion":"当前详情版本","replacement":{"preview":true,"expectedPddProductId":3}}}
+```
+
+响应 `product` 保持原关联，`collectionSource` 返回 taskId、deviceId、pddProductId、requiresSpecConfirmation，并增加 targetVersion、title、goodsId、previousTitle、previousGoodsId、deviceName。预览没有关联写入。
+
+确认提交沿用同一 SYB/设备/详情版本与原商品ID，replacement 改为：
+
+```json
+{"preview":false,"expectedPddProductId":3,"taskId":4,"targetPddProductId":5,"targetVersion":"预览返回值"}
+```
+
+- 提交按指定 taskId 核对临时采集来源、设备、completed/finishedAt、目标ID、可用规格及 targetVersion；不重新选择最新任务。旧关联、旧/目标规格版本变更返回现有409上下文冲突；阶段不再允许返回409 PDD_LINK_CONFLICT；来源不可用409 LATEST_COLLECTION_UNAVAILABLE；缺字段422。
+- 不同商品条件更新旧关联，返回更新后的 product.specContextVersion；同商品不更新关联及 last_update_request_id，但仍返回用于后续匹配的当前版本。请求不是持久化重放协议；客户端超时只回读、不自动重发。
+- 预览与提交都校验当前允许阶段；采集中拒绝。复用现有人工更换关联的映射语义，后续 auto-match 自动保存及预算沿用 #254。部分匹配/AI故障不回滚已提交关联。
+- 不提供 replacement 时 #253 行为不变；`/api/client/v1` 携带 latestCollection（包括 replacement）仍403，不扩大客户端密钥授权。
+
+## 辅助信息缺失的采集关联（#259）
+
+实现绑定 `e467706`，仅 Server；部署/验收见 #259。替代 #253/#258 中“部分完成一律拒绝”的限制，不改变 completed 原有路径。
+
+- completed_partial 的 missing 必须是非空合法列表且仅包含 salesText、shopName、reviewCount，才进入辅助信息兼容检查；title、规格/价格缺失、遍历截断、SKU数量上限及未知原因仍拒绝。
+- `shopeeproduct/partial_collection.go` 核对本次 task 的维度和值、可售SKU的完整标记/规格引用/非负价格、本次颜色价格，以及当前档案可选值由本次有效SKU覆盖，不能借旧档案合并残留的规格或价格通过。真实单维度允许，不虚构另一维度；本次明确报告缺少规格仍拒绝。
+- 一键关联、替换预览及确认提交共用验证。失败沿用409 LATEST_COLLECTION_UNAVAILABLE及现有提示，不回退更早采集、不换手机。状态 completed_partial 和 missing 原样保留；辅助字段缺失仍可在任务详情查看。
+- 无接口字段、数据库迁移、Android/Web或权限变更；普通人工关联与采购/AI资格不变。不将“允许关联”视为“已匹配或已采购”。
+
+## 采购规格现场一次重新匹配（#263）
+
+2026-09-11 实现绑定 `c6ee6c0`，Server采购与Android Agent；未发布、未安装、未完成真实采购验收。
+
+- 正式采购阶段仅在服务端下发 `specRematchAllowed=true`、Android 返回稳定的 `PURCHASE_SPEC_TARGET_NOT_VISIBLE` 且尚未进入地址/下单阶段时触发；颜色/尺码选中复核失败、售罄、点击失败、歧义、价格、地址和订单错误不触发。
+- Agent 在当前PDD规格面板重新读取候选并提交同一采购任务的 `spec_rematch_completed` 结果；Server复用现有确定性优先/必要时AI匹配，结果必须属于当次候选。匹配成功后同task重新领取正式attempt，Agent沿用当前页面继续正式规格、数量、价格、地址和下单校验，不新建任务、不重新打开浏览器链接；页面证据失效时仍按原安全路径处理。
+- 每个采购任务最多一次；结果attempt和服务端状态原子记录，旧决策指针清除后只允许最新attempt固化新决策。重复请求、无资格、已有不可逆证据或旧attempt覆盖均拒绝；不新增数据库列，依赖现有attempt result_type审计。
+- 新共享字段 `specRematchAllowed` 和结果类型仅供现有Agent采购接口；旧Agent缺省false，旧 `spec_probe_completed` 重复探测拒绝规则不变。未改变设备租约、并发、支付禁止和任务重试语义。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: SYB-ERP-Interface-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/SYB-ERP-Interface-Contract.-
-wiki_revision: df0fe874c7f3f3e9c031f2f793f8f6a0511ace25
-synchronized_at: 2026-09-07T06:25:27Z
+wiki_revision: f1792b7fe35925480c25b890e85fa5e551744812
+synchronized_at: 2026-09-11T09:11:21Z
 <!-- gitea-wiki-mirror:end -->

 # 12 顺云宝（SYB）ERP 接口契约
@@ -220,25 +220,19 @@ Admin 默认 `max_matches = 10000`，可以在配置中调整；上限针对整
 有限重试：单次 HTTP 总超时 60 秒，最多执行 3 次，重试前分别等待 1 秒、2 秒，等待须
 响应 context 取消。HTTP 401/403、明确会话失效、业务失败、接口数据完整性错误和本地
 校验失败不得重试；登录、验证码、单件码写入和任何回填请求也不得使用该机制。重试
-耗尽后返回最后一次错误，外层继续保留日期、页码和已获取数量上下文并将同步标为失败。
+耗尽后返回最后一次错误，外层保留日期、页码和已获取数量上下文，按最终已保存成果将同步标为失败或部分成功。

-今天的货运单会在同步期间持续新增。只有 UTC+8 下的今天发生上述快照漂移时，
-允许只重试今天的列表分页，最多 3 次；已经完成的历史日期不得重复拉取，每次尝试
-也必须使用独立 ID 集合。第三次仍不稳定时，可以对最后一次取得的合法唯一 ID
-读取完整明细并按既有 upsert 保存，但本次同步仍记为失败、明确提示当天未形成
-稳定快照且不推进游标，下一次继续覆盖今天。任何尝试都不得突破 `max_matches`；
-网络/业务错误、非法 ID 或不完整明细不属于可放宽的快照漂移。
-`[必须，#235]` 当天跨页重复 ID 纳入上述最多 3 次列表快照尝试（含首次），
-不增加另一层重试次数。发现跨页重复后丢弃本次列表，从预检总数和第一页重新开始，
-使用全新 ID 集合；最后一次仍重复时直接失败，不得去重后按成功或降级数据保存。
-已经完成的历史日期保持其已有结果，不重复拉取；历史日期重复不适用此恢复。
-每页先检查非法 ID 和页内重复，再检查跨页重叠；同页同时存在页内重复和跨页重叠时
-仍作为硬错误停止。原有总数漂移/短页的合法唯一列表降级保存条件保持不变。
-重复诊断只记录日期、当天尝试序号、首次/当前页码与行号、start、pageSize、
-expectedTotal 和已获取唯一数量，不记录真实重复 ID、原始响应或个人数据。
+自 #239（实现提交 c6a962d，已于 2026-09-08 随 d403f3b 部署线上）起，改为按页验证和保存：每页先验证条数、合法 ID、页内/跨页重复，再按冻结店铺快照获取并验证全部明细；外部请求完成后才开启页事务。页内任一入库失败回滚整页，已提交的前页保留，计数在事务提交后累计。
+
+当天和历史日期统一处理：分页/明细失败或最终总数漂移时停止该日期并继续后续日期，不在同次运行中重新扫描当天，以避免重复写入和计数。数据库故障、进度持久化失败、明确会话失效、上下文取消或总任务超时停止整个范围。下一次人工或定时同步重新扫描日期，按 (order_code, detail_id) 幂等覆盖并保留人工确认。跨页重复不去重后冒充完整数据；最终日期完整性校验仍覆盖所有店铺。此流程替代此前 #235 的当天三次整日快照重扫。
+
+重复诊断只记录日期、首次/当前页码和行号、start、pageSize、expectedTotal、已获取唯一数量，不记录真实重复 ID、原始响应或个人数据。

 ### 4.4 统一日期范围同步与覆盖游标

+GoAuto 同步记录页的立即同步允许管理员和采购员（purchaser）使用（#236），固定覆盖昨天和今天；其他已登录角色仅可查看记录。复用既有同步互斥、日期校验、启用店铺筛选及操作人审计，不授予店铺配置、凭据或定时任务管理权限。权限代码发布并完成启动对账后生效。
+
+
 页面只有一个同步入口，操作员确认工具条上的开始日和结束日后发起。首次打开页面
 固定默认昨天到今天，不因 `last_synced_at` 更早而自动扩大范围；需要补历史缺口时
 由操作员明确选择日期，单次仍不得超过 31 天。
@@ -255,7 +249,7 @@ expectedTotal 和已获取唯一数量，不记录真实重复 ID、原始响应
 或超过 `max_matches` 时不推进游标。

 `[必须]` 每批明细响应必须与请求的货运单 ID 一一对应。缺失、重复、出现未请求
-ID，或某张货运单返回空商品明细，都视为不完整并停止同步；已经写入的幂等数据
+ID，或某张货运单返回空商品明细，都视为不完整并停止当前日期，继续后续日期；已经写入的幂等数据
 可以保留，但只有所有日期全部成功才推进游标。

 `[必须]` 登录和验证码只是同步前置步骤。日期范围经过自动 OCR 降级、手工
@@ -497,9 +491,30 @@ POST /am/stock/detail/updateDetailCode?t=0&id={stockID}&detailId={detailID}&code
 > 以下「店铺准入」已由 GoAuto #49 采纳并实现；店铺规范化还包括全角/半角统一和忽略大小写。

 `[必须]` **同步先校验原始全量，再做店铺准入。** 顺序固定为：按日期查询原始总数
-并执行单次容量熔断 → 拉完当天原始列表并核对分页前后总数、页长和唯一 ID → 按
+并执行单次容量熔断 → 逐页核对页长和唯一 ID，整日结束复核总数 → 按
 `shopName` 去除首尾空白后与启用店铺精确匹配 → 只为接受的货运单请求明细和入库。
-不能先过滤再做完整性校验，否则非目标店铺的分页漂移会被掩盖。
+店铺过滤只决定明细获取和入库，不能减少原始列表完整性校验范围；已保存不代表整日完整。
+
+`[必须]` **店铺准入之后再按 `variationSku` 过滤商品（#269）。** 顺序固定为：店铺准入 →
+结构过滤 → 关键词过滤 → 入库。两类规则都存在 `syb_product_filter`，由 `kind` 区分：
+
+- `kind=char`：`-` 和 `#` 两条，命中任意一条即跳过（**OR，不是 AND**）。这两个字符是
+  「档口-供应商#货号」编码格式的判据。2026-09-11 核验线上 13010 行明细：含 `#` 8498 行、
+  含 `-` 6392 行、两者都含 6386 行、任一 8504 行（65%）。用 AND 只命中 6386 行，会漏掉
+  `DD#004`、`300斤牛奶絲圓領#A057` 这类只含 `#` 的 2118 行。
+- `kind=keyword`：关键词清单，匹配 `variationSku`，**不匹配 `productTitle`**。同一次核验
+  中六条初始关键词在 `productTitle` 上命中为 0，且全部已被结构过滤覆盖，净增为 0；保留它
+  是为档口改用不含 `#` 的编码时兜底。
+
+`[必须]` 空 `variationSku` **不过滤**。核验时 2724 行（21%）为空，分布在正常启用店铺且持续
+产生，属于尚未填写供应商编码的正常商品，不是档口货。
+
+`[必须]` 两类命中数分别统计并分别回写到每条规则自己的 `last_hit_count`，不得合并成单一
+「过滤总数」，也不得按 `kind` 写同一个汇总值。前者会使结构判据失效不可观测（关键词净增为 0
+时无法区分「没漏网」和「规则没生效」）；后者会让停用确认对 `#` 和 `-` 提示同一个数字。
+
+`[必须]` `kind=char` 不可新增、不可删除，只能停用，且停用需要二次确认并记录操作人与时间。
+判据本身需要变更（例如档口改用 `/` 或 `@`）属于范围变化，应另建工单评估。

 `[必须]` 同步开始时只读取一次启用店铺，整次运行使用同一个快照。列表允许但明细
 响应中的 `shopName` 变为空或非允许店铺时再次拦截。没有启用店铺时在会话/OCR/
@@ -654,3 +669,13 @@ settings:
 - 客户端实现：`server/app/goauto/sybclient/`
 - 落库与解析：`server/app/goauto/sybimport/`
 - 相关工单：[#48 客户端移植](https://git.ilapage.cn/OPC/goauto/issues/48)、[#41 SYB 货运单商品导入](https://git.ilapage.cn/OPC/goauto/issues/41)、[#37 物流调度与货运宝回填](https://git.ilapage.cn/OPC/goauto/issues/37)
+
+## SYB 逐页保存与部分成功（#239）
+
+实现绑定 c6a962d；2026-09-08 已随 d403f3b 部署线上，未手动触发真实同步验收；#240 上游尾页超时尚未修复。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。
+
+同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。
+
+`orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。
+
+Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Deployment-and-Operations
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.-
-wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
-synchronized_at: 2026-09-04T11:30:08Z
+wiki_revision: 933eaf6cc02fed843a6898269fdb5f6848ac2a8a
+synchronized_at: 2026-09-10T01:42:05Z
 <!-- gitea-wiki-mirror:end -->

 # 部署与运维
@@ -41,7 +41,7 @@ GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true

 ### API 长请求超时约束

-Admin 蝦皮规格 AI 匹配会同步等待外部 Provider：Provider 配置允许 3～600 秒，复合的一键匹配共享 600 秒总预算，Admin 客户端等待 610 秒。因此服务端 `settings.application.writetimeout` 必须至少为 620 秒，受版本管理的标准配置固定为 `620`；启动时低于该值必须明确失败，禁止以 2 秒等短写超时运行，否则连接会在领域错误返回前被截断并表现为代理 502。反向代理的读/发送超时也必须大于服务端窗口。
+Admin 蝦皮规格 AI 匹配会同步等待外部 Provider：Provider 配置允许 3～600 秒，旧版详情复合一键匹配共享600秒总预算，旧Admin客户端等待610秒；#254未部署前仍适用，部署后详情入口改用下节动态预算。因此服务端 `settings.application.writetimeout` 必须至少为 620 秒，受版本管理的标准配置固定为 `620`；启动时低于该值必须明确失败，禁止以 2 秒等短写超时运行，否则连接会在领域错误返回前被截断并表现为代理 502。反向代理的读/发送超时也必须大于服务端窗口。

 Provider 故障日志只允许记录调用关联 ID、操作类型、耗时、上游 HTTP 状态码或网络错误分类；不得记录 API Key、Authorization、Provider URL、模型输入、候选规格、商品原始内容或响应正文。Provider 失败时接口返回 HTTP 503 与 `AI_MATCHING_UNAVAILABLE`，供 Admin 显示安全中文提示。

@@ -70,3 +70,37 @@ Provider 故障日志只允许记录调用关联 ID、操作类型、耗时、
 - 服务启动会将上次进程遗留的 `running` 执行记录标记为 `interrupted`。该恢复依赖当前线上每个数据库只运行一个调度器实例；扩展为多调度器前必须另建工单引入实例租约，不能直接复用此判断。
 - 排错从 Admin 定时任务页单选任务后进入“日志”，按状态和开始时间查询。记录只含稳定错误码和脱敏摘要；需要定位细节时查看受控服务日志，不得把任务参数、Provider 配置/响应、密钥或业务原始数据复制进执行历史。
 - 当前没有执行历史删除接口和自动保留策略；删除定时任务不删除历史。数据库容量治理需要另建工单评估。#198 的 `GoAutoSYBSpecAIParse` 在 #199 发布和迁移后仍保持关闭，启用必须由管理员另行确认。
+
+## 客户端密钥部署与验证（#237）
+
+实现基线 `71f7751`；2026-09-07 已按用户授权完成本机 MySQL 迁移、管理员菜单写入和 Server/Web 构建重启；管理页面 HTTP 列表与模块加载已验证。2026-09-08 经用户授权，线上已发布 Server/Web 基线 `d403f3b`，执行迁移 `1788798000000` 并重启 GoAuto/Nginx；迁移记录、两张密钥表、仅管理员菜单关联已回读。HTTP 页面与健康检查通过；未登录管理请求 HTTP 200、业务码 401。真实密钥创建及客户端业务读写闭环尚未验证。
+
+- 发布前须单独授权追加迁移 `server/cmd/migrate/migration/version-local/1788798000000_client_api_key.go`，按既有迁移流程创建 client_api_key、client_api_key_audit 和“采采管理/客户端密钥”管理员菜单。前置父菜单必须存在；不应以赋予普通用户管理员角色代替迁移或权限核验。
+- 用户于 2026-09-07 明确确认默认兼容 HTTP/HTTPS、不设开关并接受明文风险；部署本版本并执行迁移后，现有 `http://185.216.248.75:9527` 可以使用客户端密钥管理及客户端 API。2026-09-08 线上部署及未登录拒绝检查已通过，真实密钥读写验收仍待进行。HTTP 会明文传输密钥和业务数据，仍建议使用 HTTPS。
+- 客户端密钥功能不依赖 GOAUTO_TRUST_FORWARDED_PROTO、X-Forwarded-Proto 或 Agent HTTP 例外。既有其他路由的协议和代理配置保持不变；不伪造协议头，不新增明文放行开关。
+- 代理、APM、应用日志均不得记录 Authorization、创建响应 secret 或原始业务载荷。应用对两类客户端密钥路由跳过旧请求/响应正文日志，使用专用元数据审计；实际代理日志脱敏仍须部署验收。
+- 请求审计 status=0 可能表示在途、进程中断或结果审计更新失败；先按请求关联号核对业务结果，不自动重试采购、采集、同步等操作。停用阻止后续认证，不保证取消已开始的业务操作。
+- 隔离验证：Server `go test ./app/goauto/clientkey ./app/goauto/clientapi ./cmd/migrate/migration/version-local`；Web `pnpm exec jest tests/unit/client-keys.spec.js --runInBand` 与 `pnpm run build:prod`。浏览器模拟入口 `/tests/fixtures/client-keys.html` 仅由本地 Vite 开发服务承载，使用内存模拟请求和无效示例密钥，不连接真实数据库，不证明线上鉴权已验收。
+- 真实部署验收须另行验证实际 HTTP/HTTPS 入口、管理员创建/编辑/停用、普通用户拒绝、读写/独立动作隔离、停用后的后续请求拒绝及日志无密钥；任何真实业务执行继续按独立授权范围进行。
+
+
+## Windows 本机运行目录与 #237 迁移验证（2026-09-07）
+
+- Supervisor 实际配置 `D:/supervisor/programs/goauto.conf`；程序仅 `goauto-admin-api` 和 `goauto-admin-ui`。从已有干净工作区 `D:/OPC/goauto-worktrees/main-runtime` 的 main 分支运行；源码运行基线 `ac3c63e`，版本化启动模板更新提交 `9a10d82`。
+- 原目录 `D:/OPC/goauto` 的用户改动保持原样；本机敏感配置继续读取 `D:/OPC/goauto/config.yaml`，不复制凭据到运行工作区或版本库。数据库 `127.0.0.1:3307/goauto`，API `http://127.0.0.1:8010`，Web `http://127.0.0.1:9527`。
+- API 命令：`pwsh.exe -NoLogo -NoProfile -File "D:/OPC/goauto-worktrees/main-runtime/scripts/start-server.ps1" -ConfigPath "D:/OPC/goauto/config.yaml" -SkipMigration`；Web 同目录 `scripts/start-web.ps1` 与相同 ConfigPath。已验证无需 ExecutionPolicy Bypass。
+- 真实迁移必须单独授权并先确认唯一待执行版本；常驻 API 加 `-SkipMigration`，日常重启不自动执行未来待审核迁移。#237 迁移 `1788798000000_client_api_key.go` 已执行，sys_migration 记录 `1788798000000`、两张密钥表及管理员菜单已回读；其他角色未新增菜单关联。任务启停状态未改。
+- 范围明确的服务控制：`D:/supervisor/supervisord.exe -c D:/supervisor/supervisord.conf ctl status goauto-admin-api goauto-admin-ui`，启动/停止/重启将 status 分别替换为 start/stop/restart。不得为了 GoAuto 重启整个 Supervisor 或其他项目。配置内容变化后需重新读取配置；本次调用 `supervisor.reloadConfig`，再对上述两个程序定向 start，已通过进程命令行核对新目录。
+- 日志：`D:/supervisor/logs/goauto-admin-api.log`、`D:/supervisor/logs/goauto-admin-ui.log`；对外分享只能保留脱敏结构摘要。迁移输出不得暴露凭据或业务原文。
+- 管理员刷新页面后可进入 `http://127.0.0.1:9527/#/client-keys/index`；菜单缓存未更新时重新登录。已验证列表空态、创建弹窗加载 12 模块及 HTTP 风险提示；未实际创建密钥，真实客户端读写及停用闭环仍待范围明确的验证。本节为 2026-09-07 本机验证记录；线上已于 2026-09-08 另行授权发布，见上节。
+
+
+## 蝦皮详情匹配等待与回读（#254）
+
+实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。
+
+- 本次只完成代码构建与合成测试，未改线上配置、AI设置、常驻服务或Nginx；部署与重启需另行授权。
+- 详情匹配新窗口是后端 2T+10 秒、Web POST 2T+20 秒。当前默认API最低写超时校验仍为620秒，这是历史最低值，不保证容纳所有动态预算；发布前读取实际 AI timeoutSeconds、application.writetimeout 和生效代理配置核对。
+- 建议API写超时至少为 2T+30 秒，且仍满足原最低620秒；代理读/发送超时需留足对应窗口。T=60/180时原620秒足够容纳应用预算；T=600时至少需要1230秒API写超时及适当更长的代理窗口。不得仅设置较大的AI超时却忽略传输层更早截断。
+- 上述是发布核对要求，不是本单已修改/验证线上代理的结论。超大T带来长连接占用，不能用关闭超时来代替正确预算。新增失败回读不代表必须延长任何线上请求。
+- 必须配套发布 Server/Web；仅上新版Web连接旧Server时，因缺失派生预算会提示等待时间不可用并停止匹配。原Android不需升级。
@@ -0,0 +1,8 @@
+# PDD 首页控件摘要（设备 192.168.0.9:35727）
+
+- 采集时间：2026-09-15
+- 包名：`com.xunmeng.pinduoduo`
+- 发现语义入口：`content-desc=拍照搜索`
+- 发现搜索入口：`content-desc=搜索`
+- 结论：PDD 首页存在稳定的“拍照搜索”无障碍语义入口，可作为 #277 的第一步入口探测。
+- 未保存坐标、完整控件树、截图、账号或个人数据。
@@ -0,0 +1,38 @@
+param(
+    [string]$BaseUrl = $env:GOAUTO_ADMIN_BASE_URL,
+    [int]$BatchSize = 100,
+    [int]$PageSize = 500,
+    [int]$SleepSeconds = 1,
+    [switch]$Force,
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+if ([string]::IsNullOrWhiteSpace($BaseUrl) -or [string]::IsNullOrWhiteSpace($env:GOAUTO_ADMIN_TOKEN)) {
+    throw '请设置 GOAUTO_ADMIN_BASE_URL 与 GOAUTO_ADMIN_TOKEN 环境变量'
+}
+if ($BatchSize -lt 1 -or $BatchSize -gt 500) { throw 'BatchSize 必须在 1 到 500 之间' }
+$headers = @{ Authorization = "Bearer $($env:GOAUTO_ADMIN_TOKEN)" }
+$ids = [System.Collections.Generic.List[UInt64]]::new()
+for ($page = 1; ; $page++) {
+    $uri = "$($BaseUrl.TrimEnd('/'))/api/admin/v1/syb-products?parseStatus=failed&page=$page&pageSize=$PageSize"
+    $response = Invoke-RestMethod -Uri $uri -Headers $headers -Method Get
+    $items = if ($response.data.items) { $response.data.items } elseif ($response.data.list) { $response.data.list } else { @() }
+    foreach ($item in $items) { if ($item.id) { [void]$ids.Add([UInt64]$item.id) } }
+    if ($items.Count -lt $PageSize) { break }
+}
+Write-Host "发现失败记录 $($ids.Count) 条"
+if ($DryRun -or $ids.Count -eq 0) { exit 0 }
+$ok = 0; $failed = 0
+for ($i = 0; $i -lt $ids.Count; $i += $BatchSize) {
+    $end = [Math]::Min($i + $BatchSize, $ids.Count)
+    $body = @{ ids = @($ids[$i..($end - 1)]); force = [bool]$Force } | ConvertTo-Json -Compress
+    try {
+        $result = Invoke-RestMethod -Uri "$($BaseUrl.TrimEnd('/'))/api/admin/v1/syb-products/reparse-batch" -Headers ($headers + @{ 'Content-Type' = 'application/json' }) -Method Post -Body $body
+        $rows = @($result.data.results)
+        $ok += @($rows | Where-Object { $_.newStatus -eq 'success' }).Count
+        $failed += @($rows | Where-Object { $_.newStatus -ne 'success' }).Count
+        Write-Host "已处理 $end/$($ids.Count)，成功 $ok，仍失败 $failed"
+    } catch { Write-Warning "批次 $($i + 1)-$end 请求失败：$($_.Exception.Message)" }
+    if ($SleepSeconds -gt 0 -and $end -lt $ids.Count) { Start-Sleep -Seconds $SleepSeconds }
+}
@@ -1,6 +1,6 @@
 [program:goauto-admin-api]
-command=pwsh.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "D:/OPC/goauto/scripts/start-server.ps1" -ConfigPath "D:/OPC/goauto/config.yaml"
-directory=D:/OPC/goauto
+command=pwsh.exe -NoLogo -NoProfile -File "D:/OPC/goauto-worktrees/main-runtime/scripts/start-server.ps1" -ConfigPath "D:/OPC/goauto/config.yaml" -SkipMigration
+directory=D:/OPC/goauto-worktrees/main-runtime
 autostart=true
 autorestart=true
 startsecs=3
@@ -14,8 +14,8 @@ stdout_logfile_maxbytes=50MB
 stdout_logfile_backups=5

 [program:goauto-admin-ui]
-command=pwsh.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "D:/OPC/goauto/scripts/start-web.ps1" -ConfigPath "D:/OPC/goauto/config.yaml"
-directory=D:/OPC/goauto
+command=pwsh.exe -NoLogo -NoProfile -File "D:/OPC/goauto-worktrees/main-runtime/scripts/start-web.ps1" -ConfigPath "D:/OPC/goauto/config.yaml"
+directory=D:/OPC/goauto-worktrees/main-runtime
 autostart=true
 autorestart=true
 startsecs=3
@@ -1,6 +1,7 @@
 package router

 import (
+	goautoclientapi "go-admin/app/goauto/clientapi"
 	"os"

 	"github.com/gin-gonic/gin"
@@ -17,6 +18,7 @@ import (
 	goautoshopeeproduct "go-admin/app/goauto/shopeeproduct"
 	goautosybimport "go-admin/app/goauto/sybimport"
 	goautosybinnercode "go-admin/app/goauto/sybinnercode"
+	goautosybproductfilter "go-admin/app/goauto/sybproductfilter"
 	goautosybshop "go-admin/app/goauto/sybshop"
 	goautotask "go-admin/app/goauto/task"
 	common "go-admin/common/middleware"
@@ -53,6 +55,7 @@ func InitRouter() {

 	// 注册 GoAuto Agent 与设备管理路由。
 	goautodevice.InitRouter(r, authMiddleware)
+	goautoclientapi.InitRouter(r, authMiddleware)
 	goautoapprelease.InitRouter(r, authMiddleware)
 	goautoaimatching.InitRouter(r, authMiddleware)
 	goautotask.InitRouter(r, authMiddleware)
@@ -61,8 +64,9 @@ func InitRouter() {
 	goautoproduct.InitRouter(r, authMiddleware)
 	goautoreplacement.InitRouter(r, authMiddleware)
 	goautorule.InitRouter(r, authMiddleware)
-	goautoshopeeproduct.InitRouter(r, authMiddleware)
+	goautoshopeeproduct.InitRouter(r, authMiddleware, goautopurchase.ValidateQuickReplacement)
 	goautosybimport.InitRouter(r, authMiddleware)
 	goautosybinnercode.InitRouter(r, authMiddleware)
 	goautosybshop.InitRouter(r, authMiddleware)
+	goautosybproductfilter.InitRouter(r, authMiddleware)
 }
@@ -3,18 +3,19 @@ package access
 import "strings"

 const (
-	ModuleDevices         = "devices"
-	ModulePDDProducts     = "pdd_products"
-	ModuleShopeeProducts  = "shopee_products"
-	ModuleSYBProducts     = "syb_products"
-	ModuleSYBShops        = "syb_shops"
-	ModuleSYBSyncRuns     = "syb_sync_runs"
-	ModuleSYBInnerCodes   = "syb_inner_codes"
-	ModuleCollectionRules = "collection_rules"
-	ModulePurchaseRules   = "purchase_rules"
-	ModuleCollectionTasks = "collection_tasks"
-	ModulePurchaseTasks   = "purchase_tasks"
-	ModuleAIMatching      = "ai_matching"
+	ModuleDevices           = "devices"
+	ModulePDDProducts       = "pdd_products"
+	ModuleShopeeProducts    = "shopee_products"
+	ModuleSYBProducts       = "syb_products"
+	ModuleSYBShops          = "syb_shops"
+	ModuleSYBProductFilters = "syb_product_filters"
+	ModuleSYBSyncRuns       = "syb_sync_runs"
+	ModuleSYBInnerCodes     = "syb_inner_codes"
+	ModuleCollectionRules   = "collection_rules"
+	ModulePurchaseRules     = "purchase_rules"
+	ModuleCollectionTasks   = "collection_tasks"
+	ModulePurchaseTasks     = "purchase_tasks"
+	ModuleAIMatching        = "ai_matching"
 )

 // ModuleDefinition is the single source of truth shared by menu migration,
@@ -77,6 +78,7 @@ var goAutoMenuGroupMetadata = []MenuGroupDefinition{
 		Sort:     51,
 		ModuleKeys: []string{
 			ModuleSYBShops,
+			ModuleSYBProductFilters,
 			ModuleCollectionRules,
 			ModulePurchaseRules,
 			ModuleDevices,
@@ -91,13 +93,14 @@ var goAutoModuleMetadata = []ModuleDefinition{
 	{Key: ModuleShopeeProducts, Title: "虾皮商品", Path: "/shopee-products", RouteName: "GoAutoShopeeProducts", Component: "/goauto/shopee-products/index", Icon: "goods", Sort: 52, PurchaserDefault: true},
 	{Key: ModuleSYBProducts, Title: "SYB 商品", Path: "/syb-products", RouteName: "GoAutoSybProducts", Component: "/goauto/syb-products/index", Icon: "tickets", Sort: 53, PurchaserDefault: true},
 	{Key: ModuleSYBShops, Title: "SYB 店铺", Path: "/syb-shops", RouteName: "GoAutoSybShops", Component: "/goauto/syb-shops/index", Icon: "shopping", Sort: 54, PurchaserDefault: true},
-	{Key: ModuleSYBSyncRuns, Title: "SYB 同步记录", Path: "/syb-sync-runs", RouteName: "GoAutoSybSyncRuns", Component: "/goauto/syb-sync-runs/index", Icon: "time", Sort: 55, PurchaserDefault: true},
-	{Key: ModuleSYBInnerCodes, Title: "档口入库码", Path: "/syb-inner-codes", RouteName: "GoAutoSybInnerCodes", Component: "/goauto/syb-inner-codes/index", Icon: "list", Sort: 56, PurchaserDefault: true},
-	{Key: ModuleCollectionRules, Title: "采集规则", Path: "/collection-rules", RouteName: "GoAutoCollectionRules", Component: "/goauto/collection-rules/index", Icon: "code", Sort: 57, PurchaserDefault: true},
-	{Key: ModulePurchaseRules, Title: "采购规则", Path: "/purchase-rules", RouteName: "GoAutoPurchaseRules", Component: "/goauto/purchase-rules/index", Icon: "setting", Sort: 58, PurchaserHardHidden: true},
-	{Key: ModuleCollectionTasks, Title: "采集任务", Path: "/collection-tasks", RouteName: "GoAutoCollectionTasks", Component: "/goauto/collection-tasks/index", Icon: "list", Sort: 59, PurchaserDefault: true},
-	{Key: ModulePurchaseTasks, Title: "采购管理", Path: "/purchase-tasks", RouteName: "GoAutoPurchaseTasks", Component: "/goauto/purchase-tasks/index", Icon: "shopping", Sort: 60, PurchaserDefault: true},
-	{Key: ModuleAIMatching, Title: "AI 规格匹配", Path: "/ai-matching-settings", RouteName: "GoAutoAiMatchingSettings", Component: "/goauto/ai-matching-settings/index", Icon: "setting", Sort: 61, PurchaserHardHidden: true},
+	{Key: ModuleSYBProductFilters, Title: "SYB 商品过滤", Path: "/syb-product-filters", RouteName: "GoAutoSybProductFilters", Component: "/goauto/syb-product-filters/index", Icon: "filter", Sort: 55, PurchaserDefault: true},
+	{Key: ModuleSYBSyncRuns, Title: "SYB 同步记录", Path: "/syb-sync-runs", RouteName: "GoAutoSybSyncRuns", Component: "/goauto/syb-sync-runs/index", Icon: "time", Sort: 56, PurchaserDefault: true},
+	{Key: ModuleSYBInnerCodes, Title: "档口入库码", Path: "/syb-inner-codes", RouteName: "GoAutoSybInnerCodes", Component: "/goauto/syb-inner-codes/index", Icon: "list", Sort: 57, PurchaserDefault: true},
+	{Key: ModuleCollectionRules, Title: "采集规则", Path: "/collection-rules", RouteName: "GoAutoCollectionRules", Component: "/goauto/collection-rules/index", Icon: "code", Sort: 58, PurchaserDefault: true},
+	{Key: ModulePurchaseRules, Title: "采购规则", Path: "/purchase-rules", RouteName: "GoAutoPurchaseRules", Component: "/goauto/purchase-rules/index", Icon: "setting", Sort: 59, PurchaserHardHidden: true},
+	{Key: ModuleCollectionTasks, Title: "采集任务", Path: "/collection-tasks", RouteName: "GoAutoCollectionTasks", Component: "/goauto/collection-tasks/index", Icon: "list", Sort: 60, PurchaserDefault: true},
+	{Key: ModulePurchaseTasks, Title: "采购管理", Path: "/purchase-tasks", RouteName: "GoAutoPurchaseTasks", Component: "/goauto/purchase-tasks/index", Icon: "shopping", Sort: 61, PurchaserDefault: true},
+	{Key: ModuleAIMatching, Title: "AI 规格匹配", Path: "/ai-matching-settings", RouteName: "GoAutoAiMatchingSettings", Component: "/goauto/ai-matching-settings/index", Icon: "setting", Sort: 62, PurchaserHardHidden: true},
 }

 // GoAutoModules returns independent copies so callers cannot mutate the
@@ -144,6 +147,8 @@ func moduleKeyForAPI(path string) string {
 		return ModuleSYBProducts
 	case strings.HasPrefix(path, "/api/admin/v1/syb-shops"):
 		return ModuleSYBShops
+	case strings.HasPrefix(path, "/api/admin/v1/syb-product-filters"):
+		return ModuleSYBProductFilters
 	case strings.HasPrefix(path, "/api/admin/v1/syb-inner-codes"):
 		return ModuleSYBInnerCodes
 	case strings.HasPrefix(path, "/api/admin/v1/collection-rules"):
@@ -10,8 +10,8 @@ import (

 func TestGoAutoModulesOwnEveryAdminAPIExactlyOnce(t *testing.T) {
 	modules := GoAutoModules()
-	if len(modules) != 12 {
-		t.Fatalf("got %d modules, want 12", len(modules))
+	if len(modules) != 13 {
+		t.Fatalf("got %d modules, want 13", len(modules))
 	}

 	owners := make(map[string]int)
@@ -56,8 +56,8 @@ func TestGoAutoMenuSortsFitMySQLSignedTinyInt(t *testing.T) {
 		}
 		previous = module.Sort
 	}
-	if modules[0].Sort != 50 || modules[len(modules)-1].Sort != 61 {
-		t.Fatalf("GoAuto menu sort range = %d..%d, want 50..61", modules[0].Sort, modules[len(modules)-1].Sort)
+	if modules[0].Sort != 50 || modules[len(modules)-1].Sort != 62 {
+		t.Fatalf("GoAuto menu sort range = %d..%d, want 50..62", modules[0].Sort, modules[len(modules)-1].Sort)
 	}
 }

@@ -72,7 +72,7 @@ func TestGoAutoMenuGroupsCoverModulesExactlyOnce(t *testing.T) {

 	wantOrder := [][]string{
 		{ModuleSYBProducts, ModuleSYBSyncRuns, ModuleSYBInnerCodes, ModuleShopeeProducts, ModulePDDProducts, ModuleCollectionTasks, ModulePurchaseTasks},
-		{ModuleSYBShops, ModuleCollectionRules, ModulePurchaseRules, ModuleDevices, ModuleAIMatching},
+		{ModuleSYBShops, ModuleSYBProductFilters, ModuleCollectionRules, ModulePurchaseRules, ModuleDevices, ModuleAIMatching},
 	}
 	seen := make(map[string]int)
 	for groupIndex, group := range groups {
@@ -56,7 +56,7 @@ var AdminAPIs = []APIPermission{
 	{"重新解析 SYB 商品", "/api/admin/v1/syb-products/:productId/reparse", "POST", true},
 	{"批量重新解析 SYB 商品", "/api/admin/v1/syb-products/reparse-batch", "POST", true},
 	{"人工修正 SYB 商品", "/api/admin/v1/syb-products/:productId/correction", "PATCH", true},
-	{"手动同步 SYB 商品", "/api/admin/v1/syb-products/import", "POST", false},
+	{"手动同步 SYB 商品", "/api/admin/v1/syb-products/import", "POST", true},
 	{"查看 SYB 同步记录", "/api/admin/v1/syb-products/sync-runs", "GET", true},
 	{"查看 SYB 同步详情", "/api/admin/v1/syb-products/sync-runs/:runId", "GET", true},

@@ -77,6 +77,10 @@ var AdminAPIs = []APIPermission{
 	{"启停 SYB 店铺", "/api/admin/v1/syb-shops/:shopId/enabled", "PATCH", false},
 	{"删除 SYB 店铺", "/api/admin/v1/syb-shops/:shopId", "DELETE", false},
 	{"从 SYB 发现店铺", "/api/admin/v1/syb-shops/discover", "POST", false},
+	{"查看 SYB 商品过滤", "/api/admin/v1/syb-product-filters", "GET", true},
+	{"新增 SYB 商品过滤", "/api/admin/v1/syb-product-filters", "POST", false},
+	{"启停 SYB 商品过滤", "/api/admin/v1/syb-product-filters/:filterId/enabled", "PATCH", false},
+	{"删除 SYB 商品过滤", "/api/admin/v1/syb-product-filters/:filterId", "DELETE", false},

 	{"查看采集规则模板", "/api/admin/v1/collection-rules/templates/:templateId", "GET", true},
 	{"查看采集规则", "/api/admin/v1/collection-rules", "GET", true},
@@ -94,6 +98,7 @@ var AdminAPIs = []APIPermission{
 	{"查看采集任务", "/api/admin/v1/collection-tasks", "GET", true},
 	{"创建采集任务", "/api/admin/v1/collection-tasks", "POST", true},
 	{"批量创建采集任务", "/api/admin/v1/collection-tasks/batch", "POST", true},
+	{"批量创建图搜采集任务", "/api/admin/v1/collection-tasks/image-search/batch", "POST", true},
 	{"查看采集任务详情", "/api/admin/v1/collection-tasks/:taskId", "GET", true},
 	{"重置采集任务", "/api/admin/v1/collection-tasks/:taskId/reset", "POST", true},
 	{"删除采集任务", "/api/admin/v1/collection-tasks/:taskId", "DELETE", true},
@@ -15,12 +15,14 @@ func TestPurchaserPermissionMatrixHasNoDuplicates(t *testing.T) {

 func TestPurchaserExcludesAdministratorOperations(t *testing.T) {
 	denied := map[string]bool{
-		"POST /api/admin/v1/devices/:deviceId/disable":         true,
-		"POST /api/admin/v1/syb-products/import":               true,
-		"POST /api/admin/v1/collection-rules":                  true,
-		"PUT /api/admin/v1/ai-matching-settings":               true,
-		"POST /api/admin/v1/shopee-spec-auto-match/runs":       true,
-		"GET /api/admin/v1/shopee-spec-auto-match/runs/latest": true,
+		"POST /api/admin/v1/devices/:deviceId/disable":              true,
+		"POST /api/admin/v1/syb-shops/discover":                     true,
+		"POST /api/admin/v1/syb-product-filters":                    true,
+		"PATCH /api/admin/v1/syb-product-filters/:filterId/enabled": true,
+		"POST /api/admin/v1/collection-rules":                       true,
+		"PUT /api/admin/v1/ai-matching-settings":                    true,
+		"POST /api/admin/v1/shopee-spec-auto-match/runs":            true,
+		"GET /api/admin/v1/shopee-spec-auto-match/runs/latest":      true,
 	}
 	for _, permission := range PurchaserAPIs() {
 		if denied[permission.Method+" "+permission.Path] {
@@ -55,7 +55,9 @@ func TestReconcilePurchaserPermissions(t *testing.T) {
 	}

 	assertPolicyCount(t, db, "custom-role", "/custom", "GET", 1)
-	assertPolicyCount(t, db, RolePurchaser, "/api/admin/v1/syb-products/import", "POST", 0)
+	assertPolicyCount(t, db, RolePurchaser, "/api/admin/v1/syb-products/import", "POST", 1)
+	assertPolicyCount(t, db, RolePurchaser, "/api/admin/v1/syb-shops/discover", "POST", 0)
+	assertPolicyCount(t, db, RolePurchaser, "/api/admin/v1/syb-shops", "POST", 0)
 }

 func TestReconcilePurchaserPermissionsRemovesOnlyStalePurchaserGrant(t *testing.T) {
@@ -15,6 +15,7 @@ var (
 	traditionalToSimplified *gocc.OpenCC
 	traditionalErr          error
 	weightPattern           = regexp.MustCompile(`(?i)(\d+(?:\.\d+)?)\s*(?:[-~～至到]\s*(\d+(?:\.\d+)?))?\s*(公斤|千克|kg|斤)`)
+	sizeTokenPattern        = regexp.MustCompile(`(?i)^(?:xxxs|xxl|xxxl|xxxxl|[2-9]xl|xs|s|m|l|xl|\d+xl)\b`)
 )

 // Normalize makes a deterministic comparison key. It intentionally removes
@@ -80,7 +81,7 @@ func normalizeWeight(raw string) string {
 // deliberately treated as no match instead of picking the first label.
 func DeterministicMatch(request MatchRequest) (MatchResult, bool) {
 	color, colorOK := exactCandidate(request.TargetColor, request.Colors)
-	size, sizeOK := exactCandidate(request.TargetSize, request.Sizes)
+	size, sizeOK := exactSizeCandidate(request.TargetSize, request.Sizes)
 	if !colorOK || !sizeOK {
 		return MatchResult{}, false
 	}
@@ -88,6 +89,27 @@ func DeterministicMatch(request MatchRequest) (MatchResult, bool) {
 	return result, true
 }

+func exactSizeCandidate(target string, candidates []string) (string, bool) {
+	key := sizeTokenPattern.FindString(strings.ToLower(Normalize(target)))
+	if key == "" {
+		return exactCandidate(target, candidates)
+	}
+	matches := make([]string, 0, 1)
+	seen := map[string]bool{}
+	for _, candidate := range candidates {
+		candidate = strings.TrimSpace(candidate)
+		if candidate == "" || sizeTokenPattern.FindString(strings.ToLower(Normalize(candidate))) != key || seen[candidate] {
+			continue
+		}
+		seen[candidate] = true
+		matches = append(matches, candidate)
+	}
+	if len(matches) == 1 {
+		return matches[0], true
+	}
+	return "", false
+}
+
 // ManualMatch records an already-confirmed mapping without reinterpreting it.
 // The caller owns the human-confirmation check; this helper only creates the
 // same bounded task snapshot shape used by automatic decisions.
@@ -0,0 +1,158 @@
+package clientapi
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg"
+	"go-admin/app/goauto/clientkey"
+	"go-admin/common/clientprincipal"
+	"gorm.io/gorm"
+)
+
+// Both HTTP and HTTPS are supported by explicit operator decision (#237).
+// Transport does not grant identity or permissions; secrets remain non-cacheable.
+func NoStore(c *gin.Context) {
+	c.Header("Cache-Control", "no-store")
+	c.Next()
+}
+func Gate(db *gorm.DB, e Endpoint) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Header("Cache-Control", "no-store")
+		deny := func(status int, message string) {
+			c.AbortWithStatusJSON(status, gin.H{"code": status, "message": message})
+		}
+		// Never accept a credential supplied through a URL or cookie fallback.
+		for k := range c.Request.URL.Query() {
+			if sensitive(k) || strings.EqualFold(k, "token") {
+				deny(400, "密钥只能通过 Authorization 请求头发送")
+				return
+			}
+		}
+		header := strings.Fields(c.GetHeader("Authorization"))
+		if len(header) != 2 || !strings.EqualFold(header[0], "Bearer") {
+			deny(401, "需要客户端密钥")
+			return
+		}
+		connection := db
+		var err error
+		if connection == nil {
+			connection, err = pkg.GetOrm(c)
+		}
+		if err != nil || connection == nil {
+			deny(503, "客户端认证暂不可用")
+			return
+		}
+		key, err := (clientkey.Service{DB: connection}).Authenticate(c.Request.Context(), header[1])
+		if err != nil {
+			if errors.Is(err, clientkey.ErrCredential) {
+				deny(401, "客户端密钥无效或已停用")
+			} else {
+				deny(503, "客户端认证暂不可用")
+			}
+			return
+		}
+		random := make([]byte, 16)
+		if _, err = rand.Read(random); err != nil {
+			deny(503, "审计暂不可用")
+			return
+		}
+		requestID := hex.EncodeToString(random)
+		c.Header("X-Client-Request-Id", requestID)
+		record := clientkey.Audit{KeyID: key.ID, Event: "request", RequestID: requestID, Method: e.Method, Route: "/api/client/v1" + e.Path}
+		if !key.Allows(e.Module, e.Capability) {
+			record.Status = 403
+			_ = connection.Create(&record).Error
+			deny(403, "密钥未授权此模块或执行动作")
+			return
+		}
+		// The intent must be durable before any business handler can run.
+		if err = connection.WithContext(c.Request.Context()).Create(&record).Error; err != nil {
+			deny(503, "审计暂不可用，未执行操作")
+			return
+		}
+		clientprincipal.Set(c, clientprincipal.Identity{KeyID: key.ID, RequestID: requestID, AuthorizedBy: key.UpdatedBy})
+		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 16<<20)
+		original := c.Writer
+		buffer := &responseBuffer{ResponseWriter: original, status: 200}
+		c.Writer = buffer
+		defer func() { c.Writer = original }()
+		c.Next()
+		c.Writer = original
+		status := buffer.status
+		var value any
+		if buffer.overflow || json.Unmarshal(buffer.body.Bytes(), &value) != nil {
+			status = 502
+			value = gin.H{"code": 502, "message": "无法生成客户端响应，请先核对操作结果，不要自动重试"}
+		} else {
+			value = redact(value)
+		}
+		auditCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = connection.WithContext(auditCtx).Model(&clientkey.Audit{}).Where("id = ?", record.ID).Update("status", status).Error
+		now := time.Now().UTC()
+		_ = connection.WithContext(auditCtx).Model(&clientkey.Key{}).Where("id = ?", key.ID).UpdateColumn("last_used_at", now).Error
+		c.JSON(status, value)
+	}
+}
+
+type responseBuffer struct {
+	gin.ResponseWriter
+	body     bytes.Buffer
+	status   int
+	overflow bool
+}
+
+func (w *responseBuffer) WriteHeader(status int) { w.status = status }
+func (w *responseBuffer) WriteHeaderNow()        {}
+func (w *responseBuffer) Status() int            { return w.status }
+func (w *responseBuffer) Size() int              { return w.body.Len() }
+func (w *responseBuffer) Written() bool          { return w.body.Len() > 0 }
+func (w *responseBuffer) Write(b []byte) (int, error) {
+	if w.body.Len()+len(b) > 32<<20 {
+		w.overflow = true
+		return len(b), nil
+	}
+	return w.body.Write(b)
+}
+func (w *responseBuffer) WriteString(s string) (int, error) { return w.Write([]byte(s)) }
+func (w *responseBuffer) Flush()                            {}
+
+func sensitive(k string) bool {
+	key := strings.ToLower(strings.ReplaceAll(strings.ReplaceAll(k, "_", ""), "-", ""))
+	for _, part := range []string{"password", "passwd", "secret", "credential", "cookie", "authorization", "apikey", "accesstoken", "devicetoken", "refreshtoken", "recoverycode"} {
+		if strings.Contains(key, part) {
+			return true
+		}
+	}
+	switch key {
+	case "token", "tokenhash", "digest", "rawjson", "rawpayload", "rawresponse", "requestheaders", "responseheaders":
+		return true
+	}
+	return false
+}
+func redact(v any) any {
+	switch value := v.(type) {
+	case map[string]any:
+		for k, item := range value {
+			if sensitive(k) {
+				delete(value, k)
+			} else {
+				value[k] = redact(item)
+			}
+		}
+	case []any:
+		for i, item := range value {
+			value[i] = redact(item)
+		}
+	}
+	return v
+}
@@ -0,0 +1,165 @@
+package clientapi
+
+import (
+	"context"
+	"crypto/tls"
+	"encoding/json"
+	"github.com/gin-gonic/gin"
+	"go-admin/app/goauto/clientkey"
+	"go-admin/common/clientprincipal"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func fixture(t *testing.T) (*gorm.DB, clientkey.Service) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sql, _ := db.DB()
+	sql.SetMaxOpenConns(1)
+	t.Cleanup(func() { sql.Close() })
+	if err = db.AutoMigrate(&clientkey.Key{}, &clientkey.Audit{}); err != nil {
+		t.Fatal(err)
+	}
+	return db, clientkey.Service{DB: db, Modules: Catalog(Inventory())}
+}
+func TestEveryRouteIsExplicitlyScoped(t *testing.T) {
+	db, s := fixture(t)
+	routes := Inventory()
+	if len(s.Modules) != 13 {
+		t.Fatal("menu groups lost")
+	}
+	router := gin.New()
+	seen := map[string]bool{}
+	for _, e := range routes {
+		key := e.Method + e.Path
+		if seen[key] {
+			t.Fatal("duplicate route")
+		}
+		seen[key] = true
+		if strings.Contains(e.Path, "payment") || strings.Contains(e.Path, "token") || strings.Contains(e.Path, "client-keys") || e.Handle == nil {
+			t.Fatal("forbidden route")
+		}
+		router.Handle(e.Method, "/api/client/v1"+e.Path, Gate(db, e), func(c *gin.Context) { c.JSON(200, gin.H{"data": "ok"}) })
+		if e.Method != "GET" && e.Capability == "read" {
+			t.Fatal("mutating read permission")
+		}
+	}
+	for _, e := range routes {
+		for _, scheme := range []string{"http", "https"} {
+			grant := clientkey.Grant{Module: e.Module}
+			v, token, err := s.Create(context.Background(), "test", []clientkey.Grant{grant}, 1)
+			if err != nil {
+				t.Fatal(err)
+			}
+			path := e.Path
+			for _, param := range []string{":productId", ":runId", ":recordId", ":jobId", ":batchId", ":shopId", ":ruleId", ":taskId"} {
+				path = strings.ReplaceAll(path, param, "1")
+			}
+			req := httptest.NewRequest(e.Method, scheme+"://example.test/api/client/v1"+path, nil)
+			req.Header.Set("Authorization", "Bearer "+token)
+			rr := httptest.NewRecorder()
+			router.ServeHTTP(rr, req)
+			want := 200
+			if e.Capability != "read" {
+				want = 403
+			}
+			if rr.Code != want {
+				t.Fatalf("%s got %d want %d", keyFor(e), rr.Code, want)
+			}
+			if e.Capability == "write" {
+				grant.Write = true
+			} else if e.Capability != "read" {
+				grant.Actions = []string{e.Capability}
+			}
+			if _, err = s.Update(context.Background(), v.ID, 1, 1, []clientkey.Grant{grant}, false); err != nil {
+				t.Fatal(err)
+			}
+			rr = httptest.NewRecorder()
+			router.ServeHTTP(rr, req.Clone(context.Background()))
+			if rr.Code != 200 {
+				t.Fatalf("authorized %s failed: %d", keyFor(e), rr.Code)
+			}
+		}
+	}
+}
+func keyFor(e Endpoint) string { return e.Method + " " + e.Path }
+func TestRevocationTransportRedactionAndAudit(t *testing.T) {
+	db, s := fixture(t)
+	v, token, err := s.Create(context.Background(), "test", []clientkey.Grant{{Module: "pdd_products"}}, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e := Endpoint{Method: "GET", Path: "/pdd-products", Module: "pdd_products", Capability: "read"}
+	router := gin.New()
+	calls := 0
+	router.GET("/api/client/v1/pdd-products", Gate(db, e), func(c *gin.Context) {
+		calls++
+		id, ok := clientprincipal.Get(c)
+		if !ok || id.KeyID != v.ID {
+			t.Error("client attribution missing")
+		}
+		c.JSON(200, gin.H{"code": 200, "data": gin.H{"apiKey": "sentinel-secret", "rawJson": "sentinel-raw", "title": "product", "nested": []any{gin.H{"device_token": "sentinel-token"}}}})
+	})
+	send := func(tlsOn bool, credential, path string) *httptest.ResponseRecorder {
+		req := httptest.NewRequest("GET", "http://example.test"+path, nil)
+		if tlsOn {
+			req.TLS = &tls.ConnectionState{}
+		}
+		req.Header.Set("Authorization", "Bearer "+credential)
+		rr := httptest.NewRecorder()
+		router.ServeHTTP(rr, req)
+		return rr
+	}
+	path := "/api/client/v1/pdd-products"
+	for _, tlsOn := range []bool{false, true} {
+		if send(tlsOn, "jwt", path).Code != 401 || send(tlsOn, "", path).Code != 401 || send(tlsOn, token, path+"?token=invalid").Code != 400 {
+			t.Fatal("credential fallback accepted")
+		}
+		rr := send(tlsOn, token, path)
+		if rr.Code != 200 || strings.Contains(rr.Body.String(), "sentinel") || !strings.Contains(rr.Body.String(), "product") {
+			t.Fatal("redaction failed")
+		}
+		if rr.Header().Get("Cache-Control") != "no-store" || rr.Header().Get("X-Client-Request-Id") == "" {
+			t.Fatal("cache or audit headers missing")
+		}
+	}
+	if _, err = s.Update(context.Background(), v.ID, 1, 1, nil, true); err != nil {
+		t.Fatal(err)
+	}
+	if send(true, token, path).Code != 401 || send(false, token, path).Code != 401 || calls != 2 {
+		t.Fatal("revocation not immediate")
+	}
+	var logs []clientkey.Audit
+	db.Find(&logs)
+	raw, _ := json.Marshal(logs)
+	if strings.Contains(string(raw), token) || strings.Contains(string(raw), "sentinel") {
+		t.Fatal("audit leaked payload")
+	}
+}
+func TestAuditUnavailableDoesNotExecute(t *testing.T) {
+	db, s := fixture(t)
+	_, token, err := s.Create(context.Background(), "test", []clientkey.Grant{{Module: "pdd_products", Write: true}}, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	db.Migrator().DropTable(&clientkey.Audit{})
+	router := gin.New()
+	called := false
+	e := Endpoint{Method: "POST", Path: "/pdd-products", Module: "pdd_products", Capability: "write"}
+	router.POST(e.Path, Gate(db, e), func(c *gin.Context) { called = true; c.JSON(200, gin.H{}) })
+	req := httptest.NewRequest("POST", "https://example.test"+e.Path, nil)
+	req.Header.Set("Authorization", "Bearer "+token)
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+	if rr.Code != 503 || called {
+		t.Fatal("executed without audit")
+	}
+}
@@ -0,0 +1,81 @@
+package clientapi
+
+import (
+	"context"
+	"encoding/json"
+	"github.com/gin-gonic/gin"
+	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
+	"go-admin/app/goauto/clientkey"
+	"go-admin/app/goauto/models"
+	"go-admin/app/goauto/product"
+	"go-admin/common/middleware"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestClientCanCreateProductWithoutLoginAndReplay(t *testing.T) {
+	db, s := fixture(t)
+	if err := db.AutoMigrate(&models.PDDProduct{}); err != nil {
+		t.Fatal(err)
+	}
+	_, token, err := s.Create(context.Background(), "test", []clientkey.Grant{{Module: "pdd_products", Write: true}}, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e := Endpoint{Method: "POST", Path: "/pdd-products", Module: "pdd_products", Capability: "write"}
+	router := gin.New()
+	router.Use(func(c *gin.Context) { c.Set("db", db); c.Next() })
+	router.POST("/api/client/v1/pdd-products", Gate(db, e), product.Handler{}.Create)
+	for n := 0; n < 2; n++ {
+		req := httptest.NewRequest("POST", "https://example.test/api/client/v1/pdd-products", strings.NewReader(`{"requestId":"00000000-0000-4000-8000-000000000237","url":"https://mobile.yangkeduo.com/goods.html?goods_id=100000000001"}`))
+		req.Header.Set("Authorization", "Bearer "+token)
+		rr := httptest.NewRecorder()
+		router.ServeHTTP(rr, req)
+		if rr.Code != 200 {
+			t.Fatalf("product create failed status %d", rr.Code)
+		}
+		var body struct {
+			Data struct {
+				Replayed bool `json:"replayed"`
+			}
+		}
+		json.Unmarshal(rr.Body.Bytes(), &body)
+		if (n == 1) != body.Data.Replayed {
+			t.Fatal("business idempotency changed")
+		}
+	}
+	var count int64
+	db.Model(&models.PDDProduct{}).Count(&count)
+	if count != 1 {
+		t.Fatal("duplicate business write")
+	}
+}
+
+func TestManagementRequiresAdminNotClientIdentity(t *testing.T) {
+	db, s := fixture(t)
+	h := clientkey.Handler{DB: db, Modules: s.Modules}
+	for _, role := range []string{"admin", "purchaser", "client", ""} {
+		for _, scheme := range []string{"http", "https"} {
+			router := gin.New()
+			router.Use(func(c *gin.Context) {
+				c.Set(jwt.JwtPayloadKey, jwt.MapClaims{"rolekey": role, "identity": float64(7)})
+				c.Next()
+			})
+			router.POST("/keys", middleware.RequireRoleKey("admin"), NoStore, h.Create)
+			req := httptest.NewRequest("POST", scheme+"://example.test/keys", strings.NewReader(`{"name":"test","grants":[{"module":"pdd_products","write":false,"actions":[]}]}`))
+			rr := httptest.NewRecorder()
+			router.ServeHTTP(rr, req)
+			want := 403
+			if role == "admin" {
+				want = 200
+			}
+			if rr.Code != want {
+				t.Fatalf("role %q status %d", role, rr.Code)
+			}
+			if role == "admin" && rr.Header().Get("Cache-Control") != "no-store" {
+				t.Fatal("one-time secret cacheable")
+			}
+		}
+	}
+}
@@ -0,0 +1,45 @@
+package clientapi
+
+import (
+	"encoding/json"
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg"
+	"go-admin/app/goauto/aimatching"
+	"io"
+	"net/http"
+)
+
+// resolveSpecs accepts only specification text, never a provider URL/key,
+// prompt, raw order, address or account. It returns a suggestion, not an order.
+func resolveSpecs(c *gin.Context) {
+	var req struct {
+		TargetColor string   `json:"targetColor"`
+		TargetSize  string   `json:"targetSize"`
+		Colors      []string `json:"colors"`
+		Sizes       []string `json:"sizes"`
+	}
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 64<<10)
+	d := json.NewDecoder(c.Request.Body)
+	d.DisallowUnknownFields()
+	if d.Decode(&req) != nil || d.Decode(&struct{}{}) != io.EOF || len(req.Colors) > 200 || len(req.Sizes) > 200 {
+		c.JSON(422, gin.H{"code": 422, "message": "规格请求无效"})
+		return
+	}
+	for _, s := range append(append([]string{req.TargetColor, req.TargetSize}, req.Colors...), req.Sizes...) {
+		if len([]rune(s)) > 255 {
+			c.JSON(422, gin.H{"code": 422, "message": "规格值过长"})
+			return
+		}
+	}
+	db, err := pkg.GetOrm(c)
+	if err != nil {
+		c.JSON(503, gin.H{"code": 503})
+		return
+	}
+	v, err := aimatching.NewService(db).Resolve(c.Request.Context(), aimatching.MatchRequest{TargetColor: req.TargetColor, TargetSize: req.TargetSize, Colors: req.Colors, Sizes: req.Sizes})
+	if err != nil {
+		c.JSON(422, gin.H{"code": 422, "message": "未获得可靠匹配，请检查候选规格或联系管理员"})
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": gin.H{"mappedColor": v.MappedColor, "mappedSize": v.MappedSize, "source": v.Source}})
+}
@@ -0,0 +1,171 @@
+// Package clientapi exposes only the reviewed client route inventory. It never
+// forwards arbitrary URLs or synthesizes a logged-in administrator identity.
+package clientapi
+
+import (
+	"go-admin/app/goauto/access"
+	"go-admin/app/goauto/aimatching"
+	"go-admin/app/goauto/clientkey"
+	"go-admin/app/goauto/device"
+	"go-admin/app/goauto/product"
+	"go-admin/app/goauto/purchase"
+	"go-admin/app/goauto/purchaserule"
+	"go-admin/app/goauto/rule"
+	"go-admin/app/goauto/shopeeproduct"
+	"go-admin/app/goauto/sybimport"
+	"go-admin/app/goauto/sybinnercode"
+	"go-admin/app/goauto/sybshop"
+	"go-admin/app/goauto/task"
+	"go-admin/common/middleware"
+	"sort"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg"
+	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
+)
+
+type Endpoint struct {
+	Method, Path, Module, Capability string
+	Handle                           gin.HandlerFunc
+}
+
+func Inventory() []Endpoint {
+	p := product.Handler{}
+	s := shopeeproduct.Handler{}
+	y := sybimport.Handler{}
+	i := sybinnercode.Handler{}
+	shop := sybshop.Handler{}
+	r := rule.Handler{}
+	pr := purchaserule.Handler{}
+	t := task.Handler{}
+	buy := purchase.Handler{}
+	return []Endpoint{
+		{"POST", "/ai-matching-settings/resolve", access.ModuleAIMatching, "match", resolveSpecs},
+		{"GET", "/devices", access.ModuleDevices, "read", device.Handler{}.List},
+		{"GET", "/pdd-products", access.ModulePDDProducts, "read", p.List},
+		{"GET", "/pdd-products/:productId", access.ModulePDDProducts, "read", p.Detail},
+		{"POST", "/pdd-products", access.ModulePDDProducts, "write", p.Create},
+		{"PATCH", "/pdd-products/:productId", access.ModulePDDProducts, "write", p.Update},
+		{"GET", "/shopee-products", access.ModuleShopeeProducts, "read", s.List},
+		{"GET", "/shopee-products/:productId", access.ModuleShopeeProducts, "read", s.Detail},
+		{"POST", "/shopee-products", access.ModuleShopeeProducts, "write", s.Create},
+		{"PATCH", "/shopee-products/:productId", access.ModuleShopeeProducts, "write", s.Update},
+		{"POST", "/shopee-products/:productId/link-pdd", access.ModuleShopeeProducts, "write", s.LinkPDD},
+		{"POST", "/shopee-products/:productId/specs/values", access.ModuleShopeeProducts, "write", s.AddSpecValue},
+		{"PUT", "/shopee-products/:productId/specs/mapping", access.ModuleShopeeProducts, "write", s.SetMapping},
+		{"DELETE", "/shopee-products/:productId/specs/values", access.ModuleShopeeProducts, "delete", s.RemoveSpecValue},
+		{"DELETE", "/shopee-products/:productId/specs/mapping", access.ModuleShopeeProducts, "delete", s.ClearMapping},
+		{"POST", "/shopee-products/batch-delete", access.ModuleShopeeProducts, "delete", s.BatchDelete},
+		{"POST", "/shopee-products/:productId/specs/mapping/auto-match", access.ModuleShopeeProducts, "match", s.AutoMatchMappings},
+		{"POST", "/shopee-products/:productId/specs/mapping/confirm", access.ModuleShopeeProducts, "match", s.ConfirmMapping},
+		{"GET", "/syb-products", access.ModuleSYBProducts, "read", y.List},
+		{"GET", "/syb-products/:productId", access.ModuleSYBProducts, "read", y.Detail},
+		{"PATCH", "/syb-products/:productId/correction", access.ModuleSYBProducts, "write", y.ManualCorrect},
+		{"POST", "/syb-products/:productId/reparse", access.ModuleSYBProducts, "reparse", y.Reparse},
+		{"POST", "/syb-products/reparse-batch", access.ModuleSYBProducts, "reparse", y.ReparseBatch},
+		{"GET", "/syb-products/sync-runs", access.ModuleSYBSyncRuns, "read", y.ListSyncRuns},
+		{"GET", "/syb-products/sync-runs/:runId", access.ModuleSYBSyncRuns, "read", y.SyncRunDetail},
+		{"POST", "/syb-products/import", access.ModuleSYBSyncRuns, "sync", y.Import},
+		{"GET", "/syb-inner-codes", access.ModuleSYBInnerCodes, "read", i.List},
+		{"GET", "/syb-inner-codes/:recordId", access.ModuleSYBInnerCodes, "read", i.Detail},
+		{"GET", "/syb-inner-codes/match-jobs/:jobId", access.ModuleSYBInnerCodes, "read", i.MatchJob},
+		{"GET", "/syb-inner-codes/apply-batches/:batchId", access.ModuleSYBInnerCodes, "read", i.ApplyBatch},
+		{"POST", "/syb-inner-codes/rematch", access.ModuleSYBInnerCodes, "match", i.Rematch},
+		{"POST", "/syb-inner-codes/import", access.ModuleSYBInnerCodes, "import", i.Import},
+		{"POST", "/syb-inner-codes/batch-delete", access.ModuleSYBInnerCodes, "delete", i.Delete},
+		{"POST", "/syb-inner-codes/apply-preview", access.ModuleSYBInnerCodes, "writeback", i.ApplyPreview},
+		{"POST", "/syb-inner-codes/apply", access.ModuleSYBInnerCodes, "writeback", i.Apply},
+		{"POST", "/syb-inner-codes/:recordId/recheck", access.ModuleSYBInnerCodes, "match", i.Recheck},
+		{"GET", "/syb-shops", access.ModuleSYBShops, "read", shop.List},
+		{"POST", "/syb-shops", access.ModuleSYBShops, "write", shop.Create},
+		{"PATCH", "/syb-shops/:shopId/name", access.ModuleSYBShops, "write", shop.Rename},
+		{"PATCH", "/syb-shops/:shopId/enabled", access.ModuleSYBShops, "write", shop.SetEnabled},
+		{"DELETE", "/syb-shops/:shopId", access.ModuleSYBShops, "delete", shop.Delete},
+		{"GET", "/collection-rules", access.ModuleCollectionRules, "read", r.List},
+		{"POST", "/collection-rules", access.ModuleCollectionRules, "write", r.Create},
+		{"PATCH", "/collection-rules/:ruleId", access.ModuleCollectionRules, "write", r.Update},
+		{"DELETE", "/collection-rules/:ruleId", access.ModuleCollectionRules, "delete", r.Delete},
+		{"GET", "/purchase-rules", access.ModulePurchaseRules, "read", pr.List},
+		{"GET", "/purchase-rules/current", access.ModulePurchaseRules, "read", pr.Current},
+		{"POST", "/purchase-rules", access.ModulePurchaseRules, "write", pr.Create},
+		{"PATCH", "/purchase-rules/:ruleId", access.ModulePurchaseRules, "write", pr.Update},
+		{"DELETE", "/purchase-rules/:ruleId", access.ModulePurchaseRules, "delete", pr.Delete},
+		{"PUT", "/purchase-rules/current", access.ModulePurchaseRules, "activate", pr.SetCurrent},
+		{"GET", "/collection-tasks", access.ModuleCollectionTasks, "read", t.AdminList},
+		{"GET", "/collection-tasks/:taskId", access.ModuleCollectionTasks, "read", t.AdminDetail},
+		{"POST", "/collection-tasks", access.ModuleCollectionTasks, "collect", t.AdminCreate},
+		{"POST", "/collection-tasks/batch", access.ModuleCollectionTasks, "collect", t.AdminBatchCreate},
+		{"POST", "/collection-tasks/image-search/batch", access.ModuleCollectionTasks, "collect", t.AdminBatchCreateImageSearch},
+		{"POST", "/collection-tasks/:taskId/reset", access.ModuleCollectionTasks, "collect", t.AdminReset},
+		{"DELETE", "/collection-tasks/:taskId", access.ModuleCollectionTasks, "delete", t.AdminDelete},
+		{"GET", "/purchase-tasks", access.ModulePurchaseTasks, "read", buy.AdminList},
+		{"GET", "/purchase-tasks/:taskId", access.ModulePurchaseTasks, "read", buy.AdminDetail},
+		{"POST", "/purchase-tasks/batch-preview", access.ModulePurchaseTasks, "purchase", buy.AdminBatchPreview},
+		{"POST", "/purchase-tasks", access.ModulePurchaseTasks, "purchase", buy.AdminCreate},
+		{"POST", "/purchase-tasks/batch", access.ModulePurchaseTasks, "purchase", buy.AdminBatchCreate},
+		{"POST", "/purchase-tasks/batch-retry", access.ModulePurchaseTasks, "purchase", buy.AdminBatchRetry},
+		{"POST", "/purchase-tasks/stock", access.ModulePurchaseTasks, "purchase", buy.AdminCreateStock},
+		{"GET", "/ai-matching-settings", access.ModuleAIMatching, "read", func(c *gin.Context) {
+			db, err := pkg.GetOrm(c)
+			if err != nil {
+				c.JSON(500, gin.H{"code": 500})
+				return
+			}
+			v, err := aimatching.NewService(db).Settings(c.Request.Context())
+			if err != nil {
+				c.JSON(500, gin.H{"code": 500})
+				return
+			}
+			c.JSON(200, gin.H{"code": 200, "data": gin.H{"enabled": v.Enabled}})
+		}},
+	}
+}
+
+func Catalog(routes []Endpoint) []clientkey.Module {
+	mods := map[string]clientkey.Module{}
+	for _, m := range access.GoAutoModules() {
+		mods[m.Key] = clientkey.Module{Key: m.Key, Title: m.Title, Actions: []string{}}
+	}
+	for _, e := range routes {
+		m := mods[e.Module]
+		if e.Capability == "write" {
+			m.Writable = true
+		} else if e.Capability != "read" {
+			found := false
+			for _, a := range m.Actions {
+				if a == e.Capability {
+					found = true
+				}
+			}
+			if !found {
+				m.Actions = append(m.Actions, e.Capability)
+			}
+		}
+		mods[e.Module] = m
+	}
+	out := []clientkey.Module{}
+	for _, g := range access.GoAutoMenuGroups() {
+		for _, key := range g.ModuleKeys {
+			m := mods[key]
+			m.Group = g.Title
+			sort.Strings(m.Actions)
+			out = append(out, m)
+		}
+	}
+	return out
+}
+
+func InitRouter(engine *gin.Engine, auth *jwt.GinJWTMiddleware) {
+	routes := Inventory()
+	catalog := Catalog(routes)
+	h := clientkey.Handler{Modules: catalog}
+	management := engine.Group("/api/admin/v1/client-keys", auth.MiddlewareFunc(), middleware.RequireRoleKey("admin"), NoStore)
+	management.GET("", h.List)
+	management.GET("/modules", h.Catalog)
+	management.POST("", h.Create)
+	management.PATCH("/:keyId/grants", h.Edit)
+	management.POST("/:keyId/disable", h.Disable)
+	for _, e := range routes {
+		engine.Handle(e.Method, "/api/client/v1"+e.Path, Gate(nil, e), e.Handle)
+	}
+}
@@ -0,0 +1,127 @@
+package clientkey
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth/user"
+	"gorm.io/gorm"
+)
+
+type Handler struct {
+	DB      *gorm.DB
+	Modules []Module
+}
+
+func (h Handler) service(c *gin.Context) (Service, bool) {
+	db := h.DB
+	var err error
+	if db == nil {
+		db, err = pkg.GetOrm(c)
+	}
+	if err != nil || db == nil {
+		failure(c, errors.New("database unavailable"))
+		return Service{}, false
+	}
+	c.Header("Cache-Control", "no-store")
+	return Service{db, h.Modules}, true
+}
+func failure(c *gin.Context, err error) {
+	status, message := 500, "服务端处理失败"
+	switch {
+	case errors.Is(err, ErrInvalid):
+		status, message = 422, ErrInvalid.Error()
+	case errors.Is(err, ErrConflict):
+		status, message = 409, ErrConflict.Error()
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		status, message = 404, "密钥不存在"
+	}
+	c.AbortWithStatusJSON(status, gin.H{"code": status, "message": message})
+}
+func (h Handler) Catalog(c *gin.Context) { c.JSON(200, gin.H{"code": 200, "data": h.Modules}) }
+func (h Handler) List(c *gin.Context) {
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	if page < 1 {
+		page = 1
+	}
+	size := 20
+	var total int64
+	var keys []Key
+	if err := s.DB.WithContext(c.Request.Context()).Model(&Key{}).Count(&total).Error; err != nil {
+		failure(c, err)
+		return
+	}
+	if err := s.DB.WithContext(c.Request.Context()).Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&keys).Error; err != nil {
+		failure(c, err)
+		return
+	}
+	items := make([]View, 0, len(keys))
+	for _, k := range keys {
+		items = append(items, view(k))
+	}
+	c.JSON(200, gin.H{"code": 200, "data": gin.H{"items": items, "total": total, "page": page, "pageSize": size}})
+}
+func decode(c *gin.Context, v any) bool {
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 64<<10)
+	d := json.NewDecoder(c.Request.Body)
+	d.DisallowUnknownFields()
+	if d.Decode(v) != nil || d.Decode(&struct{}{}) != io.EOF {
+		failure(c, ErrInvalid)
+		return false
+	}
+	return true
+}
+func (h Handler) Create(c *gin.Context) {
+	var req struct {
+		Name   string  `json:"name"`
+		Grants []Grant `json:"grants"`
+	}
+	if !decode(c, &req) {
+		return
+	}
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	result, secret, err := s.Create(c.Request.Context(), req.Name, req.Grants, uint64(user.GetUserId(c)))
+	if err != nil {
+		failure(c, err)
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": gin.H{"key": result, "secret": secret}})
+}
+func (h Handler) Edit(c *gin.Context)    { h.update(c, false) }
+func (h Handler) Disable(c *gin.Context) { h.update(c, true) }
+func (h Handler) update(c *gin.Context, disable bool) {
+	id, err := strconv.ParseUint(c.Param("keyId"), 10, 64)
+	if err != nil {
+		failure(c, ErrInvalid)
+		return
+	}
+	var req struct {
+		Version uint64  `json:"version"`
+		Grants  []Grant `json:"grants"`
+	}
+	if !decode(c, &req) {
+		return
+	}
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	result, err := s.Update(c.Request.Context(), id, req.Version, uint64(user.GetUserId(c)), req.Grants, disable)
+	if err != nil {
+		failure(c, err)
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": result})
+}
@@ -0,0 +1,222 @@
+// Package clientkey implements independent, revocable client credentials (#237).
+package clientkey
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"sort"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+var ErrInvalid = errors.New("名称或授权无效")
+var ErrConflict = errors.New("密钥已停用或授权已被修改，请刷新后重试")
+var ErrCredential = errors.New("客户端密钥无效或已停用")
+
+type Grant struct {
+	Module  string   `json:"module"`
+	Write   bool     `json:"write"`
+	Actions []string `json:"actions"`
+}
+type Module struct {
+	Key      string   `json:"key"`
+	Title    string   `json:"title"`
+	Group    string   `json:"group"`
+	Writable bool     `json:"writable"`
+	Actions  []string `json:"actions"`
+}
+type Key struct {
+	ID         uint64     `gorm:"primaryKey" json:"id"`
+	Name       string     `gorm:"size:80;not null" json:"name"`
+	Prefix     string     `gorm:"size:24;not null" json:"prefix"`
+	Digest     string     `gorm:"size:64;uniqueIndex;not null" json:"-"`
+	GrantsJSON string     `gorm:"type:text;not null" json:"-"`
+	Enabled    bool       `gorm:"not null" json:"enabled"`
+	Version    uint64     `gorm:"not null" json:"version"`
+	CreatedBy  uint64     `json:"createdBy"`
+	UpdatedBy  uint64     `json:"updatedBy"`
+	CreatedAt  time.Time  `json:"createdAt"`
+	UpdatedAt  time.Time  `json:"updatedAt"`
+	LastUsedAt *time.Time `json:"lastUsedAt"`
+}
+
+func (Key) TableName() string { return "client_api_key" }
+
+type Audit struct {
+	ID        uint64 `gorm:"primaryKey"`
+	KeyID     uint64 `gorm:"index;not null"`
+	ActorID   uint64
+	Event     string `gorm:"size:32;not null"`
+	RequestID string `gorm:"size:32;index"`
+	Method    string `gorm:"size:10"`
+	Route     string `gorm:"size:180"`
+	Status    int
+	Changes   string `gorm:"type:text"`
+	CreatedAt time.Time
+}
+
+func (Audit) TableName() string { return "client_api_key_audit" }
+
+type View struct {
+	Key
+	Grants []Grant `json:"grants"`
+}
+
+func view(k Key) View {
+	var g []Grant
+	_ = json.Unmarshal([]byte(k.GrantsJSON), &g)
+	return View{Key: k, Grants: g}
+}
+
+type Service struct {
+	DB      *gorm.DB
+	Modules []Module
+}
+
+func (s Service) Normalize(in []Grant) ([]Grant, error) {
+	if len(in) == 0 || len(in) > len(s.Modules) {
+		return nil, ErrInvalid
+	}
+	catalog := map[string]Module{}
+	for _, m := range s.Modules {
+		catalog[m.Key] = m
+	}
+	seen := map[string]bool{}
+	out := make([]Grant, 0, len(in))
+	for _, g := range in {
+		m, ok := catalog[g.Module]
+		if !ok || seen[g.Module] || (g.Write && !m.Writable) {
+			return nil, ErrInvalid
+		}
+		seen[g.Module] = true
+		allowed := map[string]bool{}
+		for _, a := range m.Actions {
+			allowed[a] = true
+		}
+		used := map[string]bool{}
+		actions := []string{}
+		for _, a := range g.Actions {
+			if !allowed[a] || used[a] {
+				return nil, ErrInvalid
+			}
+			used[a] = true
+			actions = append(actions, a)
+		}
+		sort.Strings(actions)
+		out = append(out, Grant{g.Module, g.Write, actions})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Module < out[j].Module })
+	return out, nil
+}
+func (s Service) Create(ctx context.Context, name string, grants []Grant, actor uint64) (View, string, error) {
+	name = strings.TrimSpace(name)
+	if name == "" || len([]rune(name)) > 80 || actor == 0 {
+		return View{}, "", ErrInvalid
+	}
+	g, err := s.Normalize(grants)
+	if err != nil {
+		return View{}, "", err
+	}
+	raw, _ := json.Marshal(g)
+	secret := make([]byte, 32)
+	if _, err = rand.Read(secret); err != nil {
+		return View{}, "", err
+	}
+	token := "gak_" + hex.EncodeToString(secret)
+	digest := sha256.Sum256([]byte(token))
+	k := Key{Name: name, Prefix: token[:16], Digest: hex.EncodeToString(digest[:]), GrantsJSON: string(raw), Enabled: true, Version: 1, CreatedBy: actor, UpdatedBy: actor}
+	err = s.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Create(&k).Error; err != nil {
+			return err
+		}
+		return tx.Create(&Audit{KeyID: k.ID, ActorID: actor, Event: "create", Changes: string(raw)}).Error
+	})
+	if err != nil {
+		return View{}, "", err
+	}
+	return view(k), token, nil
+}
+func (s Service) Update(ctx context.Context, id, version, actor uint64, grants []Grant, disable bool) (View, error) {
+	if id == 0 || version == 0 || actor == 0 {
+		return View{}, ErrInvalid
+	}
+	var raw []byte
+	if !disable {
+		g, err := s.Normalize(grants)
+		if err != nil {
+			return View{}, err
+		}
+		raw, _ = json.Marshal(g)
+	}
+	var k Key
+	err := s.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.First(&k, id).Error; err != nil {
+			return err
+		}
+		changes := map[string]any{"version": version + 1, "updated_by": actor, "updated_at": time.Now().UTC()}
+		event := "edit"
+		if disable {
+			changes["enabled"] = false
+			event = "disable"
+		} else {
+			changes["grants_json"] = string(raw)
+		}
+		result := tx.Model(&Key{}).Where("id = ? AND version = ? AND enabled = ?", id, version, true).Updates(changes)
+		if result.Error != nil {
+			return result.Error
+		}
+		if result.RowsAffected != 1 {
+			return ErrConflict
+		}
+		diff, _ := json.Marshal(map[string]string{"before": k.GrantsJSON, "after": string(raw)})
+		if err := tx.Create(&Audit{KeyID: id, ActorID: actor, Event: event, Changes: string(diff)}).Error; err != nil {
+			return err
+		}
+		return tx.First(&k, id).Error
+	})
+	return view(k), err
+}
+func (s Service) Authenticate(ctx context.Context, token string) (Key, error) {
+	if len(token) != 68 || !strings.HasPrefix(token, "gak_") {
+		return Key{}, ErrCredential
+	}
+	if _, err := hex.DecodeString(token[4:]); err != nil {
+		return Key{}, ErrCredential
+	}
+	digest := sha256.Sum256([]byte(token))
+	var k Key
+	err := s.DB.WithContext(ctx).Where("digest = ? AND enabled = ?", hex.EncodeToString(digest[:]), true).First(&k).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return Key{}, ErrCredential
+	}
+	return k, err
+}
+func (k Key) Allows(module, capability string) bool {
+	var grants []Grant
+	if json.Unmarshal([]byte(k.GrantsJSON), &grants) != nil {
+		return false
+	}
+	for _, g := range grants {
+		if g.Module != module {
+			continue
+		}
+		if capability == "read" {
+			return true
+		}
+		if capability == "write" {
+			return g.Write
+		}
+		for _, a := range g.Actions {
+			if a == capability {
+				return true
+			}
+		}
+	}
+	return false
+}
@@ -0,0 +1,115 @@
+package clientkey
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+	"strings"
+	"testing"
+)
+
+func testService(t *testing.T) Service {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sql, _ := db.DB()
+	sql.SetMaxOpenConns(1)
+	t.Cleanup(func() { sql.Close() })
+	if err = db.AutoMigrate(&Key{}, &Audit{}); err != nil {
+		t.Fatal(err)
+	}
+	return Service{db, []Module{{Key: "products", Writable: true, Actions: []string{"delete"}}, {Key: "devices", Actions: []string{}}}}
+}
+func TestCredentialLifecycle(t *testing.T) {
+	s := testService(t)
+	ctx := context.Background()
+	v, token, err := s.Create(ctx, "Tool", []Grant{{Module: "products"}}, 7)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(token) != 68 || v.Digest == token {
+		t.Fatal("invalid credential generation")
+	}
+	wire, _ := json.Marshal(v)
+	if strings.Contains(string(wire), token) || strings.Contains(string(wire), v.Digest) {
+		t.Fatal("secret serialized")
+	}
+	k, err := s.Authenticate(ctx, token)
+	if err != nil || !k.Allows("products", "read") || k.Allows("products", "write") || k.Allows("devices", "read") {
+		t.Fatal("default grants")
+	}
+	updated, err := s.Update(ctx, k.ID, 1, 8, []Grant{{Module: "products", Write: true, Actions: []string{"delete"}}}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	k, err = s.Authenticate(ctx, token)
+	if err != nil || !k.Allows("products", "write") || !k.Allows("products", "delete") || updated.Version != 2 || k.Digest != v.Digest {
+		t.Fatal("edit changed credential or failed to apply grants")
+	}
+	if _, err = s.Update(ctx, k.ID, 1, 8, []Grant{{Module: "devices"}}, false); !errors.Is(err, ErrConflict) {
+		t.Fatal("stale edit accepted")
+	}
+	if _, err = s.Update(ctx, k.ID, 2, 8, nil, true); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = s.Authenticate(ctx, token); !errors.Is(err, ErrCredential) {
+		t.Fatal("disabled credential accepted")
+	}
+	if _, err = s.Update(ctx, k.ID, 3, 8, []Grant{{Module: "products"}}, false); !errors.Is(err, ErrConflict) {
+		t.Fatal("disabled key edited")
+	}
+	var logs []Audit
+	s.DB.Find(&logs)
+	if len(logs) != 3 {
+		t.Fatalf("audit count %d", len(logs))
+	}
+	data, _ := json.Marshal(logs)
+	if strings.Contains(string(data), token) {
+		t.Fatal("secret in audit")
+	}
+}
+func TestInvalidGrantsAndCredentials(t *testing.T) {
+	s := testService(t)
+	for _, g := range [][]Grant{nil, {{Module: "admin"}}, {{Module: "devices", Write: true}}, {{Module: "products", Actions: []string{"payment"}}}, {{Module: "products"}, {Module: "products"}}} {
+		if _, err := s.Normalize(g); err == nil {
+			t.Fatal("invalid grant accepted")
+		}
+	}
+	for _, token := range []string{"", "jwt", "gak_" + strings.Repeat("z", 64), strings.Repeat("a", 68)} {
+		if _, err := s.Authenticate(context.Background(), token); !errors.Is(err, ErrCredential) {
+			t.Fatal("invalid credential accepted")
+		}
+	}
+}
+func TestAuditFailureRollsBack(t *testing.T) {
+	s := testService(t)
+	ctx := context.Background()
+	v, _, err := s.Create(ctx, "Tool", []Grant{{Module: "products"}}, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = s.DB.Migrator().DropTable(&Audit{}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = s.Update(ctx, v.ID, 1, 1, nil, true); err == nil {
+		t.Fatal("audit failure ignored")
+	}
+	var k Key
+	s.DB.First(&k, v.ID)
+	if !k.Enabled || k.Version != 1 {
+		t.Fatal("mutation not rolled back")
+	}
+	if _, secret, err := s.Create(ctx, "Failed", []Grant{{Module: "products"}}, 1); err == nil || secret != "" {
+		t.Fatal("creation audit failure ignored")
+	}
+	var count int64
+	s.DB.Model(&Key{}).Count(&count)
+	if count != 1 {
+		t.Fatal("key persisted without audit")
+	}
+}
@@ -4,6 +4,7 @@ import (
 	"strings"

 	"go-admin/app/goauto/models"
+	"go-admin/app/goauto/sybshop"

 	"gorm.io/gorm"
 )
@@ -41,6 +42,7 @@ func MigratedModels() []any {
 		&models.SYBSpecAIParseWorkItem{},
 		&models.SYBSession{},
 		&models.SYBShop{},
+		&models.SYBProductFilter{},
 		&models.SYBSyncRun{},
 		&models.SYBInnerCodeRecord{},
 		&models.SYBInnerCodeItem{},
@@ -85,6 +87,15 @@ func Migrate(db *gorm.DB) error {
 		Update("task_type", models.PurchaseTaskTypeSYBOrder).Error; err != nil {
 		return err
 	}
+	// #269: seed immutable structure判据 and the initial keyword safety net.
+	seed := []struct{ kind, keyword string }{{"char", "-"}, {"char", "#"}, {"keyword", "CVC短袖220斤"}, {"keyword", "180克純棉圓領短袖"}, {"keyword", "拼色純棉短袖"}, {"keyword", "300斤牛奶絲圓領"}, {"keyword", "印花大學T"}, {"keyword", "印花帽T"}}
+	for _, item := range seed {
+		norm := sybshop.Normalize(item.keyword)
+		row := models.SYBProductFilter{Kind: item.kind, Keyword: item.keyword, NormalizedKeyword: norm, Enabled: true}
+		if err := db.Where("kind = ? AND normalized_keyword = ?", item.kind, norm).FirstOrCreate(&row).Error; err != nil {
+			return err
+		}
+	}
 	return ensureMySQLDirectSelectConstraint(db)
 }

@@ -20,6 +20,7 @@ const (

 	CollectionTaskSourceAdmin            = "admin"
 	CollectionTaskSourceAgentCurrentPage = "agent_current_page"
+	CollectionTaskSourceImageSearch      = "image_search"
 )

 // AgentDevice identifies one Agent installation. InstallID is generated by the
@@ -181,13 +182,14 @@ type CollectionTask struct {
 	Rule                              CollectionRule `json:"-" gorm:"constraint:OnUpdate:CASCADE,OnDelete:RESTRICT"`
 	DeviceID                          *uint64        `json:"deviceId" gorm:"index;uniqueIndex:ux_collection_task_running_device,priority:1"`
 	Device                            *AgentDevice   `json:"-"`
-	Source                            string         `json:"source" gorm:"size:32;not null;default:admin;index;check:ck_collection_task_source,source IN ('admin','agent_current_page')"`
+	Source                            string         `json:"source" gorm:"size:32;not null;default:admin;index;check:ck_collection_task_source,source IN ('admin','agent_current_page','image_search')"`
 	Status                            string         `json:"status" gorm:"size:24;not null;index;check:ck_collection_task_status,status IN ('pending','running','completed','completed_partial','failed')"`
 	ActiveSlot                        *uint8         `json:"-" gorm:"uniqueIndex:ux_collection_task_active_product,priority:2;check:ck_collection_task_active_slot,(status IN ('pending','running') AND active_slot = 1) OR (status NOT IN ('pending','running') AND active_slot IS NULL)"`
 	DeviceRunSlot                     *uint8         `json:"-" gorm:"uniqueIndex:ux_collection_task_running_device,priority:2;check:ck_collection_task_device_run_slot,(status = 'running' AND device_id IS NOT NULL AND device_run_slot = 1) OR (status <> 'running' AND device_run_slot IS NULL)"`
 	URLSnapshot                       string         `json:"urlSnapshot" gorm:"type:text;not null"`
 	GoodsIDSnapshot                   string         `json:"goodsIdSnapshot" gorm:"size:32;not null;index"`
 	RuleSnapshot                      string         `json:"ruleSnapshot" gorm:"type:text;not null"`
+	ImageSearchSnapshot               *string        `json:"-" gorm:"type:text"`
 	AttemptNumber                     int            `json:"attemptNumber" gorm:"not null;default:1;check:ck_collection_task_attempt_number,attempt_number >= 1"`
 	LeaseExpiresAt                    *time.Time     `json:"leaseExpiresAt" gorm:"index"`
 	LeaseVersion                      uint64         `json:"leaseVersion" gorm:"not null;default:0"`
@@ -416,7 +418,8 @@ type ShopeeProduct struct {
 	// PDDProductID stays nullable and must NOT be unique: one Shopee product maps
 	// to at most one PDD product, but several Shopee products may share the same
 	// PDD product.
-	PDDProductID *uint64 `json:"pddProductId" gorm:"index"`
+	PDDProductID      *uint64 `json:"pddProductId" gorm:"index"`
+	ImageSearchLinked bool    `json:"imageSearchLinked" gorm:"not null;default:false;index"`
 	// ImageURL holds the SYB-provided reference image URL. It is written by the
 	// #41 import and may be overridden manually; the product domain never joins
 	// syb_products at read time.
@@ -455,7 +458,7 @@ func (product *ShopeeProduct) BeforeCreate(_ *gorm.DB) error {
 // Parse status for a SYBProduct's productSpec extraction. See sybimport.Parse.
 const (
 	SYBParseStatusSuccess   = "success"
-	SYBParseStatusUncertain = "uncertain"
+	SYBParseStatusUncertain = "uncertain" // legacy input only; persistence normalizes to failed
 	SYBParseStatusFailed    = "failed"
 )

@@ -600,32 +603,61 @@ type SYBShop struct {

 func (SYBShop) TableName() string { return "syb_shop" }

+// SYBProductFilter controls which SYB detail variationSku values are skipped.
+// Char rows are seeded business判据 and may only be enabled/disabled; keyword
+// rows are operator-maintained. DeletedFlag keeps the composite unique key
+// reusable after a keyword is soft-deleted.
+type SYBProductFilter struct {
+	ID   uint64 `json:"id" gorm:"primaryKey;autoIncrement"`
+	Kind string `json:"kind" gorm:"size:16;not null;index;uniqueIndex:ux_syb_product_filter_key,priority:1;check:ck_syb_product_filter_kind,kind IN ('char','keyword')"`
+	// Keyword and NormalizedKeyword are sized, not text: MySQL refuses a
+	// BLOB/TEXT column in a key specification without a prefix length, so the
+	// unique index below cannot be built on a text column (Error 1170). SQLite
+	// accepts either, which is why only a real MySQL migration surfaces this.
+	Keyword           string         `json:"keyword" gorm:"size:200;not null"`
+	NormalizedKeyword string         `json:"normalizedKeyword" gorm:"size:200;not null;uniqueIndex:ux_syb_product_filter_key,priority:2"`
+	Enabled           bool           `json:"enabled" gorm:"not null;default:true"`
+	LastHitAt         *time.Time     `json:"lastHitAt"`
+	LastHitCount      *int           `json:"lastHitCount"`
+	Note              *string        `json:"note" gorm:"type:text"`
+	LastChangedBy     string         `json:"lastChangedBy" gorm:"size:128;not null;default:''"`
+	LastChangedAt     *time.Time     `json:"lastChangedAt"`
+	CreatedAt         time.Time      `json:"createdAt"`
+	UpdatedAt         time.Time      `json:"updatedAt"`
+	DeletedAt         gorm.DeletedAt `json:"-" gorm:"index"`
+	DeletedFlag       uint64         `json:"-" gorm:"not null;default:0;uniqueIndex:ux_syb_product_filter_key,priority:3"`
+}
+
+func (SYBProductFilter) TableName() string { return "syb_product_filter" }
+
 // SYBSyncRun records one asynchronous SYB import. ActiveSlot is set only while
 // a run is active; its unique index is the database-level single-flight guard
 // across processes and is cleared when the run reaches a terminal state.
 type SYBSyncRun struct {
-	ID                uint64     `json:"id" gorm:"primaryKey;autoIncrement"`
-	DateFrom          string     `json:"dateFrom" gorm:"size:10;not null"`
-	DateTo            string     `json:"dateTo" gorm:"size:10;not null"`
-	Status            string     `json:"status" gorm:"size:16;not null;index"`
-	ActiveSlot        *uint8     `json:"-" gorm:"uniqueIndex:ux_syb_sync_run_active_slot"`
-	DaysTotal         int        `json:"daysTotal" gorm:"not null;default:0"`
-	DaysProcessed     int        `json:"daysProcessed" gorm:"not null;default:0"`
-	OrderCount        int        `json:"orderCount" gorm:"not null;default:0"`
-	DetailCount       int        `json:"detailCount" gorm:"not null;default:0"`
-	AcceptedCount     int        `json:"acceptedCount" gorm:"not null;default:0"`
-	ShopSkipped       int        `json:"shopSkipped" gorm:"not null;default:0"`
-	Created           int        `json:"created" gorm:"column:created_count;not null;default:0"`
-	Updated           int        `json:"updated" gorm:"column:updated_count;not null;default:0"`
-	ShopFilterHash    string     `json:"shopFilterHash" gorm:"size:64;not null"`
-	ShopBreakdownJSON string     `json:"-" gorm:"type:text;not null"`
-	ErrorMessage      string     `json:"errorMessage" gorm:"size:1000;not null;default:''"`
-	OperatorID        uint64     `json:"operatorId" gorm:"not null;default:0"`
-	OperatorName      string     `json:"operatorName" gorm:"size:128;not null;default:''"`
-	StartedAt         time.Time  `json:"startedAt" gorm:"not null"`
-	FinishedAt        *time.Time `json:"finishedAt"`
-	CreatedAt         time.Time  `json:"createdAt"`
-	UpdatedAt         time.Time  `json:"updatedAt"`
+	ID                   uint64     `json:"id" gorm:"primaryKey;autoIncrement"`
+	DateFrom             string     `json:"dateFrom" gorm:"size:10;not null"`
+	DateTo               string     `json:"dateTo" gorm:"size:10;not null"`
+	Status               string     `json:"status" gorm:"size:16;not null;index"`
+	ActiveSlot           *uint8     `json:"-" gorm:"uniqueIndex:ux_syb_sync_run_active_slot"`
+	DaysTotal            int        `json:"daysTotal" gorm:"not null;default:0"`
+	DaysProcessed        int        `json:"daysProcessed" gorm:"not null;default:0"`
+	OrderCount           int        `json:"orderCount" gorm:"not null;default:0"`
+	DetailCount          int        `json:"detailCount" gorm:"not null;default:0"`
+	AcceptedCount        int        `json:"acceptedCount" gorm:"not null;default:0"`
+	ShopSkipped          int        `json:"shopSkipped" gorm:"not null;default:0"`
+	CharFilterSkipped    int        `json:"charFilterSkipped" gorm:"column:char_filter_skipped;not null;default:0"`
+	KeywordFilterSkipped int        `json:"keywordFilterSkipped" gorm:"column:keyword_filter_skipped;not null;default:0"`
+	Created              int        `json:"created" gorm:"column:created_count;not null;default:0"`
+	Updated              int        `json:"updated" gorm:"column:updated_count;not null;default:0"`
+	ShopFilterHash       string     `json:"shopFilterHash" gorm:"size:64;not null"`
+	ShopBreakdownJSON    string     `json:"-" gorm:"type:text;not null"`
+	ErrorMessage         string     `json:"errorMessage" gorm:"size:1000;not null;default:''"`
+	OperatorID           uint64     `json:"operatorId" gorm:"not null;default:0"`
+	OperatorName         string     `json:"operatorName" gorm:"size:128;not null;default:''"`
+	StartedAt            time.Time  `json:"startedAt" gorm:"not null"`
+	FinishedAt           *time.Time `json:"finishedAt"`
+	CreatedAt            time.Time  `json:"createdAt"`
+	UpdatedAt            time.Time  `json:"updatedAt"`
 }

 func (SYBSyncRun) TableName() string { return "syb_sync_run" }
@@ -422,6 +422,14 @@ func (s *Service) previewFromDataset(id uint64, dataset batchPreviewDataset, gua
 		}
 		// #190：映射不完整不再拦截，任务以 unresolved 建立并交由规格探测解析。
 	}
+	// Readiness must agree with the mapping shown in the product detail.  A
+	// deterministic suggestion is only a preview; it is not a persisted,
+	// confirmed mapping and must not make the row appear purchase-ready.
+	if source == "unresolved" || !mappingTargetsValid(candidates, syb.TargetColor, syb.TargetSize, item.MappedColor, item.MappedSize) {
+		// Keep Eligible for the existing live-probe path, but expose the
+		// unresolved state so the UI cannot label the row purchase-ready.
+		item.ReasonCode, item.Reason, item.NextAction = CodeMappingRequired, "采购规格尚未匹配并保存", "open_mapping"
+	}
 	reference, minPrice, maxPrice, err := purchasePriceRange(pdd.SpecsJSON, item.MappedColor, guard)
 	if err != nil {
 		item.ReasonCode, item.Reason, item.NextAction = "PDD_PRICE_MISSING", err.Error(), "open_pdd"
@@ -142,7 +142,7 @@ func TestBatchSpecMatchPersistsExactMatchButPurchaseDoesNotWaitForIt(t *testing.
 	service.Matcher = matcher

 	before, err := service.BatchPreview(context.Background(), BatchPreviewRequest{SYBProductIDs: []uint64{f.syb.ID}})
-	if err != nil || len(before.Items) != 1 || !before.Items[0].Eligible || !before.Items[0].AIMatchEligible || before.Items[0].ProcessStage != ProcessStagePurchaseReady {
+	if err != nil || len(before.Items) != 1 || !before.Items[0].Eligible || !before.Items[0].AIMatchEligible || before.Items[0].ProcessStage != ProcessStageColorMapping {
 		t.Fatalf("live-probe purchase was incorrectly gated by persisted mapping: %+v err=%v", before, err)
 	}

@@ -181,7 +181,7 @@ func TestExtractedUncertainSpecsCanBeMatchedBeforePurchase(t *testing.T) {
 	service.Matcher = matcher

 	before, err := service.BatchPreview(context.Background(), BatchPreviewRequest{SYBProductIDs: []uint64{f.syb.ID}})
-	if err != nil || len(before.Items) != 1 || !before.Items[0].Eligible || !before.Items[0].AIMatchEligible || before.Items[0].ProcessStage != ProcessStagePurchaseReady {
+	if err != nil || len(before.Items) != 1 || !before.Items[0].Eligible || !before.Items[0].AIMatchEligible || before.Items[0].ProcessStage != ProcessStageColorMapping {
 		t.Fatalf("extracted uncertain specs were not purchase-ready for live probing: %+v err=%v", before, err)
 	}
 	matched, err := service.BatchSpecMatch(context.Background(), BatchSpecMatchRequest{SYBProductIDs: []uint64{f.syb.ID}})
@@ -231,7 +231,7 @@ func TestBatchPreviewExposesExplicitAIMatchEligibility(t *testing.T) {
 		t.Fatalf("preview failed: %+v err=%v", preview, err)
 	}
 	item := preview.Items[0]
-	if !item.AIMatchEligible || item.AIMatchDisabledReason != "" || !item.Eligible || item.ProcessStage != ProcessStagePurchaseReady {
+	if !item.AIMatchEligible || item.AIMatchDisabledReason != "" || !item.Eligible || item.ProcessStage != ProcessStageColorMapping {
 		t.Fatalf("explicit AI eligibility mismatch: %+v", item)
 	}
 }
@@ -314,7 +314,7 @@ func TestBatchPreviewBulkLoadsAndNeverCallsAIMatcher(t *testing.T) {
 		t.Fatalf("batch preview used %d queries, want 7 bounded queries including collection eligibility and current purchase rule", queries)
 	}
 	if len(response.Items) != 2 || !response.Items[0].Eligible || !response.Items[1].Eligible || response.EligibleCount != 2 {
-		t.Fatalf("unresolved rows must be ready for mandatory live probing: %+v", response)
+		t.Fatalf("unresolved rows remain eligible for live probing but are not purchase-ready: %+v", response)
 	}
 }

@@ -329,7 +329,7 @@ func TestBatchPreviewAllowsIncompleteArchivedCandidatesForMandatoryLiveProbe(t *
 	}

 	response, err := testService(db).BatchPreview(context.Background(), BatchPreviewRequest{SYBProductIDs: []uint64{fixture.syb.ID}})
-	if err != nil || len(response.Items) != 1 || !response.Items[0].Eligible || response.Items[0].ProcessStage != ProcessStagePurchaseReady {
+	if err != nil || len(response.Items) != 1 || !response.Items[0].Eligible || response.Items[0].ProcessStage != ProcessStageManualAction {
 		t.Fatalf("incomplete archive blocked live probe task creation: %+v err=%v", response, err)
 	}
 }
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"go-admin/common/clientprincipal"
 	"io"
 	"net/http"
 	"strconv"
@@ -470,6 +471,9 @@ func writeAdminReplay(c *gin.Context, data any, replayed bool) {
 }

 func allowedOperator(c *gin.Context) bool {
+	if _, ok := clientprincipal.Get(c); ok {
+		return true
+	}
 	role, _ := jwt.ExtractClaims(c)["rolekey"].(string)
 	if role == "admin" || role == "purchaser" {
 		return true
@@ -544,6 +548,9 @@ func writeError(c *gin.Context, err error) {
 	c.JSON(status, gin.H{"code": code, "message": msg, "retryable": retryable})
 }
 func operatorID(c *gin.Context) uint64 {
+	if id, ok := clientprincipal.Get(c); ok {
+		return id.AuthorizedBy
+	}
 	claims := jwt.ExtractClaims(c)
 	switch v := claims["identity"].(type) {
 	case float64:
@@ -8,6 +8,7 @@ import (
 	"errors"
 	"strings"
 	"time"
+	"unicode"

 	"go-admin/app/goauto/aimatching"
 	"go-admin/app/goauto/device"
@@ -397,6 +398,11 @@ func (s *Service) SubmitResult(ctx context.Context, taskID uint64, req ResultReq
 		case "failed":
 			next = models.PurchaseTaskStatusFailed
 			a.Status = models.PurchaseAttemptStatusFailed
+			// `[必须]` Write the failure onto the attempt too, not only the task.
+			// Without it every attempt produced by this branch carries a NULL
+			// error_code, so attempt-level statistics silently omit them — on
+			// production the spec-panel failures were invisible that way (#271).
+			a.ErrorCode, a.ErrorMessage = &req.ErrorCode, &req.ErrorMessage
 			t.ErrorCode = &req.ErrorCode
 			t.ErrorMessage = &req.ErrorMessage
 			t.ActualUnitPriceCent = req.ActualUnitPriceCent
@@ -447,6 +453,26 @@ var allowedOrderUnknownFailures = map[string]string{
 	CodeOrderUnpaidMissing:  "订单详情缺少待付款状态证据",
 }

+// orderFailureMessageLimit matches the error_message column width on both
+// purchase_task and purchase_task_attempt (size:1000). The canonical sentence is
+// never sacrificed to fit: only the appended agent evidence is truncated.
+const orderFailureMessageLimit = 1000
+
+// normalizeOrderUnknownFailure keeps the canonical sentence as the message
+// people read, and appends the agent's own diagnostic behind it.
+//
+// `[必须]` The canonical text stays authoritative. The agent supplies free text,
+// so it must not become the primary description of what happened, and the UI
+// wording has to stay stable per error code.
+//
+// `[必须]` The agent's evidence is nevertheless kept. Discarding it left the
+// PAYMENT_REPEATED failures unanalysable: #210 computes paymentBackAttempts and
+// consecutivePaymentSamplesAfterBack, the agent reports them, and none of the 61
+// production failures between 2026-09-07 and 09-11 carried either value, so
+// "Back did not work", "the page rendered slower than the ~1.1s window" and "the
+// page was the order page but no marker matched" could not be told apart. The
+// sibling "failed" branch already stores agent text verbatim, so keeping it here
+// introduces no new trust assumption (#271).
 func normalizeOrderUnknownFailure(code, message string) (string, string, error) {
 	code, message = strings.TrimSpace(code), strings.TrimSpace(message)
 	if code == "" && message == "" {
@@ -456,7 +482,53 @@ func normalizeOrderUnknownFailure(code, message string) (string, string, error)
 	if !ok || message == "" {
 		return "", "", fail(CodeInvalidRequest, "订单核单失败阶段无效")
 	}
-	return code, canonicalMessage, nil
+	return code, appendAgentEvidence(canonicalMessage, message), nil
+}
+
+// appendAgentEvidence joins the canonical sentence with the agent's diagnostic.
+//
+// The evidence is flattened to a single line first: agent text reaches the
+// purchase list, task detail and exports, and an embedded newline or control
+// character would break those renderings.
+func appendAgentEvidence(canonical, evidence string) string {
+	evidence = flattenAgentEvidence(evidence)
+	if evidence == "" || evidence == canonical {
+		return canonical
+	}
+	room := orderFailureMessageLimit - len([]rune(canonical)) - 1
+	if room <= 0 {
+		return canonical
+	}
+	if runes := []rune(evidence); len(runes) > room {
+		if room <= 1 {
+			return canonical
+		}
+		evidence = string(runes[:room-1]) + "…"
+	}
+	return canonical + " " + evidence
+}
+
+// flattenAgentEvidence removes control characters and collapses whitespace so
+// the appended text is always one readable line.
+func flattenAgentEvidence(evidence string) string {
+	var b strings.Builder
+	lastWasSpace := false
+	for _, r := range evidence {
+		switch {
+		case r == 0xFEFF:
+			// Zero-width no-break space: invisible, so drop it rather than
+			// turning it into a space that would look like a stray gap.
+		case unicode.IsControl(r) || unicode.IsSpace(r):
+			if !lastWasSpace {
+				b.WriteRune(' ')
+				lastWasSpace = true
+			}
+		default:
+			b.WriteRune(r)
+			lastWasSpace = false
+		}
+	}
+	return strings.TrimSpace(b.String())
 }

 func (s *Service) ApplySpecDecision(ctx context.Context, taskID uint64, req SpecDecisionRequest) (models.PurchaseTask, bool, error) {
@@ -0,0 +1,155 @@
+package purchase
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"go-admin/app/goauto/models"
+
+	"github.com/google/uuid"
+)
+
+// 这条诊断就是 #210 让 Agent 算出来、却一直没能落库的那一段。
+const paymentRepeatAgentMessage = "支付页安全返回后持续无订单证据，已停止自动核单" +
+	"[paymentBackAttempts=1;consecutivePaymentSamplesAfterBack=3]"
+
+func TestNormalizeOrderUnknownFailureKeepsCanonicalAndAgentEvidence(t *testing.T) {
+	code, message, err := normalizeOrderUnknownFailure(CodeOrderPaymentRepeat, paymentRepeatAgentMessage)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if code != CodeOrderPaymentRepeat {
+		t.Fatalf("code changed: %q", code)
+	}
+	canonical := allowedOrderUnknownFailures[CodeOrderPaymentRepeat]
+	if !strings.HasPrefix(message, canonical) {
+		t.Fatalf("canonical sentence must lead the message, got %q", message)
+	}
+	// 没有这两个值就无法区分「Back 没生效」「渲染慢于窗口」「关键词没匹配」。
+	for _, want := range []string{"paymentBackAttempts=1", "consecutivePaymentSamplesAfterBack=3"} {
+		if !strings.Contains(message, want) {
+			t.Fatalf("agent evidence %q missing from %q", want, message)
+		}
+	}
+}
+
+func TestNormalizeOrderUnknownFailureFlattensAndBounds(t *testing.T) {
+	canonical := allowedOrderUnknownFailures[CodeOrderPaymentRepeat]
+
+	t.Run("控制字符和换行被压平", func(t *testing.T) {
+		_, message, err := normalizeOrderUnknownFailure(CodeOrderPaymentRepeat, "证据行一\n\t行二\r\n行三\ufeff")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if strings.ContainsAny(message, "\n\r\t") {
+			t.Fatalf("message must stay on one line: %q", message)
+		}
+		if !strings.Contains(message, "证据行一 行二 行三") {
+			t.Fatalf("whitespace should collapse to single spaces: %q", message)
+		}
+	})
+
+	t.Run("超长证据被截断且固定文案完整保留", func(t *testing.T) {
+		_, message, err := normalizeOrderUnknownFailure(CodeOrderPaymentRepeat, strings.Repeat("证", 4000))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !strings.HasPrefix(message, canonical) {
+			t.Fatalf("canonical sentence was sacrificed to fit: %q", message)
+		}
+		if n := len([]rune(message)); n > orderFailureMessageLimit {
+			t.Fatalf("message is %d runes, column holds %d", n, orderFailureMessageLimit)
+		}
+		if !strings.HasSuffix(message, "…") {
+			t.Fatalf("truncation should be visible: %q", message[len(message)-30:])
+		}
+	})
+
+	t.Run("空消息行为不变", func(t *testing.T) {
+		if _, _, err := normalizeOrderUnknownFailure(CodeOrderPaymentRepeat, ""); code(err) != CodeInvalidRequest {
+			t.Fatalf("empty agent message must still be rejected, got %v", err)
+		}
+	})
+
+	t.Run("未批准的错误码仍被拒绝", func(t *testing.T) {
+		if _, _, err := normalizeOrderUnknownFailure("UNAPPROVED", "whatever"); code(err) != CodeInvalidRequest {
+			t.Fatalf("unapproved code must be rejected, got %v", err)
+		}
+	})
+
+	t.Run("证据与固定文案相同时不重复拼接", func(t *testing.T) {
+		_, message, err := normalizeOrderUnknownFailure(CodeOrderPaymentRepeat, canonical)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if message != canonical {
+			t.Fatalf("identical evidence should not be appended twice: %q", message)
+		}
+	})
+}
+
+// 端到端确认证据真的写进了两张表，而不是只在函数里拼对了。
+func TestSubmitOrderResultUnknownPersistsAgentEvidence(t *testing.T) {
+	db := testDB(t)
+	f := seed(t, db, liveCaps(), true)
+	s := testService(db)
+	task, _ := createLive(t, s, f)
+	started := startLivePurchaseAfterProbe(t, s, f, task)
+	if _, err := s.MarkOrderSubmitStarted(context.Background(), task.ID, ActionRequest{RequestID: uuid.NewString()}, f.token); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.SubmitResult(context.Background(), task.ID, ResultRequest{
+		RequestID: uuid.NewString(), TaskAttemptID: started.TaskAttemptID, ResultType: "order_result_unknown",
+		ErrorCode: CodeOrderPaymentRepeat, ErrorMessage: paymentRepeatAgentMessage,
+	}, f.token); err != nil {
+		t.Fatal(err)
+	}
+
+	var saved models.PurchaseTask
+	if err := db.First(&saved, task.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	var attempt models.PurchaseTaskAttempt
+	if err := db.Where("task_id = ?", task.ID).Order("attempt_number DESC, id DESC").First(&attempt).Error; err != nil {
+		t.Fatal(err)
+	}
+	for name, got := range map[string]*string{"task": saved.ErrorMessage, "attempt": attempt.ErrorMessage} {
+		if got == nil {
+			t.Fatalf("%s kept no error message", name)
+		}
+		if !strings.Contains(*got, "consecutivePaymentSamplesAfterBack=3") {
+			t.Fatalf("%s dropped the agent evidence: %q", name, *got)
+		}
+	}
+}
+
+// "failed" 分支过去只写任务不写 attempt，attempt.error_code 全是 NULL，
+// 导致按 attempt 统计时这些失败是隐形的（线上规格失败即如此）。
+func TestSubmitFailedResultRecordsErrorOnAttempt(t *testing.T) {
+	db := testDB(t)
+	f := seed(t, db, liveCaps(), true)
+	s := testService(db)
+	task, _ := createLive(t, s, f)
+	started := startLivePurchaseAfterProbe(t, s, f, task)
+
+	const failCode = "PURCHASE_SPEC_PANEL_EVIDENCE_NOT_MATCHED"
+	const failMessage = "规格入口点击后页面已变化，但规格面板强证据不足 [type=UNKNOWN;scrollables=1]"
+	if _, err := s.SubmitResult(context.Background(), task.ID, ResultRequest{
+		RequestID: uuid.NewString(), TaskAttemptID: started.TaskAttemptID, ResultType: "failed",
+		ErrorCode: failCode, ErrorMessage: failMessage,
+	}, f.token); err != nil {
+		t.Fatal(err)
+	}
+
+	var attempt models.PurchaseTaskAttempt
+	if err := db.Where("task_id = ?", task.ID).Order("attempt_number DESC, id DESC").First(&attempt).Error; err != nil {
+		t.Fatal(err)
+	}
+	if attempt.ErrorCode == nil || *attempt.ErrorCode != failCode {
+		t.Fatalf("attempt error code not recorded: %+v", attempt.ErrorCode)
+	}
+	if attempt.ErrorMessage == nil || *attempt.ErrorMessage != failMessage {
+		t.Fatalf("attempt error message not recorded: %+v", attempt.ErrorMessage)
+	}
+}
@@ -0,0 +1,44 @@
+package purchase
+
+import (
+	"context"
+
+	"go-admin/app/goauto/shopeeproduct"
+	"gorm.io/gorm"
+)
+
+// Called inside the link transaction, after locking the SYB and Shopee rows.
+// Reuse the authoritative stage calculation, without AI or task creation.
+func ValidateQuickReplacement(ctx context.Context, tx *gorm.DB, id uint64) error {
+	s := NewService(tx)
+	dataset, err := s.loadBatchPreviewDataset(ctx, []uint64{id})
+	if err != nil {
+		return err
+	}
+	guard, _, err := s.readOnlyPriceGuard(ctx)
+	if err != nil {
+		return err
+	}
+	preview := s.previewFromDataset(id, dataset, guard)
+	qualification := aiMatchQualificationForDataset(id, dataset)
+	preview.AIMatchEligible = qualification.Eligible
+	preview.AIMatchDisabledReason = qualification.DisabledReason
+	stage := processStageFromDataset(id, dataset, preview)
+	syb := dataset.sybByID[id]
+	disabled := false
+	if syb.ShopeeProductID != nil {
+		shopee := dataset.shopeeByID[*syb.ShopeeProductID]
+		if shopee.PDDProductID != nil {
+			pdd := dataset.pddByID[*shopee.PDDProductID]
+			disabled = pdd.Status == "disabled"
+			if _, active := dataset.activeCollectionByPDD[pdd.ID]; active {
+				return &shopeeproduct.ServiceError{Code: shopeeproduct.CodeLinkConflict, Message: "商品正在采集，请结束后刷新再操作"}
+			}
+		}
+	}
+	if stage.NextAction == "open_pdd" && (stage.Stage == ProcessStagePDDPending || stage.Stage == ProcessStagePDDCollectionFail ||
+		(stage.Stage == ProcessStageManualAction && (disabled || preview.ReasonCode == "PDD_PRICE_MISSING"))) {
+		return nil
+	}
+	return &shopeeproduct.ServiceError{Code: shopeeproduct.CodeLinkConflict, Message: "处理阶段已变化，当前不能一键替换，请刷新列表"}
+}
@@ -0,0 +1,44 @@
+package purchase
+
+import (
+	"context"
+	"testing"
+
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+)
+
+func TestQuickReplacementUsesCurrentStage(t *testing.T) {
+	for _, name := range []string{"pending", "disabled", "price-missing", "ready", "parse-failed", "collecting", "purchase-pending", "purchase-running", "order-created", "order-unknown"} {
+		t.Run(name, func(t *testing.T) {
+			db := testDB(t)
+			f := seed(t, db, liveCaps(), true)
+			allow := name == "pending" || name == "disabled" || name == "price-missing"
+			switch name {
+			case "pending", "disabled":
+				db.Model(&f.pdd).Update("status", name)
+			case "ready":
+				setCollectedPDDPrice(t, db, f.pdd.ID)
+			case "parse-failed":
+				db.Model(&f.syb).Update("parse_status", "failed")
+			case "collecting":
+				rule := models.CollectionRule{Name: "synthetic", ContentJSON: "{}"}
+				if err := db.Create(&rule).Error; err != nil {
+					t.Fatal(err)
+				}
+				if err := db.Create(&models.CollectionTask{DeviceID: &f.device.ID, PDDProductID: &f.pdd.ID, RuleID: rule.ID, Status: models.TaskStatusRunning, RuleSnapshot: "{}"}).Error; err != nil {
+					t.Fatal(err)
+				}
+			case "purchase-pending", "purchase-running", "order-created", "order-unknown":
+				status := map[string]string{"purchase-pending": "pending", "purchase-running": "running", "order-created": "order_created", "order-unknown": "order_result_unknown"}[name]
+				if err := db.Session(&gorm.Session{SkipHooks: true}).Create(&models.PurchaseTask{ExecutionMode: "live", Quantity: 1, SYBProductID: &f.syb.ID, PDDProductID: f.pdd.ID, Status: status, CreateRequestID: name}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			err := ValidateQuickReplacement(context.Background(), db, f.syb.ID)
+			if (err == nil) != allow {
+				t.Fatalf("allowed=%v: %v", allow, err)
+			}
+		})
+	}
+}
@@ -131,6 +131,12 @@ func (service *Service) suggestMappings(ctx context.Context, id uint64, requestC
 				item.Reason = "保留已确认映射"
 				item.Apply = true
 				response.MatchedCount++
+			case role == RoleColor && deterministicColorMatch(value.Name, candidateNames) != "":
+				item.PDDValue = deterministicColorMatch(value.Name, candidateNames)
+				item.Status = "matched"
+				item.Reason = "格式统一后唯一匹配"
+				item.Apply = true
+				response.MatchedCount++
 			case role == RoleSize && deterministicSizeMatch(value.Name, candidateNames) != "":
 				item.PDDValue = deterministicSizeMatch(value.Name, candidateNames)
 				item.Status = "matched"
@@ -237,6 +243,15 @@ func deterministicSizeMatch(value string, candidates []string) string {
 	return match.MappedSize
 }

+// Keep the original candidate label; normalization is only a comparison key.
+func deterministicColorMatch(value string, candidates []string) string {
+	match, ok := aimatching.DeterministicMatch(aimatching.MatchRequest{TargetColor: value, Colors: candidates})
+	if !ok {
+		return ""
+	}
+	return match.MappedColor
+}
+
 // aiSuggestErrorMessage turns an aimatching error into a message safe to
 // return to the admin UI (no credential, no raw provider body).
 func aiSuggestErrorMessage(err error) string {
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"strings"
+	"time"

 	"go-admin/app/goauto/aimatching"
 	"go-admin/app/goauto/models"
@@ -48,7 +49,20 @@ type autoMatchRef struct {
 // before the transaction; the transaction rechecks the complete spec context
 // and PDD candidate set so a stale decision can never be written.
 func (service *Service) AutoMatchMappings(ctx context.Context, id uint64, request AutoMatchRequest) (AutoMatchResponse, error) {
-	ctx, cancel := context.WithTimeout(ctx, aimatching.MaxProviderTimeout)
+	started := time.Now()
+	// Bound the initial settings lookup too. This budget is specific to this
+	// composite endpoint; other AI operations retain their existing limits.
+	ctx, cancel := context.WithTimeout(ctx, 1210*time.Second)
+	defer cancel()
+	seconds, err := service.autoMatchTimeout(ctx)
+	if err != nil {
+		return AutoMatchResponse{}, err
+	}
+	return service.autoMatchMappings(ctx, id, request, time.Duration(seconds)*time.Second-time.Since(started))
+}
+
+func (service *Service) autoMatchMappings(ctx context.Context, id uint64, request AutoMatchRequest, budget time.Duration) (AutoMatchResponse, error) {
+	ctx, cancel := context.WithTimeout(ctx, budget)
 	defer cancel()

 	requestID := strings.TrimSpace(request.RequestID)
@@ -248,6 +262,21 @@ func (service *Service) AutoMatchMappings(ctx context.Context, id uint64, reques
 	return response, nil
 }

+func autoMatchBudgetSeconds(providerSeconds int) int {
+	if providerSeconds < 3 || providerSeconds > 600 {
+		providerSeconds = 15 // same default as AI settings; never allow unbounded waits
+	}
+	return providerSeconds*2 + 10
+}
+
+func (service *Service) autoMatchTimeout(ctx context.Context) (int, error) {
+	settings, err := aimatching.NewService(service.DB).Settings(ctx)
+	if err != nil {
+		return 0, internalError(err)
+	}
+	return autoMatchBudgetSeconds(settings.TimeoutSeconds), nil
+}
+
 func autoMatchRefs(specs []SpecDimension, role string) []autoMatchRef {
 	refs := make([]autoMatchRef, 0)
 	for _, dimension := range specs {
@@ -10,6 +10,7 @@ import (
 	"strings"
 	"time"

+	"go-admin/app/goauto/aimatching"
 	"go-admin/app/goauto/models"

 	"github.com/google/uuid"
@@ -166,7 +167,7 @@ func (service *Service) ProcessAutoMatchRun(ctx context.Context, runID uint64) e
 		}
 		processed++
 		service.renewAutoMatchRun(run)
-		response, matchErr := service.AutoMatchMappings(ctx, product.ID, AutoMatchRequest{RequestID: uuid.NewString(), SpecContextVersion: fingerprint[:64]})
+		response, matchErr := service.autoMatchMappings(ctx, product.ID, AutoMatchRequest{RequestID: uuid.NewString(), SpecContextVersion: fingerprint[:64]}, aimatching.MaxProviderTimeout)
 		// fingerprint begins with the 64-character context version.
 		postFingerprint := fingerprint
 		if next, _, nextErr := service.autoMatchEligibility(ctx, product); nextErr == nil && next != "" {
@@ -0,0 +1,91 @@
+package shopeeproduct
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+func TestAutoMatchBudgetFollowsProviderSetting(t *testing.T) {
+	for _, tc := range []struct{ ai, total int }{{3, 16}, {60, 130}, {180, 370}, {600, 1210}, {0, 40}, {601, 40}} {
+		if got := autoMatchBudgetSeconds(tc.ai); got != tc.total {
+			t.Fatalf("AI %d: got %d want %d", tc.ai, got, tc.total)
+		}
+	}
+	db := openTestDB(t)
+	setting := seedEnabledAISetting(t, "https://example.invalid", 0.9)
+	setting.TimeoutSeconds = 60
+	if err := db.Create(&setting).Error; err != nil {
+		t.Fatal(err)
+	}
+	s := NewService(db)
+	created, err := s.Create(context.Background(), CreateRequest{RequestID: uuid.NewString(), ShopeeItemID: "budget-test"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	detail, err := s.DetailWithAutoMatchBudget(context.Background(), created.Product.ID)
+	if err != nil || detail.AutoMatchTimeoutSeconds != 130 {
+		t.Fatalf("budget detail: %d %v", detail.AutoMatchTimeoutSeconds, err)
+	}
+	body, _ := json.Marshal(detail)
+	if strings.Contains(string(body), "apiKey") || strings.Contains(string(body), "example.invalid") {
+		t.Fatal("AI configuration leaked")
+	}
+	if err := db.Model(&setting).Update("timeout_seconds", 180).Error; err != nil {
+		t.Fatal(err)
+	}
+	detail, err = s.DetailWithAutoMatchBudget(context.Background(), created.Product.ID)
+	if err != nil || detail.AutoMatchTimeoutSeconds != 370 {
+		t.Fatalf("fresh budget: %d %v", detail.AutoMatchTimeoutSeconds, err)
+	}
+}
+
+func TestAutoMatchCompositeBudgetCancelsWithoutSaving(t *testing.T) {
+	var calls atomic.Int32
+	responder := chatCompletionResponder(`{"suggestions":[{"sourceId":"s1","candidateId":"c1","confidence":0.96,"reason":"unique match"}]}`)
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if calls.Add(1) == 1 {
+			responder(w, r)
+			return
+		}
+		select {
+		case <-r.Context().Done():
+		case <-time.After(time.Second):
+		}
+	}))
+	defer provider.Close()
+	db := openTestDB(t)
+	pdd := seedPDDProduct(t, db, "active")
+	setting := seedEnabledAISetting(t, provider.URL, 0.9)
+	if err := db.Create(&setting).Error; err != nil {
+		t.Fatal(err)
+	}
+	s := NewService(db)
+	created, err := s.Create(context.Background(), CreateRequest{RequestID: uuid.NewString(), ShopeeItemID: "budget-cancel", PDDProductID: &pdd.ID,
+		Specs: []SpecDimension{{Name: "颜色", Role: RoleColor, Values: []SpecValue{{Name: "深黑", Source: ValueSourceImport}}}, {Name: "尺码", Role: RoleSize, Values: []SpecValue{{Name: "加大码", Source: ValueSourceImport}}}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	started := time.Now()
+	_, err = s.autoMatchMappings(context.Background(), created.Product.ID, AutoMatchRequest{RequestID: uuid.NewString(), SpecContextVersion: created.Product.SpecContextVersion}, 100*time.Millisecond)
+	if err == nil || time.Since(started) > time.Second {
+		t.Fatalf("budget not enforced: %v", err)
+	}
+	if calls.Load() != 2 {
+		t.Fatalf("expected sequential color and size calls, got %d", calls.Load())
+	}
+	detail, err := s.Detail(context.Background(), created.Product.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if detail.Product.Specs[0].Values[0].Mapping != nil {
+		t.Fatal("timed-out operation saved mappings")
+	}
+}
@@ -0,0 +1,100 @@
+package shopeeproduct
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/uuid"
+	"go-admin/app/goauto/models"
+)
+
+func TestColorNormalizedMatchWithoutAIKeepsOriginalLabels(t *testing.T) {
+	db := openTestDB(t)
+	pdd := seedPDDProduct(t, db, "active")
+	pdd.SpecsJSON = `[{"name":"颜色","role":"color","values":[{"name":"260#大红","selectable":true},{"name":"260#墨绿","selectable":true},{"name":"AbC黑色","selectable":true}]}]`
+	if err := db.Save(&pdd).Error; err != nil {
+		t.Fatal(err)
+	}
+	service := NewService(db)
+	sources := []string{"260#大紅", "260#墨綠", "ａｂｃ 黑色"}
+	targets := []string{"260#大红", "260#墨绿", "AbC黑色"}
+	values := []SpecValue{}
+	for _, name := range sources {
+		values = append(values, SpecValue{Name: name, Source: ValueSourceImport})
+	}
+	created, err := service.Create(context.Background(), CreateRequest{RequestID: uuid.NewString(), ShopeeItemID: "normalized-color", PDDProductID: &pdd.ID, Specs: []SpecDimension{{Name: "颜色", Role: RoleColor, Values: values}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	preview, err := service.SuggestColorMappings(context.Background(), created.Product.ID, created.Product.SpecContextVersion)
+	if err != nil {
+		t.Fatalf("exact colors must not require AI: %v", err)
+	}
+	for i, item := range preview.Items {
+		if item.Status != "matched" || !item.Apply || item.ValueName != sources[i] || item.PDDValue != targets[i] {
+			t.Fatalf("unexpected preview: %+v", item)
+		}
+	}
+	if len(preview.Items) != 3 || preview.MatchedCount != 3 {
+		t.Fatal("missing exact matches")
+	}
+	var stored models.ShopeeProduct
+	if err := db.First(&stored, created.Product.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	specs, err := Unmarshal(stored.SpecsJSON)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, value := range specs[0].Values {
+		if value.Mapping != nil {
+			t.Fatal("preview wrote mappings")
+		}
+	}
+	result, err := service.AutoMatchMappings(context.Background(), created.Product.ID, AutoMatchRequest{RequestID: uuid.NewString(), SpecContextVersion: created.Product.SpecContextVersion})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.ConfirmedCount != 3 || result.UnmatchedCount != 0 {
+		t.Fatalf("unexpected counts: %+v", result)
+	}
+	for i, value := range result.Product.Specs[0].Values {
+		m := value.Mapping
+		if value.Name != sources[i] || m == nil || m.PDDValue != targets[i] || m.Source != MappingSourceExactMatch || m.Status != MappingStatusConfirmed {
+			t.Fatalf("incorrect persisted mapping: %+v", value)
+		}
+	}
+	var after models.PDDProduct
+	if err := db.First(&after, pdd.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if after.SpecsJSON != pdd.SpecsJSON {
+		t.Fatal("changed original PDD specs")
+	}
+}
+
+func TestColorNormalizedAmbiguityAndUnavailableStillRequireAI(t *testing.T) {
+	for _, tc := range []struct{ name, source, specs string }{
+		{"ambiguous", "大紅", `[{"name":"颜色","role":"color","values":[{"name":"大红","selectable":true},{"name":"大紅","selectable":true}]}]`},
+		{"unavailable", "大紅", `[{"name":"颜色","role":"color","values":[{"name":"大红","selectable":false},{"name":"黑色","selectable":true}]}]`},
+		{"unmatched", "深紅", `[{"name":"颜色","role":"color","values":[{"name":"大红","selectable":true}]}]`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			db := openTestDB(t)
+			pdd := seedPDDProduct(t, db, "active")
+			pdd.SpecsJSON = tc.specs
+			if err := db.Save(&pdd).Error; err != nil {
+				t.Fatal(err)
+			}
+			service := NewService(db)
+			created, err := service.Create(context.Background(), CreateRequest{RequestID: uuid.NewString(), ShopeeItemID: tc.name, PDDProductID: &pdd.ID, Specs: []SpecDimension{{Name: "颜色", Role: RoleColor, Values: []SpecValue{{Name: tc.source, Source: ValueSourceImport}}}}})
+			if err != nil {
+				t.Fatal(err)
+			}
+			_, err = service.SuggestColorMappings(context.Background(), created.Product.ID, created.Product.SpecContextVersion)
+			if err == nil || errCode(t, err) != CodeAIUnavailable {
+				t.Fatalf("must fall back to AI, not guess: %v", err)
+			}
+		})
+	}
+}
@@ -14,7 +14,10 @@ import (
 	"gorm.io/gorm"
 )

-type Handler struct{ DB *gorm.DB }
+type Handler struct {
+	DB                     *gorm.DB
+	ReplacementEligibility ReplacementEligibility
+}

 func (handler Handler) List(c *gin.Context) {
 	page, err := queryInt(c.Query("page"), 1)
@@ -31,8 +34,18 @@ func (handler Handler) List(c *gin.Context) {
 	if !ok {
 		return
 	}
+	var imageSearchLinked *bool
+	if raw := strings.TrimSpace(c.Query("imageSearchLinked")); raw != "" {
+		value, parseErr := strconv.ParseBool(raw)
+		if parseErr != nil {
+			writeError(c, invalidRequest("imageSearchLinked 必须是布尔值"))
+			return
+		}
+		imageSearchLinked = &value
+	}
 	response, err := service.List(c.Request.Context(), ListRequest{
 		Page: page, PageSize: pageSize, Keyword: c.Query("keyword"), Status: strings.TrimSpace(c.Query("status")),
+		ImageSearchLinked: imageSearchLinked,
 	})
 	if err != nil {
 		writeError(c, err)
@@ -64,7 +77,7 @@ func (handler Handler) Detail(c *gin.Context) {
 	if !ok {
 		return
 	}
-	response, err := service.Detail(c.Request.Context(), id)
+	response, err := service.DetailWithAutoMatchBudget(c.Request.Context(), id)
 	respond(c, response, err)
 }

@@ -96,10 +109,17 @@ func (handler Handler) LinkPDD(c *gin.Context) {
 		writeError(c, invalidRequest("请求 JSON 无效"))
 		return
 	}
+	// This composite workflow reads SYB and device context. It must not inherit
+	// a client key's Shopee-only write grant through the shared handler.
+	if request.LatestCollection != nil && !strings.HasPrefix(c.FullPath(), "/api/admin/v1/") {
+		c.JSON(http.StatusForbidden, gin.H{"code": "FORBIDDEN", "message": "一键关联仅限 Admin 入口"})
+		return
+	}
 	service, ok := handler.service(c)
 	if !ok {
 		return
 	}
+	service.ReplacementEligibility = handler.ReplacementEligibility
 	response, err := service.LinkPDD(c.Request.Context(), id, request)
 	respond(c, response, err)
 }
@@ -467,7 +487,7 @@ func writeError(c *gin.Context, err error) {
 		status = http.StatusConflict
 	case CodeProductNotFound, CodePDDProductNotFound, CodeMappingNotFound, CodeValueNotFound:
 		status = http.StatusNotFound
-	case CodePDDProductDisabled, CodeSpecContextStale:
+	case CodePDDProductDisabled, CodeSpecContextStale, CodeLatestCollectionUnavailable, CodeLinkConflict:
 		status = http.StatusConflict
 	case CodeAIUnavailable:
 		status = http.StatusServiceUnavailable
@@ -0,0 +1,190 @@
+package shopeeproduct
+
+import (
+	"context"
+	"errors"
+
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const CodeLatestCollectionUnavailable = "LATEST_COLLECTION_UNAVAILABLE"
+const CodeLinkConflict = "PDD_LINK_CONFLICT"
+
+type LatestCollectionRequest struct {
+	SYBProductID       uint64                       `json:"sybProductId"`
+	DeviceID           uint64                       `json:"deviceId"`
+	SpecContextVersion string                       `json:"specContextVersion"`
+	Replacement        *LatestCollectionReplacement `json:"replacement,omitempty"`
+}
+
+type LatestCollectionReplacement struct {
+	Preview              bool   `json:"preview"`
+	ExpectedPDDProductID uint64 `json:"expectedPddProductId"`
+	TaskID               uint64 `json:"taskId"`
+	TargetPDDProductID   uint64 `json:"targetPddProductId"`
+	TargetVersion        string `json:"targetVersion"`
+}
+
+type LatestCollectionSource struct {
+	TaskID                   uint64 `json:"taskId"`
+	DeviceID                 uint64 `json:"deviceId"`
+	PDDProductID             uint64 `json:"pddProductId"`
+	RequiresSpecConfirmation bool   `json:"requiresSpecConfirmation"`
+	TargetVersion            string `json:"targetVersion,omitempty"`
+	Title                    string `json:"title,omitempty"`
+	GoodsID                  string `json:"goodsId,omitempty"`
+	PreviousTitle            string `json:"previousTitle,omitempty"`
+	PreviousGoodsID          string `json:"previousGoodsId,omitempty"`
+	DeviceName               string `json:"deviceName,omitempty"`
+}
+
+func latestUnavailable(message string) error {
+	return &ServiceError{Code: CodeLatestCollectionUnavailable, Message: message}
+}
+
+// Resolve the candidate exactly once under short row locks; never hold a
+// transaction while calling AI. The returned context belongs to this write,
+// not a later GET that could silently adopt another operator's association.
+func (service *Service) linkLatestCollection(ctx context.Context, id uint64, request LinkPDDRequest) (SaveResponse, error) {
+	r := request.LatestCollection
+	if request.PDDProductID != 0 || r.DeviceID == 0 || r.SYBProductID == 0 || r.SpecContextVersion == "" {
+		return SaveResponse{}, invalidRequest("一键关联需要 SYB、设备及规格版本，不能同时指定 PDD 商品")
+	}
+	var response SaveResponse
+	err := service.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var syb models.SYBProduct
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&syb, r.SYBProductID).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return latestUnavailable("SYB 明细不存在，请刷新列表")
+			}
+			return err
+		}
+		if syb.ShopeeProductID == nil || *syb.ShopeeProductID != id {
+			return contextVersionStale()
+		}
+		var shopee models.ShopeeProduct
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&shopee, id).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return productNotFound()
+			}
+			return err
+		}
+		replacement := r.Replacement
+		var old models.PDDProduct
+		if replacement != nil {
+			if shopee.PDDProductID == nil || replacement.ExpectedPDDProductID == 0 || *shopee.PDDProductID != replacement.ExpectedPDDProductID {
+				return contextVersionStale()
+			}
+			if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&old, *shopee.PDDProductID).Error; err != nil {
+				return err
+			}
+			if service.ReplacementEligibility == nil {
+				return invalidRequest("一键替换入口未配置")
+			}
+			if err := service.ReplacementEligibility(ctx, tx, syb.ID); err != nil {
+				return err
+			}
+			if !replacement.Preview && (replacement.TaskID == 0 || replacement.TargetPDDProductID == 0 || replacement.TargetVersion == "") {
+				return invalidRequest("请先预览并确认替换商品")
+			}
+		} else if shopee.PDDProductID != nil {
+			return &ServiceError{Code: CodeLinkConflict, Message: "商品已有关联，请刷新后查看；一键关联不会覆盖"}
+		}
+		if computeSpecContextVersion(shopee.PDDProductID, shopee.SpecsJSON, old.SpecsJSON) != r.SpecContextVersion {
+			return contextVersionStale()
+		}
+		var device models.AgentDevice
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&device, r.DeviceID).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return latestUnavailable("手机已不存在，请重新选择")
+			}
+			return err
+		}
+		if device.Status != models.DeviceStatusOnline && device.Status != models.DeviceStatusOffline {
+			return latestUnavailable("手机已停用，请重新选择")
+		}
+		var task models.CollectionTask
+		query := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("device_id = ? AND source = ? AND status IN ?", r.DeviceID, models.CollectionTaskSourceAgentCurrentPage, []string{models.TaskStatusCompleted, models.TaskStatusCompletedPartial})
+		if replacement != nil && !replacement.Preview {
+			query = query.Where("id = ?", replacement.TaskID)
+		}
+		err := query.Order("finished_at DESC, id DESC").First(&task).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return latestUnavailable("这台手机暂无成功的临时采集，请先采集商品")
+		}
+		if err != nil {
+			return err
+		}
+		if task.FinishedAt == nil || task.PDDProductID == nil {
+			return latestUnavailable("最近一次临时采集不完整，请先补采；不会回退关联更早的商品")
+		}
+		var pdd models.PDDProduct
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&pdd, *task.PDDProductID).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return latestUnavailable("最近采集的 PDD 商品已不存在")
+			}
+			return err
+		}
+		if pdd.Status != "active" {
+			return latestUnavailable("最近采集的 PDD 商品尚不可用，请先检查采集结果")
+		}
+		color, err := selectablePDDValues(pdd.SpecsJSON, RoleColor)
+		if err != nil {
+			return latestUnavailable("最近采集的 PDD 规格无效，请先补采")
+		}
+		size, err := selectablePDDValues(pdd.SpecsJSON, RoleSize)
+		if err != nil || len(color)+len(size) == 0 {
+			return latestUnavailable("最近采集的 PDD 缺少可用规格，请先补采")
+		}
+		if task.Status == models.TaskStatusCompletedPartial {
+			if err := validatePartialLinkResult(tx, task, color, size); err != nil {
+				return err
+			}
+		}
+		targetVersion := computeSpecContextVersion(&pdd.ID, "", pdd.SpecsJSON)
+		if replacement != nil && !replacement.Preview && (replacement.TargetPDDProductID != pdd.ID || replacement.TargetVersion != targetVersion) {
+			return contextVersionStale()
+		}
+		// Preview never writes. Same-product continuation also preserves the
+		// existing association and request marker; matching is a separate call.
+		if replacement == nil || (!replacement.Preview && old.ID != pdd.ID) {
+			query := tx.Model(&models.ShopeeProduct{}).Where("id = ?", id)
+			if replacement == nil {
+				query = query.Where("pdd_product_id IS NULL")
+			} else {
+				query = query.Where("pdd_product_id = ?", old.ID)
+			}
+			result := query.Updates(map[string]any{"pdd_product_id": pdd.ID, "last_update_request_id": request.RequestID})
+			if result.Error != nil {
+				return result.Error
+			}
+			if result.RowsAffected != 1 {
+				return contextVersionStale()
+			}
+		}
+		response, err = NewService(tx).Detail(ctx, id)
+		if err != nil {
+			return err
+		}
+		response.CollectionSource = &LatestCollectionSource{TaskID: task.ID, DeviceID: device.ID, PDDProductID: pdd.ID, RequiresSpecConfirmation: syb.ParseStatus == models.SYBParseStatusFailed && !syb.ManuallyConfirmed && !syb.AIConfirmed}
+		if replacement != nil {
+			response.CollectionSource.TargetVersion = targetVersion
+			response.CollectionSource.Title = pdd.Title
+			response.CollectionSource.GoodsID = pdd.GoodsID
+			response.CollectionSource.PreviousTitle = old.Title
+			response.CollectionSource.PreviousGoodsID = old.GoodsID
+			response.CollectionSource.DeviceName = device.Name
+		}
+		return nil
+	})
+	if err != nil {
+		var domain *ServiceError
+		if errors.As(err, &domain) {
+			return SaveResponse{}, err
+		}
+		return SaveResponse{}, internalError(err)
+	}
+	return response, nil
+}
@@ -0,0 +1,194 @@
+package shopeeproduct
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+)
+
+func latestFixture(t *testing.T) (*Service, uint64, LinkPDDRequest, models.CollectionTask) {
+	t.Helper()
+	db := openTestDB(t)
+	device := models.AgentDevice{InstallID: uuid.NewString(), TokenDigest: uuid.NewString(), Status: models.DeviceStatusOffline}
+	if err := db.Create(&device).Error; err != nil {
+		t.Fatal(err)
+	}
+	rule := models.CollectionRule{Name: "synthetic", ContentJSON: "{}"}
+	if err := db.Create(&rule).Error; err != nil {
+		t.Fatal(err)
+	}
+	pdd := seedPDDProduct(t, db, "active")
+	s := NewService(db)
+	created, err := s.Create(context.Background(), CreateRequest{RequestID: uuid.NewString(), ShopeeItemID: uuid.NewString(), Specs: []SpecDimension{{Name: "颜色", Role: RoleColor, Values: []SpecValue{{Name: "黑色", Source: ValueSourceManual}}}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	syb := models.SYBProduct{OrderCode: "synthetic", DetailID: 1, Quantity: 1, ParseStatus: "success", ShopeeProductID: &created.Product.ID}
+	if err := db.Create(&syb).Error; err != nil {
+		t.Fatal(err)
+	}
+	now := time.Now().UTC()
+	task := models.CollectionTask{DeviceID: &device.ID, RuleID: rule.ID, PDDProductID: &pdd.ID, Source: models.CollectionTaskSourceAgentCurrentPage, Status: models.TaskStatusCompleted, RuleSnapshot: "{}", FinishedAt: &now}
+	if err := db.Create(&task).Error; err != nil {
+		t.Fatal(err)
+	}
+	return s, created.Product.ID, LinkPDDRequest{RequestID: uuid.NewString(), LatestCollection: &LatestCollectionRequest{DeviceID: device.ID, SYBProductID: syb.ID, SpecContextVersion: created.Product.SpecContextVersion}}, task
+}
+
+func TestLatestCollectionOfflineAndOnlyIfUnlinked(t *testing.T) {
+	s, id, req, task := latestFixture(t)
+	result, err := s.LinkPDD(context.Background(), id, req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.CollectionSource.TaskID != task.ID || *result.Product.PDDProductID != *task.PDDProductID || result.Product.SpecContextVersion == req.LatestCollection.SpecContextVersion {
+		t.Fatalf("invalid frozen response: %+v", result)
+	}
+	// Another request (or an ambiguous network retry) cannot overwrite the link.
+	req.RequestID = uuid.NewString()
+	if _, err := s.LinkPDD(context.Background(), id, req); err == nil || errCode(t, err) != CodeLinkConflict {
+		t.Fatalf("expected conflict: %v", err)
+	}
+	other := seedPDDProduct(t, s.DB, "active")
+	if _, err := s.LinkPDD(context.Background(), id, LinkPDDRequest{RequestID: uuid.NewString(), PDDProductID: other.ID}); err != nil {
+		t.Fatalf("manual replacement regressed: %v", err)
+	}
+}
+
+func TestLatestCollectionRejectsInvalidContextWithoutWrite(t *testing.T) {
+	cases := []struct {
+		name   string
+		change func(*gorm.DB, *LinkPDDRequest, models.CollectionTask)
+	}{
+		{"partial", func(db *gorm.DB, _ *LinkPDDRequest, task models.CollectionTask) {
+			db.Model(&task).Update("status", "completed_partial")
+		}},
+		{"disabled-device", func(db *gorm.DB, r *LinkPDDRequest, _ models.CollectionTask) {
+			db.Model(&models.AgentDevice{}).Where("id = ?", r.LatestCollection.DeviceID).Update("status", "disabled")
+		}},
+		{"missing-device", func(_ *gorm.DB, r *LinkPDDRequest, _ models.CollectionTask) { r.LatestCollection.DeviceID += 100 }},
+		{"admin-source", func(db *gorm.DB, _ *LinkPDDRequest, task models.CollectionTask) {
+			db.Model(&task).Update("source", "admin")
+		}},
+		{"disabled-pdd", func(db *gorm.DB, _ *LinkPDDRequest, task models.CollectionTask) {
+			db.Model(&models.PDDProduct{}).Where("id = ?", *task.PDDProductID).Update("status", "disabled")
+		}},
+		{"empty-specs", func(db *gorm.DB, _ *LinkPDDRequest, task models.CollectionTask) {
+			db.Model(&models.PDDProduct{}).Where("id = ?", *task.PDDProductID).Update("specs_json", "[]")
+		}},
+		{"stale-version", func(_ *gorm.DB, r *LinkPDDRequest, _ models.CollectionTask) {
+			r.LatestCollection.SpecContextVersion = "stale"
+		}},
+		{"syb-link-changed", func(db *gorm.DB, r *LinkPDDRequest, _ models.CollectionTask) {
+			db.Model(&models.SYBProduct{}).Where("id = ?", r.LatestCollection.SYBProductID).Update("shopee_product_id", nil)
+		}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			s, id, r, task := latestFixture(t)
+			tc.change(s.DB, &r, task)
+			if _, err := s.LinkPDD(context.Background(), id, r); err == nil {
+				t.Fatal("unexpected successful write")
+			}
+			var product models.ShopeeProduct
+			s.DB.First(&product, id)
+			if product.PDDProductID != nil {
+				t.Fatal("rejected request wrote association")
+			}
+		})
+	}
+}
+
+func TestLatestCollectionOrdersByFinishThenIDAndDoesNotSkipPartial(t *testing.T) {
+	s, id, r, first := latestFixture(t)
+	newer := first
+	newer.ID = 0
+	newer.Status = models.TaskStatusCompletedPartial
+	if err := s.DB.Create(&newer).Error; err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.LinkPDD(context.Background(), id, r); err == nil {
+		t.Fatal("skipped latest partial")
+	}
+	// A newer ID with an older completion time must not win.
+	older := newer
+	older.ID = 0
+	older.Status = models.TaskStatusCompleted
+	ts := first.FinishedAt.Add(-time.Hour)
+	older.FinishedAt = &ts
+	if err := s.DB.Create(&older).Error; err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.LinkPDD(context.Background(), id, r); err == nil {
+		t.Fatal("sorted by id instead of completion")
+	}
+	if err := s.DB.Model(&newer).Update("status", models.TaskStatusCompleted).Error; err != nil {
+		t.Fatal(err)
+	}
+	result, err := s.LinkPDD(context.Background(), id, r)
+	if err != nil || result.CollectionSource.TaskID != newer.ID {
+		t.Fatalf("wrong latest result: %+v %v", result, err)
+	}
+}
+
+func TestLatestCollectionKeepsParseConfirmationBoundary(t *testing.T) {
+	for _, status := range []string{"success", "uncertain", "failed"} {
+		t.Run(status, func(t *testing.T) {
+			s, id, r, _ := latestFixture(t)
+			s.DB.Model(&models.SYBProduct{}).Where("id = ?", r.LatestCollection.SYBProductID).Update("parse_status", status)
+			result, err := s.LinkPDD(context.Background(), id, r)
+			if err != nil || result.CollectionSource.RequiresSpecConfirmation != (status == "failed") {
+				t.Fatalf("parse boundary: %+v %v", result, err)
+			}
+		})
+	}
+}
+
+func TestClientKeyCannotUseAdminCompositeLink(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.POST("/api/client/v1/shopee-products/:productId/link-pdd", Handler{}.LinkPDD)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/api/client/v1/shopee-products/1/link-pdd", strings.NewReader(`{"latestCollection":{"deviceId":1,"sybProductId":1,"specContextVersion":"x"}}`)))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("unexpected status: %d %s", w.Code, w.Body.String())
+	}
+}
+
+// SQLite has no row-level FOR UPDATE. A single test connection serializes
+// transactions to exercise concurrent callers; production MySQL locking must
+// additionally be verified in its deployment environment.
+func TestLatestCollectionConcurrentCallersOnlyOneWins(t *testing.T) {
+	s, id, r, _ := latestFixture(t)
+	sqlDB, err := s.DB.DB()
+	if err != nil {
+		t.Fatal(err)
+	}
+	sqlDB.SetMaxOpenConns(1)
+	errors := make(chan error, 2)
+	start := make(chan struct{})
+	for range 2 {
+		go func() { <-start; _, err := s.LinkPDD(context.Background(), id, r); errors <- err }()
+	}
+	close(start)
+	wins := 0
+	for range 2 {
+		err := <-errors
+		if err == nil {
+			wins++
+		} else if errCode(t, err) != CodeLinkConflict {
+			t.Fatal(err)
+		}
+	}
+	if wins != 1 {
+		t.Fatalf("expected one write, got %d", wins)
+	}
+}
@@ -0,0 +1,93 @@
+package shopeeproduct
+
+import (
+	"encoding/json"
+	"strings"
+
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+)
+
+// Only auxiliary metadata may be missing. Validate the source task, not the
+// merged product archive, which can retain data from an older collection.
+func validatePartialLinkResult(tx *gorm.DB, task models.CollectionTask, colors, sizes map[string]bool) error {
+	reject := func() error {
+		return latestUnavailable("最近一次采集的规格或价格仍不完整，请先补采；不会回退关联更早的商品")
+	}
+	var missing []string
+	if task.MissingJSON == nil || json.Unmarshal([]byte(*task.MissingJSON), &missing) != nil || len(missing) == 0 {
+		return reject()
+	}
+	for _, field := range missing {
+		switch field {
+		case "salesText", "shopName", "reviewCount":
+		default:
+			return reject()
+		}
+	}
+	var dimensions []models.CollectionDimension
+	if err := tx.Where("task_id = ?", task.ID).Find(&dimensions).Error; err != nil {
+		return err
+	}
+	values := map[string]map[string]bool{}
+	for _, dimension := range dimensions {
+		if (dimension.Key != RoleColor && dimension.Key != RoleSize) || values[dimension.Key] != nil {
+			return reject()
+		}
+		var rows []models.CollectionDimensionValue
+		if err := tx.Where("dimension_id = ?", dimension.ID).Find(&rows).Error; err != nil {
+			return err
+		}
+		if len(rows) == 0 {
+			return reject()
+		}
+		values[dimension.Key] = map[string]bool{}
+		for _, row := range rows {
+			if strings.TrimSpace(row.Value) == "" {
+				return reject()
+			}
+			values[dimension.Key][row.Value] = true
+		}
+	}
+	if len(values) == 0 {
+		return reject()
+	}
+	var skus []models.CollectionSKU
+	if err := tx.Where("task_id = ? AND available = ?", task.ID, true).Find(&skus).Error; err != nil {
+		return err
+	}
+	if len(skus) == 0 {
+		return reject()
+	}
+	covered := map[string]map[string]bool{RoleColor: {}, RoleSize: {}}
+	for _, sku := range skus {
+		var specs map[string]string
+		if !sku.Complete || sku.PriceCent < 0 || json.Unmarshal([]byte(sku.SpecKey), &specs) != nil || len(specs) != len(values) {
+			return reject()
+		}
+		for role, value := range specs {
+			if !values[role][value] {
+				return reject()
+			}
+			covered[role][value] = true
+		}
+	}
+	var prices []models.CollectionColorPrice
+	if err := tx.Where("task_id = ?", task.ID).Find(&prices).Error; err != nil {
+		return err
+	}
+	priced := map[string]bool{}
+	for _, price := range prices {
+		if price.PriceCent >= 0 {
+			priced[price.Color] = true
+		}
+	}
+	for role, candidates := range map[string]map[string]bool{RoleColor: colors, RoleSize: sizes} {
+		for value := range candidates {
+			if !covered[role][value] || (role == RoleColor && !priced[value]) {
+				return reject()
+			}
+		}
+	}
+	return nil
+}
@@ -0,0 +1,121 @@
+package shopeeproduct
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+)
+
+func seedPartialResult(t *testing.T, db *gorm.DB, task models.CollectionTask, missing string, single bool) {
+	t.Helper()
+	if err := db.Model(&task).Updates(map[string]any{"status": models.TaskStatusCompletedPartial, "missing_json": missing}).Error; err != nil {
+		t.Fatal(err)
+	}
+	dimensions := map[string][]string{"color": {"黑色"}, "size": {"M", "L", "XL", "2XL"}}
+	if single {
+		delete(dimensions, "size")
+		if err := db.Model(&models.PDDProduct{}).Where("id = ?", *task.PDDProductID).Update("specs_json", `[{"role":"color","name":"颜色","values":[{"name":"黑色","selectable":true,"priceCent":1000}]}]`).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	for role, values := range dimensions {
+		d := models.CollectionDimension{TaskID: task.ID, Key: role, Name: role}
+		if err := db.Create(&d).Error; err != nil {
+			t.Fatal(err)
+		}
+		for _, value := range values {
+			if err := db.Create(&models.CollectionDimensionValue{DimensionID: d.ID, Value: value}).Error; err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	if err := db.Create(&models.CollectionColorPrice{TaskID: task.ID, Color: "黑色", PriceCent: 1000}).Error; err != nil {
+		t.Fatal(err)
+	}
+	sizes := dimensions["size"]
+	if single {
+		sizes = []string{""}
+	}
+	for _, size := range sizes {
+		specs := map[string]string{"color": "黑色"}
+		if size != "" {
+			specs["size"] = size
+		}
+		raw, _ := json.Marshal(specs)
+		if err := db.Create(&models.CollectionSKU{TaskID: task.ID, SpecKey: string(raw), PriceCent: 1000, Available: true, Complete: true}).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestPartialAuxiliaryMetadataAllowsLinkAndKeepsStatus(t *testing.T) {
+	for _, missing := range []string{`["salesText"]`, `["shopName","reviewCount","salesText"]`} {
+		t.Run(missing, func(t *testing.T) {
+			s, id, req, task := latestFixture(t)
+			seedPartialResult(t, s.DB, task, missing, false)
+			result, err := s.LinkPDD(context.Background(), id, req)
+			if err != nil || result.CollectionSource.TaskID != task.ID {
+				t.Fatalf("link: %+v %v", result, err)
+			}
+			s.DB.First(&task, task.ID)
+			if task.Status != models.TaskStatusCompletedPartial || *task.MissingJSON != missing {
+				t.Fatal("changed historical completeness")
+			}
+		})
+	}
+}
+
+func TestPartialMetadataAllowsSingleDimensionAndReplacement(t *testing.T) {
+	s, id, req, task, old := replacementFixture(t)
+	seedPartialResult(t, s.DB, task, `["salesText"]`, true)
+	preview := previewReplacement(t, s, id, &req)
+	if *preview.Product.PDDProductID != old.ID {
+		t.Fatal("preview wrote")
+	}
+	result, err := s.LinkPDD(context.Background(), id, req)
+	if err != nil || *result.Product.PDDProductID != *task.PDDProductID {
+		t.Fatalf("replacement: %+v %v", result, err)
+	}
+}
+
+func TestPartialMissingOrResultDefectsStillReject(t *testing.T) {
+	for _, scenario := range []string{"[]", "null", "bad-json", `["salesText","size"]`, `["title"]`, `["price:黑色"]`, `["skuLimit:12>8"]`, `["unknown"]`, "sku-incomplete", "sku-unavailable", "sku-invalid", "no-current-price", "old-archive-value"} {
+		t.Run(scenario, func(t *testing.T) {
+			s, id, req, task := latestFixture(t)
+			missing := scenario
+			if scenario[0] != '[' && scenario != "null" && scenario != "bad-json" {
+				missing = `["salesText"]`
+			}
+			seedPartialResult(t, s.DB, task, missing, false)
+			switch scenario {
+			case "sku-incomplete":
+				s.DB.Model(&models.CollectionSKU{}).Where("task_id = ?", task.ID).Update("complete", false)
+			case "sku-unavailable":
+				s.DB.Model(&models.CollectionSKU{}).Where("task_id = ?", task.ID).Update("available", false)
+			case "sku-invalid":
+				var sku models.CollectionSKU
+				if err := s.DB.Where("task_id = ?", task.ID).First(&sku).Error; err != nil {
+					t.Fatal(err)
+				}
+				if err := s.DB.Model(&sku).Update("spec_key", `{}`).Error; err != nil {
+					t.Fatal(err)
+				}
+			case "no-current-price":
+				s.DB.Model(&models.CollectionColorPrice{}).Where("task_id = ?", task.ID).Update("color", "不是本次颜色")
+			case "old-archive-value":
+				s.DB.Model(&models.PDDProduct{}).Where("id = ?", *task.PDDProductID).Update("specs_json", `[{"role":"color","values":[{"name":"旧颜色","selectable":true,"priceCent":1000}]}]`)
+			}
+			if _, err := s.LinkPDD(context.Background(), id, req); err == nil {
+				t.Fatal("accepted incomplete current result")
+			}
+			var product models.ShopeeProduct
+			s.DB.First(&product, id)
+			if product.PDDProductID != nil {
+				t.Fatal("rejected request wrote association")
+			}
+		})
+	}
+}
@@ -0,0 +1,145 @@
+package shopeeproduct
+
+import (
+	"context"
+	"testing"
+
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+)
+
+func replacementFixture(t *testing.T) (*Service, uint64, LinkPDDRequest, models.CollectionTask, models.PDDProduct) {
+	s, id, req, task := latestFixture(t)
+	old := seedPDDProduct(t, s.DB, "pending")
+	if err := s.DB.Model(&models.ShopeeProduct{}).Where("id = ?", id).Update("pdd_product_id", old.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	detail, err := s.Detail(context.Background(), id)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.LatestCollection.SpecContextVersion = detail.Product.SpecContextVersion
+	req.LatestCollection.Replacement = &LatestCollectionReplacement{Preview: true, ExpectedPDDProductID: old.ID}
+	s.ReplacementEligibility = func(context.Context, *gorm.DB, uint64) error { return nil }
+	return s, id, req, task, old
+}
+
+func previewReplacement(t *testing.T, s *Service, id uint64, req *LinkPDDRequest) SaveResponse {
+	t.Helper()
+	preview, err := s.LinkPDD(context.Background(), id, *req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := req.LatestCollection.Replacement
+	r.Preview = false
+	r.TaskID = preview.CollectionSource.TaskID
+	r.TargetPDDProductID = preview.CollectionSource.PDDProductID
+	r.TargetVersion = preview.CollectionSource.TargetVersion
+	return preview
+}
+
+func TestReplacementPreviewIsReadOnlyAndFreezesCandidate(t *testing.T) {
+	s, id, req, task, old := replacementFixture(t)
+	preview := previewReplacement(t, s, id, &req)
+	if *preview.Product.PDDProductID != old.ID {
+		t.Fatal("preview changed association")
+	}
+	var record models.ShopeeProduct
+	s.DB.First(&record, id)
+	if *record.PDDProductID != old.ID || record.LastUpdateRequestID != nil {
+		t.Fatal("preview wrote")
+	}
+	newer := task
+	newer.ID = 0
+	newer.Status = models.TaskStatusCompletedPartial
+	if err := s.DB.Create(&newer).Error; err != nil {
+		t.Fatal(err)
+	}
+	result, err := s.LinkPDD(context.Background(), id, req)
+	if err != nil || *result.Product.PDDProductID != *task.PDDProductID || result.CollectionSource.TaskID != task.ID {
+		t.Fatalf("frozen candidate: %+v %v", result, err)
+	}
+	if _, err := s.LinkPDD(context.Background(), id, req); err == nil {
+		t.Fatal("duplicate replaced stale association")
+	}
+}
+
+func TestReplacementSameProductDoesNotRebind(t *testing.T) {
+	s, id, req, task, _ := replacementFixture(t)
+	s.DB.Model(&models.ShopeeProduct{}).Where("id = ?", id).Update("pdd_product_id", *task.PDDProductID)
+	detail, _ := s.Detail(context.Background(), id)
+	req.LatestCollection.SpecContextVersion = detail.Product.SpecContextVersion
+	req.LatestCollection.Replacement.ExpectedPDDProductID = *task.PDDProductID
+	previewReplacement(t, s, id, &req)
+	if _, err := s.LinkPDD(context.Background(), id, req); err != nil {
+		t.Fatal(err)
+	}
+	var record models.ShopeeProduct
+	s.DB.First(&record, id)
+	if record.LastUpdateRequestID != nil {
+		t.Fatal("same product wrote association")
+	}
+}
+
+func TestReplacementRejectsChangesAfterPreview(t *testing.T) {
+	for _, change := range []string{"association", "specs", "target-specs", "task-status", "device", "stage", "missing-validator", "target-id", "task-id"} {
+		t.Run(change, func(t *testing.T) {
+			s, id, req, task, old := replacementFixture(t)
+			previewReplacement(t, s, id, &req)
+			expected := old.ID
+			switch change {
+			case "association":
+				other := seedPDDProduct(t, s.DB, "active")
+				expected = other.ID
+				s.DB.Model(&models.ShopeeProduct{}).Where("id = ?", id).Update("pdd_product_id", expected)
+			case "specs":
+				s.DB.Model(&models.ShopeeProduct{}).Where("id = ?", id).Update("specs_json", "[]")
+			case "target-specs":
+				s.DB.Model(&models.PDDProduct{}).Where("id = ?", *task.PDDProductID).Update("specs_json", `[{"role":"color","name":"颜色","values":[{"name":"白色","selectable":true}]}]`)
+			case "task-status":
+				s.DB.Model(&task).Update("status", "completed_partial")
+			case "device":
+				s.DB.Model(&models.AgentDevice{}).Where("id = ?", req.LatestCollection.DeviceID).Update("status", "disabled")
+			case "stage":
+				s.ReplacementEligibility = func(context.Context, *gorm.DB, uint64) error { return &ServiceError{Code: CodeLinkConflict} }
+			case "missing-validator":
+				s.ReplacementEligibility = nil
+			case "target-id":
+				req.LatestCollection.Replacement.TargetPDDProductID++
+			case "task-id":
+				req.LatestCollection.Replacement.TaskID++
+			}
+			if _, err := s.LinkPDD(context.Background(), id, req); err == nil {
+				t.Fatal("accepted changed context")
+			}
+			var record models.ShopeeProduct
+			s.DB.First(&record, id)
+			if *record.PDDProductID != expected {
+				t.Fatal("overwrote rejected association")
+			}
+		})
+	}
+}
+
+func TestReplacementConcurrentConfirmationsOnlyOneWrites(t *testing.T) {
+	s, id, req, _, _ := replacementFixture(t)
+	previewReplacement(t, s, id, &req)
+	connection, err := s.DB.DB()
+	if err != nil {
+		t.Fatal(err)
+	}
+	connection.SetMaxOpenConns(1) // SQLite serialization, not a MySQL lock claim.
+	results := make(chan error, 2)
+	for range 2 {
+		go func() { _, err := s.LinkPDD(context.Background(), id, req); results <- err }()
+	}
+	wins := 0
+	for range 2 {
+		if <-results == nil {
+			wins++
+		}
+	}
+	if wins != 1 {
+		t.Fatalf("writes=%d", wins)
+	}
+}
@@ -7,8 +7,8 @@ import (
 	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
 )

-func InitRouter(engine *gin.Engine, auth *jwt.GinJWTMiddleware) {
-	handler := Handler{}
+func InitRouter(engine *gin.Engine, auth *jwt.GinJWTMiddleware, eligibility ReplacementEligibility) {
+	handler := Handler{ReplacementEligibility: eligibility}
 	admin := engine.Group("/api/admin/v1/shopee-products").Use(auth.MiddlewareFunc()).Use(middleware.AuthCheckRole())
 	adminOnlyRuns := engine.Group("/api/admin/v1/shopee-spec-auto-match/runs").Use(auth.MiddlewareFunc()).Use(middleware.AuthCheckRole()).Use(middleware.RequireRoleKey("admin"))
 	adminOnlyRuns.POST("", handler.StartAutoMatchRun)
@@ -57,7 +57,12 @@ func (err *ServiceError) Error() string {
 }
 func (err *ServiceError) Unwrap() error { return err.Cause }

-type Service struct{ DB *gorm.DB }
+type ReplacementEligibility func(context.Context, *gorm.DB, uint64) error
+
+type Service struct {
+	DB                     *gorm.DB
+	ReplacementEligibility ReplacementEligibility
+}

 func NewService(db *gorm.DB) *Service { return &Service{DB: db} }

@@ -76,8 +81,10 @@ type ProductView struct {
 }

 type SaveResponse struct {
-	Product  ProductView `json:"product"`
-	Replayed bool        `json:"replayed,omitempty"`
+	Product                 ProductView             `json:"product"`
+	Replayed                bool                    `json:"replayed,omitempty"`
+	AutoMatchTimeoutSeconds int                     `json:"autoMatchTimeoutSeconds,omitempty"`
+	CollectionSource        *LatestCollectionSource `json:"collectionSource,omitempty"`
 }

 type ListItemView struct {
@@ -156,6 +163,16 @@ func (service *Service) Create(ctx context.Context, request CreateRequest) (Save
 	return SaveResponse{Product: view}, err
 }

+// DetailWithAutoMatchBudget exposes only a derived time budget, never AI settings.
+func (service *Service) DetailWithAutoMatchBudget(ctx context.Context, id uint64) (SaveResponse, error) {
+	response, err := service.Detail(ctx, id)
+	if err != nil {
+		return SaveResponse{}, err
+	}
+	response.AutoMatchTimeoutSeconds, err = service.autoMatchTimeout(ctx)
+	return response, err
+}
+
 // ---------------------------------------------------------------- update (archive fields only)

 type UpdateRequest struct {
@@ -214,7 +231,8 @@ type ListRequest struct {
 	// Status filters by lifecycle: "" (default) live only, "deleted" soft-deleted
 	// only. There is no "all" value: mixing live and deleted rows in one page
 	// would defeat the point of the filter (#40 prototype: 全部（不含已删除）).
-	Status string
+	Status            string
+	ImageSearchLinked *bool
 }

 func (service *Service) List(ctx context.Context, request ListRequest) (ListResponse, error) {
@@ -240,6 +258,9 @@ func (service *Service) List(ctx context.Context, request ListRequest) (ListResp
 		like := "%" + request.Keyword + "%"
 		query = query.Where("shopee_item_id LIKE ? OR title LIKE ? OR shop_name LIKE ?", like, like, like)
 	}
+	if request.ImageSearchLinked != nil {
+		query = query.Where("image_search_linked = ?", *request.ImageSearchLinked)
+	}
 	var total int64
 	if err := query.Count(&total).Error; err != nil {
 		return ListResponse{}, internalError(err)
@@ -262,8 +283,9 @@ func (service *Service) List(ctx context.Context, request ListRequest) (ListResp
 // ---------------------------------------------------------------- link PDD

 type LinkPDDRequest struct {
-	RequestID    string `json:"requestId"`
-	PDDProductID uint64 `json:"pddProductId"`
+	RequestID        string                   `json:"requestId"`
+	PDDProductID     uint64                   `json:"pddProductId"`
+	LatestCollection *LatestCollectionRequest `json:"latestCollection,omitempty"`
 }

 // LinkPDD sets or changes the linked PDD product via the search-and-select
@@ -274,6 +296,9 @@ func (service *Service) LinkPDD(ctx context.Context, id uint64, request LinkPDDR
 	if _, err := uuid.Parse(strings.TrimSpace(request.RequestID)); err != nil {
 		return SaveResponse{}, invalidRequest("requestId 必须是 UUID")
 	}
+	if request.LatestCollection != nil {
+		return service.linkLatestCollection(ctx, id, request)
+	}
 	if request.PDDProductID == 0 {
 		return SaveResponse{}, invalidRequest("pddProductId 必填")
 	}
@@ -282,7 +307,7 @@ func (service *Service) LinkPDD(ctx context.Context, id uint64, request LinkPDDR
 		return SaveResponse{}, err
 	}
 	result := db.Model(&models.ShopeeProduct{}).Where("id = ?", id).Updates(map[string]any{
-		"pdd_product_id": request.PDDProductID, "last_update_request_id": request.RequestID,
+		"pdd_product_id": request.PDDProductID, "image_search_linked": false, "last_update_request_id": request.RequestID,
 	})
 	if result.Error != nil {
 		return SaveResponse{}, internalError(result.Error)
@@ -84,6 +84,9 @@ func ApplyDetail(ctx context.Context, db *gorm.DB, order OrderInput, detail Deta
 	}

 	parsed := Parse(detail.ProductSpec)
+	if parsed.Status == models.SYBParseStatusUncertain {
+		parsed.Status = models.SYBParseStatusFailed
+	}
 	rawJSON, err := normalizeRaw(detail.Raw)
 	if err != nil {
 		return ApplyResult{}, err
@@ -3,6 +3,8 @@ package sybimport
 import (
 	"context"
 	"errors"
+	"fmt"
+	"go-admin/common/clientprincipal"
 	"net/http"
 	"strconv"
 	"strings"
@@ -113,8 +115,10 @@ func isImportAlreadyRunning(err error) bool {
 // `[必须]` This remains the authenticated manual entry point. Both it and the
 // scheduler delegate to StartImport, and every downstream SYB call is read-only.
 func (handler Handler) Import(c *gin.Context) {
-	if claimString(jwt.ExtractClaims(c)["rolekey"]) != "admin" {
-		c.JSON(http.StatusForbidden, gin.H{"code": "FORBIDDEN", "message": "只有管理员可以开始导入"})
+	role := claimString(jwt.ExtractClaims(c)["rolekey"])
+	client, clientOK := clientprincipal.Get(c)
+	if role != "admin" && role != "purchaser" && !clientOK {
+		c.JSON(http.StatusForbidden, gin.H{"code": "FORBIDDEN", "message": "只有管理员或采购员可以开始同步"})
 		return
 	}
 	var request ImportRequest
@@ -127,9 +131,13 @@ func (handler Handler) Import(c *gin.Context) {
 		return
 	}
 	claims := jwt.ExtractClaims(c)
-	result, err := StartImport(c.Request.Context(), service.DB, request, ImportActor{
+	actor := ImportActor{
 		ID: claimUint64(claims["identity"]), Name: claimString(claims["nice"]),
-	}, false)
+	}
+	if clientOK {
+		actor = ImportActor{ID: client.AuthorizedBy, Name: fmt.Sprintf("client-key:%d", client.KeyID)}
+	}
+	result, err := StartImport(c.Request.Context(), service.DB, request, actor, false)
 	if err != nil {
 		var serviceErr *ServiceError
 		if errors.As(err, &serviceErr) {
@@ -163,6 +171,9 @@ func runImport(db *gorm.DB, runID uint64, request ImportRequest, settings config
 	status := SyncRunSucceeded
 	if err != nil {
 		status = SyncRunFailed
+		if report.Created+report.Updated > 0 {
+			status = SyncRunPartial
+		}
 	}
 	finishCtx, finishCancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer finishCancel()
@@ -53,17 +53,26 @@ func TestImportRejectsNoEnabledShopBeforeConnect(t *testing.T) {
 	}
 }

-func TestImportRequiresAdminRole(t *testing.T) {
-	gin.SetMode(gin.TestMode)
-	engine := gin.New()
-	engine.Use(func(c *gin.Context) { c.Set(jwt.JwtPayloadKey, jwt.MapClaims{"rolekey": "purchaser"}); c.Next() })
-	engine.POST("/api/admin/v1/syb-products/import", Handler{}.Import)
-	request := httptest.NewRequest(http.MethodPost, "/api/admin/v1/syb-products/import", bytes.NewBufferString(`{"dateFrom":"2026-08-19","dateTo":"2026-08-19"}`))
-	request.Header.Set("Content-Type", "application/json")
-	recorder := httptest.NewRecorder()
-	engine.ServeHTTP(recorder, request)
-	if recorder.Code != http.StatusForbidden || !strings.Contains(recorder.Body.String(), "只有管理员") {
-		t.Fatalf("采购员应被拒绝: status=%d body=%s", recorder.Code, recorder.Body.String())
+func TestImportRoleBoundary(t *testing.T) {
+	for _, role := range []string{"admin", "purchaser", "viewer", "", "custom-role"} {
+		t.Run(role, func(t *testing.T) {
+			gin.SetMode(gin.TestMode)
+			engine := gin.New()
+			engine.Use(func(c *gin.Context) { c.Set(jwt.JwtPayloadKey, jwt.MapClaims{"rolekey": role}); c.Next() })
+			engine.POST("/api/admin/v1/syb-products/import", Handler{}.Import)
+			// Authorized roles reach JSON validation; no DB or external SYB call is made.
+			request := httptest.NewRequest(http.MethodPost, "/api/admin/v1/syb-products/import", bytes.NewBufferString(`{`))
+			request.Header.Set("Content-Type", "application/json")
+			recorder := httptest.NewRecorder()
+			engine.ServeHTTP(recorder, request)
+			want := http.StatusForbidden
+			if role == "admin" || role == "purchaser" {
+				want = http.StatusUnprocessableEntity
+			}
+			if recorder.Code != want {
+				t.Fatalf("role=%q status=%d want=%d body=%s", role, recorder.Code, want, recorder.Body.String())
+			}
+		})
 	}
 }

@@ -4,44 +4,9 @@ import (
 	"context"
 	"strings"
 	"testing"
-	"time"
 )

-func freezePaginationToday(t *testing.T) {
-	t.Helper()
-	previous := syncNow
-	syncNow = func() time.Time { return time.Date(2026, 8, 29, 12, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*60*60)) }
-	t.Cleanup(func() { syncNow = previous })
-}
-
-func TestTodayCrossPageOverlapRestartsWithIndependentIDs(t *testing.T) {
-	freezePaginationToday(t)
-	f := &fakeSYB{perDay: map[string]int{"2026-08-29": 4}}
-	f.pageIDs = func(_ string, start, call int) []int64 {
-		if call == 2 {
-			return []int64{1001, 1002}
-		}
-		if call > 2 {
-			return []int64{int64(2000 + start), int64(2001 + start)}
-		}
-		return nil
-	}
-	rows, err := loadDailyListWithRecovery(context.Background(), newSyncClient(t, f), "2026-08-29", 2, 4, 100)
-	if err != nil || len(rows) != 4 || f.listTotalCalls != 2 {
-		t.Fatalf("rows=%d totals=%d err=%v", len(rows), f.listTotalCalls, err)
-	}
-	if got := strings.Join(f.listCalls, ","); got != "2026-08-29:0,2026-08-29:2,2026-08-29:0,2026-08-29:2" {
-		t.Fatalf("did not restart at first page: %s", got)
-	}
-	for index, row := range rows {
-		if row.ID != int64(2000+index) {
-			t.Fatal("rows leaked from abandoned attempt")
-		}
-	}
-}
-
-func TestTodayPersistentOverlapPreservesYesterdayButDoesNotImportToday(t *testing.T) {
-	freezePaginationToday(t)
+func TestTodayOverlapPreservesCommittedPagesWithoutImportingOverlappingPage(t *testing.T) {
 	f := &fakeSYB{perDay: map[string]int{"2026-08-28": 2, "2026-08-29": 4}}
 	f.pageIDs = func(date string, start, _ int) []int64 {
 		if date == "2026-08-29" && start == 2 {
@@ -54,7 +19,7 @@ func TestTodayPersistentOverlapPreservesYesterdayButDoesNotImportToday(t *testin
 	if err == nil {
 		t.Fatal("overlap was treated as successful sync")
 	}
-	for _, token := range []string{"连续 3 次", "跨页重复", "firstPage=1", "firstRow=2", "page=2", "row=1", "start=2", "pageSize=2", "expectedTotal=4", "unique=2"} {
+	for _, token := range []string{"跨页重复", "firstPage=1", "firstRow=2", "page=2", "row=1", "start=2", "pageSize=2", "expectedTotal=4", "unique=2"} {
 		if !strings.Contains(err.Error(), token) {
 			t.Fatalf("missing %s in %v", token, err)
 		}
@@ -62,7 +27,7 @@ func TestTodayPersistentOverlapPreservesYesterdayButDoesNotImportToday(t *testin
 	if strings.Contains(err.Error(), "1001") || strings.Contains(err.Error(), "已保存") {
 		t.Fatalf("unsafe diagnosis/degraded save: %v", err)
 	}
-	if len(f.listCalls) != 7 || f.detailCalls != 1 || report.OrderCount != 2 {
+	if len(f.listCalls) != 3 || f.detailCalls != 2 || report.OrderCount != 4 || report.Created != 2 || report.Updated != 2 {
 		t.Fatalf("unexpected retry/import boundary: pages=%d details=%d orders=%d", len(f.listCalls), f.detailCalls, report.OrderCount)
 	}
 	var count int64
@@ -72,7 +37,6 @@ func TestTodayPersistentOverlapPreservesYesterdayButDoesNotImportToday(t *testin
 }

 func TestPaginationHardErrorsDoNotUseOverlapRecovery(t *testing.T) {
-	freezePaginationToday(t)
 	for _, tc := range []struct {
 		name, date, message string
 		page                int
@@ -92,7 +56,7 @@ func TestPaginationHardErrorsDoNotUseOverlapRecovery(t *testing.T) {
 				}
 				return nil
 			}
-			rows, err := loadDailyListWithRecovery(context.Background(), newSyncClient(t, f), tc.date, 2, 4, 100)
+			rows, err := loadDailyList(context.Background(), newSyncClient(t, f), tc.date, 2, 4)
 			if rows != nil || err == nil || !strings.Contains(err.Error(), tc.message) || len(f.listCalls) != tc.calls || f.listTotalCalls != 0 {
 				t.Fatalf("unexpected recovery: rows=%d pages=%d totals=%d err=%v", len(rows), len(f.listCalls), f.listTotalCalls, err)
 			}
@@ -25,7 +25,6 @@ var explicitSizePattern = regexp.MustCompile(`(?i)^(?:均(?:码|碼|号|號)|one
 // Observed in the real SYB sample: "黑色+白色【純棉兩件裝】 簡約親膚" strips
 // its bracket to "黑色+白色 簡約親膚", which still carries a '+' and internal
 // whitespace, so it must not be reported as a confident match.
-var ambiguousPattern = regexp.MustCompile(`[+＋\s]`)

 // ParseResult is the color/size candidate extracted from one productSpec
 // string, plus how much the caller should trust it.
@@ -73,7 +72,10 @@ func Parse(raw string) ParseResult {
 		if size == "" {
 			return ParseResult{Status: models.SYBParseStatusFailed, Note: "productSpec 剥离备注后为空"}
 		}
-		return ParseResult{Size: size, Status: models.SYBParseStatusUncertain, Note: "无分隔符，仅识别出单一规格值"}
+		if explicitSizePattern.MatchString(size) {
+			return ParseResult{Size: size, Status: models.SYBParseStatusSuccess, Note: "仅识别到尺码"}
+		}
+		return ParseResult{Color: size, Status: models.SYBParseStatusSuccess, Note: "仅识别到颜色"}
 	}

 	firstPart := stripBrackets(trimmed[:lastComma])
@@ -81,7 +83,17 @@ func Parse(raw string) ParseResult {
 	colorPart, sizePart := firstPart, secondPart

 	if colorPart == "" || sizePart == "" {
-		return ParseResult{Color: colorPart, Size: sizePart, Status: models.SYBParseStatusUncertain, Note: "按逗号拆分后有一侧为空"}
+		only := colorPart
+		if only == "" {
+			only = sizePart
+		}
+		if explicitSizePattern.MatchString(only) {
+			return ParseResult{Size: only, Status: models.SYBParseStatusSuccess, Note: "仅识别到尺码"}
+		}
+		if only != "" {
+			return ParseResult{Color: only, Status: models.SYBParseStatusSuccess, Note: "仅识别到颜色"}
+		}
+		return ParseResult{Color: colorPart, Size: sizePart, Status: models.SYBParseStatusFailed, Note: "按逗号拆分后没有可靠规格"}
 	}
 	firstIsSize, secondIsSize := explicitSizePattern.MatchString(firstPart), explicitSizePattern.MatchString(secondPart)
 	if firstIsSize && secondIsSize {
@@ -90,9 +102,6 @@ func Parse(raw string) ParseResult {
 	if firstIsSize {
 		colorPart, sizePart = secondPart, firstPart
 	}
-	if ambiguousPattern.MatchString(colorPart) {
-		return ParseResult{Color: colorPart, Size: sizePart, Status: models.SYBParseStatusUncertain, Note: "颜色部分含备注文本或多个分隔符，拆分结果可能不准确"}
-	}
 	return ParseResult{Color: colorPart, Size: sizePart, Status: models.SYBParseStatusSuccess}
 }

@@ -77,6 +77,9 @@ func Reparse(ctx context.Context, db *gorm.DB, sybProductID uint64, force bool)
 			return fmt.Errorf("syb product %d: stored raw json is not decodable: %w", record.ID, err)
 		}
 		parsed := Parse(raw.ProductSpec)
+		if parsed.Status == models.SYBParseStatusUncertain {
+			parsed.Status = models.SYBParseStatusFailed
+		}
 		outcome.NewStatus = parsed.Status

 		if parsed.Color == record.TargetColor && parsed.Size == record.TargetSize && parsed.Status == record.ParseStatus {
@@ -42,6 +42,9 @@ func RepairReversedSpecRoles(ctx context.Context, db *gorm.DB) (SpecRoleRepairRe
 				continue
 			}
 			parsed := Parse(raw.ProductSpec)
+			if parsed.Status == models.SYBParseStatusUncertain {
+				parsed.Status = models.SYBParseStatusFailed
+			}
 			if parsed.Status == models.SYBParseStatusFailed || parsed.Color == record.TargetColor ||
 				parsed.Color != record.TargetSize || parsed.Size != record.TargetColor {
 				continue
@@ -19,7 +19,7 @@ func InitRouter(engine *gin.Engine, auth *jwt.GinJWTMiddleware) {
 	admin.POST("/reparse-batch", handler.ReparseBatch)
 	admin.POST("/import", handler.Import)
 	// Run history is intentionally authenticated but not Casbin-gated: #50
-	// makes it read-only for every role, while Import enforces admin itself.
+	// makes it readable for every role; Import also requires admin/purchaser.
 	readonly := engine.Group("/api/admin/v1/syb-products").Use(auth.MiddlewareFunc())
 	readonly.GET("/sync-runs", handler.ListSyncRuns)
 	readonly.GET("/sync-runs/:runId", handler.SyncRunDetail)
@@ -11,6 +11,7 @@ import (
 	"time"

 	"go-admin/app/goauto/sybclient"
+	"go-admin/app/goauto/sybproductfilter"
 	"go-admin/app/goauto/sybshop"

 	"gorm.io/gorm"
@@ -41,8 +42,7 @@ const (
 	// maxSyncDays bounds one request's window. It is a guard against a typo in
 	// the date range turning into tens of thousands of remote reads before
 	// MaxMatches trips.
-	maxSyncDays              = 31
-	maxTodaySnapshotAttempts = 3
+	maxSyncDays = 31
 )

 // SyncReport summarises one sync run.
@@ -53,8 +53,14 @@ type SyncReport struct {
 	// ShopSkipped how many did not. OrderCount stays the raw total: keeping the
 	// unfiltered number visible is what makes a shop missing from the
 	// allow-list obvious rather than silent.
-	AcceptedCount int `json:"acceptedCount"`
-	ShopSkipped   int `json:"shopSkipped"`
+	AcceptedCount        int `json:"acceptedCount"`
+	ShopSkipped          int `json:"shopSkipped"`
+	CharFilterSkipped    int `json:"charFilterSkipped"`
+	KeywordFilterSkipped int `json:"keywordFilterSkipped"`
+	// filterHits accumulates hits per filter rule id so each rule's own
+	// LastHitCount can be written back. It is unexported because it is run
+	// bookkeeping, not part of the report shown to people or stored as JSON.
+	filterHits sybproductfilter.HitCounter
 	// ShopBreakdown separates accepted and skipped orders for every shop. Without
 	// it a renamed or newly opened shop is never noticed (#50).
 	ShopBreakdown  map[string]ShopBreakdown `json:"shopBreakdown"`
@@ -82,8 +88,6 @@ type SyncProgress struct {
 	DaysProcessed int
 }

-var syncNow = time.Now
-
 type ProgressFunc func(SyncProgress) error

 type snapshotDriftError struct {
@@ -94,14 +98,6 @@ type snapshotDriftError struct {

 func (err *snapshotDriftError) Error() string { return err.message }

-func shanghaiToday() string {
-	location, err := time.LoadLocation("Asia/Shanghai")
-	if err != nil {
-		location = time.FixedZone("Asia/Shanghai", 8*60*60)
-	}
-	return syncNow().In(location).Format("2006-01-02")
-}
-
 // Sync pulls every shipment order in [dateFrom, dateTo] and folds each detail
 // line into the SYB/Shopee archive through ApplyDetail.
 //
@@ -109,16 +105,10 @@ func shanghaiToday() string {
 // a separate concern (see Connect); a session that dies mid-run surfaces as
 // sybclient.ErrSessionInvalid and is treated like any other mid-run failure.
 //
-// `[必须]` Failure stops the run immediately. Rows already written are NOT
-// rolled back — ApplyDetail is idempotent on (order_code, detail_id), so a
-// re-run overwrites them rather than duplicating. What must not happen is
-// reporting a partial run as a complete one, which would let the missing
-// orders go unnoticed forever.
-//
-// `[必须]` Every day is verified for completeness before anything is written:
-// the per-day total is re-read after paging and must not have drifted. SYB's
-// list endpoint returns the *page* size in `total` (§4.3, confirmed against
-// live data), so the paging loop is driven by listTotal, never by list.total.
+// Each validated page is committed independently. Date-local read failures
+// preserve committed pages and allow later dates to run. Database, cancellation
+// and progress persistence failures stop the run. Completeness is verified at
+// the end of each date; partial results must never be reported as full success.
 func Sync(ctx context.Context, db *gorm.DB, client *sybclient.Client, cfg SyncConfig, dateFrom, dateTo string) (SyncReport, error) {
 	return SyncWithProgress(ctx, db, client, cfg, dateFrom, dateTo, nil)
 }
@@ -136,7 +126,8 @@ func SyncWithProgress(ctx context.Context, db *gorm.DB, client *sybclient.Client
 // run's effective allow-list differ from the snapshot recorded on its row.
 func SyncWithShopSnapshot(ctx context.Context, db *gorm.DB, client *sybclient.Client, cfg SyncConfig, dateFrom, dateTo string, allowed map[string]string, progress ProgressFunc) (SyncReport, error) {
 	report := SyncReport{From: dateFrom, To: dateTo, StartedAt: time.Now().UTC(),
-		ShopBreakdown: map[string]ShopBreakdown{}, ShopFilterSnapshot: shopSnapshotNames(allowed)}
+		ShopBreakdown: map[string]ShopBreakdown{}, ShopFilterSnapshot: shopSnapshotNames(allowed),
+		filterHits: sybproductfilter.HitCounter{}}

 	dates, err := splitDateRange(dateFrom, dateTo)
 	if err != nil {
@@ -145,6 +136,10 @@ func SyncWithShopSnapshot(ctx context.Context, db *gorm.DB, client *sybclient.Cl
 	if len(allowed) == 0 {
 		return report, ErrNoEnabledShop
 	}
+	filters, err := sybproductfilter.LoadEnabled(ctx, db)
+	if err != nil {
+		return report, fmt.Errorf("读取商品过滤规则失败: %w", err)
+	}
 	report.ShopFilterHash = enabledShopHash(allowed)
 	emit := func(daysProcessed int) error {
 		if progress == nil {
@@ -190,106 +185,41 @@ func SyncWithShopSnapshot(ctx context.Context, db *gorm.DB, client *sybclient.Cl
 		plans = append(plans, dayPlan{date: date, total: total})
 	}

-	for dayIndex, plan := range plans {
-		if plan.total == 0 {
-			if err := emit(dayIndex + 1); err != nil {
-				return report, err
-			}
-			continue
-		}
-		// `[必须]` Completeness first, filtering second. loadDailyList proves the
-		// day's snapshot is whole; filtering before that would let drift among
-		// other shops' orders hide a hole in the ones we do want
-		// (docs/12-syb-erp-interface.md §8).
-		rows, listErr := loadDailyListWithRecovery(ctx, client, plan.date, pageSize, plan.total, maxMatches)
-		if listErr != nil && len(rows) == 0 {
-			return report, listErr
-		}
-		report.OrderCount += len(rows)
-
-		byID := make(map[int64]sybclient.StockRow, len(rows))
-		ids := make([]int64, 0, len(rows))
-		for _, row := range rows {
-			name := stringField(row.Raw, "shopName")
-			label := name
-			if sybshop.IsBlank(label) {
-				label = "(无店铺名)"
-			}
-			display, ok := allowed[sybshop.Normalize(name)]
-			if ok {
-				label = display
-			}
-			if !ok {
-				entry := report.ShopBreakdown[label]
-				entry.Skipped++
-				report.ShopBreakdown[label] = entry
-				report.ShopSkipped++
-				continue
-			}
-			entry := report.ShopBreakdown[label]
-			entry.Accepted++
-			report.ShopBreakdown[label] = entry
-			report.AcceptedCount++
-			byID[row.ID] = row
-			ids = append(ids, row.ID)
-		}
-		if len(ids) == 0 {
-			if err := emit(dayIndex + 1); err != nil {
-				return report, err
-			}
-			continue
-		}
-
-		for start := 0; start < len(ids); start += detailBatch {
-			end := start + detailBatch
-			if end > len(ids) {
-				end = len(ids)
-			}
-			batch := ids[start:end]
-			details, err := client.DetailListByStock(ctx, batch)
-			if err != nil {
-				return report, fmt.Errorf("拉取 %s 货运单明细失败（本次同步停止；"+
-					"已写入的数据保留，重跑会按 (order_code, detail_id) 覆盖）: %w", plan.date, err)
-			}
-			if err := validateDetailBatch(batch, details); err != nil {
-				return report, fmt.Errorf("%s 货运单明细不完整：%w；本次同步停止", plan.date, err)
-			}
-			for _, detail := range details {
-				// `[必须]` Re-check the shop on the detail response. The list said
-				// this order belongs to an enabled shop; if the detail disagrees,
-				// the two views are inconsistent and importing it would write a
-				// row for a shop nobody enabled.
-				name := stringField(detail.Raw, "shopName")
-				if sybshop.IsBlank(name) {
-					moveAcceptedToSkipped(&report, stringField(byID[detail.ID].Raw, "shopName"), "(无店铺名)", allowed)
-					report.AcceptedCount--
-					report.ShopSkipped++
-					continue
-				}
-				if _, ok := allowed[sybshop.Normalize(name)]; !ok {
-					moveAcceptedToSkipped(&report, stringField(byID[detail.ID].Raw, "shopName"), name, allowed)
-					report.AcceptedCount--
-					report.ShopSkipped++
-					continue
-				}
-				if err := applyStockDetail(ctx, db, byID[detail.ID], detail, &report); err != nil {
-					return report, err
-				}
-			}
-			if err := emit(dayIndex); err != nil {
-				return report, err
-			}
-		}
-		if listErr != nil {
-			return report, listErr
-		}
-		if err := emit(dayIndex + 1); err != nil {
+	daysCompleted := 0
+	var failures []error
+	for _, plan := range plans {
+		if err := ctx.Err(); err != nil {
 			return report, err
 		}
+		_, dayErr := loadDailyList(ctx, client, plan.date, pageSize, plan.total, func(rows []sybclient.StockRow, page int) error {
+			report.OrderCount += len(rows)
+			err := importSyncPage(ctx, db, client, rows, allowed, &report, filters)
+			if err != nil {
+				return fmt.Errorf("%s 第 %d 页明细/入库阶段失败: %w", plan.date, page, err)
+			}
+			if err := emit(daysCompleted); err != nil {
+				return &syncFatalError{err}
+			}
+			return nil
+		})
+		if dayErr != nil {
+			failures = append(failures, dayErr)
+			var fatal *syncFatalError
+			if ctx.Err() != nil || errors.As(dayErr, &fatal) || errors.Is(dayErr, sybclient.ErrSessionInvalid) {
+				return report, errors.Join(failures...)
+			}
+			continue
+		}
+		daysCompleted++
+		if err := emit(daysCompleted); err != nil {
+			return report, errors.Join(append(failures, err)...)
+		}
 	}
-
 	report.FinishedAt = time.Now().UTC()
-	return report, nil
+	if err := sybproductfilter.UpdateHits(ctx, db, filters, report.filterHits, report.FinishedAt); err != nil {
+		return report, err
+	}
+	return report, errors.Join(failures...)
 }

 func shopSnapshotNames(allowed map[string]string) []string {
@@ -336,39 +266,7 @@ func moveAcceptedToSkipped(report *SyncReport, listName, detailName string, allo
 // `[必须]` The loop bound comes from expectedTotal (listTotal), because
 // list.total is the current page's row count, not the filtered total (§4.3).
 // Driving the loop with the response's own total would stop after page one.
-func loadDailyListWithRecovery(ctx context.Context, client *sybclient.Client, date string, pageSize, expectedTotal, maxMatches int) ([]sybclient.StockRow, error) {
-	if date != shanghaiToday() {
-		return loadDailyList(ctx, client, date, pageSize, expectedTotal)
-	}
-	var last *snapshotDriftError
-	for attempt := 1; attempt <= maxTodaySnapshotAttempts; attempt++ {
-		if attempt > 1 {
-			total, err := client.ListTotal(ctx, date, date, pageSize)
-			if err != nil {
-				return nil, fmt.Errorf("重新查询今天 %s 货运单总数失败: %w", date, err)
-			}
-			if total > maxMatches {
-				return nil, fmt.Errorf("今天 %s 的货运单总数 %d 超过单次同步上限 %d", date, total, maxMatches)
-			}
-			expectedTotal = total
-		}
-		rows, err := loadDailyList(ctx, client, date, pageSize, expectedTotal)
-		if err == nil {
-			return rows, nil
-		}
-		var drift *snapshotDriftError
-		if !errors.As(err, &drift) {
-			return nil, fmt.Errorf("今天第 %d/%d 次拉取失败: %w", attempt, maxTodaySnapshotAttempts, err)
-		}
-		last = drift
-	}
-	if last != nil && last.valid && len(last.rows) > 0 {
-		return last.rows, fmt.Errorf("今天持续变化，已保存本次取得的完整明细，但未形成稳定快照；下次同步继续覆盖: %w", last)
-	}
-	return nil, fmt.Errorf("今天持续变化，连续 %d 次未形成稳定快照，本次同步停止: %w", maxTodaySnapshotAttempts, last)
-}
-
-func loadDailyList(ctx context.Context, client *sybclient.Client, date string, pageSize, expectedTotal int) ([]sybclient.StockRow, error) {
+func loadDailyList(ctx context.Context, client *sybclient.Client, date string, pageSize, expectedTotal int, consume ...func([]sybclient.StockRow, int) error) ([]sybclient.StockRow, error) {
 	rows := make([]sybclient.StockRow, 0, expectedTotal)
 	type position struct{ page, row int }
 	seen := make(map[int64]position, expectedTotal)
@@ -387,6 +285,24 @@ func loadDailyList(ctx context.Context, client *sybclient.Client, date string, p
 		if pageCount != len(page) {
 			return nil, fmt.Errorf("%s 货运单列表第 %d 页响应条数不自洽：total=%d，list=%d", date, pageIndex, pageCount, len(page))
 		}
+		// SYB may change a page while the list is being read. Re-read once
+		// before treating a boundary-page count drift as a fatal snapshot error.
+		if len(page) != expectedPageCount {
+			pause := time.NewTimer(500 * time.Millisecond)
+			select {
+			case <-ctx.Done():
+				pause.Stop()
+				return nil, ctx.Err()
+			case <-pause.C:
+			}
+			page, pageCount, err = client.ListPage(ctx, date, date, start, pageIndex, pageSize)
+			if err != nil {
+				return nil, fmt.Errorf("重读 %s 货运单列表第 %d 页失败：%w", date, pageIndex, err)
+			}
+			if pageCount != len(page) {
+				return nil, fmt.Errorf("%s 货运单列表第 %d 页重读响应条数不自洽：total=%d，list=%d", date, pageIndex, pageCount, len(page))
+			}
+		}
 		// Validate the whole page first: a same-page duplicate must not be
 		// hidden behind an earlier, recoverable cross-page overlap.
 		pageSeen := make(map[int64]int, len(page))
@@ -413,6 +329,11 @@ func loadDailyList(ctx context.Context, client *sybclient.Client, date string, p
 		if len(page) != expectedPageCount {
 			return nil, &snapshotDriftError{message: fmt.Sprintf("%s 货运单列表第 %d 页不完整且相对初始总数发生变化：预期 %d 行，实际 %d 行", date, pageIndex, expectedPageCount, len(page)), rows: rows, valid: len(page) > expectedPageCount}
 		}
+		if len(consume) > 0 {
+			if err := consume[0](page, pageIndex); err != nil {
+				return nil, err
+			}
+		}
 	}

 	// Re-read the total: if it moved while we paged, some order was inserted or
@@ -459,7 +380,11 @@ func validateDetailBatch(requested []int64, details []sybclient.StockDetail) err
 // applyStockDetail writes one shipment order's items. Each item is its own
 // ApplyDetail call and its own transaction — a several-thousand-row sync must
 // not sit in one long-held transaction.
-func applyStockDetail(ctx context.Context, db *gorm.DB, row sybclient.StockRow, detail sybclient.StockDetail, report *SyncReport) error {
+func applyStockDetail(ctx context.Context, db *gorm.DB, row sybclient.StockRow, detail sybclient.StockDetail, report *SyncReport, sets ...sybproductfilter.RuleSet) error {
+	var filters sybproductfilter.RuleSet
+	if len(sets) > 0 {
+		filters = sets[0]
+	}
 	order := OrderInput{
 		Code:     detail.Code,
 		StockID:  uint64(detail.ID),
@@ -469,6 +394,23 @@ func applyStockDetail(ctx context.Context, db *gorm.DB, row sybclient.StockRow,
 		order.Code = row.Code
 	}
 	for _, item := range detail.Details {
+		variation := stringField(item.Raw, "variationSku")
+		if rule := filters.Match(variation); rule != nil {
+			// `[必须]` Count the two kinds separately and per rule. A combined
+			// total would hide a structural rule that stopped matching because
+			// 档口 changed its code format, and a per-kind total would make the
+			// disable-confirmation dialog quote the same figure for "#" and "-"
+			// even though they match very different numbers of rows (#269).
+			if rule.Kind == "char" {
+				report.CharFilterSkipped++
+			} else {
+				report.KeywordFilterSkipped++
+			}
+			if report.filterHits != nil {
+				report.filterHits.Add(rule)
+			}
+			continue
+		}
 		raw, err := json.Marshal(item.Raw)
 		if err != nil {
 			return fmt.Errorf("货运单 %s 明细 %d 原始数据编码失败: %w", order.Code, item.ID, err)
@@ -0,0 +1,88 @@
+package sybimport
+
+import (
+	"context"
+	"go-admin/app/goauto/sybclient"
+	"go-admin/app/goauto/sybproductfilter"
+	"go-admin/app/goauto/sybshop"
+	"gorm.io/gorm"
+)
+
+// Database/progress errors stop the entire run, not merely the current date.
+type syncFatalError struct{ error }
+
+func (e *syncFatalError) Unwrap() error { return e.error }
+
+// Read all remote details before opening a page transaction. Publish counters
+// only after commit, so a rollback never reports records as saved.
+func importSyncPage(ctx context.Context, db *gorm.DB, client *sybclient.Client, rows []sybclient.StockRow, allowed map[string]string, report *SyncReport, sets ...sybproductfilter.RuleSet) error {
+	var filters sybproductfilter.RuleSet
+	if len(sets) > 0 {
+		filters = sets[0]
+	}
+	next := *report
+	next.ShopBreakdown = make(map[string]ShopBreakdown, len(report.ShopBreakdown))
+	for k, v := range report.ShopBreakdown {
+		next.ShopBreakdown[k] = v
+	}
+	byID := make(map[int64]sybclient.StockRow)
+	var ids []int64
+	for _, row := range rows {
+		name := stringField(row.Raw, "shopName")
+		label := name
+		if sybshop.IsBlank(label) {
+			label = "(无店铺名)"
+		}
+		display, ok := allowed[sybshop.Normalize(name)]
+		if ok {
+			label = display
+		}
+		entry := next.ShopBreakdown[label]
+		if ok {
+			entry.Accepted++
+			next.AcceptedCount++
+			ids = append(ids, row.ID)
+			byID[row.ID] = row
+		} else {
+			entry.Skipped++
+			next.ShopSkipped++
+		}
+		next.ShopBreakdown[label] = entry
+	}
+	var details []sybclient.StockDetail
+	for start := 0; start < len(ids); start += detailBatch {
+		end := start + detailBatch
+		if end > len(ids) {
+			end = len(ids)
+		}
+		batch, err := client.DetailListByStock(ctx, ids[start:end])
+		if err != nil {
+			return err
+		}
+		if err := validateDetailBatch(ids[start:end], batch); err != nil {
+			return err
+		}
+		details = append(details, batch...)
+	}
+	err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for _, detail := range details {
+			name := stringField(detail.Raw, "shopName")
+			_, ok := allowed[sybshop.Normalize(name)]
+			if sybshop.IsBlank(name) || !ok {
+				moveAcceptedToSkipped(&next, stringField(byID[detail.ID].Raw, "shopName"), name, allowed)
+				next.AcceptedCount--
+				next.ShopSkipped++
+				continue
+			}
+			if err := applyStockDetail(ctx, tx, byID[detail.ID], detail, &next, filters); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return &syncFatalError{err}
+	}
+	*report = next
+	return nil
+}
@@ -0,0 +1,117 @@
+package sybimport
+
+import (
+	"context"
+	"errors"
+	"go-admin/app/goauto/models"
+	"strings"
+	"testing"
+)
+
+func TestPageFailurePreservesEarlierPagesContinuesDatesAndRerunsIdempotently(t *testing.T) {
+	db := newSyncTestDB(t)
+	f := &fakeSYB{perDay: map[string]int{"2026-08-01": 3, "2026-08-02": 1}, shortPageAtIndex: 2}
+	var last SyncProgress
+	report, err := SyncWithProgress(context.Background(), db, newSyncClient(t, f), SyncConfig{PageSize: 2, MaxMatches: 100}, "2026-08-01", "2026-08-02", func(p SyncProgress) error { last = p; return nil })
+	if err == nil || !strings.Contains(err.Error(), "第 2 页") || report.Created != 2 || report.Updated != 1 || last.DaysProcessed != 1 {
+		t.Fatalf("report=%+v progress=%+v err=%v", report, last, err)
+	}
+	var count int64
+	db.Model(&models.SYBProduct{}).Count(&count)
+	if count != 2 {
+		t.Fatal(count)
+	}
+	f.shortPageAtIndex = 0
+	report, err = Sync(context.Background(), db, newSyncClient(t, f), SyncConfig{PageSize: 2, MaxMatches: 100}, "2026-08-01", "2026-08-02")
+	if err != nil || report.Created != 1 || report.Updated != 3 {
+		t.Fatalf("rerun=%+v err=%v", report, err)
+	}
+	db.Model(&models.SYBProduct{}).Count(&count)
+	if count != 3 {
+		t.Fatal(count)
+	}
+}
+
+func TestPageTransactionRollbackDoesNotPublishCountersAndStopsDates(t *testing.T) {
+	db := newSyncTestDB(t)
+	if err := db.Exec("CREATE TRIGGER reject_second BEFORE INSERT ON syb_product WHEN NEW.detail_id = 10011 BEGIN SELECT RAISE(ABORT, 'test database failure'); END").Error; err != nil {
+		t.Fatal(err)
+	}
+	f := &fakeSYB{perDay: map[string]int{"2026-08-01": 3, "2026-08-02": 1}}
+	report, err := Sync(context.Background(), db, newSyncClient(t, f), SyncConfig{PageSize: 2, MaxMatches: 100}, "2026-08-01", "2026-08-02")
+	var fatal *syncFatalError
+	if !errors.As(err, &fatal) || report.Created != 0 || report.DetailCount != 0 || len(f.listCalls) != 1 {
+		t.Fatalf("report=%+v calls=%v err=%v", report, f.listCalls, err)
+	}
+	var count int64
+	db.Model(&models.SYBProduct{}).Count(&count)
+	if count != 0 {
+		t.Fatal(count)
+	}
+}
+
+func TestPageProgressFailureStopsAfterCommittedPage(t *testing.T) {
+	db := newSyncTestDB(t)
+	f := &fakeSYB{perDay: map[string]int{"2026-08-01": 3, "2026-08-02": 1}}
+	calls := 0
+	report, err := SyncWithProgress(context.Background(), db, newSyncClient(t, f), SyncConfig{PageSize: 2, MaxMatches: 100}, "2026-08-01", "2026-08-02", func(SyncProgress) error {
+		calls++
+		if calls == 2 {
+			return errors.New("progress unavailable")
+		}
+		return nil
+	})
+	if err == nil || report.Created != 2 || len(f.listCalls) != 1 {
+		t.Fatalf("report=%+v err=%v", report, err)
+	}
+}
+
+func TestPageMissingDetailPreservesPriorPageAndContinuesNextDate(t *testing.T) {
+	db := newSyncTestDB(t)
+	f := &fakeSYB{perDay: map[string]int{"2026-08-01": 3, "2026-08-02": 1}, detailDropID: 1002}
+	report, err := Sync(context.Background(), db, newSyncClient(t, f), SyncConfig{PageSize: 2, MaxMatches: 100}, "2026-08-01", "2026-08-02")
+	if err == nil || report.Created != 2 || report.Updated != 1 || report.OrderCount != 4 || len(f.listCalls) != 3 {
+		t.Fatalf("report=%+v err=%v", report, err)
+	}
+}
+
+func TestPageCancellationPreservesCommitAndStopsNextPage(t *testing.T) {
+	db := newSyncTestDB(t)
+	f := &fakeSYB{perDay: map[string]int{"2026-08-01": 3, "2026-08-02": 1}}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	report, err := SyncWithProgress(ctx, db, newSyncClient(t, f), SyncConfig{PageSize: 2, MaxMatches: 100}, "2026-08-01", "2026-08-02", func(p SyncProgress) error {
+		if p.Report.Created > 0 {
+			cancel()
+		}
+		return nil
+	})
+	if !errors.Is(err, context.Canceled) || report.Created != 2 || len(f.listCalls) != 1 {
+		t.Fatalf("report=%+v err=%v", report, err)
+	}
+}
+
+func TestPartialFinishPreservesProgressReleasesSlotAndIsFilterable(t *testing.T) {
+	db := newSyncTestDB(t)
+	ctx := context.Background()
+	s := NewSyncRunService(db)
+	run, err := s.Create(ctx, CreateSyncRunInput{DateFrom: "2026-08-01", DateTo: "2026-08-02"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	report := SyncReport{Created: 2, DetailCount: 2, ShopBreakdown: map[string]ShopBreakdown{}}
+	if err := s.UpdateProgress(ctx, run.ID, SyncProgress{Report: report, DaysTotal: 2, DaysProcessed: 1}); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Finish(ctx, run.ID, SyncRunPartial, report, errors.New("第 2 页失败")); err != nil {
+		t.Fatal(err)
+	}
+	row, err := s.Detail(ctx, run.ID)
+	if err != nil || row.Status != SyncRunPartial || row.ActiveSlot != nil || row.ProgressPercent != 50 || row.Created != 2 {
+		t.Fatalf("row=%+v err=%v", row, err)
+	}
+	result, err := s.List(ctx, SyncRunListRequest{Page: 1, PageSize: 20, Status: SyncRunPartial})
+	if err != nil || result.Total != 1 {
+		t.Fatalf("result=%+v err=%v", result, err)
+	}
+}
@@ -18,6 +18,7 @@ import (
 const (
 	SyncRunRunning     = "running"
 	SyncRunSucceeded   = "succeeded"
+	SyncRunPartial     = "partial_success"
 	SyncRunFailed      = "failed"
 	SyncRunInterrupted = "interrupted"
 )
@@ -69,13 +70,14 @@ func (s *SyncRunService) UpdateProgress(ctx context.Context, id uint64, progress
 		"days_total": progress.DaysTotal, "days_processed": progress.DaysProcessed,
 		"order_count": progress.Report.OrderCount, "detail_count": progress.Report.DetailCount,
 		"accepted_count": progress.Report.AcceptedCount, "shop_skipped": progress.Report.ShopSkipped,
+		"char_filter_skipped": progress.Report.CharFilterSkipped, "keyword_filter_skipped": progress.Report.KeywordFilterSkipped,
 		"created_count": progress.Report.Created, "updated_count": progress.Report.Updated,
 		"shop_filter_hash": progress.Report.ShopFilterHash, "shop_breakdown_json": payload,
 	}).Error
 }

 func (s *SyncRunService) Finish(ctx context.Context, id uint64, status string, report SyncReport, runErr error) error {
-	if status != SyncRunSucceeded && status != SyncRunFailed {
+	if status != SyncRunSucceeded && status != SyncRunPartial && status != SyncRunFailed {
 		return fmt.Errorf("invalid terminal sync status %q", status)
 	}
 	payload, err := marshalSyncRunPayload(report.ShopBreakdown, report.ShopFilterSnapshot)
@@ -91,6 +93,7 @@ func (s *SyncRunService) Finish(ctx context.Context, id uint64, status string, r
 		"status": status, "active_slot": nil, "finished_at": now, "error_message": message,
 		"order_count": report.OrderCount, "detail_count": report.DetailCount,
 		"accepted_count": report.AcceptedCount, "shop_skipped": report.ShopSkipped,
+		"char_filter_skipped": report.CharFilterSkipped, "keyword_filter_skipped": report.KeywordFilterSkipped,
 		"created_count": report.Created, "updated_count": report.Updated,
 		"shop_breakdown_json": payload,
 	}
@@ -20,7 +20,7 @@ func (handler Handler) ListSyncRuns(c *gin.Context) {
 		return
 	}
 	status := strings.TrimSpace(c.Query("status"))
-	if status != "" && status != SyncRunRunning && status != SyncRunSucceeded && status != SyncRunFailed && status != SyncRunInterrupted {
+	if status != "" && status != SyncRunRunning && status != SyncRunSucceeded && status != SyncRunPartial && status != SyncRunFailed && status != SyncRunInterrupted {
 		writeError(c, invalidRequest("status 无效"))
 		return
 	}
@@ -36,4 +36,12 @@ func TestSyncRunListAndDetailHandlers(t *testing.T) {
 	if detail.Code != http.StatusOK || !strings.Contains(detail.Body.String(), `"operatorName":"管理员"`) {
 		t.Fatalf("详情响应不正确: %d %s", detail.Code, detail.Body.String())
 	}
+	if err := NewSyncRunService(db).Finish(context.Background(), run.ID, SyncRunPartial, SyncReport{Created: 1}, nil); err != nil {
+		t.Fatal(err)
+	}
+	partial := httptest.NewRecorder()
+	engine.ServeHTTP(partial, httptest.NewRequest(http.MethodGet, "/sync-runs?status=partial_success", nil))
+	if partial.Code != http.StatusOK || !strings.Contains(partial.Body.String(), `"total":1`) {
+		t.Fatalf("partial filter: %d %s", partial.Code, partial.Body.String())
+	}
 }
@@ -9,7 +9,6 @@ import (
 	"net/http/httptest"
 	"strings"
 	"testing"
-	"time"

 	"go-admin/app/goauto/migrations"
 	"go-admin/app/goauto/models"
@@ -276,39 +275,6 @@ func TestSyncStopsWhenTotalDriftsDuringPaging(t *testing.T) {
 	}
 }

-func TestTodaySnapshotDriftRetriesFromFirstPage(t *testing.T) {
-	originalNow := syncNow
-	syncNow = func() time.Time { return time.Date(2026, 8, 29, 12, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*60*60)) }
-	t.Cleanup(func() { syncNow = originalNow })
-	f := &fakeSYB{perDay: map[string]int{"2026-08-29": 10}, totalOverride: map[int]int{1: 11, 2: 10, 3: 10}}
-	rows, err := loadDailyListWithRecovery(context.Background(), newSyncClient(t, f), "2026-08-29", 10, 10, 1000)
-	if err != nil || len(rows) != 10 || f.listTotalCalls != 3 {
-		t.Fatalf("rows=%d totalCalls=%d err=%v", len(rows), f.listTotalCalls, err)
-	}
-}
-
-func TestTodayThirdDriftReturnsValidLastListForDegradedSave(t *testing.T) {
-	originalNow := syncNow
-	syncNow = func() time.Time { return time.Date(2026, 8, 29, 12, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*60*60)) }
-	t.Cleanup(func() { syncNow = originalNow })
-	f := &fakeSYB{perDay: map[string]int{"2026-08-29": 10}, totalOverride: map[int]int{1: 11, 2: 10, 3: 11, 4: 10, 5: 11}}
-	rows, err := loadDailyListWithRecovery(context.Background(), newSyncClient(t, f), "2026-08-29", 10, 10, 1000)
-	if err == nil || len(rows) != 10 || !strings.Contains(err.Error(), "已保存本次取得的完整明细") {
-		t.Fatalf("rows=%d err=%v", len(rows), err)
-	}
-}
-
-func TestHistoricalSnapshotDriftDoesNotRetry(t *testing.T) {
-	originalNow := syncNow
-	syncNow = func() time.Time { return time.Date(2026, 8, 29, 12, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*60*60)) }
-	t.Cleanup(func() { syncNow = originalNow })
-	f := &fakeSYB{perDay: map[string]int{"2026-08-28": 10}, totalOverride: map[int]int{1: 11}}
-	rows, err := loadDailyListWithRecovery(context.Background(), newSyncClient(t, f), "2026-08-28", 10, 10, 1000)
-	if err == nil || rows != nil || f.listTotalCalls != 1 {
-		t.Fatalf("rows=%v totalCalls=%d err=%v", rows, f.listTotalCalls, err)
-	}
-}
-
 // 某页行数少于预期同样是不完整快照。
 func TestSyncStopsOnShortPage(t *testing.T) {
 	db := newSyncTestDB(t)
@@ -3,6 +3,7 @@ package sybinnercode
 import (
 	"encoding/json"
 	"errors"
+	"go-admin/common/clientprincipal"
 	"io"
 	"net/http"
 	"strconv"
@@ -81,13 +82,19 @@ func (h Handler) Import(c *gin.Context) {
 	if !ok {
 		return
 	}
-	result, err := service.Import(c.Request.Context(), src, file.Filename, uint64(user.GetUserId(c)), c.PostForm("requestId"))
+	result, err := service.Import(c.Request.Context(), src, file.Filename, clientOperator(c), c.PostForm("requestId"))
 	if err != nil {
 		writeError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"code": 200, "data": result})
 }
+func clientOperator(c *gin.Context) uint64 {
+	if p, ok := clientprincipal.Get(c); ok {
+		return p.AuthorizedBy
+	}
+	return uint64(user.GetUserId(c))
+}
 func (h Handler) Delete(c *gin.Context) {
 	var request DeleteRequest
 	if err := decode(c, &request); err != nil {
@@ -98,7 +105,7 @@ func (h Handler) Delete(c *gin.Context) {
 	if !ok {
 		return
 	}
-	result, err := service.Delete(c.Request.Context(), uint64(user.GetUserId(c)), request)
+	result, err := service.Delete(c.Request.Context(), clientOperator(c), request)
 	if err != nil {
 		writeError(c, err)
 		return
@@ -150,7 +157,7 @@ func (h Handler) Apply(c *gin.Context) {
 	if !ok {
 		return
 	}
-	result, err := service.QueueApply(c.Request.Context(), uint64(user.GetUserId(c)), request)
+	result, err := service.QueueApply(c.Request.Context(), clientOperator(c), request)
 	if err != nil {
 		writeError(c, err)
 		return
@@ -0,0 +1,129 @@
+package sybproductfilter
+
+import (
+	"encoding/json"
+	"errors"
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/sdk/pkg"
+	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
+	"gorm.io/gorm"
+	"net/http"
+	"strconv"
+)
+
+type Handler struct{ DB *gorm.DB }
+
+func (h Handler) service(c *gin.Context) (*Service, bool) {
+	db := h.DB
+	var e error
+	if db == nil {
+		db, e = pkg.GetOrm(c)
+	}
+	if e != nil {
+		writeError(c, internal(e))
+		return nil, false
+	}
+	return NewService(db), true
+}
+func (h Handler) List(c *gin.Context) {
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	p, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	ps, _ := strconv.Atoi(c.DefaultQuery("pageSize", "50"))
+	r, e := s.List(c.Request.Context(), ListRequest{Page: p, PageSize: ps, Kind: c.Query("kind"), Keyword: c.Query("keyword"), EnabledOnly: c.Query("enabledOnly") == "true"})
+	if e != nil {
+		writeError(c, e)
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": r})
+}
+func (h Handler) Create(c *gin.Context) {
+	var r CreateRequest
+	if !decode(c, &r) {
+		return
+	}
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	x, e := s.Create(c.Request.Context(), r)
+	if e != nil {
+		writeError(c, e)
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": x})
+}
+func (h Handler) SetEnabled(c *gin.Context) {
+	id, ok := idParam(c)
+	if !ok {
+		return
+	}
+	var r SetEnabledRequest
+	if !decode(c, &r) {
+		return
+	}
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	claims := jwt.ExtractClaims(c)
+	name, _ := claims["nice"].(string)
+	x, e := s.SetEnabled(c.Request.Context(), id, r, name)
+	if e != nil {
+		writeError(c, e)
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": x})
+}
+func (h Handler) Delete(c *gin.Context) {
+	id, ok := idParam(c)
+	if !ok {
+		return
+	}
+	s, ok := h.service(c)
+	if !ok {
+		return
+	}
+	if e := s.Delete(c.Request.Context(), id); e != nil {
+		writeError(c, e)
+		return
+	}
+	c.JSON(200, gin.H{"code": 200, "data": gin.H{"deleted": true}})
+}
+func idParam(c *gin.Context) (uint64, bool) {
+	id, e := strconv.ParseUint(c.Param("filterId"), 10, 64)
+	if e != nil || id == 0 {
+		writeError(c, invalid("过滤规则 id 必须是正整数"))
+		return 0, false
+	}
+	return id, true
+}
+func decode(c *gin.Context, t any) bool {
+	d := json.NewDecoder(c.Request.Body)
+	d.DisallowUnknownFields()
+	if e := d.Decode(t); e != nil {
+		writeError(c, invalid("请求体解析失败："+e.Error()))
+		return false
+	}
+	return true
+}
+func writeError(c *gin.Context, e error) {
+	var se *ServiceError
+	if !errors.As(e, &se) {
+		se = internal(e).(*ServiceError)
+	}
+	status := 500
+	switch se.Code {
+	case CodeInvalidRequest:
+		status = 422
+	case CodeConflict:
+		status = 409
+	case CodeNotFound:
+		status = 404
+	case CodeForbidden:
+		status = http.StatusForbidden
+	}
+	c.JSON(status, gin.H{"code": se.Code, "message": se.Message})
+}
@@ -0,0 +1,84 @@
+package sybproductfilter
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// 用线上真实取到的 variationSku 样本，验证过滤判定与每条规则各自计数。
+func TestRealWorldSamplesPerRuleCounting(t *testing.T) {
+	db := testDB(t)
+	ctx := context.Background()
+	set, err := LoadEnabled(ctx, db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	samples := []struct {
+		v        string
+		wantKind string // "" = 不过滤
+	}{
+		{"新寮-雅伊阁大码女装#301", "char"},
+		{"广达-爆款大码女装#9018", "char"},
+		{"DD#004", "char"},
+		{"300斤牛奶絲圓領#A057", "char"},
+		{"上寮-琪琪尚雅网批#2604##(&15)", "char"},
+		{"PDD0582", ""},
+		{"my238", ""},
+		{"le171", ""},
+		{"1", ""},
+		{"引流款", ""},
+		{"", ""},
+	}
+	hits := HitCounter{}
+	var charN, kwN, keptN int
+	for _, s := range samples {
+		rule := set.Match(s.v)
+		if s.wantKind == "" {
+			if rule != nil {
+				t.Fatalf("%q 不应被过滤，却命中了 %q", s.v, rule.Keyword)
+			}
+			keptN++
+			continue
+		}
+		if rule == nil || rule.Kind != s.wantKind {
+			t.Fatalf("%q 应命中 %s 规则，实际 %v", s.v, s.wantKind, rule)
+		}
+		hits.Add(rule)
+		if rule.Kind == "char" {
+			charN++
+		} else {
+			kwN++
+		}
+	}
+	if charN != 5 || kwN != 0 || keptN != 6 {
+		t.Fatalf("统计不符：char=%d keyword=%d kept=%d", charN, kwN, keptN)
+	}
+	if err := UpdateHits(ctx, db, set, hits, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	after, err := LoadEnabled(ctx, db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]int{}
+	for _, x := range after.Chars {
+		if x.LastHitCount == nil {
+			t.Fatalf("规则 %q 必须被写入命中数", x.Keyword)
+		}
+		got[x.Keyword] = *x.LastHitCount
+	}
+	// "#" 命中 4 条（301/9018/DD#004/A057 ... 其中带 - 的先被 "-" 规则接走）
+	if got["-"]+got["#"] != 5 {
+		t.Fatalf("两条结构规则命中数之和应为 5，实际 - =%d # =%d", got["-"], got["#"])
+	}
+	if got["-"] == got["#"] {
+		t.Fatalf("两条规则不应记成同一个数（这正是 #269 修的 bug）: - =%d # =%d", got["-"], got["#"])
+	}
+	for _, x := range after.Keywords {
+		if x.LastHitCount == nil || *x.LastHitCount != 0 {
+			t.Fatalf("未命中的关键词 %q 应记 0，实际 %v", x.Keyword, x.LastHitCount)
+		}
+	}
+	t.Logf("结构规则命中：- =%d  # =%d", got["-"], got["#"])
+}
@@ -0,0 +1,15 @@
+package sybproductfilter
+
+import (
+	"github.com/gin-gonic/gin"
+	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
+	"go-admin/common/middleware"
+)
+
+func InitRouter(e *gin.Engine, a *jwt.GinJWTMiddleware) {
+	g := e.Group("/api/admin/v1/syb-product-filters").Use(a.MiddlewareFunc()).Use(middleware.AuthCheckRole())
+	g.GET("", Handler{}.List)
+	g.POST("", middleware.RequireRoleKey("admin"), Handler{}.Create)
+	g.PATCH("/:filterId/enabled", middleware.RequireRoleKey("admin"), Handler{}.SetEnabled)
+	g.DELETE("/:filterId", middleware.RequireRoleKey("admin"), Handler{}.Delete)
+}
@@ -0,0 +1,252 @@
+package sybproductfilter
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"go-admin/app/goauto/models"
+	"go-admin/app/goauto/sybshop"
+	"gorm.io/gorm"
+)
+
+type ServiceError struct {
+	Code, Message string
+	Cause         error
+}
+
+func (e *ServiceError) Error() string {
+	if e.Cause != nil {
+		return fmt.Sprintf("%s: %v", e.Message, e.Cause)
+	}
+	return e.Message
+}
+func (e *ServiceError) Unwrap() error { return e.Cause }
+
+const (
+	CodeInvalidRequest = "INVALID_REQUEST"
+	CodeNotFound       = "SYB_PRODUCT_FILTER_NOT_FOUND"
+	CodeConflict       = "SYB_PRODUCT_FILTER_DUPLICATE"
+	CodeForbidden      = "FORBIDDEN"
+)
+
+func invalid(m string) error { return &ServiceError{Code: CodeInvalidRequest, Message: m} }
+func internal(e error) error {
+	return &ServiceError{Code: "INTERNAL_ERROR", Message: "服务器内部错误", Cause: e}
+}
+
+type Service struct{ DB *gorm.DB }
+
+func NewService(db *gorm.DB) *Service { return &Service{DB: db} }
+
+type ListRequest struct {
+	Page, PageSize int
+	Kind, Keyword  string
+	EnabledOnly    bool
+}
+type ListResponse struct {
+	Items        []models.SYBProductFilter `json:"items"`
+	Total        int64                     `json:"total"`
+	EnabledCount int64                     `json:"enabledCount"`
+	Page         int                       `json:"page"`
+	PageSize     int                       `json:"pageSize"`
+}
+
+func (s *Service) List(ctx context.Context, r ListRequest) (ListResponse, error) {
+	if r.Page < 1 {
+		r.Page = 1
+	}
+	if r.PageSize < 1 || r.PageSize > 200 {
+		r.PageSize = 50
+	}
+	q := s.DB.WithContext(ctx).Model(&models.SYBProductFilter{})
+	if r.Kind != "" {
+		q = q.Where("kind = ?", r.Kind)
+	}
+	if k := sybshop.Normalize(r.Keyword); k != "" {
+		q = q.Where("normalized_keyword LIKE ?", "%"+k+"%")
+	}
+	if r.EnabledOnly {
+		q = q.Where("enabled = ?", true)
+	}
+	var total, enabled int64
+	if err := q.Count(&total).Error; err != nil {
+		return ListResponse{}, internal(err)
+	}
+	items := make([]models.SYBProductFilter, 0, r.PageSize)
+	if err := q.Order("kind ASC, id ASC").Offset((r.Page - 1) * r.PageSize).Limit(r.PageSize).Find(&items).Error; err != nil {
+		return ListResponse{}, internal(err)
+	}
+	if err := s.DB.WithContext(ctx).Model(&models.SYBProductFilter{}).Where("enabled = ?", true).Count(&enabled).Error; err != nil {
+		return ListResponse{}, internal(err)
+	}
+	return ListResponse{Items: items, Total: total, EnabledCount: enabled, Page: r.Page, PageSize: r.PageSize}, nil
+}
+
+type CreateRequest struct {
+	Kind    string  `json:"kind"`
+	Keyword string  `json:"keyword"`
+	Enabled *bool   `json:"enabled"`
+	Note    *string `json:"note"`
+}
+
+func validate(kind, keyword string) (string, string, error) {
+	if kind != "char" && kind != "keyword" {
+		return "", "", invalid("kind 必须是 char 或 keyword")
+	}
+	keyword = strings.TrimSpace(keyword)
+	if keyword == "" {
+		return "", "", invalid("关键词不能为空")
+	}
+	if sybshop.ContainsControl(keyword) {
+		return "", "", invalid("关键词不能包含控制字符")
+	}
+	return keyword, sybshop.Normalize(keyword), nil
+}
+func (s *Service) Create(ctx context.Context, r CreateRequest) (models.SYBProductFilter, error) {
+	if r.Kind == "char" {
+		return models.SYBProductFilter{}, &ServiceError{Code: CodeForbidden, Message: "结构过滤不可新增"}
+	}
+	k, n, e := validate(r.Kind, r.Keyword)
+	if e != nil {
+		return models.SYBProductFilter{}, e
+	}
+	var x models.SYBProductFilter
+	if err := s.DB.WithContext(ctx).Where("kind = ? AND normalized_keyword = ?", r.Kind, n).First(&x).Error; err == nil {
+		return models.SYBProductFilter{}, &ServiceError{Code: CodeConflict, Message: fmt.Sprintf("该关键词已存在（归一化后与「%s」相同）", x.Keyword)}
+	} else if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return models.SYBProductFilter{}, internal(err)
+	}
+	en := true
+	if r.Enabled != nil {
+		en = *r.Enabled
+	}
+	x = models.SYBProductFilter{Kind: r.Kind, Keyword: k, NormalizedKeyword: n, Enabled: en, Note: r.Note}
+	if err := s.DB.WithContext(ctx).Create(&x).Error; err != nil {
+		return models.SYBProductFilter{}, internal(err)
+	}
+	return x, nil
+}
+
+type SetEnabledRequest struct {
+	Enabled bool `json:"enabled"`
+}
+
+func (s *Service) SetEnabled(ctx context.Context, id uint64, r SetEnabledRequest, operator string) (models.SYBProductFilter, error) {
+	var x models.SYBProductFilter
+	if err := s.DB.WithContext(ctx).First(&x, id).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return x, &ServiceError{Code: CodeNotFound, Message: "过滤规则不存在"}
+		}
+		return x, internal(err)
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{"enabled": r.Enabled, "updated_at": now}
+	if x.Kind == "char" {
+		updates["last_changed_by"] = strings.TrimSpace(operator)
+		updates["last_changed_at"] = now
+	}
+	if err := s.DB.WithContext(ctx).Model(&x).Updates(updates).Error; err != nil {
+		return x, internal(err)
+	}
+	x.Enabled = r.Enabled
+	x.UpdatedAt = now
+	if x.Kind == "char" {
+		x.LastChangedBy = strings.TrimSpace(operator)
+		x.LastChangedAt = &now
+	}
+	return x, nil
+}
+func (s *Service) Delete(ctx context.Context, id uint64) error {
+	return s.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var x models.SYBProductFilter
+		if err := tx.First(&x, id).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return &ServiceError{Code: CodeNotFound, Message: "过滤规则不存在"}
+			}
+			return internal(err)
+		}
+		if x.Kind == "char" {
+			return &ServiceError{Code: CodeForbidden, Message: "结构过滤不可删除"}
+		}
+		return tx.Model(&x).Updates(map[string]any{"deleted_flag": x.ID, "deleted_at": time.Now().UTC()}).Error
+	})
+}
+
+type RuleSet struct{ Chars, Keywords []models.SYBProductFilter }
+
+func LoadEnabled(ctx context.Context, db *gorm.DB) (RuleSet, error) {
+	var rows []models.SYBProductFilter
+	if err := db.WithContext(ctx).Where("enabled = ?", true).Find(&rows).Error; err != nil {
+		return RuleSet{}, err
+	}
+	r := RuleSet{}
+	for _, x := range rows {
+		if x.Kind == "char" {
+			r.Chars = append(r.Chars, x)
+		} else {
+			r.Keywords = append(r.Keywords, x)
+		}
+	}
+	return r, nil
+}
+
+// Match reports which enabled rule first matched v, or nil when none did.
+//
+// It returns the matching rule rather than a pair of booleans because the
+// caller has to attribute the hit to one specific rule: every rule keeps its
+// own LastHitCount, and the disable-confirmation dialog quotes that per-rule
+// number ("停用「#」会让约 N 条恢复入库"). Collapsing the result to
+// char/keyword booleans would force every rule of a kind to share one
+// aggregate, and the dialog would then warn with the wrong figure — on real
+// data "#" matches 8498 rows and "-" matches 6392, so the two must never be
+// reported as the same number.
+//
+// Structural rules are checked before keyword rules so a hit is attributed the
+// way the page presents the two sections, and an empty variationSku never
+// matches: it is a product with no supplier code yet, not a 档口 item.
+func (r RuleSet) Match(v string) *models.SYBProductFilter {
+	if v == "" {
+		return nil
+	}
+	n := sybshop.Normalize(v)
+	for i, x := range r.Chars {
+		if strings.Contains(n, x.NormalizedKeyword) {
+			return &r.Chars[i]
+		}
+	}
+	for i, x := range r.Keywords {
+		if strings.Contains(n, x.NormalizedKeyword) {
+			return &r.Keywords[i]
+		}
+	}
+	return nil
+}
+
+// HitCounter accumulates per-rule hits over one sync run, keyed by rule id.
+type HitCounter map[uint64]int
+
+// Add records one hit against the rule that matched.
+func (h HitCounter) Add(rule *models.SYBProductFilter) {
+	if rule == nil {
+		return
+	}
+	h[rule.ID]++
+}
+
+// UpdateHits writes each rule's own hit count back to its row.
+//
+// Every rule in the set is written, including those with zero hits: leaving a
+// previous run's number in place would make the confirmation dialog quote a
+// figure that no longer describes the current data.
+func UpdateHits(ctx context.Context, db *gorm.DB, r RuleSet, hits HitCounter, at time.Time) error {
+	for _, x := range append(append([]models.SYBProductFilter{}, r.Chars...), r.Keywords...) {
+		if err := db.WithContext(ctx).Model(&models.SYBProductFilter{}).Where("id = ?", x.ID).
+			Updates(map[string]any{"last_hit_count": hits[x.ID], "last_hit_at": at}).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
@@ -0,0 +1,127 @@
+package sybproductfilter
+
+import (
+	"context"
+	"go-admin/app/goauto/migrations"
+	"go-admin/app/goauto/models"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"testing"
+	"time"
+)
+
+func testDB(t *testing.T) *gorm.DB {
+	db, err := gorm.Open(sqlite.Open("file:"+t.Name()+"?mode=memory&cache=shared"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = migrations.Migrate(db); err != nil {
+		t.Fatal(err)
+	}
+	return db
+}
+
+func TestMatchORAndNormalization(t *testing.T) {
+	r := RuleSet{
+		Chars:    []models.SYBProductFilter{{ID: 1, Kind: "char", NormalizedKeyword: "-"}, {ID: 2, Kind: "char", NormalizedKeyword: "#"}},
+		Keywords: []models.SYBProductFilter{{ID: 3, Kind: "keyword", NormalizedKeyword: "cvc短袖220斤"}},
+	}
+	// `[必须]` OR, never AND. Both of these contain "#" but no "-", and on real
+	// production data that difference is 2118 rows (#269).
+	for _, v := range []string{"DD#004", "300斤牛奶絲圓領#A057"} {
+		hit := r.Match(v)
+		if hit == nil || hit.Kind != "char" {
+			t.Fatalf("%q should match a structural rule, got %v", v, hit)
+		}
+		if hit.ID != 2 {
+			t.Fatalf("%q should be attributed to the \"#\" rule, got id %d", v, hit.ID)
+		}
+	}
+	if hit := r.Match("新寮-雅伊阁大码女装"); hit == nil || hit.ID != 1 {
+		t.Fatalf("dash-only value should be attributed to the \"-\" rule, got %v", hit)
+	}
+	if hit := r.Match(""); hit != nil {
+		t.Fatal("empty variationSku must not match: it is a product without a supplier code")
+	}
+	if hit := r.Match("PDD0582"); hit != nil {
+		t.Fatalf("own product code must not match, got %v", hit)
+	}
+	if hit := r.Match(" ＣＶＣ短袖220斤 "); hit == nil || hit.Kind != "keyword" {
+		t.Fatalf("full-width and surrounding spaces should normalize to a keyword hit, got %v", hit)
+	}
+	if hit := r.Match("cvc短袖220斤"); hit == nil || hit.Kind != "keyword" {
+		t.Fatalf("lowercase should normalize to a keyword hit, got %v", hit)
+	}
+	if hit := r.Match("纯棉"); hit != nil {
+		t.Fatal("normalization must not convert traditional to simplified Chinese")
+	}
+}
+
+// TestUpdateHitsIsPerRule pins the rule that每条规则各记各的命中数. Writing one
+// aggregate per kind would make the disable-confirmation dialog quote the same
+// figure for "#" and "-" even though they match very different numbers of rows.
+func TestUpdateHitsIsPerRule(t *testing.T) {
+	db := testDB(t)
+	ctx := context.Background()
+	set, err := LoadEnabled(ctx, db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(set.Chars) != 2 {
+		t.Fatalf("migration should seed 2 structural rules, got %d", len(set.Chars))
+	}
+	byKeyword := map[string]uint64{}
+	for _, x := range set.Chars {
+		byKeyword[x.Keyword] = x.ID
+	}
+	hits := HitCounter{}
+	for i := 0; i < 8498; i++ {
+		hits[byKeyword["#"]]++
+	}
+	for i := 0; i < 6392; i++ {
+		hits[byKeyword["-"]]++
+	}
+	if err := UpdateHits(ctx, db, set, hits, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	var rows []models.SYBProductFilter
+	if err := db.Find(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]int{"#": 8498, "-": 6392}
+	for _, x := range rows {
+		if x.LastHitCount == nil {
+			t.Fatalf("rule %q must be written even when it matched nothing", x.Keyword)
+		}
+		if w, ok := want[x.Keyword]; ok {
+			if *x.LastHitCount != w {
+				t.Fatalf("rule %q should record its own %d hits, got %d", x.Keyword, w, *x.LastHitCount)
+			}
+			continue
+		}
+		if *x.LastHitCount != 0 {
+			t.Fatalf("keyword rule %q matched nothing and must record 0, got %d", x.Keyword, *x.LastHitCount)
+		}
+		if x.LastHitAt == nil {
+			t.Fatalf("rule %q must still be stamped so a stale count is never left behind", x.Keyword)
+		}
+	}
+}
+
+func TestCharCreateDeleteRejectedAndKeywordDuplicate(t *testing.T) {
+	db := testDB(t)
+	s := NewService(db)
+	ctx := context.Background()
+	if _, e := s.Create(ctx, CreateRequest{Kind: "char", Keyword: "@"}); e == nil {
+		t.Fatal("char create must be rejected")
+	}
+	if e := s.Delete(ctx, 1); e == nil {
+		t.Fatal("seed char delete must be rejected")
+	}
+	if _, e := s.Create(ctx, CreateRequest{Kind: "keyword", Keyword: " CVC "}); e != nil {
+		t.Fatal(e)
+	}
+	if _, e := s.Create(ctx, CreateRequest{Kind: "keyword", Keyword: "ｃｖｃ"}); e == nil {
+		t.Fatal("normalized duplicate must be rejected")
+	}
+}
@@ -78,6 +78,25 @@ func (handler Handler) AdminBatchCreate(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 200, "data": response})
 }

+func (handler Handler) AdminBatchCreateImageSearch(c *gin.Context) {
+	var request ImageSearchBatchRequest
+	if err := decodeStrict(c, &request); err != nil {
+		writeError(c, serviceError("INVALID_REQUEST", "请求 JSON 无效"))
+		return
+	}
+	service, _, ok := handler.service(c)
+	if !ok {
+		return
+	}
+	response, err := service.BatchCreateImageSearch(c.Request.Context(), request)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	c.Header("Cache-Control", "no-store")
+	c.JSON(http.StatusOK, gin.H{"code": 200, "data": response})
+}
+
 func (handler Handler) AdminDetail(c *gin.Context) {
 	id, err := taskID(c)
 	if err != nil || id == 0 {
@@ -211,7 +211,7 @@ func (service *Service) IdentifyCurrentPage(ctx context.Context, taskID uint64,
 		}
 		return CurrentPageIdentifyResponse{}, internalError(err)
 	}
-	if existing.Source != models.CollectionTaskSourceAgentCurrentPage || existing.DeviceID == nil || *existing.DeviceID != deviceRecord.ID {
+	if (existing.Source != models.CollectionTaskSourceAgentCurrentPage && existing.Source != models.CollectionTaskSourceImageSearch) || existing.DeviceID == nil || *existing.DeviceID != deviceRecord.ID {
 		return CurrentPageIdentifyResponse{}, serviceError(CodeTaskNotFound, "任务不存在")
 	}
 	if existing.IdentifyRequestID != nil && *existing.IdentifyRequestID == request.RequestID && existing.PDDProductID != nil {
@@ -240,7 +240,7 @@ func (service *Service) IdentifyCurrentPage(ctx context.Context, taskID uint64,
 			}
 			return internalError(err)
 		}
-		if record.Source != models.CollectionTaskSourceAgentCurrentPage || record.DeviceID == nil || *record.DeviceID != deviceRecord.ID {
+		if (record.Source != models.CollectionTaskSourceAgentCurrentPage && record.Source != models.CollectionTaskSourceImageSearch) || record.DeviceID == nil || *record.DeviceID != deviceRecord.ID {
 			return serviceError(CodeTaskNotFound, "任务不存在")
 		}
 		if record.IdentifyRequestID != nil && *record.IdentifyRequestID == request.RequestID && record.PDDProductID != nil {
@@ -255,7 +255,9 @@ func (service *Service) IdentifyCurrentPage(ctx context.Context, taskID uint64,
 				return serviceError(CodeCurrentPageIdentityConflict, "当前商品与任务已识别商品不一致")
 			}
 			now := service.Now()
-			if err := tx.Model(&models.CollectionTask{}).Where("id = ?", record.ID).Updates(map[string]any{
+			// Validate the locked task's real state; an empty model fails BeforeSave
+			// when a retried current-page task already has a product binding.
+			if err := tx.Model(&record).Where("id = ?", record.ID).Updates(map[string]any{
 				"identify_request_id": request.RequestID, "identity_resolved_at": now,
 			}).Error; err != nil {
 				return internalError(err)
@@ -0,0 +1,153 @@
+package task
+
+import (
+	"context"
+	"reflect"
+	"testing"
+
+	"go-admin/app/goauto/models"
+	"go-admin/app/goauto/rulecontract"
+
+	"github.com/google/uuid"
+)
+
+func TestCurrentPageReidentifyAfterSameTaskRetry(t *testing.T) {
+	db := openTaskDatabase(t)
+	_, token := registerTaskDeviceWithCapabilities(t, db, "retry-device", []string{
+		rulecontract.CapabilitySchemaV2,
+		rulecontract.CapabilityPDDProductDetailV1,
+		rulecontract.CapabilityPDDCurrentPageShareV1,
+	})
+	_, otherToken := registerTaskDevice(t, db, "other-device")
+	rule := models.CollectionRule{Name: "retry-rule", ContentJSON: v2TaskRuleSnapshot()}
+	if err := db.Create(&rule).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&models.AgentManualCollectionSetting{ID: 1, RuleID: rule.ID}).Error; err != nil {
+		t.Fatal(err)
+	}
+	service := newTaskService(db)
+	ctx := context.Background()
+	created, err := service.CreateCurrentPage(ctx, CurrentPageCreateRequest{RequestID: uuid.NewString()}, token)
+	if err != nil {
+		t.Fatal(err)
+	}
+	load := func() models.CollectionTask {
+		t.Helper()
+		var record models.CollectionTask
+		if err := db.First(&record, created.TaskID).Error; err != nil {
+			t.Fatal(err)
+		}
+		return record
+	}
+	request := CurrentPageIdentifyRequest{
+		RequestID: uuid.NewString(), ShareURL: "https://mobile.yangkeduo.com/goods.html?goods_id=700000000255",
+	}
+	// Direct links resolve locally: the regression never calls PDD or a live DB.
+	identity, err := service.IdentifyCurrentPage(ctx, created.TaskID, request, token)
+	if err != nil {
+		t.Fatal(err)
+	}
+	const failureCode = "SPEC_PANEL_EVIDENCE_NOT_MATCHED"
+	if _, err := service.SubmitFailure(ctx, created.TaskID, FailRequest{
+		RequestID: uuid.NewString(), Code: failureCode, Message: "Synthetic panel failure",
+	}, token); err != nil {
+		t.Fatal(err)
+	}
+	reset, err := service.ResetForDevice(ctx, created.TaskID, ActionRequest{RequestID: uuid.NewString()}, token)
+	if err != nil || reset.TaskID != created.TaskID || reset.AttemptNumber != 2 || reset.Status != models.TaskStatusPending {
+		t.Fatalf("same-task reset: %+v, %v", reset, err)
+	}
+	resetRecord := load()
+	if resetRecord.PDDProductID == nil || *resetRecord.PDDProductID != identity.PDDProductID ||
+		resetRecord.IdentifyRequestID != nil || resetRecord.IdentityResolvedAt != nil {
+		t.Fatal("reset must keep the product and clear per-attempt identification")
+	}
+	if _, err := service.Claim(ctx, created.TaskID, ActionRequest{RequestID: uuid.NewString()}, token); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := service.Start(ctx, created.TaskID, ActionRequest{RequestID: uuid.NewString()}, token); err != nil {
+		t.Fatal(err)
+	}
+	before := load()
+	request.RequestID = uuid.NewString()
+	for _, tc := range []struct {
+		name, token, url, code string
+	}{
+		{"other device", otherToken, request.ShareURL, CodeTaskNotFound},
+		{"other product", token, "https://mobile.yangkeduo.com/goods.html?goods_id=700000000256", CodeCurrentPageIdentityConflict},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := service.IdentifyCurrentPage(ctx, created.TaskID, CurrentPageIdentifyRequest{RequestID: uuid.NewString(), ShareURL: tc.url}, tc.token)
+			if taskErrorCode(t, err) != tc.code {
+				t.Fatalf("expected %s, got %v", tc.code, err)
+			}
+			if !reflect.DeepEqual(before, load()) {
+				t.Fatal("rejected identification changed the task")
+			}
+		})
+	}
+	reidentified, err := service.IdentifyCurrentPage(ctx, created.TaskID, request, token)
+	if err != nil {
+		t.Fatalf("reidentify same product after retry: %v", err)
+	}
+	if reidentified.TaskID != created.TaskID || reidentified.PDDProductID != identity.PDDProductID ||
+		reidentified.GoodsID != identity.GoodsID || reidentified.URL != identity.URL || !reidentified.Replayed {
+		t.Fatalf("identity changed: %+v", reidentified)
+	}
+	after := load()
+	if after.IdentifyRequestID == nil || *after.IdentifyRequestID != request.RequestID || after.IdentityResolvedAt == nil {
+		t.Fatal("new attempt identification was not persisted")
+	}
+	// Apart from identity metadata and the normal update timestamp, every field
+	// (including status, device, rule, lease and uniqueness slots) must survive.
+	expected := before
+	expected.IdentifyRequestID = after.IdentifyRequestID
+	expected.IdentityResolvedAt = after.IdentityResolvedAt
+	expected.UpdatedAt = after.UpdatedAt
+	if !reflect.DeepEqual(expected, after) {
+		t.Fatal("reidentification changed unrelated task fields")
+	}
+	service.ResolveCurrentPageShare = func(context.Context, string) (ResolvedPDDShare, error) {
+		t.Fatal("replay must not resolve the link again")
+		return ResolvedPDDShare{}, nil
+	}
+	replay, err := service.IdentifyCurrentPage(ctx, created.TaskID, request, token)
+	if err != nil || replay != reidentified || !reflect.DeepEqual(after, load()) {
+		t.Fatalf("replay changed identity or task: %+v, %v", replay, err)
+	}
+	service.ResolveCurrentPageShare = nil
+	title := "Synthetic collected product"
+	result, err := service.SubmitResult(ctx, created.TaskID, ResultRequest{
+		RequestID: uuid.NewString(), Status: models.TaskStatusCompleted,
+		Product:     ResultProduct{PDDGoodsID: identity.GoodsID, Title: &title},
+		Dimensions:  []ResultDimension{{Key: "color", Name: "颜色", Values: []string{"黑色"}}},
+		ColorPrices: []ResultColorPrice{{Color: "黑色", PriceCent: 1200}},
+		SKUs:        []ResultSKU{{Specs: map[string]string{"color": "黑色"}, PriceCent: 1200, Available: true}},
+	}, token)
+	if err != nil || result.Task.ID != created.TaskID || result.Task.Status != models.TaskStatusCompleted {
+		t.Fatalf("complete retried collection: %+v, %v", result, err)
+	}
+	terminal := load()
+	request.RequestID = uuid.NewString()
+	if _, err := service.IdentifyCurrentPage(ctx, created.TaskID, request, token); taskErrorCode(t, err) != CodeTaskStateConflict {
+		t.Fatalf("expected terminal-state rejection: %v", err)
+	}
+	if !reflect.DeepEqual(terminal, load()) {
+		t.Fatal("terminal identification changed the task")
+	}
+	var archived []models.CollectionTaskAttempt
+	if err := db.Where("task_id = ?", created.TaskID).Find(&archived).Error; err != nil {
+		t.Fatal(err)
+	}
+	if len(archived) != 1 || archived[0].AttemptNumber != 1 || archived[0].Status != models.TaskStatusFailed ||
+		archived[0].ErrorCode == nil || *archived[0].ErrorCode != failureCode {
+		t.Fatal("original failed attempt was not preserved")
+	}
+	for _, model := range []any{&models.CollectionTask{}, &models.PDDProduct{}} {
+		var count int64
+		if err := db.Model(model).Count(&count).Error; err != nil || count != 1 {
+			t.Fatalf("retry duplicated task/product: count=%d, %v", count, err)
+		}
+	}
+}
@@ -0,0 +1,373 @@
+package task
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"image"
+	_ "image/jpeg"
+	_ "image/png"
+	"io"
+	"net/http"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"go-admin/app/goauto/device"
+	"go-admin/app/goauto/models"
+
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const ImageSearchCapability = "pdd.image-search.v1"
+const imageSearchMaxBytes int64 = 10 << 20
+
+func validImageMetadata(value ImageSearchImage) bool {
+	if value.SizeBytes <= 0 || value.SizeBytes > imageSearchMaxBytes || len(value.SHA256) != 64 || value.SHA256 != strings.ToLower(value.SHA256) || value.ImageURL == "" {
+		return false
+	}
+	return value.MediaType == "image/jpeg" || value.MediaType == "image/png"
+}
+
+func fetchImageSearchImage(ctx context.Context, rawURL string) (ImageSearchImage, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+	if err != nil {
+		return ImageSearchImage{}, err
+	}
+	response, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
+	if err != nil {
+		return ImageSearchImage{}, err
+	}
+	defer response.Body.Close()
+	if response.StatusCode < 200 || response.StatusCode >= 300 {
+		return ImageSearchImage{}, fmt.Errorf("reference image status %d", response.StatusCode)
+	}
+	data, err := io.ReadAll(io.LimitReader(response.Body, imageSearchMaxBytes+1))
+	if err != nil || int64(len(data)) > imageSearchMaxBytes {
+		return ImageSearchImage{}, errors.New("reference image exceeds limit")
+	}
+	config, format, err := image.DecodeConfig(bytes.NewReader(data))
+	if err != nil || config.Width < 1 || config.Height < 1 {
+		return ImageSearchImage{}, errors.New("unsupported image format")
+	}
+	media := "image/" + format
+	if format == "jpeg" {
+		media = "image/jpeg"
+	}
+	hash := sha256.Sum256(data)
+	return ImageSearchImage{ImageURL: rawURL, MediaType: media, SizeBytes: int64(len(data)), SHA256: hex.EncodeToString(hash[:])}, nil
+}
+
+// Only this subset is sent to Agent. Association and price snapshots stay on Server.
+type ImageSearchImage struct {
+	ImageURL  string `json:"imageUrl"`
+	MediaType string `json:"mediaType"`
+	SizeBytes int64  `json:"sizeBytes"`
+	SHA256    string `json:"sha256"`
+}
+
+type ImageSearchSnapshot struct {
+	ImageSearchImage
+	ShopeeProductID            uint64   `json:"shopeeProductId"`
+	SYBProductIDs              []uint64 `json:"sybProductIds"`
+	RepresentativeSYBProductID uint64   `json:"representativeSybProductId"`
+	OriginalPDDProductID       *uint64  `json:"originalPddProductId"`
+	ReferencePriceCent         int64    `json:"referencePriceCent"`
+	ReferenceCurrency          string   `json:"referenceCurrency"`
+	MaxPriceRatio              int64    `json:"maxPriceRatio"`
+	PriceGuardSkipped          bool     `json:"priceGuardSkipped"`
+	PriceGuardSkipReason       string   `json:"priceGuardSkipReason,omitempty"`
+	RequestFingerprint         string   `json:"requestFingerprint"`
+}
+
+type ImageSearchBatchRequest struct {
+	RequestID       string   `json:"requestId"`
+	SYBProductIDs   []uint64 `json:"sybProductIds"`
+	RuleID          uint64   `json:"ruleId"`
+	DeviceID        *uint64  `json:"deviceId"`
+	OverwriteLinked bool     `json:"overwriteLinked"`
+}
+
+type ImageSearchBatchItem struct {
+	ShopeeProductID uint64   `json:"shopeeProductId"`
+	SYBProductIDs   []uint64 `json:"sybProductIds"`
+	Success         bool     `json:"success"`
+	TaskID          uint64   `json:"taskId,omitempty"`
+	Replayed        bool     `json:"replayed,omitempty"`
+	Code            string   `json:"code,omitempty"`
+	Message         string   `json:"message,omitempty"`
+}
+
+type ImageSearchBatchResponse struct {
+	Items        []ImageSearchBatchItem `json:"items"`
+	SuccessCount int                    `json:"successCount"`
+	FailureCount int                    `json:"failureCount"`
+	SkippedCount int                    `json:"skippedCount"`
+}
+
+func (service *Service) BatchCreateImageSearch(ctx context.Context, request ImageSearchBatchRequest) (ImageSearchBatchResponse, error) {
+	batchID, err := uuid.Parse(strings.TrimSpace(request.RequestID))
+	if err != nil || request.RuleID == 0 || len(request.SYBProductIDs) == 0 || len(request.SYBProductIDs) > 100 || request.DeviceID != nil && *request.DeviceID == 0 {
+		return ImageSearchBatchResponse{}, serviceError("INVALID_REQUEST", "批次、SYB 商品、规则和设备参数无效（最多 100 条）")
+	}
+	seen := map[uint64]bool{}
+	for _, id := range request.SYBProductIDs {
+		if id == 0 || seen[id] {
+			return ImageSearchBatchResponse{}, serviceError("INVALID_REQUEST", "SYB 商品列表包含无效或重复 ID")
+		}
+		seen[id] = true
+	}
+	// Bound the complete synchronous batch, not just each individual download.
+	ctx, cancel := context.WithTimeout(ctx, 45*time.Second)
+	defer cancel()
+	var rows []models.SYBProduct
+	if err := service.DB.WithContext(ctx).Where("id IN ?", request.SYBProductIDs).Find(&rows).Error; err != nil {
+		return ImageSearchBatchResponse{}, internalError(err)
+	}
+	byID := map[uint64]models.SYBProduct{}
+	for _, row := range rows {
+		byID[row.ID] = row
+	}
+	response := ImageSearchBatchResponse{Items: []ImageSearchBatchItem{}}
+	groups := map[uint64]int{}
+	for _, id := range request.SYBProductIDs {
+		row, found := byID[id]
+		if !found || row.ShopeeProductID == nil || *row.ShopeeProductID == 0 {
+			response.Items = append(response.Items, ImageSearchBatchItem{SYBProductIDs: []uint64{id}, Code: "SYB_PRODUCT_UNAVAILABLE", Message: "SYB 商品不存在或未关联蝦皮商品"})
+			continue
+		}
+		if index, ok := groups[*row.ShopeeProductID]; ok {
+			response.Items[index].SYBProductIDs = append(response.Items[index].SYBProductIDs, id)
+		} else {
+			groups[*row.ShopeeProductID] = len(response.Items)
+			response.Items = append(response.Items, ImageSearchBatchItem{ShopeeProductID: *row.ShopeeProductID, SYBProductIDs: []uint64{id}})
+		}
+	}
+	for index := range response.Items {
+		item := &response.Items[index]
+		if item.Code == "" {
+			itemRequestID := uuid.NewSHA1(batchID, []byte(strconv.FormatUint(item.ShopeeProductID, 10))).String()
+			id, replayed, createErr := service.createImageSearch(ctx, request, *item, itemRequestID)
+			if createErr == nil {
+				item.Success, item.TaskID, item.Replayed = true, id, replayed
+			} else {
+				var target *ServiceError
+				if !errors.As(createErr, &target) {
+					target = internalError(createErr).(*ServiceError)
+				}
+				item.Code, item.Message = target.Code, target.Message
+			}
+		}
+		if item.Success {
+			response.SuccessCount++
+		} else if item.Code == "IMAGE_SEARCH_ALREADY_LINKED" {
+			response.SkippedCount++
+		} else {
+			response.FailureCount++
+		}
+	}
+	return response, nil
+}
+
+func imageRequestFingerprint(request ImageSearchBatchRequest, item ImageSearchBatchItem) string {
+	// Include group membership so a reused request ID cannot silently change intent.
+	request.RequestID = ""
+	request.SYBProductIDs = item.SYBProductIDs
+	raw, _ := json.Marshal(request)
+	hash := sha256.Sum256(raw)
+	return hex.EncodeToString(hash[:])
+}
+
+func loadImageSearchSnapshot(record models.CollectionTask) (ImageSearchSnapshot, error) {
+	var snapshot ImageSearchSnapshot
+	if record.ImageSearchSnapshot == nil || json.Unmarshal([]byte(*record.ImageSearchSnapshot), &snapshot) != nil || snapshot.ShopeeProductID == 0 || snapshot.RepresentativeSYBProductID == 0 || snapshot.MaxPriceRatio < 1 || !validImageMetadata(snapshot.ImageSearchImage) {
+		return snapshot, serviceError("IMAGE_SEARCH_SNAPSHOT_INVALID", "图搜任务快照无效")
+	}
+	return snapshot, nil
+}
+
+// ImageSearchPriceAllowed deliberately refuses to compare unlike currencies.
+// A skipped check is returned as comparable=false so callers must require
+// manual confirmation before automatic association.
+func ImageSearchPriceAllowed(snapshot ImageSearchSnapshot, pddCurrency string, priceCent int64) (allowed bool, comparable bool) {
+	if priceCent < 0 || snapshot.ReferencePriceCent < 0 || snapshot.ReferencePriceCent == 0 || snapshot.MaxPriceRatio < 1 {
+		return false, false
+	}
+	if strings.ToUpper(strings.TrimSpace(snapshot.ReferenceCurrency)) != strings.ToUpper(strings.TrimSpace(pddCurrency)) {
+		return false, false
+	}
+	return priceCent <= snapshot.ReferencePriceCent*snapshot.MaxPriceRatio, true
+}
+
+func (service *Service) createImageSearch(ctx context.Context, request ImageSearchBatchRequest, item ImageSearchBatchItem, requestID string) (uint64, bool, error) {
+	fingerprint := imageRequestFingerprint(request, item)
+	replay := func(db *gorm.DB) (uint64, bool, error) {
+		var record models.CollectionTask
+		err := db.Where("create_request_id = ?", requestID).First(&record).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return 0, false, nil
+		}
+		if err != nil {
+			return 0, false, internalError(err)
+		}
+		snapshot, err := loadImageSearchSnapshot(record)
+		if err != nil {
+			return 0, false, err
+		}
+		if record.Source != models.CollectionTaskSourceImageSearch || snapshot.RequestFingerprint != fingerprint {
+			return 0, false, serviceError("IMAGE_SEARCH_REQUEST_CONFLICT", "同一请求 ID 的参数已变化")
+		}
+		return record.ID, true, nil
+	}
+	db := service.DB.WithContext(ctx)
+	if id, found, err := replay(db); found || err != nil {
+		return id, found, err
+	}
+	var shopee models.ShopeeProduct
+	if err := db.First(&shopee, item.ShopeeProductID).Error; err != nil {
+		return 0, false, serviceError("SHOPEE_PRODUCT_NOT_FOUND", "蝦皮商品不存在")
+	}
+	if shopee.PDDProductID != nil && !request.OverwriteLinked {
+		return 0, false, serviceError("IMAGE_SEARCH_ALREADY_LINKED", "商品已关联 PDD，已跳过")
+	}
+	var rule models.CollectionRule
+	if err := db.First(&rule, request.RuleID).Error; err != nil {
+		return 0, false, serviceError(CodeRuleNotFound, "采集规则不存在")
+	}
+	if err := ensureCurrentPageRule(rule.ContentJSON); err != nil {
+		return 0, false, err
+	}
+	if request.DeviceID != nil {
+		var target models.AgentDevice
+		if err := db.First(&target, *request.DeviceID).Error; err != nil || target.Status == models.DeviceStatusDisabled {
+			return 0, false, serviceError(CodeDeviceNotFound, "设备不存在或已停用")
+		}
+		if err := ensureTaskCompatible(target, models.CollectionTask{Source: models.CollectionTaskSourceImageSearch, RuleSnapshot: rule.ContentJSON}); err != nil {
+			return 0, false, err
+		}
+	}
+	ratio := int64(3)
+	if value := strings.TrimSpace(os.Getenv("GOAUTO_IMAGE_SEARCH_MAX_PRICE_RATIO")); value != "" {
+		var err error
+		ratio, err = strconv.ParseInt(value, 10, 64)
+		if err != nil || ratio < 1 || ratio > 100 {
+			return 0, false, serviceError("IMAGE_SEARCH_CONFIG_INVALID", "图搜价格倍数配置须为 1～100 的整数")
+		}
+	}
+	var representative models.SYBProduct
+	var image ImageSearchImage
+	fetch := service.FetchImageSearchImage
+	if fetch == nil {
+		fetch = fetchImageSearchImage
+	}
+	for _, id := range item.SYBProductIDs {
+		var row models.SYBProduct
+		if err := db.First(&row, id).Error; err != nil {
+			return 0, false, internalError(err)
+		}
+		if row.ShopeeProductID == nil || *row.ShopeeProductID != shopee.ID {
+			return 0, false, serviceError("IMAGE_SEARCH_INPUT_CHANGED", "SYB 商品关联已变化，请刷新后重试")
+		}
+		if strings.TrimSpace(row.ImageURL) == "" {
+			continue
+		}
+		var err error
+		image, err = fetch(ctx, row.ImageURL)
+		if err == nil && validImageMetadata(image) {
+			representative = row
+			break
+		}
+		if ctx.Err() != nil {
+			break
+		}
+	}
+	if representative.ID == 0 {
+		return 0, false, serviceError("IMAGE_SEARCH_IMAGE_INVALID", "参考图下载失败、格式不支持或超过限制")
+	}
+	referenceCurrency := strings.ToUpper(strings.TrimSpace(shopee.Currency))
+	priceSkipped := referenceCurrency != "CNY"
+	snapshot := ImageSearchSnapshot{ImageSearchImage: image, ShopeeProductID: shopee.ID, SYBProductIDs: item.SYBProductIDs, RepresentativeSYBProductID: representative.ID,
+		OriginalPDDProductID: shopee.PDDProductID, ReferencePriceCent: representative.UnitPriceCent, ReferenceCurrency: referenceCurrency, MaxPriceRatio: ratio, RequestFingerprint: fingerprint,
+		PriceGuardSkipped: priceSkipped}
+	if priceSkipped {
+		snapshot.PriceGuardSkipReason = "CROSS_CURRENCY_TWD_PDD_CNY"
+	}
+	raw, _ := json.Marshal(snapshot)
+	stored := string(raw)
+	var taskID uint64
+	var replayed bool
+	err := db.Transaction(func(tx *gorm.DB) error {
+		var current models.ShopeeProduct
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&current, shopee.ID).Error; err != nil {
+			return internalError(err)
+		}
+		if id, found, err := replay(tx); found || err != nil {
+			taskID, replayed = id, found
+			return err
+		}
+		if !sameImageSearchLink(current.PDDProductID, shopee.PDDProductID) || current.Currency != shopee.Currency {
+			return serviceError("IMAGE_SEARCH_INPUT_CHANGED", "蝦皮商品关联或币种已变化，请刷新后重试")
+		}
+		for _, id := range item.SYBProductIDs {
+			var row models.SYBProduct
+			if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&row, id).Error; err != nil {
+				return internalError(err)
+			}
+			if row.ShopeeProductID == nil || *row.ShopeeProductID != shopee.ID || id == representative.ID && (row.ImageURL != representative.ImageURL || row.UnitPriceCent != representative.UnitPriceCent) {
+				return serviceError("IMAGE_SEARCH_INPUT_CHANGED", "参考图片或价格已变化，请刷新后重试")
+			}
+		}
+		var active []models.CollectionTask
+		if err := tx.Where("source = ? AND status IN ?", models.CollectionTaskSourceImageSearch, []string{models.TaskStatusPending, models.TaskStatusRunning}).Find(&active).Error; err != nil {
+			return internalError(err)
+		}
+		for _, candidate := range active {
+			other, err := loadImageSearchSnapshot(candidate)
+			if err != nil {
+				return err
+			}
+			if other.ShopeeProductID == shopee.ID {
+				return serviceError("IMAGE_SEARCH_TASK_ACTIVE", "该蝦皮商品已有未结束的图搜任务")
+			}
+		}
+		record := models.CollectionTask{Source: models.CollectionTaskSourceImageSearch, Status: models.TaskStatusPending, RuleID: rule.ID, RuleSnapshot: rule.ContentJSON, DeviceID: request.DeviceID, CreateRequestID: &requestID, ImageSearchSnapshot: &stored}
+		if err := tx.Create(&record).Error; err != nil {
+			return internalError(err)
+		}
+		taskID = record.ID
+		return nil
+	})
+	return taskID, replayed, err
+}
+
+func sameImageSearchLink(left, right *uint64) bool {
+	return left == nil && right == nil || left != nil && right != nil && *left == *right
+}
+
+func taskCompatible(record models.AgentDevice, task models.CollectionTask) (bool, error) {
+	if task.Source == models.CollectionTaskSourceImageSearch {
+		ok, err := device.Supports(record, []string{ImageSearchCapability})
+		if err != nil || !ok {
+			return false, err
+		}
+	}
+	return ruleCompatible(record, task.RuleSnapshot)
+}
+
+func ensureTaskCompatible(record models.AgentDevice, task models.CollectionTask) error {
+	ok, err := taskCompatible(record, task)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return serviceError(CodeDeviceCapabilityMismatch, "设备不支持任务所需能力，请更新 Agent")
+	}
+	return nil
+}
@@ -0,0 +1,60 @@
+package task
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"go-admin/app/goauto/models"
+	"gorm.io/gorm"
+)
+
+// autoLinkImageSearch is deliberately a narrow post-result hook. It only
+// writes an association when the task was a complete collection, the frozen
+// original association is unchanged, and the target product is active. Manual
+// changes made while the Agent was running win by the CAS predicate.
+func (service *Service) autoLinkImageSearch(ctx context.Context, taskID uint64) error {
+	var task models.CollectionTask
+	if err := service.DB.WithContext(ctx).First(&task, taskID).Error; err != nil {
+		return internalError(err)
+	}
+	if task.Source != models.CollectionTaskSourceImageSearch || task.Status != models.TaskStatusCompleted || task.PDDProductID == nil || task.ImageSearchSnapshot == nil {
+		return nil
+	}
+	snapshot, err := loadImageSearchSnapshot(task)
+	if err != nil {
+		return err
+	}
+	if snapshot.PriceGuardSkipped {
+		return nil
+	}
+	var product models.ShopeeProduct
+	if err := service.DB.WithContext(ctx).First(&product, snapshot.ShopeeProductID).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		return internalError(err)
+	}
+	// PDD products are RMB in the current contract; unlike-currency snapshots
+	// must remain available for manual review and can never auto-link.
+	if strings.ToUpper(strings.TrimSpace(product.Currency)) != "CNY" {
+		return nil
+	}
+	var pdd models.PDDProduct
+	if err := service.DB.WithContext(ctx).Select("id", "status").First(&pdd, *task.PDDProductID).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		return internalError(err)
+	}
+	if pdd.Status != "active" {
+		return nil
+	}
+	result := service.DB.WithContext(ctx).Model(&models.ShopeeProduct{}).
+		Where("id = ? AND pdd_product_id IS NULL AND image_search_linked = ?", product.ID, false).
+		Updates(map[string]any{"pdd_product_id": *task.PDDProductID, "image_search_linked": true})
+	if result.Error != nil {
+		return internalError(result.Error)
+	}
+	return nil
+}
@@ -0,0 +1,81 @@
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"go-admin/app/goauto/models"
+)
+
+func TestImageSearchPriceAllowedRefusesCrossCurrency(t *testing.T) {
+	snapshot := ImageSearchSnapshot{ReferencePriceCent: 1000, ReferenceCurrency: "TWD", MaxPriceRatio: 3}
+	if allowed, comparable := ImageSearchPriceAllowed(snapshot, "CNY", 2000); allowed || comparable {
+		t.Fatalf("cross-currency price must not be compared: allowed=%v comparable=%v", allowed, comparable)
+	}
+	if allowed, comparable := ImageSearchPriceAllowed(snapshot, "TWD", 3000); !allowed || !comparable {
+		t.Fatalf("same-currency price within ratio should pass: allowed=%v comparable=%v", allowed, comparable)
+	}
+	if allowed, comparable := ImageSearchPriceAllowed(snapshot, "TWD", 3001); allowed || !comparable {
+		t.Fatalf("same-currency price over ratio should fail: allowed=%v comparable=%v", allowed, comparable)
+	}
+}
+
+func TestImageSearchPayloadOnlyContainsImageMetadata(t *testing.T) {
+	secret := `{"shopeeProductId":99,"representativeSybProductId":1,"maxPriceRatio":3,"referenceCurrency":"TWD","imageUrl":"https://example.invalid/ref.jpg","mediaType":"image/jpeg","sizeBytes":10,"sha256":"0123456789012345678901234567890101234567890123456789012345678901"}`
+	record := models.CollectionTask{Source: models.CollectionTaskSourceImageSearch, RuleSnapshot: `{}`, ImageSearchSnapshot: &secret}
+	payload, err := NewService(nil).payload(record, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw := string(payload.ImageSearch)
+	if raw == "" || containsAny(raw, "shopeeProductId", "referenceCurrency") {
+		t.Fatalf("internal snapshot fields leaked in Agent payload: %s", raw)
+	}
+}
+
+func containsAny(value string, needles ...string) bool {
+	for _, needle := range needles {
+		if strings.Contains(value, needle) {
+			return true
+		}
+	}
+	return false
+}
+
+func TestAutoLinkImageSearchDoesNotOverwriteManualAssociation(t *testing.T) {
+	db := openTaskDatabase(t)
+	manualPDD := models.PDDProduct{GoodsID: "manual-pdd", URL: "https://mobile.yangkeduo.com/goods.html?goods_id=manual-pdd", Status: "active"}
+	autoPDD := models.PDDProduct{GoodsID: "auto-pdd", URL: "https://mobile.yangkeduo.com/goods.html?goods_id=auto-pdd", Status: "active"}
+	if err := db.Create(&manualPDD).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&autoPDD).Error; err != nil {
+		t.Fatal(err)
+	}
+	shopee := models.ShopeeProduct{ShopeeItemID: "auto-link-test", Title: "test", Currency: "CNY", SpecsJSON: "[]", PDDProductID: &manualPDD.ID}
+	if err := db.Create(&shopee).Error; err != nil {
+		t.Fatal(err)
+	}
+	rule := models.CollectionRule{Name: "image-search-test", ContentJSON: "{}"}
+	if err := db.Create(&rule).Error; err != nil {
+		t.Fatal(err)
+	}
+	snapshot := ImageSearchSnapshot{ShopeeProductID: shopee.ID, RepresentativeSYBProductID: 1, ReferenceCurrency: "CNY", ReferencePriceCent: 100, MaxPriceRatio: 3, ImageSearchImage: ImageSearchImage{ImageURL: "https://example.invalid/a.jpg", MediaType: "image/jpeg", SizeBytes: 1, SHA256: "0123456789012345678901234567890101234567890123456789012345678901"}}
+	raw, _ := json.Marshal(snapshot)
+	task := models.CollectionTask{Source: models.CollectionTaskSourceImageSearch, Status: models.TaskStatusCompleted, PDDProductID: &autoPDD.ID, RuleID: rule.ID, RuleSnapshot: "{}", ImageSearchSnapshot: func() *string { v := string(raw); return &v }()}
+	if err := db.Create(&task).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := NewService(db).autoLinkImageSearch(context.Background(), task.ID); err != nil {
+		t.Fatal(err)
+	}
+	var saved models.ShopeeProduct
+	if err := db.First(&saved, shopee.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if saved.PDDProductID == nil || *saved.PDDProductID != manualPDD.ID || saved.ImageSearchLinked {
+		t.Fatalf("manual association was overwritten: %+v", saved)
+	}
+}
@@ -123,6 +123,9 @@ func (service *Service) SubmitResult(ctx context.Context, taskID uint64, request
 	if err := service.activatePersistedReplacement(ctx, taskID); err != nil {
 		return DetailResponse{}, err
 	}
+	if err := service.autoLinkImageSearch(ctx, taskID); err != nil {
+		return DetailResponse{}, err
+	}
 	detail, err := service.Detail(ctx, taskID)
 	detail.Replayed = replayed
 	return detail, err
@@ -31,6 +31,7 @@ func InitRouter(engine *gin.Engine, auth *jwt.GinJWTMiddleware) {
 	admin.GET("", handler.AdminList)
 	admin.POST("", handler.AdminCreate)
 	admin.POST("/batch", handler.AdminBatchCreate)
+	admin.POST("/image-search/batch", handler.AdminBatchCreateImageSearch)
 	admin.GET("/:taskId", handler.AdminDetail)
 	admin.POST("/:taskId/reset", handler.AdminReset)
 	admin.DELETE("/:taskId", handler.AdminDelete)
@@ -60,6 +60,7 @@ type TaskPayload struct {
 	ReplacementOriginType string          `json:"replacementOriginType,omitempty"`
 	RuleID                uint64          `json:"ruleId"`
 	RuleSnapshot          json.RawMessage `json:"ruleSnapshot"`
+	ImageSearch           json.RawMessage `json:"imageSearch,omitempty"`
 	TimeoutSeconds        int             `json:"timeoutSeconds"`
 	LeaseExpiresAt        *time.Time      `json:"leaseExpiresAt,omitempty"`
 	LeaseVersion          uint64          `json:"leaseVersion"`
@@ -74,6 +75,7 @@ type Service struct {
 	TaskTimeout             int
 	ResolveCurrentPageShare func(context.Context, string) (ResolvedPDDShare, error)
 	ColorImageDirectory     string
+	FetchImageSearchImage   func(context.Context, string) (ImageSearchImage, error)
 }

 func NewService(db *gorm.DB) *Service {
@@ -107,7 +109,7 @@ func (service *Service) Next(ctx context.Context, token string) (*TaskPayload, e
 		Where("device_id = ? AND status = ? AND lease_expires_at > ?", deviceRecord.ID, models.TaskStatusPending, now).
 		Order("created_at ASC, id ASC").First(&record).Error
 	if err == nil {
-		if err := ensureRuleCompatible(deviceRecord, record.RuleSnapshot); err != nil {
+		if err := ensureTaskCompatible(deviceRecord, record); err != nil {
 			return nil, err
 		}
 		payload, payloadErr := service.payload(record, false)
@@ -124,7 +126,7 @@ func (service *Service) Next(ctx context.Context, token string) (*TaskPayload, e
 		return nil, internalError(err)
 	}
 	for _, candidate := range candidates {
-		compatible, compatibilityErr := ruleCompatible(deviceRecord, candidate.RuleSnapshot)
+		compatible, compatibilityErr := taskCompatible(deviceRecord, candidate)
 		if compatibilityErr != nil {
 			return nil, compatibilityErr
 		}
@@ -167,7 +169,7 @@ func (service *Service) Claim(ctx context.Context, taskID uint64, request Action
 		if record.Status != models.TaskStatusPending {
 			return serviceError(CodeTaskStateConflict, "只有待执行任务可以领取")
 		}
-		if err := ensureRuleCompatible(deviceRecord, record.RuleSnapshot); err != nil {
+		if err := ensureTaskCompatible(deviceRecord, record); err != nil {
 			return err
 		}
 		now := service.Now()
@@ -235,7 +237,7 @@ func (service *Service) Start(ctx context.Context, taskID uint64, request Action
 		if record.Status != models.TaskStatusPending {
 			return serviceError(CodeTaskStateConflict, "任务当前状态不能开始")
 		}
-		if err := ensureRuleCompatible(deviceRecord, record.RuleSnapshot); err != nil {
+		if err := ensureTaskCompatible(deviceRecord, record); err != nil {
 			return err
 		}
 		if record.DeviceID == nil || *record.DeviceID != deviceRecord.ID {
@@ -286,6 +288,17 @@ func (service *Service) payload(record models.CollectionTask, replayed bool) (Ta
 	if !json.Valid(rule) {
 		return TaskPayload{}, internalError(errors.New("stored rule snapshot is invalid JSON"))
 	}
+	var imageSearch json.RawMessage
+	if record.ImageSearchSnapshot != nil && *record.ImageSearchSnapshot != "" {
+		snapshot, snapshotErr := loadImageSearchSnapshot(record)
+		if snapshotErr != nil {
+			return TaskPayload{}, snapshotErr
+		}
+		imageSearch, _ = json.Marshal(snapshot.ImageSearchImage)
+		if !json.Valid(imageSearch) {
+			return TaskPayload{}, internalError(errors.New("stored image search snapshot is invalid JSON"))
+		}
+	}
 	timeout := service.TaskTimeout
 	if timeout <= 0 {
 		timeout = DefaultTaskTimeout
@@ -295,6 +308,7 @@ func (service *Service) payload(record models.CollectionTask, replayed bool) (Ta
 		URLSnapshot: record.URLSnapshot, GoodsIDSnapshot: record.GoodsIDSnapshot,
 		Source: record.Source, ReplacementOriginType: pointerValue(record.ReplacementOriginType),
 		RuleID: record.RuleID, RuleSnapshot: rule, TimeoutSeconds: timeout,
+		ImageSearch:    imageSearch,
 		LeaseExpiresAt: record.LeaseExpiresAt, LeaseVersion: record.LeaseVersion,
 		Status: record.Status, Replayed: replayed,
 	}, nil
@@ -38,11 +38,11 @@ func TestEnsurePurchaserRoleAndPolicies(t *testing.T) {
 	if count != int64(len(access.PurchaserAPIs())) {
 		t.Fatalf("got %d policies, want %d", count, len(access.PurchaserAPIs()))
 	}
-	var forbidden int64
+	var allowed int64
 	db.Model(&purchaserCasbinRule{}).
 		Where("v0 = ? AND v1 = ? AND v2 = ?", access.RolePurchaser, "/api/admin/v1/syb-products/import", "POST").
-		Count(&forbidden)
-	if forbidden != 0 {
-		t.Fatal("manual SYB import must remain administrator-only")
+		Count(&allowed)
+	if allowed != 1 {
+		t.Fatal("manual SYB import must follow the current purchaser permission matrix")
 	}
 }
@@ -0,0 +1,42 @@
+package version_local
+
+import (
+	"fmt"
+	"go-admin/app/goauto/clientkey"
+	"go-admin/cmd/migrate/migration"
+	migrationmodels "go-admin/cmd/migrate/migration/models"
+	common "go-admin/common/models"
+	"gorm.io/gorm"
+	"runtime"
+)
+
+func init() {
+	_, file, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(file), migrateClientAPIKey)
+}
+func migrateClientAPIKey(db *gorm.DB, version string) error {
+	if err := db.AutoMigrate(&clientkey.Key{}, &clientkey.Audit{}); err != nil {
+		return err
+	}
+	return db.Transaction(func(tx *gorm.DB) error {
+		var parent migrationmodels.SysMenu
+		if err := tx.Where("menu_name = ?", "GoAutoCollectionManagement").First(&parent).Error; err != nil {
+			return err
+		}
+		child, _, err := upsertGoAutoMenu(tx, migrationmodels.SysMenu{MenuName: "GoAutoClientKeys", Title: "客户端密钥", Icon: "lock", Path: "/client-keys/index", MenuType: "C", Action: "无", ParentId: parent.MenuId, Component: "/goauto/client-keys/index", Sort: 6, Visible: "0", IsFrame: "1"})
+		if err != nil {
+			return err
+		}
+		if err = tx.Model(&child).Update("paths", fmt.Sprintf("/0/%d/%d", parent.MenuId, child.MenuId)).Error; err != nil {
+			return err
+		}
+		var admin migrationmodels.SysRole
+		if err = tx.Where("role_key = ?", "admin").First(&admin).Error; err != nil {
+			return err
+		}
+		if err = tx.Model(&admin).Association("SysMenu").Append(&child); err != nil {
+			return err
+		}
+		return tx.Create(&common.Migration{Version: version}).Error
+	})
+}
@@ -0,0 +1,45 @@
+package version_local
+
+import (
+	"go-admin/app/goauto/clientkey"
+	migrationmodels "go-admin/cmd/migrate/migration/models"
+	common "go-admin/common/models"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"testing"
+)
+
+func TestClientKeyMigrationOnlyAdminMenu(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sql, _ := db.DB()
+	defer sql.Close()
+	if err = db.AutoMigrate(&migrationmodels.SysRole{}, &migrationmodels.SysMenu{}, &migrationmodels.SysApi{}, &common.Migration{}); err != nil {
+		t.Fatal(err)
+	}
+	admin := migrationmodels.SysRole{RoleKey: "admin"}
+	purchaser := migrationmodels.SysRole{RoleKey: "purchaser"}
+	parent := migrationmodels.SysMenu{MenuName: "GoAutoCollectionManagement"}
+	for _, v := range []any{&admin, &purchaser, &parent} {
+		if err = db.Create(v).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err = migrateClientAPIKey(db, "client-key-test"); err != nil {
+		t.Fatal(err)
+	}
+	if !db.Migrator().HasTable(&clientkey.Key{}) || !db.Migrator().HasTable(&clientkey.Audit{}) {
+		t.Fatal("missing tables")
+	}
+	var child migrationmodels.SysMenu
+	if err = db.Where("menu_name = ?", "GoAutoClientKeys").First(&child).Error; err != nil {
+		t.Fatal(err)
+	}
+	if child.ParentId != parent.MenuId {
+		t.Fatal("wrong menu group")
+	}
+	assertRoleHasMenu(t, db, admin.RoleId, child.MenuId, true)
+	assertRoleHasMenu(t, db, purchaser.RoleId, child.MenuId, false)
+}
@@ -0,0 +1,63 @@
+package version_local
+
+import (
+	"runtime"
+
+	"go-admin/app/goauto/models"
+	"go-admin/app/goauto/sybshop"
+	"go-admin/cmd/migrate/migration"
+	common "go-admin/common/models"
+
+	"gorm.io/gorm"
+)
+
+func init() {
+	_, file, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(file), migrateSYBProductFilterTable)
+}
+
+// migrateSYBProductFilterTable creates syb_product_filter and seeds its rules
+// for #269.
+//
+// `[必须]` Adding the model to migrations.Migrate only covers databases created
+// from scratch. Every existing database already has the older version numbers
+// recorded in sys_migration, so that list never runs again there — a new model
+// needs its own version file, which is what the post-migration table check in
+// cmd/migrate enforces.
+//
+// The seed is deliberately the same set the fresh-database path writes, created
+// with FirstOrCreate on the normalized key so running both paths against one
+// database cannot produce duplicates.
+func migrateSYBProductFilterTable(db *gorm.DB, version string) error {
+	if err := db.AutoMigrate(&models.SYBProductFilter{}); err != nil {
+		return err
+	}
+	return db.Transaction(func(tx *gorm.DB) error {
+		// 结构判据 is what defines a 档口 product; the keywords are the forward
+		// safety net for the day those codes stop carrying "#" (#269).
+		seed := []struct{ kind, keyword string }{
+			{"char", "-"},
+			{"char", "#"},
+			{"keyword", "CVC短袖220斤"},
+			{"keyword", "180克純棉圓領短袖"},
+			{"keyword", "拼色純棉短袖"},
+			{"keyword", "300斤牛奶絲圓領"},
+			{"keyword", "印花大學T"},
+			{"keyword", "印花帽T"},
+		}
+		for _, item := range seed {
+			norm := sybshop.Normalize(item.keyword)
+			row := models.SYBProductFilter{
+				Kind:              item.kind,
+				Keyword:           item.keyword,
+				NormalizedKeyword: norm,
+				Enabled:           true,
+			}
+			if err := tx.Where("kind = ? AND normalized_keyword = ?", item.kind, norm).
+				FirstOrCreate(&row).Error; err != nil {
+				return err
+			}
+		}
+		return tx.Create(&common.Migration{Version: version}).Error
+	})
+}
@@ -0,0 +1,91 @@
+package version_local
+
+import (
+	"fmt"
+	"runtime"
+
+	"go-admin/app/goauto/access"
+	"go-admin/cmd/migrate/migration"
+	migrationmodels "go-admin/cmd/migrate/migration/models"
+	common "go-admin/common/models"
+
+	"gorm.io/gorm"
+)
+
+func init() {
+	_, file, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(file), migrateSYBProductFilterMenu)
+}
+
+// migrateSYBProductFilterMenu adds the 「SYB 商品过滤」 menu entry for #269.
+//
+// `[必须]` Adding a module to access.GoAutoModules() is not enough to make its
+// page reachable. Menus are written by the versioned migration that first
+// created them, and that version is already recorded in sys_migration on every
+// existing database — it never runs again. Startup only reconciles the casbin
+// API matrix (access.ReconcilePurchaserPermissions), not sys_menu. Without this
+// migration the page exists, the API answers and the route resolves, yet nobody
+// can navigate to it on an already-migrated database.
+func migrateSYBProductFilterMenu(db *gorm.DB, version string) error {
+	return db.Transaction(func(tx *gorm.DB) error {
+		module, ok := goAutoModuleByKey(access.ModuleSYBProductFilters)
+		if !ok {
+			return fmt.Errorf("module %q is not registered in access.GoAutoModules()", access.ModuleSYBProductFilters)
+		}
+
+		// The page belongs beside 「SYB 店铺」 under 采采管理, which is where the
+		// admin already manages which SYB data enters the system.
+		var parent migrationmodels.SysMenu
+		if err := tx.Where("menu_name = ?", "GoAutoCollectionManagement").First(&parent).Error; err != nil {
+			return err
+		}
+
+		child, _, err := upsertGoAutoMenu(tx, migrationmodels.SysMenu{
+			MenuName:  module.RouteName,
+			Title:     module.Title,
+			Icon:      module.Icon,
+			Path:      module.Path + "/index",
+			MenuType:  "C",
+			Action:    "无",
+			ParentId:  parent.MenuId,
+			Component: module.Component,
+			Sort:      module.Sort,
+			Visible:   "0",
+			IsFrame:   "1",
+		})
+		if err != nil {
+			return err
+		}
+		if err = tx.Model(&child).Update("paths", fmt.Sprintf("/0/%d/%d", parent.MenuId, child.MenuId)).Error; err != nil {
+			return err
+		}
+
+		// Bind to both roles the module declares. 采购员 needs it because the
+		// module is PurchaserDefault; 管理员 needs it because only an admin may
+		// change the rules (the write routes are RequireRoleKey("admin")).
+		roleKeys := []string{"admin"}
+		if module.PurchaserDefault {
+			roleKeys = append(roleKeys, access.RolePurchaser)
+		}
+		for _, key := range roleKeys {
+			var role migrationmodels.SysRole
+			if err = tx.Where("role_key = ?", key).First(&role).Error; err != nil {
+				return err
+			}
+			if err = tx.Model(&role).Association("SysMenu").Append(&child); err != nil {
+				return err
+			}
+		}
+
+		return tx.Create(&common.Migration{Version: version}).Error
+	})
+}
+
+func goAutoModuleByKey(key string) (access.ModuleDefinition, bool) {
+	for _, module := range access.GoAutoModules() {
+		if module.Key == key {
+			return module, true
+		}
+	}
+	return access.ModuleDefinition{}, false
+}
@@ -0,0 +1,27 @@
+package version_local
+
+import (
+	"go-admin/app/goauto/models"
+	"go-admin/cmd/migrate/migration"
+	common "go-admin/common/models"
+	"gorm.io/gorm"
+)
+
+func init() { migration.Migrate.SetVersion("1789200000000", migrateSYBParseStatusBinary) }
+
+// migrateSYBParseStatusBinary folds legacy uncertain rows into failed and
+// narrows the check constraint to the two supported states (#272).
+func migrateSYBParseStatusBinary(db *gorm.DB, version string) error {
+	if err := db.Model(&models.SYBProduct{}).Where("parse_status = ?", "uncertain").Update("parse_status", models.SYBParseStatusFailed).Error; err != nil {
+		return err
+	}
+	if db.Dialector.Name() == "mysql" {
+		if err := db.Exec("ALTER TABLE syb_product DROP CHECK ck_syb_product_parse_status").Error; err != nil {
+			return err
+		}
+		if err := db.Exec("ALTER TABLE syb_product ADD CONSTRAINT ck_syb_product_parse_status CHECK (parse_status IN ('success','failed'))").Error; err != nil {
+			return err
+		}
+	}
+	return db.Create(&common.Migration{Version: version}).Error
+}
@@ -0,0 +1,36 @@
+package version_local
+
+import (
+	"runtime"
+
+	"go-admin/app/goauto/models"
+	"go-admin/cmd/migrate/migration"
+	common "go-admin/common/models"
+	"gorm.io/gorm"
+)
+
+func init() {
+	_, fileName, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(fileName), migrateImageSearchCollection)
+}
+
+// #278 permits image-search tasks while preserving existing task rows.
+func migrateImageSearchCollection(db *gorm.DB, version string) error {
+	return db.Transaction(func(tx *gorm.DB) error {
+		if !tx.Migrator().HasColumn(&models.CollectionTask{}, "ImageSearchSnapshot") {
+			if err := tx.Migrator().AddColumn(&models.CollectionTask{}, "ImageSearchSnapshot"); err != nil {
+				return err
+			}
+		}
+		if tx.Dialector.Name() == "mysql" {
+			// MySQL does not support ALTER CHECK in place.  The migration runner
+			// records this version once, so dropping/recreating the named check is
+			// deterministic and does not trigger a whole-schema AutoMigrate.
+			_ = tx.Exec("ALTER TABLE collection_task DROP CHECK ck_collection_task_source").Error
+			if err := tx.Exec("ALTER TABLE collection_task ADD CONSTRAINT ck_collection_task_source CHECK (source IN ('admin','agent_current_page','image_search'))").Error; err != nil {
+				return err
+			}
+		}
+		return tx.Create(&common.Migration{Version: version}).Error
+	})
+}
@@ -0,0 +1,25 @@
+package version_local
+
+import (
+	"runtime"
+
+	goautomigrations "go-admin/app/goauto/migrations"
+	"go-admin/cmd/migrate/migration"
+	common "go-admin/common/models"
+	"gorm.io/gorm"
+)
+
+func init() {
+	_, fileName, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(fileName), migrateImageSearchLinkMarker)
+}
+
+// #279 stores whether the current Shopee→PDD link was created by image search.
+func migrateImageSearchLinkMarker(db *gorm.DB, version string) error {
+	return db.Transaction(func(tx *gorm.DB) error {
+		if err := goautomigrations.Migrate(tx); err != nil {
+			return err
+		}
+		return tx.Create(&common.Migration{Version: version}).Error
+	})
+}
@@ -0,0 +1,20 @@
+// Package clientprincipal carries an authenticated client identity, never an
+// administrator or purchaser JWT. Only the client gateway sets it.
+package clientprincipal
+
+import "github.com/gin-gonic/gin"
+
+const contextKey = "goauto.authenticatedClient"
+
+type Identity struct {
+	KeyID        uint64
+	RequestID    string
+	AuthorizedBy uint64
+}
+
+func Set(c *gin.Context, id Identity) { c.Set(contextKey, id) }
+func Get(c *gin.Context) (Identity, bool) {
+	v, ok := c.Get(contextKey)
+	id, valid := v.(Identity)
+	return id, ok && valid && id.KeyID > 0
+}
@@ -24,6 +24,12 @@ import (
 // LoggerToFile 日志记录到文件
 func LoggerToFile() gin.HandlerFunc {
 	return func(c *gin.Context) {
+		// #237: client request/response bodies and one-time credentials must never
+		// enter the legacy operation logger. The client gateway keeps metadata-only audit.
+		if strings.HasPrefix(c.Request.URL.Path, "/api/client/") || strings.HasPrefix(c.Request.URL.Path, "/api/admin/v1/client-keys") {
+			c.Next()
+			return
+		}
 		log := api.GetRequestLogger(c)
 		// 开始时间
 		startTime := time.Now()
@@ -0,0 +1,8 @@
+import request from '@/utils/request'
+
+const base = '/api/admin/v1/client-keys'
+export const listClientKeys = page => request({ url: base, method: 'get', params: { page }, suppressErrorMessage: true })
+export const clientKeyModules = () => request({ url: `${base}/modules`, method: 'get', suppressErrorMessage: true })
+export const createClientKey = data => request({ url: base, method: 'post', data, suppressErrorMessage: true })
+export const editClientKey = (id, data) => request({ url: `${base}/${id}/grants`, method: 'patch', data, suppressErrorMessage: true })
+export const disableClientKey = (id, version) => request({ url: `${base}/${id}/disable`, method: 'post', data: { version }, suppressErrorMessage: true })
@@ -3,6 +3,7 @@ import request from '@/utils/request'
 export function listCollectionTasks(params) { return request({ url: '/api/admin/v1/collection-tasks', method: 'get', params }) }
 export function createCollectionTask(data) { return request({ url: '/api/admin/v1/collection-tasks', method: 'post', data }) }
 export function batchCreateCollectionTasks(data) { return request({ url: '/api/admin/v1/collection-tasks/batch', method: 'post', data }) }
+export function batchCreateImageSearchCollectionTasks(data) { return request({ url: '/api/admin/v1/collection-tasks/image-search/batch', method: 'post', data }) }
 export function getCollectionTask(taskId) { return request({ url: `/api/admin/v1/collection-tasks/${taskId}`, method: 'get' }) }
 export function resetCollectionTask(taskId, data) { return request({ url: `/api/admin/v1/collection-tasks/${taskId}/reset`, method: 'post', data }) }
 export function deleteCollectionTask(taskId, data) { return request({ url: `/api/admin/v1/collection-tasks/${taskId}`, method: 'delete', data }) }
@@ -8,16 +8,16 @@ export function createShopeeProduct(data) {
  return request({ url: '/api/admin/v1/shopee-products', method: 'post', data })
 }

-export function getShopeeProduct(productId) {
-  return request({ url: `/api/admin/v1/shopee-products/${productId}`, method: 'get' })
+export function getShopeeProduct(productId, options = {}) {
+  return request({ url: `/api/admin/v1/shopee-products/${productId}`, method: 'get', ...options })
 }

 export function updateShopeeProduct(productId, data) {
  return request({ url: `/api/admin/v1/shopee-products/${productId}`, method: 'patch', data })
 }

-export function linkShopeeProductPdd(productId, data) {
-  return request({ url: `/api/admin/v1/shopee-products/${productId}/link-pdd`, method: 'post', data })
+export function linkShopeeProductPdd(productId, data, options = {}) {
+  return request({ url: `/api/admin/v1/shopee-products/${productId}/link-pdd`, method: 'post', data, ...options })
 }

 export function restoreShopeeProduct(productId, data) {
@@ -66,8 +66,11 @@ export function suggestShopeeSizeMappings(productId, data) {
  return request({ url: `/api/admin/v1/shopee-products/${productId}/specs/mapping/suggest-sizes`, method: 'post', data, timeout: aiSuggestTimeoutMs })
 }

-export function autoMatchShopeeSpecMappings(productId, data) {
-  return request({ url: `/api/admin/v1/shopee-products/${productId}/specs/mapping/auto-match`, method: 'post', data, timeout: aiSuggestTimeoutMs })
+export function autoMatchShopeeSpecMappings(productId, data, timeoutSeconds) {
+  if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 16 || timeoutSeconds > 1210) {
+    return Promise.reject(new Error('匹配等待时间不可用，请刷新页面后重试'))
+  }
+  return request({ url: `/api/admin/v1/shopee-products/${productId}/specs/mapping/auto-match`, method: 'post', data, timeout: (timeoutSeconds + 10) * 1000, suppressErrorMessage: true })
 }

 export function startShopeeSpecAutoMatchRun(data) {
@@ -0,0 +1,6 @@
+import request from '@/utils/request'
+const base = '/api/admin/v1/syb-product-filters'
+export function listSybProductFilters(params) { return request({ url: base, method: 'get', params }) }
+export function createSybProductFilter(data) { return request({ url: base, method: 'post', data }) }
+export function setSybProductFilterEnabled(id, data) { return request({ url: `${base}/${id}/enabled`, method: 'patch', data }) }
+export function deleteSybProductFilter(id) { return request({ url: `${base}/${id}`, method: 'delete' }) }
@@ -0,0 +1,24 @@
+// Separate from the purchase-device preference; browser origin provides the
+// outer isolation and API environment + user identify the inner namespace.
+function key(userId) {
+  const id = Number(userId)
+  return Number.isSafeInteger(id) && id > 0 ? `goauto:quick-link-device:${encodeURIComponent(process.env.VUE_APP_BASE_API || '/')}:user:${id}` : null
+}
+
+export function readQuickLinkDevice(userId) {
+  try {
+    const name = key(userId)
+    if (!name) return null
+    const id = JSON.parse(localStorage.getItem(name) || 'null')
+    return Number.isSafeInteger(id) && id > 0 ? id : null
+  } catch { return null }
+}
+
+export function rememberQuickLinkDevice(userId, deviceId) {
+  try {
+    const name = key(userId)
+    if (!name || !Number.isSafeInteger(deviceId) || deviceId <= 0) return false
+    localStorage.setItem(name, JSON.stringify(deviceId))
+    return true
+  } catch { return false }
+}
@@ -0,0 +1,121 @@
+<template>
+  <BasicLayout>
+    <template #wrapper>
+      <el-card shadow="never">
+        <el-alert v-if="!isAdmin" title="只有管理员可以管理客户端密钥" type="warning" :closable="false" />
+        <template v-else>
+          <div class="heading"><div><h2>客户端密钥</h2><p>按菜单模块开放客户端访问。完整密钥仅在创建成功后显示一次。</p></div><el-button type="primary" :disabled="loading || !!loadError" @click="openEditor()">创建密钥</el-button></div>
+          <el-alert v-if="loadError" :title="loadError" type="error" :closable="false"><el-button @click="load">重新加载</el-button></el-alert>
+          <el-table v-loading="loading" :data="items" row-key="id" border empty-text="还没有客户端密钥，点击右上角创建">
+            <el-table-column label="名称 / 标识" min-width="210"><template #default="{ row }"><strong>{{ row.name }}</strong><p class="muted">{{ row.prefix }}••••</p></template></el-table-column>
+            <el-table-column label="授权模块" min-width="250"><template #default="{ row }"><div v-for="g in row.grants" :key="g.module">{{ moduleName(g.module) }} · {{ g.write ? '读写' : '只读' }}<span v-if="g.actions.length"> / {{ g.actions.map(actionName).join('、') }}</span></div></template></el-table-column>
+            <el-table-column label="状态" width="100"><template #default="{ row }"><el-tag :type="row.enabled ? 'success' : 'info'">{{ row.enabled ? '启用中' : '已停用' }}</el-tag></template></el-table-column>
+            <el-table-column label="最后使用" min-width="170"><template #default="{ row }">{{ row.lastUsedAt ? formatTime(row.lastUsedAt) : '尚未使用' }}</template></el-table-column>
+            <el-table-column label="操作" width="255"><template #default="{ row }"><el-button link type="primary" @click="openEditor(row, true)">查看授权</el-button><el-button link type="primary" :disabled="!row.enabled || saving" @click="openEditor(row)">编辑授权</el-button><el-button link type="danger" :disabled="!row.enabled || saving" @click="disable(row)">停用</el-button></template></el-table-column>
+          </el-table>
+          <el-pagination v-if="total" v-model:current-page="page" :total="total" :page-size="20" layout="prev, pager, next, total" @current-change="load" />
+          <p class="muted">客户端地址：/api/client/v1。支持 HTTP / HTTPS；HTTP 明文传输密钥和数据。不开放支付、账号权限管理及敏感密钥读取。</p>
+        </template>
+      </el-card>
+      <el-dialog v-model="editorOpen" :title="readonly ? '查看授权' : editing ? '编辑授权' : '创建客户端密钥'" width="min(1080px, 95vw)" :close-on-click-modal="false" :close-on-press-escape="!saving" :show-close="!saving" :before-close="closeEditor">
+        <el-alert v-if="editError" :title="editError" type="error" :closable="false" class="notice" />
+        <el-form label-position="top" @submit.prevent="save">
+          <el-form-item label="名称" required><el-input v-model.trim="name" maxlength="80" :disabled="readonly || editing || saving" placeholder="例如：商品同步工具" /></el-form-item>
+          <p v-if="editing" class="muted">标识：{{ selected.prefix }}•••• · 保存不会更换 API Key，完整密钥不可再次查看。</p>
+          <el-alert title="新选模块默认只读；同步、采集、采购、回写、删除等动作需单独勾选。新增菜单不会自动授权。" type="info" :closable="false" class="notice" />
+          <div class="groups">
+            <section v-for="group in groups" :key="group.title" class="module-group">
+              <el-checkbox :model-value="group.modules.every(m => !!grants[m.key])" :indeterminate="group.modules.some(m => !!grants[m.key]) && !group.modules.every(m => !!grants[m.key])" :disabled="readonly || saving" @change="value => selectGroup(group, value)">{{ group.title }}</el-checkbox>
+              <div v-for="m in group.modules" :key="m.key" class="module-row">
+                <div class="module-main"><el-checkbox :model-value="!!grants[m.key]" :disabled="readonly || saving" @change="value => selectModule(m.key, value)">{{ m.title }}</el-checkbox><el-radio-group v-if="grants[m.key]" v-model="grants[m.key].write" :disabled="readonly || saving" size="small" :aria-label="`${m.title}访问方式`"><el-radio-button :value="false">只读</el-radio-button><el-radio-button :value="true" :disabled="!m.writable">读写</el-radio-button></el-radio-group></div>
+                <div v-if="grants[m.key] && m.actions.length" class="actions"><span class="muted">独立动作：</span><el-checkbox-group v-model="grants[m.key].actions" :disabled="readonly || saving"><el-checkbox v-for="action in m.actions" :key="action" :value="action">{{ actionName(action) }}</el-checkbox></el-checkbox-group></div>
+              </div>
+            </section>
+          </div>
+          <p v-if="editing" class="muted">{{ selected.enabled ? '保存成功后，后续请求按新授权校验；已执行操作不回滚。' : '密钥已停用，只允许查看授权。' }} 最近修改：管理员 #{{ selected.updatedBy }} · {{ formatTime(selected.updatedAt) }}</p>
+          <p v-if="!Object.keys(grants).length" class="validation" role="alert">至少选择一个模块；要禁止全部访问，请使用停用。</p>
+        </el-form>
+        <template #footer><el-button :disabled="saving" @click="closeEditor()">{{ readonly ? '关闭' : '取消' }}</el-button><el-button v-if="!readonly" type="primary" :loading="saving" :disabled="!valid || !changed || conflicted" @click="save">{{ editing ? '保存授权' : '创建密钥' }}</el-button></template>
+      </el-dialog>
+      <el-dialog v-model="secretOpen" title="密钥已创建，请立即保存" width="min(650px, 95vw)" :close-on-click-modal="false" @closed="clearSecret">
+        <el-alert title="完整密钥只显示这一次；关闭后不可再次查看。请勿放入 URL、日志或前端代码。" type="warning" :closable="false" />
+        <pre class="secret">{{ secret }}</pre><el-button type="primary" @click="copySecret">复制密钥</el-button>
+        <p>请求头：Authorization: Bearer &lt;客户端密钥&gt;</p>
+        <template #footer><el-button type="primary" @click="secretOpen = false">已保存，返回列表</el-button></template>
+      </el-dialog>
+    </template>
+  </BasicLayout>
+</template>
+
+<script>
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { listClientKeys, clientKeyModules, createClientKey, editClientKey, disableClientKey } from '@/api/goauto/client-keys'
+
+const actionLabels = { sync: '立即同步', import: '导入', match: '匹配 / 确认', collect: '创建 / 重新采集', purchase: '创建 / 重试采购', writeback: '回写', delete: '删除', reparse: '重新解析', activate: '设置当前规则' }
+const snapshot = grants => JSON.stringify(Object.values(grants).map(g => ({ ...g, actions: [...g.actions].sort() })).sort((a, b) => a.module.localeCompare(b.module)))
+const errorText = error => error.response?.data?.message || '请求失败，请检查网络后重试'
+
+export default {
+  name: 'GoAutoClientKeys',
+  data() { return { active: true, items: [], modules: [], total: 0, page: 1, loading: false, loadError: '', saving: false, editorOpen: false, editing: false, readonly: false, selected: null, name: '', grants: {}, initial: '', editError: '', conflicted: false, secret: '', secretOpen: false } },
+  computed: {
+    isAdmin() { return (this.$store.getters.roles || []).includes('admin') },
+    groups() { return [...new Set(this.modules.map(m => m.group))].map(title => ({ title, modules: this.modules.filter(m => m.group === title) })) },
+    valid() { return !!this.name.trim() && Object.keys(this.grants).length > 0 },
+    changed() { return !this.editing || snapshot(this.grants) !== this.initial }
+  },
+  mounted() { this.load() },
+  activated() { this.active = true },
+  deactivated() { this.active = false; this.clearSecret(); this.secretOpen = false },
+  beforeUnmount() { this.active = false; this.clearSecret() },
+  methods: {
+    moduleName(key) { return this.modules.find(m => m.key === key)?.title || key },
+    actionName(action) { return actionLabels[action] || action },
+    formatTime(value) { return value ? new Date(value).toLocaleString() : '—' },
+    async load() {
+      if (!this.isAdmin || this.loading) return
+      this.loading = true; this.loadError = ''
+      try { const [rows, catalog] = await Promise.all([listClientKeys(this.page), clientKeyModules()]); this.items = rows.data.items; this.total = rows.data.total; this.modules = catalog.data } catch (error) { this.loadError = errorText(error) } finally { this.loading = false }
+    },
+    openEditor(row = null, readonly = false) {
+      if (!this.isAdmin || (row && !row.enabled && !readonly)) return
+      this.selected = row; this.editing = !!row; this.readonly = readonly; this.name = row?.name || ''; this.grants = {}
+      for (const g of row?.grants || []) this.grants[g.module] = { ...g, actions: [...g.actions] }
+      this.initial = snapshot(this.grants); this.editError = ''; this.conflicted = false; this.editorOpen = true
+    },
+    selectModule(key, value) { if (value) { if (!this.grants[key]) this.grants[key] = { module: key, write: false, actions: [] } } else delete this.grants[key] },
+    selectGroup(group, value) { for (const m of group.modules) this.selectModule(m.key, value) },
+    closeEditor(done) { if (this.saving) return; this.editorOpen = false; this.grants = {}; if (typeof done === 'function') done() },
+    async save() {
+      if (!this.valid || !this.changed || this.saving || this.readonly || this.conflicted) return
+      this.saving = true; this.editError = ''
+      try {
+        if (this.editing) { await editClientKey(this.selected.id, { version: this.selected.version, grants: Object.values(this.grants) }); ElMessage.success('授权已更新，API Key 保持不变') } else { const result = await createClientKey({ name: this.name, grants: Object.values(this.grants) }); if (this.active) { this.secret = result.data.secret; this.secretOpen = true } }
+        this.editorOpen = false; await this.load()
+      } catch (error) { this.editError = errorText(error); if (!this.editing) this.editError += '。响应丢失时可能已创建，请先检查列表；丢失密钥需停用后重建。'; this.conflicted = error.response?.status === 409; if (this.conflicted) { this.editError += '。请取消并刷新列表后重新打开。'; await this.load() } } finally { this.saving = false }
+    },
+    async disable(row) {
+      try { await ElMessageBox.confirm(`停用“${row.name}”后，新请求将被拒绝，已执行操作不回滚。首版不支持恢复。`, '停用客户端密钥', { confirmButtonText: '确认停用', cancelButtonText: '取消', type: 'warning' }) } catch { return }
+      this.saving = true
+      try { await disableClientKey(row.id, row.version); ElMessage.success('密钥已停用'); await this.load() } catch (error) { ElMessage.error(errorText(error)); await this.load() } finally { this.saving = false }
+    },
+    async copySecret() { try { await navigator.clipboard.writeText(this.secret); ElMessage.success('已复制，请妥善保存') } catch { ElMessage.warning('复制失败，请手动选择并复制密钥') } },
+    clearSecret() { this.secret = '' }
+  }
+}
+</script>
+
+<style scoped>
+.heading { display: flex; align-items: center; justify-content: space-between; gap: 20px; margin-bottom: 24px; }
+h2 { margin: 0 0 12px; }
+.muted, .heading p { color: var(--el-text-color-secondary); font-size: 13px; line-height: 1.6; }
+.groups { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
+.module-group { padding: 16px; border: 1px solid var(--el-border-color); border-radius: 6px; min-width: 0; }
+.module-row { padding: 10px 0; border-top: 1px solid var(--el-border-color-lighter); }
+.module-main { display: flex; align-items: center; justify-content: space-between; gap: 8px; flex-wrap: wrap; }
+.actions { padding: 4px 0 0 22px; }
+.notice, .el-pagination { margin: 16px 0; }
+.validation { color: var(--el-color-danger); }
+.secret { white-space: pre-wrap; overflow-wrap: anywhere; padding: 16px; background: var(--el-fill-color-light); }
+@media (max-width: 760px) { .groups { grid-template-columns: 1fr; } .heading { align-items: flex-start; } }
+</style>
@@ -13,8 +13,8 @@
        <template #default><el-button link type="primary" @click="reload">重新加载</el-button></template>
      </el-alert>
      <template v-if="detail.product">
-        <div class="drawer-actions"><el-tag :type="mappingMeta(detail.product).type">{{ mappingMeta(detail.product).label }}</el-tag><el-button type="primary" @click="openEdit">编辑档案</el-button></div>
-        <el-descriptions :column="2" border>
+        <div class="drawer-actions"><div class="drawer-status"><el-tag :type="mappingMeta(detail.product).type">{{ mappingMeta(detail.product).label }}</el-tag><el-tag v-if="detail.product.imageSearchLinked" type="success" size="small">图搜自动关联</el-tag></div><el-button type="primary" :disabled="detail.aiMatching" @click="openEdit">编辑档案</el-button></div>
+        <el-descriptions :column="2" border :inert="detail.aiMatching">
          <el-descriptions-item label="虾皮商品ID">{{ detail.product.shopeeItemId }}</el-descriptions-item>
          <el-descriptions-item label="店铺">{{ detail.product.shopName || '未填写' }}</el-descriptions-item>
          <el-descriptions-item label="标题" :span="2">{{ detail.product.title || '未填写' }}</el-descriptions-item>
@@ -27,7 +27,10 @@
        <el-alert title="成功匹配会直接保存并可用于采购；未通过置信度或候选校验的项目保持未匹配。不会修改蝦皮或 PDD 的原始颜色和尺码。" type="info" :closable="false" show-icon class="notice" />
        <el-alert v-if="!detail.product.pddProductId" title="请先关联 PDD 商品，再进行规格匹配。" type="warning" :closable="false" show-icon class="notice" />
        <el-alert v-else-if="detail.pddLoaded && !pddSpecValues('color').length && !pddSpecValues('size').length" title="关联的 PDD 商品暂无可用规格，请先完成商品采集。" type="warning" :closable="false" show-icon class="notice" />
-        <el-tabs v-model="detail.activeSpecTab" class="mapping-tabs">
+        <el-alert v-if="detail.matchMessage" :title="detail.matchMessage" :type="detail.matchMessageType" :closable="false" show-icon class="notice" role="status" aria-live="polite">
+          <template #default><el-button v-if="!detail.aiMatching" link type="primary" @click="reload">刷新查看</el-button></template>
+        </el-alert>
+        <el-tabs v-model="detail.activeSpecTab" class="mapping-tabs" :inert="detail.aiMatching">
          <el-tab-pane label="颜色匹配" name="color">
            <el-empty v-if="!specRows('color').length" description="虾皮商品暂无颜色规格" />
            <el-table v-else :data="specRows('color')" :row-class-name="mappingRowClass" border size="small">
@@ -48,10 +51,10 @@
          </el-tab-pane>
        </el-tabs>
        <div class="section-heading"><h3>添加规格值</h3></div>
-        <div class="quick-row"><span class="quick-label">维度</span><el-select v-model="addValueForm.role" size="small" style="width:110px"><el-option label="颜色" value="color" /><el-option label="尺码" value="size" /><el-option label="其他" value="other" /></el-select><el-input v-model="addValueForm.dimension" size="small" placeholder="维度名称，如 颜色 / 尺码" style="width:160px" /><el-input v-model="addValueForm.name" size="small" placeholder="规格值名称" style="width:160px" /><el-button size="small" type="primary" @click="submitAddValue">+ 添加规格值</el-button></div>
+        <div class="quick-row" :inert="detail.aiMatching"><span class="quick-label">维度</span><el-select v-model="addValueForm.role" size="small" style="width:110px"><el-option label="颜色" value="color" /><el-option label="尺码" value="size" /><el-option label="其他" value="other" /></el-select><el-input v-model="addValueForm.dimension" size="small" placeholder="维度名称，如 颜色 / 尺码" style="width:160px" /><el-input v-model="addValueForm.name" size="small" placeholder="规格值名称" style="width:160px" /><el-button size="small" type="primary" @click="submitAddValue">+ 添加规格值</el-button></div>
      </template>
    </div>
-    <template #footer><el-button @click="closeDetail">关闭</el-button><el-button type="primary" :loading="detail.saving" :disabled="!hasMappingChanges" @click="saveAllMappings">保存修改</el-button></template>
+    <template #footer><el-button @click="closeDetail">关闭</el-button><el-button type="primary" :loading="detail.saving" :disabled="detail.aiMatching || !hasMappingChanges" @click="saveAllMappings">保存修改</el-button></template>
  </el-drawer>

  <el-dialog v-model="pddPicker.open" title="搜索并选择 PDD 商品" width="860px" append-to-body :close-on-click-modal="false">
@@ -95,7 +98,7 @@ export default {
  emits: ['update:modelValue', 'product-updated', 'mapping-updated', 'pdd-linked', 'purchase-created', 'switch-cancelled'],
  data() {
    return {
-      detailDrawerOpen: false, detail: this.emptyDetail(), loadError: '', requestGeneration: 0, loadedProductId: null,
+      detailDrawerOpen: false, detail: this.emptyDetail(), loadError: '', requestGeneration: 0, loadedProductId: null, matchOperation: 0,
      pddPicker: { open: false, loading: false, keyword: '', items: [] }, pddDetail: { open: false, productId: null },
      edit: { open: false, saving: false, productId: null }, editData: { title: '', shopName: '', imageUrl: '', salePriceCent: null },
      addValueForm: { dimension: '', role: 'other', name: '' }
@@ -105,7 +108,7 @@ export default {
    allSpecRows() { return this.detail.product ? this.detail.product.specs.flatMap(d => d.values) : [] },
    hasMappingChanges() { return this.allSpecRows.some(row => (row.pddValueDraft || '') !== (row.originalPddValue || '')) },
    mappingProgressText() { const rows = this.allSpecRows.filter(row => row.role === 'color' || row.role === 'size'); const valid = rows.filter(row => row.pddValueDraft && this.pddValueExists(row.role, row.pddValueDraft)).length; return rows.length ? `${valid}/${rows.length} 已匹配` : '暂无可匹配规格' },
-    canAutoMatch() { return this.detail.pddLoaded && !this.hasMappingChanges && ['color', 'size'].some(role => this.specRows(role).length > 0 && this.pddSpecValues(role).length > 0) }
+    canAutoMatch() { return !this.detail.aiMatching && !this.detail.loading && !this.detail.saving && !this.edit.open && !this.pddPicker.open && !this.pddDetail.open && this.detail.pddLoaded && !this.hasMappingChanges && ['color', 'size'].some(role => this.specRows(role).length > 0 && this.pddSpecValues(role).length > 0) }
  },
  watch: {
    modelValue: { immediate: true, handler(open) { if (open) this.requestSwitch(this.productId); else this.closeInternals() } },
@@ -114,17 +117,17 @@ export default {
    action(value) { if (value === 'link_pdd' && this.detail.product && !this.pddPicker.open) this.openPddPicker() }
  },
  methods: {
-    emptyDetail() { return { loading: false, saving: false, aiMatching: false, product: null, pddProduct: null, pddLoaded: false, activeSpecTab: 'color', highlightColor: '' } },
+    emptyDetail() { return { loading: false, saving: false, aiMatching: false, matchMessage: '', matchMessageType: 'info', product: null, pddProduct: null, pddLoaded: false, activeSpecTab: 'color', highlightColor: '' } },
    validProductId(id) { return Number.isInteger(Number(id)) && Number(id) > 0 },
-    isCurrent(generation, id) { return this.modelValue && generation === this.requestGeneration && Number(this.productId) === Number(id) },
+    isCurrent(generation, id) { return this.modelValue && this.detailDrawerOpen && generation === this.requestGeneration && Number(this.productId) === Number(id) },
    async confirmDiscard() { if (!this.hasMappingChanges) return true; return this.$confirm('当前有未保存的规格匹配，确定放弃吗？', '放弃修改？', { type: 'warning', confirmButtonText: '放弃修改', cancelButtonText: '继续编辑' }).then(() => true).catch(() => false) },
    async requestSwitch(id) {
      if (!this.validProductId(id)) { this.loadError = '虾皮商品编号无效'; this.detailDrawerOpen = true; return }
-      if (this.loadedProductId === Number(id) && this.detail.product) { this.detailDrawerOpen = true; return }
      if (this.detail.product && !await this.confirmDiscard()) { this.$emit('switch-cancelled', this.loadedProductId); return }
      await this.loadProduct(Number(id))
    },
    async loadProduct(id) {
+      this.finishMatchView()
      const generation = ++this.requestGeneration
      this.loadedProductId = null; this.detailDrawerOpen = true; this.detail = { ...this.emptyDetail(), loading: true, highlightColor: String(this.targetColor || '').trim() }; this.loadError = ''; this.pddPicker.open = false; this.pddDetail.open = false
      try {
@@ -138,13 +141,14 @@ export default {
        this.loadError = error?.response?.data?.message || error?.response?.data?.msg || '虾皮商品详情加载失败，请稍后重试'
      } finally { if (this.isCurrent(generation, id)) this.detail.loading = false }
    },
-    reload() { return this.loadProduct(Number(this.productId)) },
-    closeInternals() { this.requestGeneration++; this.detailDrawerOpen = false; this.pddPicker.open = false; this.pddDetail.open = false; this.edit.open = false },
-    async beforeCloseDetail(done) { if (this.pddDetail.open) return; if (!await this.confirmDiscard()) return; done(); this.requestGeneration++; this.$emit('update:modelValue', false) },
+    async reload() { if (this.detail.aiMatching || !await this.confirmDiscard()) return; return this.loadProduct(Number(this.productId)) },
+    finishMatchView() { this.matchOperation++; this.detail.aiMatching = false; this.detail.matchMessage = '' },
+    closeInternals() { this.finishMatchView(); this.requestGeneration++; this.detailDrawerOpen = false; this.pddPicker.open = false; this.pddDetail.open = false; this.edit.open = false },
+    async beforeCloseDetail(done) { if (this.pddDetail.open) return; if (!await this.confirmDiscard()) return; this.finishMatchView(); done(); this.requestGeneration++; this.$emit('update:modelValue', false) },
    closeDetail() { this.beforeCloseDetail(() => { this.detailDrawerOpen = false }) },
    withDraftMappings(product) { return { ...product, specs: (product.specs || []).map(d => ({ ...d, values: d.values.map(v => ({ ...v, dimensionName: d.name, role: d.role, pddValueDraft: v.mapping ? v.mapping.pddValue : '', originalPddValue: v.mapping ? v.mapping.pddValue : '', draftSource: v.mapping ? v.mapping.source : 'manual', previewReason: '', draftConfidence: null })) })) } },
    async loadLinkedPdd(pddId, generation = this.requestGeneration, productId = this.loadedProductId) { this.detail.pddLoaded = false; this.detail.pddProduct = null; try { const r = await getPddProduct(pddId); if (!this.isCurrent(generation, productId)) return; this.detail.pddProduct = r.data.product } finally { if (this.isCurrent(generation, productId)) this.detail.pddLoaded = true } },
-    async refreshDetail(eventName = 'mapping-updated') { const id = this.loadedProductId; const generation = this.requestGeneration; const r = await getShopeeProduct(id); if (!this.isCurrent(generation, id)) return; this.detail.product = this.withDraftMappings(r.data.product); if (this.detail.product.pddProductId) await this.loadLinkedPdd(this.detail.product.pddProductId, generation, id); this.$emit(eventName, { id, product: this.detail.product }) },
+    async refreshDetail(eventName = 'mapping-updated') { const id = this.loadedProductId; const generation = this.requestGeneration; const r = await getShopeeProduct(id, { suppressErrorMessage: this.detail.aiMatching }); if (!this.isCurrent(generation, id)) return; this.detail.product = this.withDraftMappings(r.data.product); if (this.detail.product.pddProductId) await this.loadLinkedPdd(this.detail.product.pddProductId, generation, id); if (this.isCurrent(generation, id)) this.$emit(eventName, { id, product: this.detail.product }) },
    priceText(row) { if (row.salePriceCent === null || row.salePriceCent === undefined) return '—'; return `${row.currency || ''} ${(row.salePriceCent / 100).toFixed(2)}` },
    mappingMeta(product) { if (!product) return { label: '-', type: 'info' }; if (!product.pddProductId) return { label: '未关联 PDD 商品', type: 'info' }; const values = (product.specs || []).flatMap(d => d.values); if (!values.length) return { label: '待完善', type: 'warning' }; const confirmed = values.filter(v => v.mapping && v.mapping.status === 'confirmed' && (!this.detail.pddLoaded || this.pddValueExists(v.role || '', v.mapping.pddValue))).length; return confirmed === values.length ? { label: '可采购', type: 'success' } : { label: `待完善 · ${confirmed}/${values.length} 已确认`, type: 'warning' } },
    openPddPicker() { this.pddPicker = { open: true, loading: false, keyword: '', items: [] }; this.searchPddPicker() },
@@ -161,7 +165,60 @@ export default {
    markManual(row) { row.draftSource = 'manual'; row.previewReason = ''; row.draftConfidence = null },
    clearDraft(row) { row.pddValueDraft = ''; row.draftSource = 'manual'; row.previewReason = ''; row.draftConfidence = null },
    mappingRowClass({ row }) { return this.detail.highlightColor && row.role === 'color' && row.name === this.detail.highlightColor ? 'mapping-row-highlight' : '' },
-    async autoMatchMappings() { const id = this.loadedProductId; const generation = this.requestGeneration; this.detail.aiMatching = true; try { const r = await autoMatchShopeeSpecMappings(id, { requestId: createRequestId(), specContextVersion: this.detail.product.specContextVersion }); if (!this.isCurrent(generation, id)) return; const confirmed = Number(r.data.confirmedCount || 0); const preserved = Number(r.data.preservedCount || 0); const unmatched = Number(r.data.unmatchedCount || 0); await this.refreshDetail(); const message = `新匹配并确认 ${confirmed} 项，保留已确认 ${preserved} 项，未匹配 ${unmatched} 项`; if (unmatched > 0) ElMessage.warning(message); else ElMessage.success(message) } finally { if (this.isCurrent(generation, id)) this.detail.aiMatching = false } },
+    async autoMatchMappings() {
+      if (!this.canAutoMatch) return
+      const id = this.loadedProductId
+      const generation = this.requestGeneration
+      const operation = ++this.matchOperation
+      const current = () => this.isCurrent(generation, id) && operation === this.matchOperation
+      this.detail.aiMatching = true
+      this.detail.matchMessage = '正在读取最新规格与等待时间'
+      this.detail.matchMessageType = 'info'
+      let submitted = false
+      let received = false
+      try {
+        const prepared = await getShopeeProduct(id, { suppressErrorMessage: true })
+        if (!current()) return
+        const seconds = prepared.data.autoMatchTimeoutSeconds
+        if (!Number.isInteger(seconds) || seconds < 16 || seconds > 1210) throw new Error('匹配等待时间不可用，请确认服务端已更新后刷新重试')
+        this.detail.product = this.withDraftMappings(prepared.data.product)
+        this.detail.matchMessage = `正在匹配并保存，最多等待 ${seconds + 10} 秒`
+        submitted = true
+        const r = await autoMatchShopeeSpecMappings(id, { requestId: createRequestId(), specContextVersion: prepared.data.product.specContextVersion }, seconds)
+        if (!current()) return
+        received = true
+        this.detail.matchMessage = '匹配请求已完成，正在读取保存结果'
+        await this.refreshDetail()
+        if (!current()) return
+        const unmatched = Number(r.data.unmatchedCount || 0)
+        const message = `新匹配并确认 ${Number(r.data.confirmedCount || 0)} 项，保留已确认 ${Number(r.data.preservedCount || 0)} 项，未匹配 ${unmatched} 项`
+        this.detail.matchMessage = message
+        this.detail.matchMessageType = unmatched ? 'warning' : 'success'
+        if (unmatched) ElMessage.warning(message); else ElMessage.success(message)
+      } catch (error) {
+        if (!current()) return
+        this.detail.matchMessageType = 'warning'
+        if (!submitted) {
+          this.detail.matchMessage = error?.message || '读取匹配设置失败，请刷新后重试'
+          return
+        }
+        // A lost response is not proof of a rollback. Read once, never retry POST.
+        if (received) {
+          this.detail.matchMessage = '匹配请求已完成，但结果暂未确认，请刷新查看'
+          return
+        }
+        this.detail.matchMessage = '匹配请求超时或未正常返回，正在核对保存结果'
+        try {
+          await this.refreshDetail()
+          if (!current()) return
+          this.detail.matchMessage = '已刷新当前保存结果；原请求未正常返回，请检查未匹配项后再操作'
+        } catch {
+          if (current()) this.detail.matchMessage = '结果暂未确认，请刷新查看；不要重复提交匹配'
+        }
+      } finally {
+        if (current()) this.detail.aiMatching = false
+      }
+    },
    async confirmPendingMapping(row) { await confirmShopeeSpecMapping(this.loadedProductId, { requestId: createRequestId(), dimension: row.dimensionName, valueName: row.name }); await this.refreshDetail() },
    async saveAllMappings() { const changes = this.allSpecRows.filter(row => (row.pddValueDraft || '') !== (row.originalPddValue || '')); if (!changes.length) return; const invalid = changes.find(row => row.pddValueDraft && !this.pddValueExists(row.role, row.pddValueDraft)); if (invalid) { ElMessage.warning(`PDD 规格“${invalid.pddValueDraft}”已不存在，请重新选择`); return } this.detail.saving = true; try { for (const row of changes) { if (!row.pddValueDraft) { if (row.originalPddValue) await clearShopeeSpecMapping(this.loadedProductId, { requestId: createRequestId(), dimension: row.dimensionName, valueName: row.name }); continue } const source = ['exact_match', 'ai_match'].includes(row.draftSource) ? row.draftSource : 'manual'; const payload = { requestId: createRequestId(), dimension: row.dimensionName, valueName: row.name, pddValue: row.pddValueDraft, source }; if (source === 'ai_match') { if (row.draftConfidence !== null && row.draftConfidence !== undefined) payload.confidence = row.draftConfidence; if (row.previewReason) payload.reason = row.previewReason } await setShopeeSpecMapping(this.loadedProductId, payload); if (source === 'exact_match') await confirmShopeeSpecMapping(this.loadedProductId, { requestId: createRequestId(), dimension: row.dimensionName, valueName: row.name }) } ElMessage.success('规格匹配已保存'); await this.refreshDetail() } finally { this.detail.saving = false } },
    async submitAddValue() { const dimension = this.addValueForm.dimension.trim(); const name = this.addValueForm.name.trim(); if (!dimension || !name) { ElMessage.warning('请填写维度名称和规格值'); return } await addShopeeSpecValue(this.loadedProductId, { requestId: createRequestId(), dimension, role: this.addValueForm.role, name }); this.addValueForm = { dimension: '', role: 'other', name: '' }; await this.refreshDetail() },
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
QiuSW	a16e6920b7	docs(#277 ): record sanitized pdd home evidence	2026-09-15 10:07:27 +08:00
QiuSW	def0a86f63	fix(#277 ): fail image search tasks explicitly until automation is available	2026-09-15 09:59:56 +08:00
QiuSW	ba7d2a6b72	feat(#280 ): remember image search device	2026-09-15 09:57:17 +08:00
QiuSW	a3cf98940a	fix(#279 ): only auto-link active pdd products	2026-09-15 09:51:39 +08:00
QiuSW	56706a0b45	fix(#280 ): show image search association marker	2026-09-15 09:45:50 +08:00
QiuSW	a4874091a8	feat: prepare validated image search media asset (#277 )	2026-09-15 09:42:25 +08:00
QiuSW	9e0dcc254e	feat: parse image search task metadata in agent (#277 )	2026-09-15 09:40:51 +08:00
QiuSW	cda1978bc6	test: prevent image snapshot payload leakage (#278 )	2026-09-15 09:37:01 +08:00
QiuSW	c80d0c91d5	feat: add image search batch dialog to syb products (#280 )	2026-09-15 09:07:45 +08:00
QiuSW	be491c7692	feat: expose image search batch API to web (#280 )	2026-09-15 09:02:08 +08:00
QiuSW	90c1668fe3	test: cover image search auto-link guards (#279 )	2026-09-15 09:01:10 +08:00
QiuSW	804448ede0	feat: show image search link marker in shopee detail (#279 )	2026-09-15 08:59:37 +08:00
QiuSW	5a7e219230	feat: add image-search linked filter to shopee list (#279 )	2026-09-15 08:58:35 +08:00
QiuSW	36d1f82ce2	feat: filter image-search linked shopee products (#279 )	2026-09-15 08:53:37 +08:00
QiuSW	1c998911be	feat: auto link completed image search results (#279 )	2026-09-15 08:50:19 +08:00
QiuSW	45437a9214	feat: record cross-currency image search price guard (#278 )	2026-09-15 08:44:39 +08:00
QiuSW	42b5312198	feat: support image search identity handoff and safe payload (#278 )	2026-09-15 08:42:11 +08:00
QiuSW	7b540f3163	feat: create and dispatch image search tasks (#278 )	2026-09-15 08:41:42 +08:00
QiuSW	ffa5fc0710	fix: add idempotent image snapshot column migration (#278 )	2026-09-14 18:02:22 +08:00
QiuSW	66ab36c88c	feat: expose image search snapshot in task payload (#278 )	2026-09-14 16:49:35 +08:00
QiuSW	35b69fc25a	fix: narrow image search migration (#278 )	2026-09-14 16:31:07 +08:00
QiuSW	b4dc7fc9ae	feat: track image search links and preserve manual overrides (#279 )	2026-09-14 16:08:55 +08:00
QiuSW	baa9408a36	feat: allow image search collection task source (#278 )	2026-09-14 16:05:01 +08:00
QiuSW	e01fcd9860	feat: request media permission for image search (#276 )	2026-09-14 16:03:21 +08:00
QiuSW	be03972779	merge: #283 purchase readiness consistency	2026-09-14 14:48:13 +08:00
QiuSW	c137f5072f	fix: keep purchase readiness consistent with confirmed mappings (#283 )	2026-09-14 14:42:11 +08:00
QiuSW	82b4ebd406	feat(ops): add batch SYB failed reparse script (#282 )	2026-09-14 11:34:36 +08:00
QiuSW	b83f20c6b7	fix(syb): accept descriptive color specs (#274 )	2026-09-14 10:52:02 +08:00
QiuSW	e0ed05d15a	fix(syb): accept reliable single spec dimension (#274 )	2026-09-12 12:01:15 +08:00
QiuSW	8163dd10eb	fix(ai): match size by standard token (#273 )	2026-09-12 11:46:46 +08:00
QiuSW	aed295c8c1	fix(syb): reduce parse status to success or failed (#272 )	2026-09-12 11:36:43 +08:00
QiuSWandClaude Opus 5	c14f5f528b	fix(server): keep agent diagnostics on order-check failures #271 normalizeOrderUnknownFailure replaced the agent's message with a canonical sentence, so the diagnostic #210 added never reached the database. Across the 61 PURCHASE_ORDER_PAYMENT_REPEATED failures on production between 2026-09-07 and 09-11, not one carried paymentBackAttempts or consecutivePaymentSamplesAfterBack, which left three very different causes indistinguishable: the Back never left the payment activity, the page rendered slower than the ~1.1s window the agent allows, or the page was already the order page and no marker matched. Those need different fixes, and there was no way to tell which one to make. The canonical sentence stays authoritative and leads the message — agent text is free-form and the wording per error code has to stay stable — but the agent evidence is now appended behind it, flattened to one line (control characters and U+FEFF removed, whitespace collapsed) and truncated to the column's 1000 runes with the canonical part kept whole. The sibling "failed" branch already stored agent text verbatim, so this adds no new trust assumption. That branch also only wrote the failure onto the task, never the attempt, so every attempt it produced carried a NULL error_code and was invisible to attempt-level statistics — the spec-panel failures on production are exactly that. It now writes both. This restores observability only; it does not reduce how often PAYMENT_REPEATED happens. Tuning the agent's sampling window is deliberately left out until the next production failure shows real values. Wiki updated first: Android-Agent-API-Contract@ba259178. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-12 11:13:02 +08:00
QiuSW	8293b27c19	fix(syb): retry drifting sync page once (#270 )	2026-09-12 09:34:44 +08:00
QiuSWandClaude Opus 5	c24e8a4439	docs: refresh stale wiki mirrors picked up by the same sync run Unrelated to #269. These three pages were changed online by other work and the local mirror had drifted (02 and 03 from 2026-09-10, 06 from 2026-09-04). The sync that mirrored the #269 pages regenerates every mapping, so it brought these along; they are committed separately to keep the ticket's own commit limited to its files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-11 17:15:38 +08:00
QiuSWandClaude Opus 5	40a254dc41	docs: mirror SYB product filter rules and admin API #269 Wiki updated online first, then mirrored: - SYB-ERP-Interface-Contract@f1792b7f — filter order after shop admission, OR-not-AND with the 8498/6392/6386/8504 figures from the 2026-09-11 production check, empty variationSku kept, per-rule hit counts, and the no-add/no-delete rule for structural criteria. - Android-Agent-API-Contract@38869285 — the syb-product-filters endpoints, the server-side refusal of char add/delete, and the live lastHitCount requirement for the disable confirmation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-11 17:15:38 +08:00
QiuSWandClaude Opus 5	503b3cbbc5	fix(goauto): create syb_product_filter on existing databases #269 Three defects that only a real MySQL run could show. The table had no version-local migration. Adding the model to migrations.Migrate covers databases built from scratch, but every existing one already has the older versions recorded in sys_migration, so that list never runs again there. cmd/migrate's post-migration table check caught it: "迁移后仍缺少表：syb_product_filter". The new version file creates the table and seeds the same eight rules with FirstOrCreate on the normalized key, so running both paths against one database cannot duplicate them. Keyword and NormalizedKeyword were typed text, which MySQL refuses to put in a key specification without a prefix length (Error 1170), so the unique index could not be built at all. They are sized 200 now, matching how SYBShop sizes its own matching key. SQLite accepts text in an index, which is why the whole test suite passed while the real migration failed. The 只看启用 filter is removed rather than kept: hiding a disabled structural rule would conceal the one state on this page that matters most, since a disabled "#" means roughly 65% of 档口 rows start entering the system again. Keyword search stays. Verified against the local MySQL database: migration applies, eight rules present with traditional Chinese preserved (印花大學T normalizes to 印花大學t), menu row created under 采采管理. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-11 17:00:11 +08:00
QiuSWandClaude Opus 5	cad9f6d185	fix(goauto): add the missing menu migration for SYB product filters #269 Registering a module in access.GoAutoModules() does not make its page reachable on an existing database. sys_menu rows are written by the versioned migration that first created them, and that version is already recorded in sys_migration everywhere — it never runs again. Startup only reconciles the casbin API matrix, not menus. So on a fresh database the page appeared and on every real one it did not: the table, the API and the route were all present with no way to navigate there. This adds a migration that upserts the entry under 采采管理 beside 「SYB 店铺」 and binds it to both 管理员 and 采购员. Verified by deleting the row from an already-migrated database and re-running migrate: 新执行 1 个，跳过 42 个, row restored with both roles. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-11 16:49:56 +08:00
QiuSWandClaude Opus 5	78df997fc3	test(goauto): pin SYB filter behaviour against real variationSku samples #269 The samples are the ones the production database actually holds: 档口 codes like "新寮-雅伊阁大码女装#301" and "DD#004" must be filtered, while own codes like "PDD0582", "my238", "1" and "引流款" must not, and an empty variationSku is a product without a supplier code rather than a 档口 item. The test also asserts the two structural rules record different hit counts. That is the property the previous aggregate-per-kind write could not hold, and the disable-confirmation dialog depends on it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-11 16:37:43 +08:00
QiuSWandClaude Opus 5	20f59b68bd	fix(goauto): record SYB filter hits per rule, not per kind #269 UpdateHits wrote one aggregate per kind, so every structural rule stored the same number. The disable-confirmation dialog quotes that number ("停用「#」后…约 N 条明细会恢复入库"), and on real data "#" matches 8498 rows while "-" matches 6392 — the dialog would have warned with a figure 2100 rows off for one of them. Match now returns the rule that matched instead of a char/keyword pair, so the caller can attribute each hit to one rule, and UpdateHits writes every rule's own count. Rules that matched nothing are written as 0 so a previous run's number is never left behind. The management page is reformatted to the repo's usual Vue layout and gains the search / 只看启用 / 重置 controls the approved prototype shows. Cancelling the disable confirmation now just reverts the switch instead of throwing an unhandled rejection. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTDbDcwbDw1TSAcE6wfh2F	2026-09-11 16:27:13 +08:00
QiuSW	652bf30f5a	feat(goauto): add SYB product variation filters (#269 )	2026-09-11 16:20:26 +08:00
QiuSW	79929036bb	docs: clarify metadata-only partial collection eligibility #259	2026-09-10 16:10:13 +08:00
QiuSW	e4677069d7	fix(syb): allow metadata-only partial collection links #259	2026-09-10 16:07:58 +08:00
QiuSW	8cfd32babe	docs: record one-click replacement contract and boundaries #258	2026-09-10 15:52:03 +08:00
QiuSW	3181302c16	test: capture stable replacement confirmation states #258	2026-09-10 15:48:17 +08:00
QiuSW	2b01974fe5	feat(syb): confirm one-click replacement from latest collection #258	2026-09-10 15:47:27 +08:00
QiuSW	305062dba0	docs: record normalized color matching rule #257	2026-09-10 14:56:01 +08:00
QiuSW	ea38ced58c	fix(shopee): normalize colors before AI matching #257	2026-09-10 14:54:56 +08:00
QiuSW	2cb78ad8cd	fix(collection): preserve task state during current-page reidentify #255	2026-09-10 14:26:39 +08:00
QiuSW	ca997f6108	docs: record SYB quick-link behavior and API #253	2026-09-10 11:39:34 +08:00
QiuSW	b1594dc7bd	feat(syb): link latest device collection and match specs #253	2026-09-10 11:34:22 +08:00
QiuSW	08d939a9b8	docs: sync dynamic match timeout contract #254	2026-09-10 09:43:53 +08:00
QiuSW	9088e6b734	fix(shopee): bound matching waits and recover drawer loading #254	2026-09-10 09:37:02 +08:00
QiuSW	fdd26afaf0	docs: record online deployment for #237 and #239	2026-09-08 10:26:01 +08:00
QiuSW	d403f3b3a0	docs(syb): define page commits and partial success contract (#239 )	2026-09-08 09:39:59 +08:00
QiuSW	c6a962d522	fix(syb): persist validated pages and report partial sync success (#239 )	2026-09-08 09:35:36 +08:00
QiuSW	9d5242b371	docs(local): record verified client key migration and service startup (#237 )	2026-09-07 17:45:38 +08:00
QiuSW	9a10d82cf4	chore(local): run GoAuto from main runtime with explicit migrations (#237 )	2026-09-07 17:41:34 +08:00
QiuSW	ac3c63ead6	docs(client-api): record approved HTTP compatibility (#237 )	2026-09-07 17:29:28 +08:00
QiuSW	71f7751754	fix(client-api): support HTTP and HTTPS by default (#237 )	2026-09-07 17:25:55 +08:00
QiuSW	76c94e33e0	docs(client-api): sync key contracts and deployment prerequisites (#237 )	2026-09-07 17:15:02 +08:00
QiuSW	57b0f1595f	feat(client-api): add scoped editable client keys (#237 )	2026-09-07 16:20:46 +08:00
QiuSW	29ba16e4f9	feat(syb): allow purchaser manual sync (#236 )	2026-09-07 15:03:31 +08:00