# 前端接入测试环境

## 地址

| 用途 | 地址 |
| --- | --- |
| API Base URL | `https://jinhua.puman.cc/api` |
| 存活检查 | `https://jinhua.puman.cc/api/health` |
| 在线文档 | `https://jinhua.puman.cc/docs/` |
| 逐端点目录 | `https://jinhua.puman.cc/docs/endpoint-catalog.md` |

Base URL 是请求前缀，前端需在其后拼接路径，例如 `/staff/sessions`，不要重复拼接 `/api`。浏览器直接打开 Base URL 会跳转到在线文档；要检查服务，请打开上表的 `/health`。已部署的测试库是独立空库，业务请求需要在受控流程中建立测试账号、小区、房屋及权限；健康检查不代表存在可登录账号。

## 请求约定

1. 登录按作用端使用 `POST /resident/sessions`、`POST /staff/sessions` 或 `POST /admin/sessions`。员工使用手机号和密码，后台使用用户名或手机号及密码，居民使用微信登录 `code`；居民微信登录还依赖正式小程序凭据。
2. 登录成功后保存响应 `token`，后续请求使用 `Authorization: Bearer <token>`。三个作用端的 token 不可互换。有效期以响应 `expiresAt` 为准，退出时调用对应的服务端退出接口。
3. JSON 请求发送 `Content-Type: application/json`。金额使用整数分；带 `clientRequestId` 或 `expectedVersion` 的端点按[共同约定](common.md)处理重试和并发。
4. 按[逐端点目录](endpoint-catalog.md)传参数和处理响应。成功响应并非统一 `{data: ...}` 包装；失败通常是 `{code, message}`。

```sh
curl -i https://jinhua.puman.cc/api/health

# 拿到受控分发的员工测试账号后，将占位符替换为测试值。
curl -i https://jinhua.puman.cc/api/staff/sessions \
  -H 'Content-Type: application/json' \
  --data '{"phone":"<test-phone>","password":"<test-password>"}'

curl -i https://jinhua.puman.cc/api/staff/sessions/me \
  -H 'Authorization: Bearer <staff-token>'
```

网页可直接使用此 HTTPS Base URL。微信小程序发版前须在小程序管理后台将 `demo.puman.cc` 加入合法 request 域名，并用真实 AppID/备案状态完成开发者工具和真机验证；当前文档不代表微信侧配置已完成。支付、银行、门禁、福行和公众号的真实调用条件见[外部能力](integrations.md)。