Author Luke Version
v1.9 Date 2026-10-07 Status
Draft Platform BRAND_A &
BRAND_B Type K
Template Baseprd
Template adjustments: Keep manual input and CSV
import in one module, retain import-task rules and open points, and
place acceptance criteria and the visual inventory in separate collapsed
Appendices A and B.
Version history
Version
Date
Summary
v1.9
2026-10-07
Streamline the document; retain pagination and current-page
selection, remove the row-level history action, and clarify that ranges
must be expanded into individual IPs before import (§3). Synchronize
bilingual messages and Notice (§6); collapse Appendices A and B.
v1.8
2026-08-17
Restructure L0, fields and fail-open behavior; count remarks as
characters equally across languages; retain four permission operations,
silent filtering and 29 ACs (§2–§6, Appendix A).
v1.6
2026-07-21
Remove subnet/CIDR input; unify silent filtering, use direct DB
lookup, four permissions and plaintext export; pagination was removed in
that version (§2–§5).
v1.5
2026-07-01
Set CSV limit to 1000; concrete-platform dropdown without All;
remove related screenshots (§2.2).
Physical deletion with before-values, batch deletion and
asynchronous CSV import (§2.2, §2.3, §5.2).
v1.0
2026-06-30
Backoffice list management and registration/login interception (§2,
§3).
Contents
L0 · Executive Summary
① One-sentence requirement
Operations maintain malicious-source IPs per channel in Website
Management → Register/Login IP Blocklist. Registration/login blocks only
a full-IP match in the same channel; players receive a neutral
Notice.
② Fixed terminology
Term
Only meaning in this document
Real public IP
Source value written by the gateway into the internal header;
external IP fields are not trusted (§2.1).
Channel
BRAND_A/BRAND_B; the UI field Platform and platform permissions
refer to this isolation dimension (§2.1, §5).
Silent filtering
Invalid/duplicate rows are discarded without row-level errors or
failure details; only the success count is returned (§3.2).
Physical deletion
Remove the list record and store its complete before-values and
deletion reason in the existing Admin Action Log (§3.3).
Import task
Asynchronous CSV-processing entity; its state is separate from
list-record existence (§3.2).
③ Global invariants
#
Invariant
Impact if violated
Verification
G1
Trust only the gateway-provided real IP.
Forged external headers bypass blocking.
AC28
G2
Match a full IPv4 value within the same channel; no range
input/matching.
Other IPs in the same range are incorrectly blocked.
AC1, AC2
G3
Channel A's list does not affect B.
Cross-platform blocking.
AC18
G4
Missing IP, unknown channel or DB failure: log and allow.
Service failures block normal players.
AC5, AC8
G5
Manual and CSV input both silently filter invalid/duplicate rows and
return only success counts.
The input channels produce different results.
AC10, AC11
G6
Report file-level failures without creating a task.
Operators mistake a failed upload for success.
AC13
G7
Blocked players receive only neutral text, without IPs or matching
reasons.
List or decision information is exposed.
AC26
G8
Preserve complete before-values and deletion reason; no one-click
restore.
Deleted records cannot be audited.
AC20
G9
Repeat requests with the same idempotency key replay the first
completed result.
Retries execute again or return a new conflict.
AC23
④ Scope and exclusions
In scope: Registration/login evaluation (§1–§2);
paginated BO list, manual/CSV input, deletion/batch deletion and export
(§3); effectiveness/failures (§4); four permissions and auditing (§5);
neutral Notice and retry after closing (§6).
Out of scope: Range conversion, wildcard/prefix
matching and native IPv6 (§2.1, §3.2); whitelist, editing,
enable/disable, expiry or one-click restore (§2.2, §3.3); OTP
interception and historical-account freezing (§1); caching, circuit
breakers, active alerts and new rate limits (§4, §6.2).
Audience: BO/client frontend, backend, QA, operations and audit. The
Chinese PRD is authoritative.
1. Scope and entry
Item
Rule
BO
Website Management → Register/Login IP Blocklist; list, add form and
deletion confirmation.
Client
Existing login/registration flow; evaluate only POST /api/register
and POST /api/login. OTP/preliminary verification APIs keep existing
behavior.
Channel
BRAND_A & BRAND_B are isolated; use the existing
domain-to-platform mapping.
Existing accounts
No retroactive changes/freezing. A later login from a listed IP is
still blocked; an unmatched source follows normal evaluation.
Page evidence
, covering BO and Client Notice.
2. Core evaluation
2.1 Inputs and order
The gateway strips external X-Forwarded-For/X-Real-IP and writes one
real-IP value into the internal header. The gateway maintains trusted
proxies.
Normalize IPv4-mapped IPv6 to IPv4. Missing, unknown, malformed,
wildcard/CIDR, native IPv6 and these non-public sources are
identification failures: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16,
127.0.0.0/8, 169.254.0.0/16, 100.64.0.0/10, 0.0.0.0/8 and ::1. These
CIDRs describe boundaries, not accepted input.
Resolve the Host using the existing domain module, ignoring port and
case; multiple domains may map to one channel. Missing mapping and
module failure both allow but have different fail_reason values.
Query the DB directly for exact channel/normalized IPv4 equality.
Block only on a match. Matching logs identify the matched IP and record
ID.
2.2 Outcomes and record state
Condition
Outcome
Audit/message
Same-channel match
HTTP 200, code:4031, i18nKey and neutral message; stop this
login/registration request
§6.2 Notice; no list details in response
No match / empty channel list
Continue the existing login/registration flow
No new module message
IP/channel/DB identification or lookup failure
Continue the existing flow
System runtime log; no player-facing fallback reason
List record
Exists / does not exist only
No toggle, draft, expiry or global switch; delete to allow
3. BO pages and fields
3.1 Paginated list
Control/field
Rule
Platform
Single-select; All includes authorized channels only. Single-channel
accounts are locked to that channel without All.
IP
Individual IPv4 exact search; no range, wildcard, prefix or fuzzy
search.
Administrator
Exact search, ≤50 characters.
Added time
Date range; combine filters with AND; preserve existing date
controls.
List
Selection, ID, Platform, IP, added time, Administrator, Remarks,
Action. ID is a string and need not be consecutive. Default added-time
descending; sortable ID/added time.
Action
Delete only. Use the existing Admin Action Log, queried by channel +
IP, for history even after physical deletion.
Pagination
Retain existing pagination/page size. Search returns to page 1.
Select All affects only the current page; page changes/new searches
clear selection.
Page actions
Add at top right; Search/Export in filters; Batch Delete at bottom
left; pagination at bottom right. No new list Reset.
3.2 Add and CSV import
Field
Type
Required/default
Validation timing/boundary
Platform
Enum
Required/empty
Authorized concrete platform only, no All; block submission if
missing.
IP blocklist file
CSV
Exactly one of CSV/manual; empty
≤1000 data rows excluding header, ≤10MB. Validate file and row limit
on selection.
Manual IP input
String
Exactly one of CSV/manual; empty
English-comma separated, ≤100 entries; check count at submission, no
frontend row-level validity errors.
Remarks
String
Required/empty
≤100 characters, equal weight across languages; block submission if
missing/too long; apply the same remarks to all CSV rows.
Template has only the ip column, case-insensitive header, UTF-8 BOM
support and ignored blank lines. Operators expand ranges outside the
system into individual IPs and split batches to the limits. CSV cannot
contain CIDR/wildcard ranges.
Manual input is synchronous, CSV asynchronous. Both discard
malformed values, non-public addresses, native IPv6, within-batch
duplicates and existing records silently. Valid rows are inserted; only
the success count is returned, without failure details or a
partial-success state. The count may be 0.
Files >10MB, empty/header-only, non-UTF-8 or missing ip header
fail at file level without creating a task. CSV >1000/manual >100
is rejected as a whole. CSV must use the single-column template
format.
Save submits the selected method. Reset clears the add form. CSV and
manual input cannot be submitted together; remove a chosen file before
switching to manual input.
Task state
Entry/transition
PENDING
Created, not taken by worker; start → RUNNING; cancel before start →
CANCELLED.
Stop taking new rows; settle current batch → CANCELLED.
SUCCESS / FAILED / CANCELLED
Terminal; retry by uploading the original file as a new task. No
partial-success state. Already committed rows survive worker failure and
remain effective.
3.2.1 Writes carry Idempotency-Key. Repeated
requests with the same key replay the first completed status/body. For
concurrent writes using different Idempotency-Key values to add the same
channel/IP, the first commit succeeds; others return 4092 without
duplicate records.
Current-page selection; disabled when none selected; confirm count
and one required deletion remark.
Result
Success N / failure M only; unauthorized, nonexistent and
system-error cases share the failure count.
Audit
Record complete before-values: ID, channel, IP, added time, original
Administrator and original Remarks. Store deletion reason separately. No
restore entry; add again to block again.
3.4 Export
3.4.1 Export the last applied query within
authorization scope, with exact IP filtering. Fields: ID, channel, IP,
added time, Administrator and Remarks. Plaintext, no watermark; log
exporter, time, channel and count. IPs are configuration values without
associated names/phones/documents, so no masking or unmask permission.
Limit: once per user per hour; excess returns 4291.
4. Effectiveness,
failures and fallback
Scenario
Result
Add/delete committed
Effective on next query; DB is authoritative. No cache, breaker,
invalidation compensation or delay.
DB failure
Allow entry and log; create no erroneous blocking record.
Intentional design: All four permissions are independently assigned;
new accounts have no permissions until explicitly granted. Add and
Delete have different risks. No fixed roles/super-admin. Reuse Admin
Action Log, recording operation type (add/delete/import/export),
affected count, Administrator, time, channel and Remarks. Retention
follows existing administrator-log rules. Record IP/channel/DB failures
in runtime logs.
6. Messages
6.1 BO messages
Scenario
Approved Chinese
English
Presentation/result
CSV accepted
已提交（CSV：任务已创建，见任务中心）
Submitted (CSV: task created; see Task Center)
Toast; asynchronous task created
Limit
超出上限，请拆分后重试
Limit exceeded. Split the input and try again.
Inline; no submission
File failure
文件不符合要求：{具体原因}
File does not meet requirements: {reason}
Inline; no task. Reasons: empty file/header-only/non-UTF-8/missing
ip header/invalid CSV format. Files >10MB use the limit message and
also create no task.
Manual complete
成功录入 N 笔（无效 / 重复已自动剔除）
Successfully added N records (invalid / duplicate entries
automatically discarded)
Toast
CSV complete
成功导入 N 笔（无效 / 重复已自动剔除）
Successfully imported N records (invalid / duplicate entries
automatically discarded)
Toast/Task Center
Delete complete
操作完成：成功 N 笔，失败 M 笔
Operation completed: N succeeded, M failed
Toast
Conflict
操作失败，数据可能已更新，列表已刷新，请确认后重试
Operation failed. Data may have changed. The list has been
refreshed; check and try again.
Toast; refresh list
Export limit
导出过于频繁，请稍后再试
Exporting too frequently. Please try again later.
Toast
Required/method
请选择用户渠道、填写备注，并选择一种录入方式
Select a platform, enter remarks, and choose one input method.
Inline
Remarks length
备注最多 100 字符
Remarks must not exceed 100 characters.
Inline
IP query format
请输入单一 IPv4 地址
Enter an individual IPv4 address.
Inline; no query
Reversed dates
开始时间不得晚于结束时间
Start time must not be later than end time.
Inline; no query
Row confirm
确认删除 {IP} 吗？
Delete {IP}?
Modal
Batch confirm
确认删除 N 笔吗？
Delete N records?
Modal
Deletion remarks
请填写删除备注
Enter deletion remarks.
Inline; no deletion
No results
暂无数据
No data available.
Empty list
6.2 Client Notice and
existing actions
Key/scenario
Chinese
English
Presentation/result
block.network_unavailable
当前网络环境异常，无法登录 / 注册，详情请联系客服。
Your network environment is currently unavailable. Please contact customer support.
Modal; title Notice; Chat action; top-right X
Agreement unchecked
请先同意隐私政策
Please agree to the privacy policy
Existing Toast; registration/login not submitted
OTP sent
验证码发送成功
Verification code sent successfully
Existing Toast; no blocklist interception
6.2.1 Modern clients use i18nKey; legacy clients
display message when 4031 is unknown, while blocking still applies.
Notice has no additional salutation. Response includes only
code/i18nKey/neutral message, without IPs, records or reasons.
6.2.2 Close Notice to return to the original form.
The CTA is visually grey but remains clickable for retry; disable
repeated clicks only while the request is loading. Chat uses the
existing support entry. Reuse platform rate limiting. Do not freeze
accounts or add account states based on an IP match.
7. Open points
#
Question
Owner
Deadline
OP-1
ID sequence/digits; reuse existing generation if available
Backend
Before development review
OP-2
Future IPv6 storage length; IPv4 ≤15 characters this phase
Backend
Before future phase
OP-3
Direct-DB performance threshold and timing for cache assessment
Development
Development review
OP-4
Import timeout/commit granularity; >5 minutes without heartbeat
is a suggestion only
