# Phase 0 Research - 租户个人中心 API（第一版）

## Decision 1: 接口组织采用“总览聚合 + 明细分页”组合

- **Decision**: 使用 `GET /personal/overview` 提供聚合首屏数据，同时为账单、支付、操作记录、消息等提供独立分页接口。
- **Rationale**: 聚合接口满足首屏加载效率，独立接口避免过度返回，便于分别鉴权、分页和缓存。
- **Alternatives considered**:
  - 单一超大接口一次返回全部数据：实现简单但耦合高、回归风险大。
  - 全拆分接口无聚合：调用次数多，首屏体验差。

## Decision 2: 聚合查询采用“部分失败降级返回”

- **Decision**: 请求语义正确时返回可用模块数据，并在响应中显式标识失败模块、错误码与错误原因。
- **Rationale**: 个人中心是查询场景，部分可用优于整页失败；显式失败标识可避免前端误判空数据。
- **Alternatives considered**:
  - 任一模块失败即整体失败：稳定性差，用户可用性低。
  - 静默置空失败模块：对排障与运营监控不友好。

## Decision 3: 时间范围与分页采用统一默认策略

- **Decision**: 账单/支付/操作记录在未传时间筛选时默认查询最近 90 天；操作记录单次返回默认 50 条且上限 50 条。
- **Rationale**: 兼顾查询性能与业务可用性，满足已确认的产品澄清并降低大租户尾页查询压力。
- **Alternatives considered**:
  - 默认 30 天：可能不足以覆盖常见追溯场景。
  - 默认全量历史：高并发与高数据量下风险高。

## Decision 4: 账单与配额可见范围由租户角色清单配置

- **Decision**: 提供租户级角色清单配置能力，账单/配额查询仅对配置角色开放。
- **Rationale**: 满足不同租户组织结构差异，遵循最小权限原则，减少硬编码角色导致的维护成本。
- **Alternatives considered**:
  - 全员可见：敏感信息暴露面过大。
  - 固定仅管理员可见：灵活性不足，无法适配租户自定义角色模型。

## Decision 5: 安全与审计采用“敏感查询强审计 + 脱敏输出”

- **Decision**: 手机号、邮箱统一脱敏输出；敏感查询记录审计事件（操作者、租户、模块、结果、追踪标识）。
- **Rationale**: 满足商用 SaaS 合规要求，支持事后追溯与安全稽核。
- **Alternatives considered**:
  - 前端脱敏：后端仍可能泄露原始敏感字段。
  - 仅失败请求审计：无法覆盖敏感数据浏览行为追踪。

## Decision 6: 可观测与回滚按发布门禁前置

- **Decision**: 对新增接口输出结构化日志与 OTel 指标/追踪；定义失败率和延迟阈值，触发功能开关回滚。
- **Rationale**: 与宪法“可观测与可回滚”原则对齐，降低首版全量发布风险。
- **Alternatives considered**:
  - 仅记录日志无指标：无法快速发现趋势型故障。
  - 人工回滚无阈值：响应慢且容易扩大故障窗口。

## Research Resolution Summary

- 技术上下文中的不确定项已消解，本阶段无 `NEEDS CLARIFICATION` 遗留项。
- 研究结论已回写到 `plan.md`、`data-model.md` 与 `contracts/openapi.yaml` 的设计约束中。