3.2 KiB
3.2 KiB
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的设计约束中。