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

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

1. 前置条件

• 已切换到分支 001-personal-center-api。
• 本地已准备 TenantApi 运行依赖（PostgreSQL、Redis、配置文件）。
• 具备至少两个测试账号：
  • 账号 A：在账单/配额可见角色清单内。
  • 账号 B：不在账单/配额可见角色清单内。

2. 构建与启动

dotnet build "D:/MsuMshkCode/TakeoutSaaS.TenantApi/TakeoutSaaS.sln"
dotnet run --project "D:/MsuMshkCode/TakeoutSaaS.TenantApi/src/Api/TakeoutSaaS.TenantApi/TakeoutSaaS.TenantApi.csproj"

3. 登录获取 Token

curl -X POST "https://api-tenant-dev.laosankeji.com/api/tenant/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"account":"tenant_admin","password":"your-password"}'

保存响应中的 data.accessToken，后续请求使用：

Authorization: Bearer <accessToken>

4. 核心接口验证

4.1 总览接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/overview" \
  -H "Authorization: Bearer <accessToken>"

预期：

• 返回 success=true。
• data.overallStatus 为 success 或 partial_success。
• data.accountProfile.phoneMasked、data.accountProfile.emailMasked 为脱敏值。
• 若有降级，data.moduleStatuses 包含失败模块与错误码。

4.2 角色权限接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/roles" \
  -H "Authorization: Bearer <accessToken>"

预期：

• 返回角色列表与权限数量。

4.3 配额摘要接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/quota" \
  -H "Authorization: Bearer <accessToken>"

预期：

• 账号 A 返回配额数据。
• 账号 B 返回 403（不在可见角色清单）。

4.4 账单与支付分页接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/billing/statements?page=1&pageSize=20" \
  -H "Authorization: Bearer <accessToken>"

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/billing/payments?page=1&pageSize=20" \
  -H "Authorization: Bearer <accessToken>"

预期：

• 未传 from/to 时默认按最近 90 天查询。
• 数据按时间倒序返回。

4.5 操作记录接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/operations?page=1" \
  -H "Authorization: Bearer <accessToken>"

预期：

• 默认查询最近 90 天。
• 默认 pageSize=50。
• 当传入 pageSize>50 时，返回条数仍不超过 50。

4.6 消息摘要接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/notifications?page=1&pageSize=20" \
  -H "Authorization: Bearer <accessToken>"

预期：

• 无数据时返回空数组而非错误。

4.7 可见角色清单配置接口

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/visibility/roles" \
  -H "Authorization: Bearer <accessToken>"

curl -X PUT "https://api-tenant-dev.laosankeji.com/api/tenant/v1/personal/visibility/roles" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"quotaVisibleRoleCodes":["tenant-owner","finance"],"billingVisibleRoleCodes":["tenant-owner","finance"]}'

预期：

• 更新后再次访问账单/配额接口，权限判定按新清单生效。

5. 回归检查清单

• 现有接口 /api/tenant/v1/auth/profile、/api/tenant/v1/auth/permissions、/api/tenant/v1/merchant/info 行为不变。
• 所有新增接口均要求认证。
• 越权访问返回 403 或 401，且不泄露其他租户数据。
• 响应体不出现未脱敏手机号、邮箱或其他敏感字段。

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/auth/profile" \
  -H "Authorization: Bearer <accessToken>"

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/auth/permissions" \
  -H "Authorization: Bearer <accessToken>"

curl -X GET "https://api-tenant-dev.laosankeji.com/api/tenant/v1/merchant/info" \
  -H "Authorization: Bearer <accessToken>"

6. 可观测性检查

• 每个请求日志中可关联 TraceId / requestId。
• 当模块降级时，日志与指标中可定位失败模块、错误码与耗时。
• 新增接口失败率和耗时可在监控面板中观测。

7. 发布与回滚验证

• 发布后执行第 4 节和第 5 节的全部接口烟测。
• 若出现严重故障，先回滚到上一版本，再复测 /auth/profile、/merchant/info 与 /personal/overview。
• 回滚后重点确认：账单/支付接口仍遵循租户隔离与角色可见性规则。