禁止同 IP 用户参与 · PRD

作者 Luke　版本 v1.15　日期 2026-10-06　状态 进行中　平台 BRAND_A & BRAND_B　类 P

模板基准 prd

模板调整说明：沿用一页式 L0/L1 结构；将旧版独立后台名单说明并入 §6，减少同一需求出现两份现行 PRD 的歧义。Axure「更新2_Promo List_活动管理列表」仅是活动模板共用条件与名单功能参考，不是需求 06 的同名精确页面。

L0 · 快速掌握

① 一句话需求

在活动模板 Basic Info 增加共用条件「是否禁止同 IP 参与」；开启后，Apply／Claim 的领取人若与同品牌、同活动实例内的已领奖账号共享回看窗口内任一完整登录 IP，则永久自动拒绝本账号。

② 术语写死表

③ 全局红线表

④ 适用范围与「不做」边界

本期做

1. 活动模板 Basic Info 共用开关与 Apply／Claim 判断链（§1–§2）。
2. 成功、永久自动拒绝、系统繁忙三种结果及记录（§3）。
3. 活动级白名单、用户黑名单既有批量操作，以及登录 IP 黑名单的查询／下载／下钻页面（§4、§6）。
4. 并发、幂等、fail-close 与监测边界（§5、附录 C）。

明确不做

1. 不适用于 payday 排程派奖（§1）。
2. 不新增 claim IP，不以 login_ip_snapshot 参与判断（§2、§3）。
3. 不支持 IPv6；本期只处理规范化后的 IPv4（§2）。
4. 不以登录 IP 黑名单的失效时间做判断闸门；该 Tab 不提供删除、导入或模板下载（§6）。
5. 不补 Client HTML；玩家侧沿用既有活动页、Toast 与消息中心（§3）。
6. 不回填上线前的已领奖或拒绝资料；新 aid 由空资料开始（§3）。

读者为后台前端、服务端、测试、运营与稽核。

1. 范围、入口与优先级

1.1 配置入口与原型依据

1.2 判定优先级

1. 先走活动有效、领取资格、身份与既有幂等前置检查。
2. 前置通过后先查活动白名单；命中则跳过永久拒绝与同 IP 判断，直接走派奖。
3. 未命中白名单才查永久拒绝记录；已有记录则立即返回自动拒绝。
4. 未命中白名单且无永久拒绝记录，才取活动锁并执行同 IP 判断。
5. 任一步资料读取失败或超时都进入系统繁忙，不得按未命中处理。

2. 同 IP 判定

2.1 判断范围与资料集

2.2 IP 规范化

1. 只比较登录 IP，不读取领取请求 IP。
2. IPv4 在集合化前规范化为同一数值表达，例如 192.000.002.001 与 192.0.2.1 相同。
3. 只做完整 IP 精确相等，不做 /24、字串前缀或地理区域匹配。
4. IPv4-mapped IPv6 必须转为对应 IPv4；其他 IPv6 本期不纳入。

2.3 结果决策

2.3.1 一次触发只会落入下列一种结果：

2.3.2 每个共享 IP 群组的第一位领取者必然可能成功；这是先到先得模型的已知边界，不得在文案中承诺「同 IP 的所有人都不会得奖」。

3. 结果、提示与记录

3.1 三种结果与玩家文案

3.1.1 Toast 只表达结果；站内信承载正式说明：

3.1.2 成功信正文：An amount of {Bonus Amount}PHP has been credited to your account. To view the details of this transaction, please check Balance Record.

3.1.3 拒绝信正文：Your Reload Bonus of {Bonus Amount}PHP on {Claim Time} was not successful. / You are no longer eligible for this promotion.

3.1.4 {Claim Time} 为用户点击 Apply／Claim 的服务端时间，格式 YYYY-MM-DD HH:mm:ss。Toast 与站内信不得出现 IP、关联账号、账号数、命中规则或复查承诺。

3.2 永久拒绝记录

3.3 后台派发记录备注

3.3.1 自动拒绝时于 Remarks 写：Related claimed accounts: {total}; First 5: {sorted usernames}。账号去重后依稳定规则排序，只列前 5 个与总数，不写 IP；栏位长度须容纳最坏约 112 字符（OP-4）。

4. 白名单

4.1 作用与优先级

1. 白名单资料按 aid 管理；入口可从所有活动列进入。
2. 只有既有前置检查通过后才查白名单；活动过期或账号无资格时不发奖。
3. 命中白名单即跳过同 IP 判断并直接走既有派奖。
4. 加白不删除永久拒绝记录；删白后恢复原状态，已有永久拒绝者仍被拒绝。
5. 白名单长期有效，直到管理员手动删除；可选择账号下线一并加白。

4.2 管理行为

5. 并发、失败与性能

5.1 并发与幂等

5.2 fail-close 与缓存

1. 持久层是真源；一般资料缓存失效时回源真源，真源不可用则系统繁忙。
2. 白名单读取、锁服务或登录资料不可用时系统繁忙，不得按未命中放行。
3. DDoS 前置拦截只可在本次白名单查询未命中后读取；命中已永久拒绝账号／IP 的缓存时可直接回自动拒绝。新增、删除或导入白名单必须先失效同 brand + aid + user_hash 的拒绝快取；该前置层不可用时按现行规则返回系统繁忙。
4. 系统繁忙须写固定原因标签的运行日志，但不写永久拒绝记录或拒绝信。

5.3 性能基线

5.3.1 判断链目标 p99 < 50 ms；以 IP＋时间复合索引反查，成本应随 |Set_A| 增长，不得逐一加载所有已领奖账号的历史。只有实测 p99 > 800 ms 才评估异步；若采用异步，仅在自动重试耗尽仍无结果时发送「未处理」信。

6. 后台页面与字段

6.1 页面地图

6.2 登录 IP 黑名单字段

6.2.1 登录 IP 黑名单可依 IP 或 Username 查询；「下载／Export」紧邻「搜索／Search」，导出当前筛选的全部资料。本 Tab 没有删除全部、导入、批量编辑或下载导入模板。

6.2.2 黑名单与白名单页面标题均显示「名单类型 — [活动名称]」；活动名称必须由用户在活动列表点击的该笔记录动态带入，不得写死示例名称。

6.3 白名单字段

6.3.1 白名单批量操作列按 Axure 排列：左侧「删除全部数据」，右侧依序为「导入数据／导出数据／下载导入模板」。新增使用整页表单：Username、下线是否加白（默认「否」）、Remarks、确认与取消。

6.3.2 白名单 Excel 导入模板比照 Axure 截图，表头固定为 用户名 / 下线是否加白 / 备注；第二栏只接受 Y / N。「下载导入模板」必须下载真实 .xlsx 文件，不得只显示成功提示。

6.4 页面状态

6.4.1 活动列表、黑名单双 Tab、下钻与白名单页面都须具备 Content、Loading、Empty、Error；Error 提供 Retry。删除确认只陈述「从本活动白名单移除后恢复原资格状态」，不得承诺一定可以或不可以参与。

6.5 后台逐字文案

7. 权限、审计与资料边界

7.1 权限契约

7.1.1 功能级权限点最终名称见 OP-6；至少须分别控制：查看活动名单、查看登录 IP 下钻、导出登录 IP 黑名单、新增白名单、删除白名单、白名单导入／导出／下载模板。用户黑名单批量操作沿用既有权限；登录 IP 黑名单不定义删除、导入或批量编辑权限。

7.2 Admin Action Log

7.2.1 用户黑名单与白名单的新增、删除、导入与导出沿用既有审计；登录 IP 黑名单下钻与下载属于敏感查询，记录查询人、时间、aid 与查询条件；日志不得复制完整导出内容。

7.3 品牌与隐私

7.3.1 管理员只能看到被授权品牌与活动。玩家接口永远不回传 IP 或其他账号；后台 IP 与账号资料只供获授权的运营／稽核人员使用。

文档版本：v1.15 | 日期: 2026-10-06 | 作者: Luke | 文档状态：进行中

Block Users Sharing the Same IP · PRD

Author Luke　Version v1.15　Date 2026-10-06　Status In Progress　Platforms BRAND_A & BRAND_B　Class P　Template Baseline prd

Template adjustment: Uses the current one-page L0/L1 structure. The former standalone Backoffice-list specification is consolidated into §6 so Requirement 06 has one authoritative current PRD. The Axure page “更新2_Promo List_活动管理列表” is a shared campaign-template condition and list-management reference, not an exact page named after Requirement 06.

L0 · At a Glance

① One-Sentence Requirement

Add the shared condition “Block users sharing the same IP” to Campaign Template Basic Info. When enabled, an Apply/Claim user is permanently and automatically rejected if they share any complete login IP within the lookback window with a rewarded account in the same brand and campaign instance.

② Locked Terminology

③ Global Invariants

④ Included and Explicitly Excluded

Included

1. The Campaign Template Basic Info switch and Apply/Claim judgment chain (§1–§2).
2. Success, permanent automatic rejection, system-busy retry, and their records (§3).
3. Campaign whitelist, batch-manageable IP blacklist list, and Backoffice management (§4, §6).
4. Concurrency, idempotency, fail-close behavior, and monitoring (§5, Appendix C).

Explicitly excluded

1. Payday scheduled payouts (§1).
2. A new claim-IP field or use of login_ip_snapshot as judgment input (§2–§3).
3. IPv6 other than normalized IPv4-mapped values (§2).
4. Using IP-list Invalid Time as a gate. Delete All removes list data only; it does not remove claimed records or permanent account-rejection records (§6).
5. Client HTML; the existing campaign page, Toast, and Message Center remain (§3).
6. Backfilling claimed or rejected history before launch; every new aid starts empty (§3).

Audience: Backoffice frontend, backend, QA, Operations, and Audit.

1. Scope, Entry, and Priority

1.1 Configuration Entry and Prototype Evidence

1.2 Evaluation Priority

1. Run existing campaign-validity, eligibility, identity, and idempotency prechecks.
2. After prechecks, read the campaign whitelist first; a match bypasses both permanent-rejection and same-IP judgment and proceeds to payout.
3. Only after a whitelist miss, read the permanent-rejection record; an existing record returns automatic rejection immediately.
4. Only after a whitelist miss and no permanent rejection, acquire the campaign lock and run same-IP judgment.
5. A read failure or timeout at any step returns system busy; it must not be treated as “not found.”

2. Same-IP Judgment

2.1 Scope and Data Sets

2.2 IP Normalization

1. Compare login IPs only; never use the claim request IP.
2. Normalize IPv4 before forming sets; for example, 192.000.002.001 equals 192.0.2.1.
3. Match the full IP exactly; never use /24, string-prefix, or geographic matching.
4. Convert IPv4-mapped IPv6 to IPv4; other IPv6 values are out of scope.

2.3 Decision

The first claimant in each shared-IP group may succeed. This is a known first-come-first-served boundary; copy must not promise that every account sharing an IP is denied.

3. Outcomes, Copy, and Records

3.1 Three Outcomes and Player Copy

Success body: An amount of {Bonus Amount}PHP has been credited to your account. To view the details of this transaction, please check Balance Record.

Rejection body: Your Reload Bonus of {Bonus Amount}PHP on {Claim Time} was not successful. / You are no longer eligible for this promotion.

{Claim Time} is server time when Apply/Claim is clicked, formatted YYYY-MM-DD HH:mm:ss. Toasts, messages, and APIs must never expose IPs, related accounts, counts, matched rules, or a review promise.

3.2 Permanent Rejection Record

3.3 Payout-Record Remarks

For an automatic rejection, write Related claimed accounts: {total}; First 5: {sorted usernames} to Remarks. Deduplicate accounts, use stable sorting, list the first five plus the total, and never include an IP. The field must hold the worst-case estimate of about 112 characters (OP-4).

4. Whitelist

4.1 Effect and Priority

1. Whitelist data is scoped by aid; every Campaign List row may provide an entry.
2. Read the whitelist only after existing prechecks pass; an expired campaign or ineligible account is not paid.
3. A whitelist match bypasses same-IP judgment and proceeds through the existing payout path.
4. Adding to the whitelist does not delete permanent rejection; after removal, original eligibility resumes and an existing permanent rejection still rejects.
5. The whitelist remains effective until manually removed; optionally include the account’s downline.

4.2 Management Behavior

5. Concurrency, Failure, and Performance

5.1 Concurrency and Idempotency

5.2 Fail-Close and Cache

1. Persistent data is authoritative. A normal-data cache failure falls back to the source; source failure returns system busy.
2. Whitelist read, lock service, or login-data failure returns system busy and never counts as “not found.”
3. The DDoS rejection prefilter may be read only after the current whitelist lookup misses. A cached hit for an already rejected account/IP may then return automatic rejection without deep queries. Adding, removing, or importing a whitelist entry must first invalidate the rejection cache for the same brand + aid + user_hash; if the prefilter is unavailable, current behavior is system busy.
4. System busy records a fixed reason tag in runtime logs, but no rejection record or rejection message.

5.3 Performance Baseline

Judgment target: p99 < 50 ms. Reverse lookup depends on a composite IP-and-time index and must scale with |Set_A|; never load every rewarded user’s entire history one by one. Evaluate async only if measured p99 exceeds 800 ms. In async mode, send “not processed” only after automatic retries are exhausted without a result.

6. Backoffice Pages and Fields

6.1 Page Map

6.2 Login IP Blacklist Fields

Search Login IP Blacklist by IP or Username. Download/Export sits beside Search and exports all rows under the current filter. This tab has no Delete All, Import, batch edit, or Download Import Template.

Blacklist and whitelist headings follow List Type — [Campaign Name]. The campaign name is carried from the row clicked on Campaign List and must never be a hardcoded example.

6.3 Whitelist Fields

The whitelist batch-action row follows Axure: Delete All Data on the left, then Import Data, Export Data, and Download Import Template on the right. Add opens a full-page form containing Username, Whitelist Downline (default No), Remarks, Confirm, and Cancel.

The whitelist Excel import template follows the supplied Axure screenshot with fixed columns 用户名 / 下线是否加白 / 备注; the second column accepts Y / N only. Download Import Template must download a real, openable .xlsx, not only show a success message.

6.4 Page States

Campaign List, blacklist tabs, drill-down, and whitelist must each support Content, Loading, Empty, and Error; Error provides Retry. Delete confirmation states only that removal restores the account’s original eligibility state; it must not promise that participation will or will not be allowed.

6.5 Verbatim Backoffice Copy

7. Permissions, Audit, and Data Boundaries

7.1 Permission Contract

Final permission keys are OP-6. Separate controls are required for campaign-list view, Login IP drill-down/export, whitelist add/delete, and whitelist Import/Export/template download. User Blacklist batch actions retain existing permissions. Login IP Blacklist defines no delete, import, or batch-edit permission.

7.2 Admin Action Log

User Blacklist and Whitelist mutations retain existing audit behavior. Login IP drill-down and export are sensitive access and log viewer, time, aid, and search criteria. Logs must not copy full export content.

7.3 Brand and Privacy

Administrators see only authorized brands and campaigns. Player APIs never return IPs or other accounts. Backoffice IP/account data is limited to authorized Operations and Audit roles.

Document version: v1.15 | Date: 2026-10-06 | Author: Luke | Status: In Progress