# 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 天窗口 + 分页约束保障查询稳定性。
- 总览聚合在单请求内访问多个数据源，必须提供模块级状态便于前端降级展示与运维定位。