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

## 1. 前置条件

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

## 2. 构建与启动

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

## 3. 登录获取 Token

```bash
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`，后续请求使用：

```text
Authorization: Bearer <accessToken>
```

## 4. 核心接口验证

### 4.1 总览接口

```bash
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 角色权限接口

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

预期：
- 返回角色列表与权限数量。

### 4.3 配额摘要接口

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

预期：
- 账号 A 返回配额数据。
- 账号 B 返回 `403`（不在可见角色清单）。

### 4.4 账单与支付分页接口

```bash
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 操作记录接口

```bash
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 消息摘要接口

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

预期：
- 无数据时返回空数组而非错误。

### 4.7 可见角色清单配置接口

```bash
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`，且不泄露其他租户数据。
- 响应体不出现未脱敏手机号、邮箱或其他敏感字段。

```bash
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`。
- 回滚后重点确认：账单/支付接口仍遵循租户隔离与角色可见性规则。