Player Report · 周报与月报 · PRD

作者 Luke　版本 v1.16　日期 2026-09-17　状态 待开发评审　平台 BRAND_A & BRAND_B　类 R

目标：协助菲籍同事按月制作监管 Player Report。读者：菲籍报表人员、后台前端、报表后端与测试；开发与测试以本中文稿为准。

L0 · 先看结论

⓪ 换版差异（开发手上 v1.15 → v1.16）

没有改的：本期注册 cohort、三日 KYC 判定期限、Active、Suspended、Line、测试账号、fake=true 与 Attendance 的业务公式均不变。

只改说明方式的：删除跨报表栏号映射，改由字段名称直接说明计算口径，并在原型说明栏同步显示。

① 一句话需求

Player Report 新增 Weekly、Monthly、Time Period，各人数栏在每个报表周期内按用户账号去重；注册、KYC 与账号状态改按 CMED-EG-1680 定义计算。

② 术语写死表

③ 全局红线表

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

本期做：ReportType 四档、快捷按钮随档切换、周期切分、13 个人数栏按周期去重、对应的 Date 显示，以及 §3 的 16 栏字段定义。

定义优先级：Luke 已确认本版依 CMED-EG-1680 新定义执行。因此，原需求中「既有取数口径不改」「不重定义栏位」「日报数字不变」只保留为历史记录，并由本版覆盖。覆盖范围限于 Registered、Total Registered、Partial / Initial、Active 与年龄档、Inactive、Suspended、Verified；四种 ReportType（含 Daily）统一使用新定义。

明确不做：增加 Quarter、Year、Bi-weekly、Dormant、合计行、筛选项、权限点、提示语、残段标记、导出上限及“Active Total 必须等于年龄分档和”的校验；不改 Tax Report、PlatformReport、代理盈亏、其他报表的 ReportType、二级子表 Forfeited Players 与非实时取数节奏。

1. ReportType 与快捷按钮

适用页面：ReportManagement ▸ Player Report。本文将查询日期栏统一称为 DateRange。

1.1　ReportType 沿用横排 radio，四档同时显示，顺序固定：

Daily → Weekly → Monthly → Time Period

默认选中 Daily，日期默认 Today。Time Period 不切周期；每个 Nationality 在整个查询区间聚合为一行。

1.2　切换 ReportType 时，快捷按钮整组替换：

Time Period 的按钮整组消失，不显示置灰按钮。快捷按钮只填写查询日期，不改变 §2 的周期规则。

切换 ReportType 时，日期重设为该类型第一颗快捷按钮；切到 Time Period 时保留原日期。周／月快捷按钮都填写完整自然周期：This 填当前完整周／月，Last N 填当前周期及前 N-1 个完整周期。区间可含未来日期；未来日期没有资料时计 0。

1.3　变更 ReportType、日期、快捷按钮或其他筛选项，只更新尚未送出的查询条件；表格维持上一次成功查询。按 Search 后才同时套用全部条件并回到第 1 页。Export 一律依据上一次成功查询，不读取尚未送出的修改。

1.4　Date 显示格式：

Time Period 查询单日也保留相同的起止日期，不缩成单一日期。

2. 周期与残段

2.1 周：周一 00:00:00.000 至周日 23:59:59.999，两端都含；不是滚动 7 天，也不是周日起算。

2.2 月：自然月 1 日 00:00:00.000 至最后一日 23:59:59.999；2 月按当年实际天数。

2.3 残段：查询只覆盖某周或某月的一部分时，必须同时满足：

例：Weekly 查询 2026/08/20 ~ 2026/08/23，Date 显示 2026/08/17 ~ 2026/08/23，数字只包含 4 天。

Monthly 查询 2026/06/30 ~ 2026/08/31 时，依新到旧输出三行：

3. 取数口径

3.1 共通基准

• 定义来源：CMED-EG-1680。原型搜索区必须显示 Def by CMED-EG-1680。
• 去重键为用户账号。每一行、每一个人数栏分别去重；不用姓名、手机号或 KYC 资料去重。
• 只统计 player（usertype=0），代理不计。Line 是现行查询条件：选 All 纳入全部 userline，选特定值则只统计该 userline；不得在取数层额外写死 userline=1。正式与测试账号都计入，不以 istester 排除。
• 需求 20 的节点 1（全程免 KYC）与节点 2（提款前才校验 KYC）是现行正常业务分支，不是异常账号排除条件。fake=true 的系统默认 KYC 资料视为尚未提交真实 KYC。
• Nationality：结算时点尚未提交 KYC 的注册账号归 Filipino；已提交 KYC 的账号依申报国籍归 Filipino 或 Non-Filipino。KYC 国籍为前台必填项，未填写不能提交。
• 区间采用左闭右开：开始时间 <= event_time < 结束时间的下一毫秒；沿用平台既有时区。
• 事件型指标读取“有效统计区间”；状态型指标读取“结算时点”。历史报表不得用查询当下的状态代替历史状态。

3.2 现行 16 栏字段表

开发与测试只需按画面表头辨识字段；下表的定义、计算条件与时间口径就是唯一实现依据。本需求不要求另找监管月报截图，也不要求建立另一套栏号与 BO 栏位的映射。

一行＝Nationality × 周期段。GamingVenue 是查询筛选，不是拆行维度；每个指标按用户账号去重。本页没有合计行，因此“合计”均为 —。

3.3 KYC 状态与对账

KYC 只允许四个值：Not Set、Under Review、Rejected、Verified。尚未提交 KYC 的注册账号按 Not Set 计算，并归入 Filipino。

同一当期新注册 cohort、筛选条件与 KYC 判定期限下，必须满足：

Partially / Initially Verified + Fully Verified = Registered Player Counts

Total Registered Players 是截至本行截止时点的累计注册数，不参与当期 03／04 二分。跨月对账时，必须以每个月的注册 cohort 累加 03／04，不能拿单月 03／04 与累计 02 相加或比较。

3.4 账号状态互斥

每个账号依下列顺序判断，命中后停止：

1. 结算时点已冻结：先排除于 Active／Inactive；若冻结事件发生在有效统计区间内，计入当期 Suspended，否则归为「往期冻结存量 C」。
2. 否则，真实 KYC 已通过，或需求 20 当前节点仍有效且 fake=true；有效统计区间内登入过时计 Active。
3. 否则，真实 KYC 未通过且注册满 3 天：Inactive / Deactivated。
4. 其余不进入画面上的三类。

因此同一人不得同时进入 Active、Inactive、当期 Suspended 或「往期冻结存量 C」；画面上的三类相加不一定等于 Total Registered Players。以下两类也会落在“其余”：

• 注册未满 3 天、KYC 尚未通过、未冻结。
• KYC 已通过、期间内未登入、未冻结。

3.5 截止时点与三天宽限期

状态型指标只看本行截止时点，不以查询执行时间或截止后的状态回写历史。Inactive 在 registration_time + 3 days < 本行截止时点 时才算逾期；两者相等时仍在宽限期。Rejected 不提前计入 Inactive。

本段的 03／04 是监管月报编号，不是 Player Report 画面的第 3／4 栏。03／04 只二分本行新增注册 cohort。每个账号的 KYC 判定期限为 min(registration_time + 3 days, 本行截止时点)；在期限内完成并通过 KYC 计 04，否则计 03。月报因此同时具有「当月新注册」范围与「月底截止」限制；月底之后才完成的 KYC 不得回写该月。若账号注册满 3 天的时点早于月底，则以满 3 天时点冻结 03／04 归类。

KYC 在截止边界当刻完成、或冻结状态在边界当刻改变，均归入下一段；同一区间内多次变更只取截止时点最后状态。历史重跑必须读取当时快照。部分周／月也以该残段结束时刻为截止，不等待完整周期结束。

需求 20 已定义两种现行流程：节点 1 全程免 KYC，节点 2 在提交提款前才校验 KYC。这些 player 在 fake=true 期间视为没有真实 KYC：国籍归 Filipino，当期注册 cohort 归 Partially / Initially Verified而非 Fully Verified；只要符合登入／成功金流事件，仍可分别进入 Active Total 与 Attendance。提交真实 KYC 后 fake=false，国籍、KYC 状态与后续 Active 身份就按一般流程判定；03／04 历史 cohort 仍守原判定期限，不因晚到的 KYC 回写。

3.6 年龄分档

只使用玩家提交的真实 KYC 生日，以登入当天的年龄归档。fake=true 的系统默认生日不是真实身份资料，不得用于监管年龄栏；这类玩家可计 Active Total，但在真实 KYC 提交前不进四个年龄档。会员在同一周期跨年龄档且两边都有登入时，可同时进入两个年龄档；Total 仍只计一个账号。因此 Total 与四档之和不必相等。

跨档点只有 30 → 31、40 → 41、50 → 51。Daily 不会跨档；Weekly、Monthly 可能跨档，且 Monthly 较常发生。三个跨档点都使用相同规则。

3.7 数据时间

报表沿用非实时更新节奏。所有状态型字段必须能还原结算时点的 KYC 与冻结状态；若现有资料只能取得当前状态，开发须在开工前提出，不得静默改成当前快照。

本需求的最低取数来源为：会员注册与账号属性、KYC 历程、登录日志、冻结／解冻日志、成功金流／账变明细，以及没收资料。月报人工执行可继续以「会员注册档、登录日志、冻结日志」三份基础档为起点，但涉及 03／04、08 与 Forfeited 的检核，必须再回查对应历程或明细，不得把三份基础档齐全误判成所有指标来源齐全。

4. 页面、排序与导出

4.1　表格为 §3.2 的 16 栏。人数显示整数与千分位；零显示 0，不显示 --。Nationality 维持 Filipino／Non-Filipino 两组，并依 §3.2 分组。

4.2　按周期起始日由新到旧排序；分页沿用现行。

4.3 导出契约：

其余导出行为沿用现行；本需求不新增统一笔数上限。

4.4　GamingVenue、Line、Platform 三个筛选项及 Forfeited Players 二级明细沿用现行；不增加合计行。GamingVenue = All 的语义为“不按实体站过滤”：全部实体站合并统计，每个 Nationality × 周期段 只出一行，第 16 栏显示 All；不得把各实体站逐一列出。选择特定实体站时，第 16 栏显示该站且只统计该站。

5. 权限与提示语

5.1　不新增权限点。四档随 Player Report 查看权限出现，导出沿用既有权限。

5.2　本需求不新增提示语。查询失败、无数据与导出沿用页面既有处理；残段不提示。

原型若呈现查无资料，必须逐字使用：

该文案来自后台通用空态；若线上 Player Report 实测不同，以线上为准并同步修改 PRD 与 HTML。

02 期末在册 = 05 活跃
              + 06 非活跃
              + 07 本月冻结且月底仍冻结
              + A 休眠（已验证、本月未登录、月底未冻结）
              + B 宽限（未验证、注册未满 3 日、月底未冻结）
              + C 往月冻结存量（本月无冻结事件、月底仍冻结）

文档版本：v1.16 | 日期: 2026-09-17 | 作者: Luke | 文档状态：待开发评审

Player Report · Weekly and Monthly Reports · PRD

Author Luke　Version v1.16　Date 2026-09-17　Status Pending Development Review　Platform BRAND_A & BRAND_B　Class R

Goal: Help the Filipino reporting colleague prepare the monthly regulatory Player Report. Audience: Filipino reporting staff, BO frontend, reporting backend, and QA. Development and QA follow the Chinese source PRD.

L0 · Executive Summary

⓪ Version difference (development copy v1.15 → v1.16)

Unchanged: the current registration cohort, three-day KYC deadline, Active, Suspended, Line, test-account, fake=true, and Attendance formulas.

Explanation-only change: removes the cross-report number mapping and explains calculations directly through field names, mirrored in the prototype notes.

① One-sentence requirement

Add Weekly, Monthly, and Time Period to Player Report. Deduplicate every people-count field by user account within each report period, and calculate registration, KYC, and account status using CMED-EG-1680.

② Fixed terminology

③ Global invariants

④ Scope and exclusions

Included: four ReportType values, type-specific shortcuts, period segmentation, period-level deduplication for 13 count fields, matching Date display, and the 16 field definitions in §3.

Definition priority: Luke confirmed this version follows CMED-EG-1680. The original statements “keep existing data definitions,” “do not redefine fields,” and “daily numbers remain unchanged” are historical only and are overridden here for Registered, Total Registered, Partial / Initial, Active and its age bands, Inactive, Suspended, and Verified. All four report types, including Daily, use these definitions.

Excluded: Quarter, Year, Bi-weekly, Dormant, total rows, filters, permissions, copy, partial-period badges, export limits, or a rule forcing Active Total to equal the age-band sum. Do not change Tax Report, PlatformReport, Agent P&L, other reports' ReportType, the Forfeited Players child table, or the non-real-time refresh cadence.

1. ReportType and shortcuts

Page: ReportManagement ▸ Player Report. This document calls the query date field DateRange.

1.1 Keep the horizontal radio layout and display all four options in this fixed order:

Daily → Weekly → Monthly → Time Period

Default to Daily and Today. Time Period does not split periods; each Nationality is aggregated into one row across the entire query range.

1.2 Replace the complete shortcut set when ReportType changes:

For Time Period, remove the entire shortcut set; do not show disabled buttons. Shortcuts only populate dates and do not alter §2.

When switching type, reset dates to that type's first shortcut. When switching to Time Period, retain the existing dates. Weekly/monthly shortcuts use complete calendar periods: This selects the current complete week/month, and Last N selects the current period plus the previous N-1 complete periods. Future dates are allowed; missing future data counts as 0.

1.3 Changing type, dates, shortcuts, or filters only changes pending query criteria. Keep the last successful table until Search is pressed. Search applies all criteria and returns to page 1. Export always uses the last successful query and ignores unsent changes.

1.4 Date formats:

A one-day Time Period query still displays both identical endpoints.

2. Periods and partial periods

2.1 Week: Monday 00:00:00.000 through Sunday 23:59:59.999, inclusive. It is neither a rolling seven-day window nor Sunday-start.

2.2 Month: Calendar day 1 00:00:00.000 through the last day 23:59:59.999; February follows the actual year.

2.3 Partial period: when a query covers only part of a week/month, all rules below apply:

Example: a Weekly query for 2026/08/20 ~ 2026/08/23 displays 2026/08/17 ~ 2026/08/23 and counts four days only.

A Monthly query for 2026/06/30 ~ 2026/08/31 returns three rows, newest first:

3. Data definitions

3.1 Common basis

• Source: CMED-EG-1680. The prototype search area must show Def by CMED-EG-1680 exactly.
• Deduplication key is user account. Deduplicate independently for each row and each count field; never use name, phone, or KYC data.
• Count players only (usertype=0); exclude agents. Line is an existing query filter: All includes every userline, while a selected value includes only that userline. The data layer must not add a hidden userline=1 restriction. Include production and test accounts; do not filter on istester.
• Requirement 20 node 1 (no KYC throughout) and node 2 (KYC checked only before withdrawal) are current valid business branches, not account exclusions. System-default KYC with fake=true means no real KYC has been submitted.
• Nationality: registered accounts without submitted KYC are Filipino; submitted KYC uses declared Filipino or Non-Filipino. Nationality is mandatory before KYC submission.
• Intervals are left-closed and right-open: start_time <= event_time < the millisecond after end_time; use the platform's existing timezone.
• Event metrics use the effective statistical interval. Status metrics use the cutoff time. Historical reports must not replace historical status with current query-time status.

3.2 Current 16-column field table

Development and QA identify fields only by the visible Player Report headers. The definitions, calculations, and time bases below are the sole implementation source. This requirement does not require a separate regulatory-report screenshot or a mapping from another numbering system to BO columns.

One row = Nationality × period segment. GamingVenue is a query filter, not a row-splitting dimension. Deduplicate every metric by user account. This page has no total row, so every Total column below is —.

3.3 KYC statuses and reconciliation

Allowed KYC values: Not Set, Under Review, Rejected, Verified. A registered account without submitted KYC is Not Set and grouped as Filipino.

For the same current-period registration cohort, filters, and KYC decision deadlines:

Partially / Initially Verified + Fully Verified = Registered Player Counts

Total Registered Players is cumulative through row cutoff and is not part of the current-period 03/04 split. Cross-month reconciliation must accumulate monthly 03/04 cohorts; never add or compare one month's 03/04 directly against cumulative 02.

3.4 Mutually exclusive account status

Evaluate each account in order and stop at the first match:

1. Frozen at cutoff → exclude from Active/Inactive first. If a freeze event occurred in the effective interval, count current-period Suspended; otherwise classify as prior-period frozen inventory C.
2. Otherwise, if real KYC is verified, or a Requirement 20 node is currently effective with fake=true, count Active when the account logged in during the effective interval.
3. Otherwise, if real KYC is unverified and registration is over three days old, count Inactive / Deactivated.
4. Otherwise, the account enters none of the three displayed classes.

An account cannot be Active, Inactive, current-period Suspended, and prior-period frozen inventory C at the same time. The three displayed classes need not sum to Total Registered. The remainder also includes accounts under the three-day grace period and verified accounts with no login during the interval, provided they are not frozen.

3.5 Cutoff and three-day grace period

Status metrics use row cutoff only; never rewrite history using query-time or post-cutoff status. An account is overdue for Inactive only when registration_time + 3 days < row cutoff; equality remains inside the grace period. Rejected does not make the account Inactive early.

The 03/04 in this paragraph are regulatory monthly numbers, not BO screen columns 3/4. They partition the current row's registration cohort only. Each account's KYC decision deadline is min(registration_time + 3 days, row cutoff): verification completed and approved by that deadline counts in 04; every other cohort account counts in 03. A monthly report therefore applies both the current-month registration scope and month-end cutoff. KYC completed after month-end never rewrites that month. If the three-day point occurs before month-end, freeze the 03/04 classification at that three-day point.

KYC completion or freeze changes exactly on the cutoff boundary belong to the next segment. Multiple changes inside one interval use the final status at cutoff. Historical reruns must read the historical snapshot. A partial week/month uses the partial segment's end as its cutoff and does not wait for the full period to end.

Requirement 20 defines two current flows: node 1 never requires KYC, and node 2 checks KYC only before withdrawal submission. While fake=true, these players have no real KYC: classify Nationality as Filipino and a current registration cohort account as Partially/Initially Verified rather than Fully Verified. Actual login and successful money-movement events may still place them in Active Total and Attendance. After real KYC is submitted and fake=false, use the normal declared nationality, review state, and Active eligibility. The historical 03/04 cohort remains frozen at its original decision deadline and is not rewritten by late KYC.

3.6 Age bands

Use only the birth date submitted in real KYC and assign age on each login day. A system-default birth date under fake=true is not real identity data and must never feed a regulatory age band; such a player may count in Active Total but enters no age band before real KYC submission. If a member crosses an age band within a period and logs in on both sides, the member enters both bands while Total counts the account once; therefore Total need not equal the four-band sum.

The only transitions are 30 → 31, 40 → 41, and 50 → 51. Daily cannot cross a band; Weekly and Monthly can, with Monthly more common. All three transitions use the same rule.

3.7 Data timing

Keep the report's non-real-time refresh cadence. All status fields must reconstruct KYC and freeze state at cutoff. If the current data model only exposes current status, development must raise this before implementation and must not silently substitute the current snapshot.

Minimum data sources are member registration/account attributes, KYC history, login logs, freeze/unfreeze logs, successful money-movement/ledger details, and forfeiture data. Monthly manual processing may begin with the three base files—member registration, login log, and freeze log—but 03/04, 08, and Forfeited must additionally query their corresponding histories/details. Completeness of the three base files alone must not be treated as completeness for every metric.

4. Page, sorting, and export

4.1 Use the complete 16-column structure in §3.2. Counts are integers with thousands separators; show zero as 0, never --. Keep Filipino and Non-Filipino, grouped per §3.2.

4.2 Sort by period start, newest first. Keep existing pagination.

4.3 Export contract:

All other export behavior remains unchanged. This requirement defines no unified row limit.

4.4 Keep GamingVenue, Line, Platform, and the Forfeited Players child table unchanged. Add no total row. GamingVenue = All means no venue filter: aggregate all venues, return one row per Nationality × period segment, and show All in column 16; never list venues separately. When one venue is selected, show that venue in column 16 and count only that venue.

5. Permissions and copy

5.1 Add no permission. All four types follow existing Player Report view permission; export follows existing permission.

5.2 Add no new copy. Query failure, no data, and export retain existing behavior; partial periods show no notice.

If the prototype shows an empty result, use exactly:

This is the BO-wide empty-state copy. If production Player Report differs, production wins and both PRD and HTML must be updated together.

02 registered at period end = 05 active
                              + 06 inactive
                              + 07 frozen this month and still frozen at month-end
                              + A dormant (verified, no monthly login, not frozen)
                              + B grace (unverified, registered under three days, not frozen)
                              + C prior-period frozen inventory (no current freeze event, still frozen)

Document version: v1.16 | Date: 2026-09-17 | Author: Luke | Status: Pending Development Review

Translation: EN-1.5 | Source: PRD v1.16 | Date: 2026-09-17