# 居民业务 API

所有居民业务端点需 Resident 会话，且依据当前有效绑定和目标记录重新授权。下表只给出当前 `app.ts` 注册的分组；带 `:id` 的资源只能访问本人有权记录。

| 模块 | 当前路由 | 说明 |
| --- | --- | --- |
| 通知/活动 | `GET /resident/notices`, `GET /resident/notices/:id`, `PUT /resident/activities/:id/my-registration`, `GET /resident/me/activities` | 已发布且当前小区可见的内容；活动报名/取消受截止期、名额、有效绑定校验。 |
| 门禁 | `GET /resident/access-points`, `POST /resident/access-points/:id/open`，访问记录查询 | 点位按房屋归属过滤；每次开门提交唯一请求 ID。设备离线或返回未知时不能显示为已开门。 |
| 物业账单 | `GET /resident/bills`, `POST /resident/payments`, `GET /resident/payments/:id`, `GET /resident/receipts`, `GET /resident/receipts/:id` | 仅本人有效房屋账单。服务端核算金额；渠道状态以验签回调或认证查单为准。 |
| 订餐 | `/resident/meal-menus`, `/resident/meal-packages/:id`, `/resident/meal-orders` 及单笔订单查询 | 按菜单版本和服务对象校验。重复下单、过期价格或同周冲突由服务端拒绝/返回冲突。 |
| 助浴 | `/resident/bathing/packages`, `/resident/bathing/appointments` 及 appointment 详情/确认/附件读取 | 预约、确认和附件操作遵循服务端状态、关系及附件权限。签名/照片受限。 |
| 报修 | `/resident/repairs`、单号进度、`confirm-completion`、`rating` 等子路径 | 居民仅查询/确认有权订单；工单需业主确认后才可由受派师傅结单。 |
| 陪诊 | `/resident/escort/bookings`（另有兼容 `/resident/escort-bookings`） | 平台只记录预约与交接状态；福行实际履约/收费不在此 API 内。 |
| 保洁 | `GET /cleaning/quote`, `GET /cleaning/schedules`, `GET/POST /resident/cleaning/bookings/:...`、确认完工及完工照片读取 | 报价/时段查询不代表占位；预约、照片确认和完成依版本/所有权校验。 |
| 商店 | `GET /shop/catalog`, `GET /shop/placements/:id/destination` | 服务端重新校验小区与投放状态；跳转不代表已经购买。 |

## 请求示例：居民绑定申请

```http
POST <API_BASE_URL>/resident/bindings
Authorization: Bearer <RESIDENT_SESSION_TOKEN>
Content-Type: application/json

{"houseId":"<TEST_HOUSE_ID>","realName":"<TEST_NAME>","relationType":"OWNER"}
```

路径根据服务实现还可使用社区、楼栋及室号定位；提交字段以实际房屋台账和绑定流程为准。返回值是绑定申请结果，不应自行假定已审核字段。

## 请求示例：活动报名

```http
PUT <API_BASE_URL>/resident/activities/<ACTIVITY_ID>/my-registration
Authorization: Bearer <RESIDENT_SESSION_TOKEN>
Content-Type: application/json

{"status":"ACTIVE","houseId":"<TEST_HOUSE_ID>"}
```

同一状态重复提交幂等；满额并发、报名关闭/过期返回业务错误。取消使用 `status: "CANCELLED"`，开始后不可取消。

## 响应使用注意

居民账单/订单响应可能含个人字段；避免客户端持久化超出当前业务需要的副本。订单详情、照片、收据必须始终通过服务端授权读取。接口未返回的字段不得由前端臆造。