TakeoutSaaS.Prototypes/specs/001-personal-center-api/data-model.md

Data Model - 租户个人中心 API（第一版）

1. Entity Overview

本特性为查询型聚合能力，核心是将多个已有业务实体以“个人中心视图模型”方式输出。

2. Entities

2.1 PersonalOverview

• Description: 个人中心总览聚合结果。
• Fields:
  • requestId (string): 请求追踪标识。
  • overallStatus (enum): success | partial_success | failure。
  • accountProfile (AccountProfile | null)
  • securitySnapshot (SecuritySnapshot | null)
  • roleSummary (RolePermissionSummary | null)
  • tenantAffiliation (TenantAffiliation | null)
  • quotaSummary (QuotaUsageSummary | null)
  • moduleStatuses (ModuleStatus[]): 子模块执行状态集合。

2.2 AccountProfile

• Description: 当前登录用户账号基础信息。
• Fields:
  • userId (string)
  • account (string)
  • displayName (string)
  • avatarUrl (string | null)
  • phoneMasked (string | null)
  • emailMasked (string | null)
  • registeredAt (datetime)

2.3 SecuritySnapshot

• Description: 账号安全状态快照。
• Fields:
  • lastLoginAt (datetime | null)
  • failedLoginCount (int)
  • isLocked (bool)
  • lockedUntil (datetime | null)
  • isForceChangePassword (bool)

2.4 RolePermissionSummary

• Description: 当前用户角色与权限概览。
• Fields:
  • roles (RoleItem[])
  • permissionCount (int)
• RoleItem:
  • roleCode (string)
  • roleName (string)

2.5 TenantAffiliation

• Description: 用户归属与订阅信息。
• Fields:
  • tenantId (string)
  • tenantName (string)
  • merchantId (string)
  • merchantName (string)
  • merchantStatus (string)
  • packageName (string | null)
  • subscriptionExpireAt (datetime | null)

2.6 QuotaUsageSummary

• Description: 配额使用摘要。
• Fields:
  • items (QuotaUsageItem[])
• QuotaUsageItem:
  • quotaCode (string)
  • quotaName (string)
  • limitValue (decimal)
  • usedValue (decimal)
  • unit (string)
  • usageRatio (decimal)

2.7 BillingStatement

• Description: 账单记录。
• Fields:
  • statementId (string)
  • billingPeriodStart (date)
  • billingPeriodEnd (date)
  • amountDue (decimal)
  • amountPaid (decimal)
  • status (enum: pending | partial_paid | paid | overdue | cancelled)
  • dueAt (datetime)

2.8 PaymentRecord

• Description: 支付流水记录。
• Fields:
  • paymentId (string)
  • statementId (string)
  • paidAmount (decimal)
  • paymentMethod (enum: wechat | alipay | bank_transfer | offline)
  • paymentStatus (enum: initiated | success | failed | refunded)
  • paidAt (datetime | null)

2.9 PersonalOperationLog

• Description: 当前用户操作记录。
• Fields:
  • operationId (string)
  • operatorUserId (string)
  • actionType (string)
  • targetType (string)
  • targetId (string | null)
  • isSuccess (bool)
  • occurredAt (datetime)

2.10 PersonalNotification

• Description: 当前用户消息摘要。
• Fields:
  • notificationId (string)
  • title (string)
  • category (string)
  • isRead (bool)
  • sentAt (datetime)

2.11 TenantVisibilityRoleRule

• Description: 租户级账单/配额可见角色规则。
• Fields:
  • tenantId (string) [unique]
  • quotaVisibleRoleCodes (string[])
  • billingVisibleRoleCodes (string[])
  • updatedBy (string)
  • updatedAt (datetime)

2.12 ModuleStatus

• Description: 聚合子模块执行状态。
• Fields:
  • module (string)
  • status (enum: ok | degraded | failed | timeout | skipped)
  • errorCode (string | null)
  • errorMessage (string | null)
  • traceId (string | null)

3. Relationships

• PersonalOverview 1:1 聚合 AccountProfile、SecuritySnapshot、RolePermissionSummary、TenantAffiliation。
• PersonalOverview 1:1 可选聚合 QuotaUsageSummary（可能因权限或降级为空）。
• BillingStatement 1:N PaymentRecord（通过 statementId 关联）。
• TenantVisibilityRoleRule 按 tenantId 管控 QuotaUsageSummary 与 BillingStatement/PaymentRecord 的可见性。
• PersonalOperationLog、PersonalNotification 与当前登录用户 userId 强绑定，不允许跨用户读取。

4. Identity & Uniqueness Rules

• 所有业务主键在 API 层按 string 传输（Snowflake ID）。
• TenantVisibilityRoleRule.tenantId 全局唯一（每租户一份有效规则）。
• 可见角色清单中的 roleCode 必须去重，且必须属于当前租户角色集合。

5. Validation Rules

• 列表查询参数：page >= 1。
• 通用 pageSize：1..50。
• 操作记录查询：默认 pageSize=50，且最大 50。
• 未传 from/to 时默认查询最近 90 天。
• 显式时间窗最大跨度 <= 365 天；超限返回校验错误。
• 手机号、邮箱只输出脱敏值，原始值不得出现在响应体。
• 账单/配额查询需命中租户可见角色清单，否则返回权限不足。

6. Lifecycle / State Transitions

6.1 模块执行状态（请求内）

• 初始：ok（执行成功）
• 异常分支：degraded / failed / timeout / skipped
• 汇总规则：任一模块非 ok 时，overallStatus=partial_success；全部失败且无可用数据时 overallStatus=failure。

6.2 账单状态（只读语义）

• pending -> partial_paid -> paid
• pending -> overdue
• pending -> cancelled

6.3 支付状态（只读语义）

• initiated -> success
• initiated -> failed
• success -> refunded

7. Data Volume Assumptions

• 操作记录和支付记录为高增长数据，默认 90 天窗口 + 分页约束保障查询稳定性。
• 总览聚合在单请求内访问多个数据源，必须提供模块级状态便于前端降级展示与运维定位。