TakeoutSaaS.Prototypes/specs/001-personal-center-api/spec.md

Feature Specification: 租户个人中心 API（第一版）

Feature Branch: 001-personal-center-api
Created: 2026-02-09
Status: Draft
Input: User description: "我现在要完成这个文档里面的功能 你需要帮我负责实现api部分 D:\MsuMshkCode\personal-center-prd.md"

Clarifications

Session 2026-02-09

• Q: 本次 API 交付范围是否只做 P0，还是覆盖 P0-P2？ → A: 选择 C，首版同批交付 P0 + P1 + P2 全部查询能力。
• Q: 聚合查询在部分子数据源异常时采用何种策略？ → A: 选择 B，全量降级返回可用数据并标记失败部分。
• Q: 账单/支付/操作记录列表在未传时间筛选时默认查询范围是多少？ → A: 选择 B，默认最近 90 天。
• Q: 账单与配额数据在租户内的可见权限如何定义？ → A: 选择 D，由租户自行配置可见角色清单。
• Q: 操作记录单次请求默认返回条数上限是多少？ → A: 选择 B，默认上限 50 条。

User Scenarios & Testing (mandatory)

User Story 1 - 查询个人中心总览 (Priority: P1)

作为租户端已登录用户，我希望一次性看到个人账号、安全状态、角色权限概览和归属信息， 以便快速确认账号可用性与租户/商户状态。

Why this priority: 这是个人中心首屏价值，缺失会导致页面无法可用。

Independent Test: 使用有效租户账号请求总览，返回完整字段且敏感信息脱敏， 不依赖后续账单或日志接口即可单独上线。

Acceptance Scenarios:

1. Given 用户已登录且账号正常，When 请求个人中心总览， Then 返回账号信息、安全信息、角色权限概览和归属信息。
2. Given 用户手机号或邮箱存在，When 请求个人中心总览， Then 返回脱敏后的展示值而不是完整敏感数据。
3. Given 用户尝试访问非本租户数据，When 发起总览查询， Then 系统拒绝请求且不返回任何他租户信息。

---

User Story 2 - 查询套餐配额与账单支付 (Priority: P2)

作为租户端运营人员，我希望查看套餐额度使用和近期账单支付记录， 以便判断续费风险和经营成本。

Why this priority: 该能力直接影响续费、配额预警和日常财务决策。

Independent Test: 在不改动总览接口的情况下，单独查询套餐配额与账单支付列表， 能够独立完成分页浏览和状态判断。

Acceptance Scenarios:

1. Given 租户已有套餐与配额，When 查询套餐配额摘要， Then 返回各配额项上限、已用量和到期相关信息。
2. Given 租户存在历史账单与支付记录，When 按分页查询账单与支付， Then 返回按时间倒序的数据并包含核心状态信息。
3. Given 用户请求超出本租户范围的账单数据，When 发起查询， Then 系统拒绝并记录安全审计事件。
4. Given 用户未传时间筛选条件，When 查询账单或支付记录， Then 系统默认返回最近 90 天的数据。
5. Given 用户角色未包含在租户配置的可见角色清单中，When 查询账单或配额数据， Then 系统拒绝访问并返回权限不足提示。

---

User Story 3 - 查询个人操作记录与消息摘要 (Priority: P3)

作为租户端用户，我希望查看自己的关键操作记录和消息摘要， 以便追溯行为并跟进待处理通知。

Why this priority: 这是增强能力，能提升可追溯性和用户自助排障效率。

Independent Test: 在不依赖前两组接口扩展的前提下，单独查询个人操作记录与消息摘要， 可以独立验证权限范围和空数据处理。

Acceptance Scenarios:

1. Given 当前用户存在历史操作，When 查询个人操作记录， Then 仅返回当前用户可见范围内的记录。
2. Given 当前用户没有消息数据，When 查询消息摘要， Then 返回空列表且不报错。
3. Given 当前用户尝试读取其他用户记录，When 发起请求， Then 系统拒绝并返回明确的权限不足提示。
4. Given 用户未传时间筛选条件，When 查询个人操作记录， Then 系统默认返回最近 90 天的数据。
5. Given 用户未传分页大小或传入过大分页大小，When 查询个人操作记录， Then 系统单次返回条数不超过 50 条。

---

Multi-Project Impact (mandatory)

• Impacted Projects: TenantApi（实现范围）, TenantUI（契约消费与联调范围）
• Primary Contract Surface: 个人中心总览、角色概览、套餐配额、账单支付、操作记录、消息摘要查询接口
• Change Type: Backward compatible（新增查询能力，不破坏现有登录与菜单能力）
• Compatibility Plan: 保留现有可用查询接口与返回口径；新增查询能力在同一版本窗口一次性开放并联调验收
• Rollback Plan: 出现高风险故障时关闭新增能力入口并回退到既有个人信息查询口径

Edge Cases

• 用户账号被锁定、冻结或强制改密时，仍需返回可解释的账号安全状态。
• 用户缺少头像、邮箱或手机号等可选资料时，接口需稳定返回可识别的空值。
• 用户拥有多个角色且权限重叠时，权限概览需去重并保持统计一致。
• 套餐已到期但账单仍有未结项时，账单与套餐状态需可同时展示。
• 大量历史账单或操作记录分页到尾页时，需返回空页而不是异常。
• 通知、操作记录等增强能力暂无数据时，需返回空集合并保证页面可正常渲染。
• 聚合查询中某个子模块异常时，接口需返回其他可用模块，并在响应中标注降级模块与原因。
• 操作记录查询在请求分页大小超过上限时，需按上限 50 条进行约束并保持响应成功。

Requirements (mandatory)

Functional Requirements

• FR-001: 系统 MUST 为已认证租户用户提供个人中心总览查询能力。
• FR-002: 总览结果 MUST 包含我的账号、账号安全、角色权限概览和归属信息四类内容。
• FR-003: 系统 MUST 提供我的角色与权限概览查询，至少包含角色标识和权限数量。
• FR-004: 系统 MUST 提供套餐与配额摘要查询，至少包含每类配额的上限与已用量。
• FR-005: 系统 MUST 提供账单列表查询，支持分页并返回核心账单状态信息。
• FR-006: 系统 MUST 提供支付记录查询，支持分页并返回支付方式、支付状态和支付时间。
• FR-007: 系统 MUST 提供个人操作记录查询，且仅返回当前登录用户可见范围的数据。
• FR-008: 系统 MUST 提供个人消息摘要查询，并在无数据时返回空集合。
• FR-009: 系统 MUST 对手机号和邮箱进行脱敏展示，禁止返回完整敏感值。
• FR-010: 系统 MUST 严禁返回密码哈希、完整敏感审计参数和其他高敏字段。
• FR-011: 所有个人中心查询 MUST 执行租户隔离与用户权限校验，杜绝跨租户访问。
• FR-012: 系统 MUST 为敏感查询行为记录审计事件，支持后续追踪与合规检查。
• FR-013: 系统 MUST 保持现有登录、权限和商户信息相关能力不被本次变更破坏。
• FR-014: 首版发布 MUST 同批交付 P0、P1、P2 所有查询能力，不拆分为多次功能发布。
• FR-015: 当部分子查询失败时，系统 MUST 返回可用数据，并明确标记失败模块及失败原因，禁止无提示静默置空。
• FR-016: 账单、支付、操作记录查询在未显式传入时间条件时 MUST 默认返回最近 90 天数据，并支持自定义时间范围查询。
• FR-017: 账单与配额相关查询 MUST 支持租户级可见角色清单配置，仅配置内角色可访问对应数据。
• FR-018: 个人操作记录查询 MUST 在未指定分页大小时默认返回 50 条，且单次请求返回上限不得超过 50 条。

Key Entities (include if feature involves data)

• PersonalOverview: 个人中心总览聚合对象，承载账号、安全、角色和归属信息。
• AccountProfile: 账号基础信息对象，包含账号标识、昵称、头像、联系方式、注册时间。
• SecuritySnapshot: 账号安全状态对象，包含最近登录、失败次数、锁定状态、改密要求。
• RolePermissionSummary: 角色权限概览对象，包含角色集合与权限数量统计。
• TenantAffiliation: 归属信息对象，包含租户名称、商户名称、商户状态、套餐到期信息。
• QuotaUsageSummary: 配额摘要对象，包含各配额项的上限、已用量与预警状态。
• BillingStatement: 账单对象，包含账单周期、应付/实付金额、账单状态。
• PaymentRecord: 支付记录对象，包含支付方式、支付状态、支付时间与关联账单标识。
• PersonalOperationLog: 个人操作记录对象，包含操作类型、对象、结果和时间。
• PersonalNotification: 个人消息对象，包含消息标题、类型、发送时间与已读状态。

Non-Functional Requirements (mandatory)

• NFR-001: 在正常业务负载下，95% 的个人中心查询请求应在 2 秒内完成。
• NFR-002: 个人中心查询能力月度可用性应不低于 99.9%。
• NFR-003: 核心查询能力（总览、账单、配额）在发布后必须具备可监控性，且可识别失败原因。
• NFR-004: 所有响应必须符合敏感信息脱敏与最小暴露原则。
• NFR-005: 发生发布故障时，新增能力必须可在 10 分钟内回退至稳定状态。
• NFR-006: 当出现部分降级时，95% 的请求应在 2 秒内返回可用数据并附带降级标识。

Scope Boundaries

• 本期发布目标：P0、P1、P2 查询能力一次性交付并完成联调验收。
• 本期包含：个人中心查询类能力（总览、角色概览、套餐配额、账单支付、操作记录、消息摘要）。
• 本期不包含：个人资料编辑、密码修改、头像上传、通知发送策略改造。
• 本期不包含：管理员端个人中心改版与跨端统一消息中心建设。

Assumptions & Dependencies

• 认证体系已能识别当前登录用户和所属租户。
• 租户、商户、账单、支付、日志等数据源可在本期提供稳定查询能力。
• 租户端前端将按新增契约在同一版本窗口完成接入与联调，不采用分阶段隐藏标签策略。
• 消息数据在首版可能为空，空集合被视为有效业务响应。
• 每个租户可维护并生效一份账单/配额可见角色清单，用于查询权限判定。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 试点租户中，至少 95% 的用户可在首次访问时成功看到个人中心核心信息。
• SC-002: 上线后跨租户越权读取事件为 0，且抽检中无敏感字段泄露。
• SC-003: 账单与配额查询场景下，至少 95% 的用户可在 3 秒内获得可用结果。
• SC-004: 上线 30 天内，与“找不到个人账号/安全/套餐信息”相关的工单数量下降 50%。
• SC-005: 首版发布后，个人中心相关请求成功率保持在 99% 及以上（无效认证请求除外）。