# API 文档

本目录记录 `services/api/src/app.ts` 当前实际注册的 HTTP JSON API，面向居民小程序、员工小程序和管理后台前端。它不是尚未联调的完整第三方接口规格。接口以代码实际行为为准；规格中仅规划而代码未注册的接口不列为可用。

2026-11-05 测试环境已部署 API、独立 PostgreSQL（66 个迁移）和每分钟社区提醒任务；公网健康检查、数据库认证拒绝及 OSS 合成附件往返已验证。测试库尚无账号和业务数据，真实微信登录、支付、银行、门禁、福行和公众号仍以各自联调结果为准。

## 接入

- 测试环境 Base URL：`https://jinhua.puman.cc/api`，它是接口前缀，浏览器直接打开会跳转文档。例如 `GET https://jinhua.puman.cc/api/health`。服务端同时接受省略内部 `/api` 前缀的路径；前端请统一使用此 Base URL。
- JSON 请求使用 `Content-Type: application/json`。支付回调使用原始请求字节；附件上传端点另见模块章节。
- 居民会话由 `POST /resident/sessions` 建立；员工与后台会话分别用 `POST /staff/sessions`、`POST /admin/sessions`。需认证的请求发送 `Authorization: Bearer <session-token>`；兼容头 `X-Session-Token` 也被服务端识别。三个作用端的会话不能互换。
- 不要在前端日志、URL、错误上报或示例数据中记录 token、密码、手机号、住户资料或附件地址。会话有效期以登录响应的 `expiresAt` 为准；员工/后台代码配置的默认有效期为 24 小时。
- 金额字段以整数分计。时间戳应保留服务端返回的时区/偏移。

## 目录

- [共同约定](common.md)：错误、分页、版本冲突、幂等、安全边界。
- [前端接入](frontend-guide.md)：测试环境地址、认证、请求示例与小程序域名要求。
- [身份、住户与员工管理](identity.md)：登录、绑定、房屋、账号、工作台、消息。
- [居民业务](resident.md)：公告活动、门禁、缴费、订餐、助浴、维修、陪诊、保洁、商店。
- [员工与后台业务](operations.md)：员工工作流、收费、运营、报表、大屏及权限角色。
- [外部能力与限制](integrations.md)：真实支付/门禁/福行/公众号/ASR/对象存储的当前状态。
- [逐端点目录](endpoint-catalog.md)：按实际 method + path 查请求字段、身份与响应形状。
- [契约覆盖情况](coverage.md)：按模块统计尚未细化的 JSON 响应和请求字段。
- [OpenAPI 3.0 文件](openapi.json)：由逐端点目录生成，可导入支持 OpenAPI 的工具。
- [交互式文档站](index.html)：业务分组筛选、参数浏览、Bearer 授权与测试环境在线调试；[文字说明](guide.html)保留。

OpenAPI 直链：`https://jinhua.puman.cc/docs/openapi.json`，可供前端工具按 URL 导入。仓库生成命令：`python3 scripts/generate-api-openapi.py`。当前规范对未在路由层明确声明的字段只提供业务说明，不将其猜测为严格 schema。

每个接口现按中文业务用途展示访问身份、请求字段、成功响应和所属模块规则；支付回调、开门、工单确认等关键写操作另写明幂等、版本或外部结果边界。已从服务端签名核对助浴预约、维修、公区确认人、支付和福行人工核对的关键必填字段。复杂领域 DTO 的内部字段仍需随前后端联调逐项补齐，不能把当前宽松响应 schema 当作完整类型契约。

## 角色与接口路径

路径以下表为索引，详细方法、路径参数、请求和响应以源码分支为准；不是每个规格中拟议路径都已实现。

| 使用者 | 路由分组 |
| --- | --- |
| 公共 | `GET /health`、公开菜谱图片 `GET /uploads/:key`、支付 callback |
| 居民 | `/resident/sessions`、`/resident/bindings`、`/resident/feedback`、`/resident/inbox`、`/resident/voice-drafts`、`/resident/notices`、`/resident/activities`、`/resident/access-*`、`/resident/bills`、`/resident/payments`、`/resident/receipts`、`/resident/meal-*`、`/resident/bathing/*`、`/resident/repairs`、`/resident/escort*`、`/resident/cleaning/*`；`/shop/catalog`、`/shop/placements/:id/destination` |
| 员工 | `/staff/sessions`、`/staff/workbench`、`/staff/bindings`、`/staff/access-*`、`/staff/reminders`、`/staff/activities`、`/staff/bathing/*`、`/staff/repairs`、`/staff/cleaning/*`、`/staff/meal-*` |
| 管理员/供应商 | `/admin/sessions`、`/admin/accounts`、`/admin/vendors`、`/admin/houses`、`/admin/bindings`、`/admin/notices`、`/admin/activities`、`/admin/access-*`、`/admin/bills`、`/admin/reconciliation`、`/admin/meal-*`、`/admin/bathing`、`/admin/repairs`、`/admin/cleaning`、`/admin/escort/handovers`、`/admin/shop`、`/dashboard/*` |

服务端逐请求重新检查会话作用端、角色、授权模块/动作、小区、房屋/订单归属和状态。客户端传入的 ID 用于定位，不构成授权。越权/过期对象在部分居民资源上有意返回 404，以免泄露资源是否存在。

`GET /uploads/:key` 是公开访问的菜谱图片路径，不是私有工单附件接口。私有工单附件使用对应业务下的鉴权端点，详见[逐端点目录](endpoint-catalog.md)。