{"record":{"id":"1d06423c591ceb71","repo":"flipped-aurora/gin-vue-admin","slug":"id-d-d-username","errorCode":null,"errorMessage":"未找到 ID 为 %d 的用户(已扫描前 %d 条,大用户量场景请传 username 参数精确定位)","messagePattern":"未找到 ID 为 (.+?) 的用户\\(已扫描前 (.+?) 条,大用户量场景请传 username 参数精确定位\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mcp/org_common.go","lineNumber":256,"sourceCode":"\t\t\treturn nil, fmt.Errorf(\"获取用户列表失败: %w\", err)\n\t\t}\n\t\tfor i := range resp.Data.List {\n\t\t\tif resp.Data.List[i].ID == userID {\n\t\t\t\treturn &resp.Data.List[i], nil\n\t\t\t}\n\t\t}\n\t\t// hint 仅是加速命中的优化;username 为 LIKE 模糊匹配且只查首页,未命中(名不匹配或\n\t\t// 命中过多致目标不在首页)时不误报,回退全量翻页扫描兜底\n\t}\n\n\tfound, _, err := scanUsersByIDs(ctx, []uint{userID})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif user, ok := found[userID]; ok {\n\t\treturn &user, nil\n\t}\n\treturn nil, fmt.Errorf(\"未找到 ID 为 %d 的用户(已扫描前 %d 条,大用户量场景请传 username 参数精确定位)\", userID, orgUserScanMaxPages*orgUserScanPageSize)\n}\n\n// requireNonEmptyList 语义化的必填列表校验\nfunc requireNonEmptyList(ids []uint, name string) error {\n\tif len(ids) == 0 {\n\t\treturn errors.New(name + \" 参数是必需的,且至少包含一个ID\")\n\t}\n\treturn nil\n}\n\n// parseOptionalPositiveInt 解析可选的正整数分页参数,兼容数字与字符串两种形式\n// (与本工具集\"数字参数兼容字符串\"的既定设计一致);缺省或非法时返回 def\nfunc parseOptionalPositiveInt(v any, def int) int {\n\tswitch value := v.(type) {\n\tcase float64:\n\t\tif value >= 1 {\n\t\t\treturn int(value)\n\t\t}","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/mcp/org_common.go#L238-L274","documentation":"findUserByID exhausts its scan: upstream getUserList lacks ID filtering, so the tool scans up to 20 pages of 100 users (2000 records). If the target ID never appears (or the user is outside the caller's data-scope visibility), this error is returned with guidance to pass a username hint.","triggerScenarios":"Requesting an org operation on a userId whose record is not within the first 2000 visible rows of /user/getUserList, the user does not exist, or the row is hidden by the caller's data-scope permissions.","commonSituations":"Large deployments with >2000 users where the target user sits beyond the scan limit; userId typo or from another environment; data-scope engine filters the row out for this token; user soft-deleted.","solutions":["Pass the username parameter so the tool can locate the user precisely via the LIKE filter","Verify the userId is correct and the user exists in the admin UI","Check the user is within the MCP token's data-scope visible range","Confirm the user has not been deleted","If the deployment is very large and username unknown, look up the ID in the frontend first"],"exampleFix":"// before\n{\"userId\": 8873}\n// after\n{\"userId\": 8873, \"username\": \"zhangsan\"}  // precise locate, avoids 2000-row scan","handlingStrategy":"validation","validationCode":"// resolve the user first via a direct lookup, only call the assign tool with a confirmed ID + username\nconst user = await findUserByUsername(username)\nif (!user) throw new Error('target user does not exist')\n// then pass both: { userId: user.ID, username: user.username }","typeGuard":null,"tryCatchPattern":"try {\n  await callMcpTool('assign_user_org', args)\n} catch (e) {\n  if (/未找到 ID 为 \\d+ 的用户/.test(e.message)) {\n    // re-call with username hint, or verify the ID/data-scope visibility in the admin UI\n  }\n}","preventionTips":["Always supply the username hint in deployments with >2000 users","Validate userIds exist (and are data-scope visible for the token) before calling","Keep environment-specific ID maps instead of hardcoding user IDs"],"tags":["mcp","user-lookup","not-found","pagination","data-scope"],"backgroundTag":"user-not-found","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}