# 员工与后台业务 API

## 员工端

员工端均需 Staff 会话；供应商虽可能通过管理后台应用登录，仍按供应商角色、会话 vendor ID 与授权小区受限。

| 业务 | 路由分组（以 `app.ts` 注册为准） |
| --- | --- |
| 住户审核 | `GET /staff/bindings`, `POST /staff/bindings/:id/review` |
| 工作台 | `GET /staff/workbench`, `GET /staff/my-tasks` |
| 门禁状态 | `GET /staff/access-points` |
| 公告活动名单 | `GET /staff/activities/:id/roster`（不可导出） |
| 助浴 | `/staff/bathing/appointments/...` |
| 维修 | `/staff/repairs/...`；个人任务按员工记录筛选 |
| 保洁 | `/staff/cleaning/...` |
| 订餐与配送 | `/staff/meal-residents`, `/staff/meal-orders`, `/staff/meal-collections`, `/staff/meal-handovers`, `/staff/meal-assignments`, `/staff/meal-deliveries` |
| 提醒 | `GET /staff/reminders` |

每个动作按当前员工、角色、派单关系、小区和工单状态校验。客户端不能以 ID 指定其他员工作为操作人。

## 管理后台

后台需 Admin 会话并按账号角色、模块授权、社区动作和数据归属检查。

| 业务 | 路由分组 |
| --- | --- |
| 账号与供应商 | `/admin/accounts`, `/admin/vendors`, `/admin/vendor-options`, `/admin/audit-logs` |
| 房屋与住户 | `/admin/bindings`, `/admin/houses`, `/admin/feedback` |
| 公告活动 | `/admin/notices`, `/admin/activities/:id/roster`, `/admin/activities/:id/roster-export` |
| 门禁 | `/admin/access-points`, `/admin/access-history`（含查询/导出） |
| 物业收费 | `/admin/fee-rules`, `/admin/bill-imports/preview`, `/admin/bill-imports/:id/confirm`, `/admin/bills`, `/admin/offline-receipts`, `/admin/receipts`, `/admin/reminders`, `/admin/reconciliation/report`, `/admin/reconciliation/export` |
| 订餐 | `/admin/meal-menus`, `/admin/meal-orders`, `/admin/meal-collections`, `/admin/meal-options`, `/admin/meal-settlements` |
| 助浴 | `/admin/bathing/...` |
| 维修 | `/admin/repairs/...`（含派工、回访、统计、导出、公区代表） |
| 保洁 | `/admin/cleaning/...`（catalog、bookings、设置、价格、排期、结算导出） |
| 陪诊交接 | `/admin/escort/handovers`、详情和人工核对 |
| 商店 | `/admin/shop/catalog`, `/admin/shop/placements` |
| 大屏 | `GET /dashboard/communities`, `GET /dashboard/summary` |

非根管理员列表/报表必须显式给目标小区（若端点要求）且只能访问被授权范围。供应商订单摘要不得扩展为联系人/附件/支付凭证查询。

## 请求/响应样例：后台仪表盘

```http
GET <API_BASE_URL>/dashboard/summary?communityId=<COMMUNITY_ID>&from=2026-11-01T00%3A00%3A00%2B08%3A00&to=2026-11-02T00%3A00%3A00%2B08%3A00
Authorization: Bearer <ADMIN_SESSION_TOKEN>
```

```json
{
  "communityId": "<COMMUNITY_ID>",
  "from": "<ISO_TIMESTAMP>",
  "to": "<ISO_TIMESTAMP>",
  "generatedAt": "<ISO_TIMESTAMP>",
  "timeZone": "Asia/Shanghai",
  "blocks": [{"status":"available","visible":true,"metrics":[{"code":"repair.closed","label":"<LABEL>","unit":"<UNIT>","value":0}] }]
}
```

值为脱敏结构示意；目前指标代码包括 `repair.closed`, `meal.delivered_portions`, `bathing.completed`, `escort.handed_over`，以及有来源时的 `cleaning.orders_created`。不可用数据块会使用 `status: "unavailable"`，不能误显示成 0。

## 版本与幂等

账号、公告、账单、订单、派工、结单、照片、结算等写入各有请求字段约定。阅读对应操作函数后再组装请求：不要把 `expectedVersion`、`clientRequestId` 臆加到未要求它们的接口，也不要省略已要求的字段。CSV 导出使用单独端点和权限，不要在前端从所有社区数据拼接导出。