# 身份、住户与员工管理

## 会话

| 方法 | 路径 | 身份 | 请求/成功响应 |
| --- | --- | --- | --- |
| POST | `/resident/sessions` | 无 | body 接受微信 `code`，可选 `phoneCode`、`name`；返回居民认证结果。没有 `code` 返回 400。正式微信凭据未配置时不可视作可登录测试环境。 |
| GET | `/resident/sessions/me` | Resident | 返回经验证的当前居民会话数据。 |
| POST | `/resident/sessions/logout` | Resident（有效 token） | `{ success: true, message }`；撤销服务端会话。 |
| POST | `/staff/sessions` | 无 | `{ phone, password }`；成功返回 `{ token, clientType:"STAFF", account, jurisdictions, expiresAt }`。 |
| GET | `/staff/sessions/me` | Staff | 当前员工会话。 |
| POST | `/staff/sessions/logout` | Staff | 撤销员工会话。 |
| POST | `/admin/sessions` | 无 | 管理员账号凭据；成功包含 `token`, `clientType:"ADMIN"`, `account`, `permissions`, `jurisdictions`, `expiresAt`。 |
| GET | `/admin/sessions/me` | Admin | 当前后台会话。 |
| POST | `/admin/sessions/logout` | Admin | 撤销后台会话。另兼容 `DELETE /admin/sessions`。 |

**安全提醒：** 不要将真实登录响应复制到日志或文档。不要硬编码 token；token 仅保存在对应作用端的安全会话存储中。

## 居民、绑定与房屋

- `GET/POST /resident/bindings`：当前居民查询/提交本人房屋绑定；提交至少提供 `relationType`，以及 `houseId` 或完整社区/楼栋/室号定位。创建申请由服务端审核，不等于立即获得房屋业务访问权。
- `POST /resident/bindings/:id/unbind`：当前居民申请解绑，可传原因。
- `GET /admin/bindings`、`GET /staff/bindings`：授权员工按状态/范围读取申请；`POST /admin/bindings/:id/review`、`POST /staff/bindings/:id/review`：审核。仅审核权限适用范围内可操作。
- `GET /admin/houses`、`GET /admin/houses/:id/corrections`、房屋更新路由：需 HOUSE_LEDGER/相应社区授权；修改带版本并写审计。以实际字段为准，不要把外部房号当稳定 ID。
- `POST /resident/feedback` 与 `GET /admin/feedback`：居民提交反馈、管理员按权限查看。

## 管理员账号与供应商

- `GET/POST /admin/accounts`：账号列表/创建；`GET/PATCH|PUT|DELETE /admin/accounts/:id` 与 `POST /admin/accounts/:id/status` 管理账号；账号修改要求 `expectedVersion`。`GET/POST/DELETE /admin/accounts/:id/community-permissions` 管理社区动作授权。
- `GET /admin/audit-logs`：授权管理员审计记录查询。
- `/admin/vendors` 的列表/创建/更新/状态变更是根管理员能力；`GET /admin/vendor-options` 需要账号管理权限。停用供应商会撤销关联会话，恢复不使旧 token 复活。

示例（员工登录，仅用虚构占位符）：

```http
POST <API_BASE_URL>/staff/sessions
Content-Type: application/json

{"phone":"<TEST_ACCOUNT_PHONE>","password":"<TEST_PASSWORD>"}
```

响应形状示例（字段值刻意不提供）：

```json
{"token":"<SESSION_TOKEN>","clientType":"STAFF","account":{},"jurisdictions":[],"expiresAt":"<ISO_TIMESTAMP>"}
```

`account` 和 `jurisdictions` 内部字段由当前账号配置决定；请使用实际响应类型，勿按此空对象写字段假设。

## 工作台

- `GET /staff/workbench`、`GET /admin/workbench` 可选 `communityId`（只能缩小授权范围）。响应契约：`{ audience, communities, items, counts, generatedAt }`。工作项包括来源、记录 ID、小区、标题、状态、创建时间和可空链接；跳转后仍需调用业务接口重新鉴权。
- `GET /staff/my-tasks` 等领域待办端点按当前员工和所辖社区过滤。不要通过传入任意员工 ID 请求其他人员工作项。

## 居民收件箱与语音草稿

- `GET /resident/inbox?limit=30&before=<ISO timestamp>` 返回本人 `{ list, total }`，最多 100 条。
- `POST /resident/inbox/:id/read` 首次设置已读时间，重放保持原时间。
- `GET /resident/inbox/:id/delivery-attempts` 返回本人消息触达结果及脱敏错误。
- `POST /resident/voice-drafts` 接受 `clientRequestId`, `intent`, `recognizedText` 及可选 `proposedPayload`；当前为手动整理草稿，不代表语音识别可用。
- `POST /resident/voice-drafts/:id/confirm` 保存确认内容并返回 `requiresManualSubmission: true`；不会代替居民创建业务单。