{ "openapi": "3.0.3", "info": { "title": "进华物业一期测试 API", "version": "0.1.0-staging", "description": "由已核对的 HTTP 逐端点目录生成，覆盖现有主业务路由。测试库仅有合成小区、房屋和受限员工账号，尚无居民及真实订单；真实微信登录、支付、银行、门禁、福行、公众号等外部能力仍需凭据和联调。列表/领域对象的内部字段尚未全部建模，未明确字段以实际服务端响应为准。" }, "servers": [ { "url": "https://jinhua.puman.cc/api", "description": "进华内部测试环境" } ], "tags": [ { "name": "住户与房屋", "description": "列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "保洁", "description": "完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "公共接口", "description": "公开资源不含私有工单附件；健康检查只表示 API 进程存活。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "助浴", "description": "照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "助餐与结算", "description": "订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "员工工作台", "description": "待办条目按来源业务模块和小区范围逐条授权。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "居民通用服务", "description": "居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "数据大屏", "description": "只读汇总必须遵守小区范围；统计应能与源业务记录复核。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "物业收费", "description": "金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "社区公告与活动", "description": "居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "社区商店", "description": "目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "维修", "description": "家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "账号与授权", "description": "服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "身份与会话", "description": "三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "门禁", "description": "开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } }, { "name": "陪诊", "description": "福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "externalDocs": { "description": "查看业务说明与调用约定", "url": "https://jinhua.puman.cc/docs/guide.html#common.md" } } ], "paths": { "/health": { "get": { "tags": [ "公共接口" ], "summary": "检查 API 进程存活", "description": "**用途**：检查 API 进程存活。\n\n**访问身份**：无。\n\n**请求**：—。\n\n**成功响应**：健康状态对象（服务端实现返回） 。\n\n**模块规则**：公开资源不含私有工单附件；健康检查只表示 API 进程存活。", "operationId": "get_0bb4da595b0a", "responses": { "200": { "description": "API 进程存活；不代表数据库或外部渠道已通过业务验收。", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service", "version", "uptime", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string", "enum": [ "services-api" ] }, "version": { "type": "string" }, "uptime": { "type": "number", "description": "进程运行秒数。" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/uploads/{key}": { "get": { "tags": [ "公共接口" ], "summary": "读取公开菜谱图片", "description": "**用途**：读取公开菜谱图片。\n\n**访问身份**：无；公开资源。\n\n**请求**：`key` 菜谱图片路径。\n\n**成功响应**：图片字节；公开缓存。仅公开菜单图片，不适用于私有业务附件。 。\n\n**模块规则**：公开资源不含私有工单附件；健康检查只表示 API 进程存活。", "operationId": "get_fb31bf18dac6", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "公开菜谱图片的存储路径；私有附件不可从此接口读取。" } ], "responses": { "200": { "description": "图片字节；公开缓存。仅公开菜单图片，不适用于私有业务附件。 ", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/sessions": { "post": { "tags": [ "身份与会话" ], "summary": "居民微信登录", "description": "**用途**：居民微信登录。\n\n**访问身份**：无。\n\n**请求**：`code` 必填；可选 `phoneCode`, `name`。\n\n**成功响应**：微信居民认证结果（领域 DTO） 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "post_8c6afc1f13ee", "responses": { "200": { "description": "居民微信认证成功，返回会话和当前居民资料。", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "resident", "expiresAt" ], "properties": { "token": { "type": "string", "description": "仅供居民端使用的 Bearer token。" }, "resident": { "$ref": "#/components/schemas/Resident" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "description": "`code` 必填；可选 `phoneCode`, `name`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`code` 必填；可选 `phoneCode`, `name`", "properties": { "code": { "type": "string", "description": "微信小程序登录 code；仅供居民登录使用。" }, "phoneCode": { "type": "string", "description": "phoneCode；`code` 必填；可选 `phoneCode`, `name`" }, "name": { "type": "string", "description": "name；`code` 必填；可选 `phoneCode`, `name`" } }, "required": [ "code" ] } } } } } }, "/resident/sessions/me": { "get": { "tags": [ "身份与会话" ], "summary": "读取当前居民会话", "description": "**用途**：读取当前居民会话。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：当前居民会话数据 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "get_bb724e594f53", "responses": { "200": { "description": "当前居民会话数据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "身份与会话" ], "summary": "居民退出登录", "description": "**用途**：居民退出登录。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：`{ success, message }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "delete_bb724e594f53", "responses": { "200": { "description": "`{ success, message }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "message；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/sessions/logout": { "post": { "tags": [ "身份与会话" ], "summary": "居民退出登录", "description": "**用途**：居民退出登录。\n\n**访问身份**：Resident（若带 token 即撤销）。\n\n**请求**：—。\n\n**成功响应**：`{ success, message }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "post_22bfdfcff9a4", "responses": { "200": { "description": "`{ success, message }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "message；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ {}, { "BearerAuth": [] } ] } }, "/staff/sessions": { "post": { "tags": [ "身份与会话" ], "summary": "员工账号登录", "description": "**用途**：员工账号登录。\n\n**访问身份**：无。\n\n**请求**：`phone`, `password`。\n\n**成功响应**：`{ token, clientType:\"STAFF\", account, jurisdictions, expiresAt }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "post_bb2c946fb7cf", "responses": { "200": { "description": "STAFF 作用端认证成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "clientType", "account", "jurisdictions", "expiresAt" ], "properties": { "token": { "type": "string", "description": "仅供STAFF端使用的 Bearer token。" }, "clientType": { "type": "string", "enum": [ "STAFF" ] }, "account": { "$ref": "#/components/schemas/StaffAccount" }, "jurisdictions": { "type": "array", "items": { "$ref": "#/components/schemas/StaffJurisdiction" } }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "description": "`phone`, `password`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`phone`, `password`", "properties": { "phone": { "type": "string", "description": "手机号；仅在该接口要求时传入。" }, "password": { "type": "string", "description": "账号密码；只放在 HTTPS 请求体，不放 URL 或日志。" } }, "required": [ "password", "phone" ] } } } } } }, "/staff/sessions/me": { "get": { "tags": [ "身份与会话" ], "summary": "读取当前员工会话", "description": "**用途**：读取当前员工会话。\n\n**访问身份**：Staff。\n\n**请求**：—。\n\n**成功响应**：当前员工会话数据 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "get_bd7223dc9c92", "responses": { "200": { "description": "当前员工会话数据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/sessions/logout": { "post": { "tags": [ "身份与会话" ], "summary": "员工退出登录", "description": "**用途**：员工退出登录。\n\n**访问身份**：Staff。\n\n**请求**：—。\n\n**成功响应**：`{ success, message }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "post_9809d690fb16", "responses": { "200": { "description": "`{ success, message }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "message；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/sessions": { "post": { "tags": [ "身份与会话" ], "summary": "后台账号登录", "description": "**用途**：后台账号登录。\n\n**访问身份**：无。\n\n**请求**：`username` 和/或 `phone`（由认证服务判断），`password`。\n\n**成功响应**：`{ token, clientType:\"ADMIN\", account, permissions, jurisdictions, expiresAt }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "post_969a0f671be4", "responses": { "200": { "description": "ADMIN 作用端认证成功。", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "clientType", "account", "jurisdictions", "expiresAt", "permissions" ], "properties": { "token": { "type": "string", "description": "仅供ADMIN端使用的 Bearer token。" }, "clientType": { "type": "string", "enum": [ "ADMIN" ] }, "account": { "$ref": "#/components/schemas/StaffAccount" }, "jurisdictions": { "type": "array", "items": { "$ref": "#/components/schemas/StaffJurisdiction" } }, "expiresAt": { "type": "string", "format": "date-time" }, "permissions": { "type": "array", "items": { "type": "string" } } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "description": "`username` 和/或 `phone`（由认证服务判断），`password`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`username` 和/或 `phone`（由认证服务判断），`password`", "properties": { "username": { "type": "string", "description": "后台账号用户名。" }, "phone": { "type": "string", "description": "手机号；仅在该接口要求时传入。" }, "password": { "type": "string", "description": "账号密码；只放在 HTTPS 请求体，不放 URL 或日志。" } }, "required": [ "password" ] } } } } }, "delete": { "tags": [ "身份与会话" ], "summary": "后台账号退出登录", "description": "**用途**：后台账号退出登录。\n\n**访问身份**：Admin。\n\n**请求**：—。\n\n**成功响应**：`{ success, message }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "delete_969a0f671be4", "responses": { "200": { "description": "`{ success, message }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "message；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/sessions/me": { "get": { "tags": [ "身份与会话" ], "summary": "读取当前后台会话", "description": "**用途**：读取当前后台会话。\n\n**访问身份**：Admin。\n\n**请求**：—。\n\n**成功响应**：当前后台会话数据 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "get_f3242cf28f07", "responses": { "200": { "description": "当前后台会话数据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/sessions/logout": { "post": { "tags": [ "身份与会话" ], "summary": "后台账号退出登录", "description": "**用途**：后台账号退出登录。\n\n**访问身份**：Admin。\n\n**请求**：—。\n\n**成功响应**：`{ success, message }` 。\n\n**模块规则**：三个作用端的令牌不可互用；退出须调用对应端的服务端接口撤销会话。", "operationId": "post_e57ee79cbea2", "responses": { "200": { "description": "`{ success, message }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "message；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/bindings": { "get": { "tags": [ "住户与房屋" ], "summary": "查询本人房屋认证记录", "description": "**用途**：查询本人房屋认证记录。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：`{ list, total }`；list 为本人历次房屋认证记录，含关系、审核状态、房屋展示字段和时间，按创建时间倒序 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。\n\n**本接口注意**：返回当前登录居民的历次房屋认证申请，按创建时间倒序；状态可为待审核、已生效、已拒绝或已撤销，不返回其他居民的绑定。", "operationId": "get_cea7b6328639", "responses": { "200": { "description": "当前居民的房屋认证记录，按申请创建时间倒序。", "content": { "application/json": { "schema": { "type": "object", "required": [ "list", "total" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ResidentBinding" } }, "total": { "type": "integer", "description": "本次返回的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "住户与房屋" ], "summary": "申请绑定房屋", "description": "**用途**：申请绑定房屋。\n\n**访问身份**：Resident。\n\n**请求**：必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`。\n\n**成功响应**：201 房屋认证申请结果 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。\n\n**本接口注意**：relationType 为 OWNER、FAMILY 或 TENANT；须提供房屋 ID，或完整的小区、楼栋及室号定位信息。提交后按审核流程生效。", "operationId": "post_cea7b6328639", "responses": { "201": { "description": "201 房屋认证申请结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`", "properties": { "relationType": { "type": "string", "description": "居民与目标房屋的关系类型，由服务端校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "communityName": { "type": "string", "description": "communityName；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" }, "buildingId": { "type": "string", "description": "buildingId；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" }, "buildingNo": { "type": "string", "description": "buildingNo；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" }, "roomNo": { "type": "string", "description": "roomNo；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" }, "unitNo": { "type": "string", "description": "unitNo；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" }, "realName": { "type": "string", "description": "realName；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" }, "proofMaterialId": { "type": "string", "description": "proofMaterialId；必填 `relationType`；另需 `houseId`，或 `communityId`/`communityName` + `buildingId`/`buildingNo` + `roomNo` 定位房屋；可选 `unitNo`, `realName`, `proofMaterialId`" } }, "required": [ "relationType" ] } } } } } }, "/resident/bindings/{id}/unbind": { "post": { "tags": [ "住户与房屋" ], "summary": "解除本人房屋绑定", "description": "**用途**：解除本人房屋绑定。\n\n**访问身份**：Resident。\n\n**请求**：可选 `reason`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "post_9f9be601d871", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可选 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可选 `reason`", "properties": { "reason": { "type": "string", "description": "reason；可选 `reason`" } } } } } } } }, "/admin/bindings": { "get": { "tags": [ "住户与房屋" ], "summary": "查询住户绑定", "description": "**用途**：查询住户绑定。\n\n**访问身份**：对应后台/员工。\n\n**请求**：可选 `communityId`, `status`, `keyword`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "get_1ea7c3ca564c", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `keyword`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/bindings": { "get": { "tags": [ "住户与房屋" ], "summary": "查询住户绑定", "description": "**用途**：查询住户绑定。\n\n**访问身份**：对应后台/员工。\n\n**请求**：可选 `communityId`, `status`, `keyword`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "get_c485087b4bbe", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `keyword`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bindings/{id}/review": { "post": { "tags": [ "住户与房屋" ], "summary": "审核住户绑定", "description": "**用途**：审核住户绑定。\n\n**访问身份**：对应后台/员工审核权限。\n\n**请求**：`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "post_616f6188110b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`", "properties": { "decision": { "type": "string", "description": "审核或核对决定；仅接受该接口定义的状态值。" }, "reason": { "type": "string", "description": "reason；`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`" } }, "required": [ "decision", "reason" ] } } } } } }, "/staff/bindings/{id}/review": { "post": { "tags": [ "住户与房屋" ], "summary": "审核住户绑定", "description": "**用途**：审核住户绑定。\n\n**访问身份**：对应后台/员工审核权限。\n\n**请求**：`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "post_66d507ea6f67", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`", "properties": { "decision": { "type": "string", "description": "审核或核对决定；仅接受该接口定义的状态值。" }, "reason": { "type": "string", "description": "reason；`decision` 必填 (`APPROVE`/`REJECT`)，可选 `reason`" } }, "required": [ "decision", "reason" ] } } } } } }, "/admin/houses": { "get": { "tags": [ "住户与房屋" ], "summary": "查询房屋台账", "description": "**用途**：查询房屋台账。\n\n**访问身份**：Admin。\n\n**请求**：可选 `communityId`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "get_f1cd9677fe1f", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/houses/{id}": { "patch": { "tags": [ "住户与房屋" ], "summary": "更新房屋台账", "description": "**用途**：更新房屋台账。\n\n**访问身份**：Admin + 台账授权。\n\n**请求**：`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "patch_fe60c0450602", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "properties": { "reason": { "type": "string", "description": "reason；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "buildingId": { "type": "string", "description": "buildingId；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "unitNo": { "type": "string", "description": "unitNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "roomNo": { "type": "string", "description": "roomNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" } }, "required": [ "reason" ] } } } } }, "put": { "tags": [ "住户与房屋" ], "summary": "更新房屋台账", "description": "**用途**：更新房屋台账。\n\n**访问身份**：Admin + 台账授权。\n\n**请求**：`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "put_fe60c0450602", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "properties": { "reason": { "type": "string", "description": "reason；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "buildingId": { "type": "string", "description": "buildingId；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "unitNo": { "type": "string", "description": "unitNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "roomNo": { "type": "string", "description": "roomNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" } }, "required": [ "reason" ] } } } } } }, "/admin/houses/{id}/corrections": { "get": { "tags": [ "住户与房屋" ], "summary": "查看房屋台账", "description": "**用途**：查看房屋台账。\n\n**访问身份**：Admin + 台账授权。\n\n**请求**：—。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "get_8b55804dd3ec", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "住户与房屋" ], "summary": "更正房屋台账", "description": "**用途**：更正房屋台账。\n\n**访问身份**：Admin + 台账授权。\n\n**请求**：`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "post_8b55804dd3ec", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "properties": { "reason": { "type": "string", "description": "reason；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "buildingId": { "type": "string", "description": "buildingId；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "unitNo": { "type": "string", "description": "unitNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "roomNo": { "type": "string", "description": "roomNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" } }, "required": [ "reason" ] } } } } } }, "/admin/houses/{id}/correction": { "get": { "tags": [ "住户与房屋" ], "summary": "查看房屋台账", "description": "**用途**：查看房屋台账。\n\n**访问身份**：Admin + 台账授权。\n\n**请求**：—。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "get_743a3d8193b9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "住户与房屋" ], "summary": "更正房屋台账", "description": "**用途**：更正房屋台账。\n\n**访问身份**：Admin + 台账授权。\n\n**请求**：`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "post_743a3d8193b9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`", "properties": { "reason": { "type": "string", "description": "reason；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "buildingId": { "type": "string", "description": "buildingId；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "unitNo": { "type": "string", "description": "unitNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" }, "roomNo": { "type": "string", "description": "roomNo；`reason` 必填；可传 `buildingId`, `unitNo`, `roomNo`" } }, "required": [ "reason" ] } } } } } }, "/resident/feedback": { "post": { "tags": [ "居民通用服务" ], "summary": "创建居民反馈", "description": "**用途**：创建居民反馈。\n\n**访问身份**：Resident。\n\n**请求**：`communityId`, `content` 必填。\n\n**成功响应**：201 `{ success, ...result }` 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "post_196ffb679967", "responses": { "201": { "description": "201 `{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`communityId`, `content` 必填", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`communityId`, `content` 必填", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "content": { "type": "string", "description": "content；`communityId`, `content` 必填" } }, "required": [ "communityId", "content" ] } } } } } }, "/admin/feedback": { "get": { "tags": [ "居民通用服务" ], "summary": "查询居民反馈", "description": "**用途**：查询居民反馈。\n\n**访问身份**：Admin + 小区 VIEW。\n\n**请求**：`communityId` 必填；可选 `status`, `limit`, `offset`。\n\n**成功响应**：反馈列表 DTO 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "get_d94a90225767", "parameters": [ { "name": "communityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "反馈列表 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/inbox": { "get": { "tags": [ "居民通用服务" ], "summary": "查询站内消息", "description": "**用途**：查询站内消息。\n\n**访问身份**：Resident。\n\n**请求**：可选 `limit`, `before`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "get_4c8f8d331a93", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `limit`, `before`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/inbox/{id}/read": { "post": { "tags": [ "居民通用服务" ], "summary": "标记站内消息已读", "description": "**用途**：标记站内消息已读。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：`{ item }` 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "post_1f1cc2b2ec35", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ item }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "item": { "type": "object", "additionalProperties": true, "description": "item 结构由所属业务接口定义。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/inbox/{id}/delivery-attempts": { "get": { "tags": [ "居民通用服务" ], "summary": "查看站内消息", "description": "**用途**：查看站内消息。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：`{ list }` 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "get_00a7b1db165a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ list }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/voice-drafts": { "post": { "tags": [ "居民通用服务" ], "summary": "创建语音草稿", "description": "**用途**：创建语音草稿。\n\n**访问身份**：Resident。\n\n**请求**：`clientRequestId`, `intent`, `recognizedText`; 可选 `proposedPayload`。\n\n**成功响应**：201 草稿 DTO 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "post_1ed4f4185947", "responses": { "201": { "description": "201 草稿 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`clientRequestId`, `intent`, `recognizedText`; 可选 `proposedPayload`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`clientRequestId`, `intent`, `recognizedText`; 可选 `proposedPayload`", "properties": { "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "intent": { "type": "string", "description": "intent；`clientRequestId`, `intent`, `recognizedText`; 可选 `proposedPayload`" }, "recognizedText": { "type": "string", "description": "recognizedText；`clientRequestId`, `intent`, `recognizedText`; 可选 `proposedPayload`" }, "proposedPayload": { "type": "object", "additionalProperties": true, "description": "proposedPayload；`clientRequestId`, `intent`, `recognizedText`; 可选 `proposedPayload`" } } } } } } } }, "/resident/voice-drafts/{id}/confirm": { "post": { "tags": [ "居民通用服务" ], "summary": "确认语音草稿", "description": "**用途**：确认语音草稿。\n\n**访问身份**：Resident。\n\n**请求**：可选 `confirmedPayload`。\n\n**成功响应**：草稿确认结果；标记 `requiresManualSubmission`，不创建业务订单 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "post_d07c369ae6db", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "草稿确认结果；标记 `requiresManualSubmission`，不创建业务订单 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可选 `confirmedPayload`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可选 `confirmedPayload`", "properties": { "confirmedPayload": { "type": "object", "additionalProperties": true, "description": "confirmedPayload；可选 `confirmedPayload`" } } } } } } } }, "/admin/accounts": { "get": { "tags": [ "账号与授权" ], "summary": "查询员工账号", "description": "**用途**：查询员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：可选 `role`, `status`, `keyword`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "get_a1cfa70d0b35", "parameters": [ { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `role`, `status`, `keyword`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `role`, `status`, `keyword`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "账号与授权" ], "summary": "创建员工账号", "description": "**用途**：创建员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：账号字段由创建服务校验：`username`, `password`, `name`, `phone`, `role` 等。\n\n**成功响应**：201 创建结果 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "post_a1cfa70d0b35", "responses": { "201": { "description": "201 创建结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "账号字段由创建服务校验：`username`, `password`, `name`, `phone`, `role` 等", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "账号字段由创建服务校验：`username`, `password`, `name`, `phone`, `role` 等", "properties": { "username": { "type": "string", "description": "后台账号用户名。" }, "password": { "type": "string", "description": "账号密码；只放在 HTTPS 请求体，不放 URL 或日志。" }, "name": { "type": "string", "description": "name；账号字段由创建服务校验：`username`, `password`, `name`, `phone`, `role` 等" }, "phone": { "type": "string", "description": "手机号；仅在该接口要求时传入。" }, "role": { "type": "string", "description": "role；账号字段由创建服务校验：`username`, `password`, `name`, `phone`, `role` 等" } } } } } } } }, "/admin/accounts/{id}": { "get": { "tags": [ "账号与授权" ], "summary": "查看员工账号", "description": "**用途**：查看员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：—。\n\n**成功响应**：账号对象 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "get_ae995f4b8ad4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "账号对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "账号与授权" ], "summary": "更新员工账号", "description": "**用途**：更新员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`。\n\n**成功响应**：更新账号结果 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "patch_ae995f4b8ad4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新账号结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "name": { "type": "string", "description": "name；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" }, "phone": { "type": "string", "description": "手机号；仅在该接口要求时传入。" }, "permissions": { "type": "array", "items": {}, "description": "permissions；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" }, "jurisdictions": { "type": "array", "items": {}, "description": "jurisdictions；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" }, "modules": { "type": "array", "items": {}, "description": "modules；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" } }, "required": [ "expectedVersion" ] } } } } }, "put": { "tags": [ "账号与授权" ], "summary": "更新员工账号", "description": "**用途**：更新员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`。\n\n**成功响应**：更新账号结果 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "put_ae995f4b8ad4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新账号结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "name": { "type": "string", "description": "name；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" }, "phone": { "type": "string", "description": "手机号；仅在该接口要求时传入。" }, "permissions": { "type": "array", "items": {}, "description": "permissions；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" }, "jurisdictions": { "type": "array", "items": {}, "description": "jurisdictions；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" }, "modules": { "type": "array", "items": {}, "description": "modules；`expectedVersion` 必填；可传 `name`, `phone`, `permissions`, `jurisdictions`, `modules`" } }, "required": [ "expectedVersion" ] } } } } }, "delete": { "tags": [ "账号与授权" ], "summary": "注销员工账号", "description": "**用途**：注销员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：`expectedVersion`, 可选 `reason`。\n\n**成功响应**：`{ success, ...result }` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "delete_ae995f4b8ad4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success, ...result }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`, 可选 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`, 可选 `reason`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "reason": { "type": "string", "description": "reason；`expectedVersion`, 可选 `reason`" } } } } } } } }, "/admin/accounts/{id}/status": { "post": { "tags": [ "账号与授权" ], "summary": "更新员工账号状态", "description": "**用途**：更新员工账号状态。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：`targetStatus` 必须为 `ACTIVE`/`DISABLED`/`DELETED`；`expectedVersion`; 可选 `reason`。\n\n**成功响应**：状态更新结果 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "post_1e0546ed4be1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "状态更新结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`targetStatus` 必须为 `ACTIVE`/`DISABLED`/`DELETED`；`expectedVersion`; 可选 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`targetStatus` 必须为 `ACTIVE`/`DISABLED`/`DELETED`；`expectedVersion`; 可选 `reason`", "properties": { "targetStatus": { "type": "string", "description": "目标状态；服务端检查合法状态流转及操作权限。" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "reason": { "type": "string", "description": "reason；`targetStatus` 必须为 `ACTIVE`/`DISABLED`/`DELETED`；`expectedVersion`; 可选 `reason`" } } } } } } } }, "/admin/accounts/{id}/community-permissions": { "get": { "tags": [ "账号与授权" ], "summary": "查看员工账号", "description": "**用途**：查看员工账号。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：—。\n\n**成功响应**：`{ list }` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "get_7beca47766af", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ list }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "账号与授权" ], "summary": "授予员工小区操作权限", "description": "**用途**：授予员工小区操作权限。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：`communityId`, `permission` 必填。\n\n**成功响应**：`{ success:true, communityId, permission }` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "post_7beca47766af", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success:true, communityId, permission }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "permission": { "type": "string", "description": "permission；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`communityId`, `permission` 必填", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`communityId`, `permission` 必填", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "permission": { "type": "string", "description": "permission；`communityId`, `permission` 必填" } }, "required": [ "communityId", "permission" ] } } } } }, "delete": { "tags": [ "账号与授权" ], "summary": "撤销员工小区操作权限", "description": "**用途**：撤销员工小区操作权限。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：JSON body: `communityId`, `permission` 必填。\n\n**成功响应**：`{ success:true, communityId, permission }` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "delete_7beca47766af", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "`{ success:true, communityId, permission }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "permission": { "type": "string", "description": "permission；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "JSON body: `communityId`, `permission` 必填", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON body: `communityId`, `permission` 必填", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "permission": { "type": "string", "description": "permission；JSON body: `communityId`, `permission` 必填" } }, "required": [ "communityId", "permission" ] } } } } } }, "/admin/audit-logs": { "get": { "tags": [ "居民通用服务" ], "summary": "查询审计记录", "description": "**用途**：查询审计记录。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：可选 `targetAccountId`, `action`, `limit`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "get_b1bb085b9749", "parameters": [ { "name": "targetAccountId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `targetAccountId`, `action`, `limit`" }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `targetAccountId`, `action`, `limit`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/vendors": { "get": { "tags": [ "账号与授权" ], "summary": "查询供应商", "description": "**用途**：查询供应商。\n\n**访问身份**：Root Admin。\n\n**请求**：创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`。\n\n**成功响应**：列表包装 `{list}`；写入 `{vendor}` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "get_30c0334b754a", "parameters": [ { "name": "targetStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标状态；服务端检查合法状态流转及操作权限。" }, { "name": "expectedVersion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } ], "responses": { "200": { "description": "列表包装 `{list}`；写入 `{vendor}` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "账号与授权" ], "summary": "创建供应商", "description": "**用途**：创建供应商。\n\n**访问身份**：Root Admin。\n\n**请求**：创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`。\n\n**成功响应**：列表包装 `{list}`；写入 `{vendor}` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "post_30c0334b754a", "responses": { "200": { "description": "列表包装 `{list}`；写入 `{vendor}` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`", "properties": { "targetStatus": { "type": "string", "description": "目标状态；服务端检查合法状态流转及操作权限。" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } } }, "/admin/vendors/{id}": { "put": { "tags": [ "账号与授权" ], "summary": "更新供应商", "description": "**用途**：更新供应商。\n\n**访问身份**：Root Admin。\n\n**请求**：创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`。\n\n**成功响应**：列表包装 `{list}`；写入 `{vendor}` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "put_08c2cf84d467", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "列表包装 `{list}`；写入 `{vendor}` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`", "properties": { "targetStatus": { "type": "string", "description": "目标状态；服务端检查合法状态流转及操作权限。" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } } }, "/admin/vendors/{id}/status": { "post": { "tags": [ "账号与授权" ], "summary": "更新供应商状态", "description": "**用途**：更新供应商状态。\n\n**访问身份**：Root Admin。\n\n**请求**：创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`。\n\n**成功响应**：列表包装 `{list}`；写入 `{vendor}` 。\n\n**模块规则**：服务端按角色、业务模块、操作权限和小区范围校验；停用账号后旧会话须失效。", "operationId": "post_a1d8cbb051fa", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "列表包装 `{list}`；写入 `{vendor}` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "创建/更新字段由供应商服务校验；状态请求传 `targetStatus`, `expectedVersion`", "properties": { "targetStatus": { "type": "string", "description": "目标状态；服务端检查合法状态流转及操作权限。" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } } }, "/admin/vendor-options": { "get": { "tags": [ "居民通用服务" ], "summary": "查询居民通用服务", "description": "**用途**：查询居民通用服务。\n\n**访问身份**：Admin + 账号管理权限。\n\n**请求**：—。\n\n**成功响应**：`{ list }` 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "get_6bd96293d487", "responses": { "200": { "description": "`{ list }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "string", "description": "当前查询可见范围内的记录。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/workbench": { "get": { "tags": [ "员工工作台" ], "summary": "查询工作台", "description": "**用途**：查询工作台。\n\n**访问身份**：Staff / Admin。\n\n**请求**：可选 `communityId`。\n\n**成功响应**：`{ audience, communities, items, counts, generatedAt }` 。\n\n**模块规则**：待办条目按来源业务模块和小区范围逐条授权。", "operationId": "get_c0921be09ef0", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "`{ audience, communities, items, counts, generatedAt }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "audience": { "type": "string", "description": "audience；具体结构以服务端业务响应为准。" }, "communities": { "type": "string", "description": "communities；具体结构以服务端业务响应为准。" }, "items": { "type": "array", "items": {}, "description": "items；具体结构以服务端业务响应为准。" }, "counts": { "type": "string", "description": "counts；具体结构以服务端业务响应为准。" }, "generatedAt": { "type": "string", "description": "generatedAt；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/workbench": { "get": { "tags": [ "员工工作台" ], "summary": "查询工作台", "description": "**用途**：查询工作台。\n\n**访问身份**：Staff / Admin。\n\n**请求**：可选 `communityId`。\n\n**成功响应**：`{ audience, communities, items, counts, generatedAt }` 。\n\n**模块规则**：待办条目按来源业务模块和小区范围逐条授权。", "operationId": "get_40befa97fa53", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "`{ audience, communities, items, counts, generatedAt }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "audience": { "type": "string", "description": "audience；具体结构以服务端业务响应为准。" }, "communities": { "type": "string", "description": "communities；具体结构以服务端业务响应为准。" }, "items": { "type": "array", "items": {}, "description": "items；具体结构以服务端业务响应为准。" }, "counts": { "type": "string", "description": "counts；具体结构以服务端业务响应为准。" }, "generatedAt": { "type": "string", "description": "generatedAt；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/notices": { "get": { "tags": [ "社区公告与活动" ], "summary": "查询公告", "description": "**用途**：查询公告。\n\n**访问身份**：Admin + 公告授权。\n\n**请求**：可选 `communityId`, `status`, `category`, `limit`, `offset`。\n\n**成功响应**：Notice 查询 DTO 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_f7843e0570d2", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `category`, `limit`, `offset`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "Notice 查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "社区公告与活动" ], "summary": "创建公告", "description": "**用途**：创建公告。\n\n**访问身份**：Admin + 公告 HANDLE。\n\n**请求**：创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`。\n\n**成功响应**：201 公告对象 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "post_f7843e0570d2", "responses": { "201": { "description": "201 公告对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "category": { "type": "string", "description": "category；创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`" }, "title": { "type": "string", "description": "title；创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`" }, "content": { "type": "string", "description": "content；创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`" }, "activity": { "type": "object", "additionalProperties": true, "description": "activity；创建字段含 `communityId`, `category`, `title`, `content`；可选发布字段与 `activity`" } } } } } } } }, "/admin/notices/{id}": { "get": { "tags": [ "社区公告与活动" ], "summary": "查看公告", "description": "**用途**：查看公告。\n\n**访问身份**：Admin + 公告授权。\n\n**请求**：—。\n\n**成功响应**：公告详情 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_d10c74d7b59f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "公告详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "社区公告与活动" ], "summary": "更新公告", "description": "**用途**：更新公告。\n\n**访问身份**：Admin + 公告 HANDLE。\n\n**请求**：`expectedVersion`；可传标题/正文/分类/图/置顶/时间/活动字段。\n\n**成功响应**：更新公告对象 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "patch_d10c74d7b59f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新公告对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`；可传标题/正文/分类/图/置顶/时间/活动字段", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`；可传标题/正文/分类/图/置顶/时间/活动字段", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } }, "put": { "tags": [ "社区公告与活动" ], "summary": "更新公告", "description": "**用途**：更新公告。\n\n**访问身份**：Admin + 公告 HANDLE。\n\n**请求**：`expectedVersion`；可传标题/正文/分类/图/置顶/时间/活动字段。\n\n**成功响应**：更新公告对象 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "put_d10c74d7b59f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新公告对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`；可传标题/正文/分类/图/置顶/时间/活动字段", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`；可传标题/正文/分类/图/置顶/时间/活动字段", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } } }, "/admin/notices/{id}/publish": { "post": { "tags": [ "社区公告与活动" ], "summary": "发布公告", "description": "**用途**：发布公告。\n\n**访问身份**：Admin + 公告 HANDLE。\n\n**请求**：`expectedVersion`，可选 `publishAt`。\n\n**成功响应**：已发布公告 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "post_ac8e6b6d6ec9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "已发布公告 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`，可选 `publishAt`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`，可选 `publishAt`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "publishAt": { "type": "string", "format": "date-time", "description": "publishAt；`expectedVersion`，可选 `publishAt`" } } } } } } } }, "/admin/notices/{id}/revoke": { "post": { "tags": [ "社区公告与活动" ], "summary": "撤下公告", "description": "**用途**：撤下公告。\n\n**访问身份**：Admin + 公告 HANDLE。\n\n**请求**：`expectedVersion`。\n\n**成功响应**：已撤下公告 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "post_c998be683ccd", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "已撤下公告 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } } }, "/admin/notices/{id}/toggle-registration": { "post": { "tags": [ "社区公告与活动" ], "summary": "开启或关闭活动报名", "description": "**用途**：开启或关闭活动报名。\n\n**访问身份**：Admin + 公告 HANDLE。\n\n**请求**：`registrationOpen` 必须是 boolean。\n\n**成功响应**：活动配置 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "post_b34cf3e4eb7e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "活动配置 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`registrationOpen` 必须是 boolean", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`registrationOpen` 必须是 boolean", "properties": { "registrationOpen": { "type": "boolean", "description": "是否开放活动报名。" } } } } } } } }, "/resident/notices": { "get": { "tags": [ "社区公告与活动" ], "summary": "查询公告", "description": "**用途**：查询公告。\n\n**访问身份**：Resident。\n\n**请求**：可选 `communityId`, `category`, `limit`, `offset`。\n\n**成功响应**：居民公告查询 DTO 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_1a853f955d63", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `category`, `limit`, `offset`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "居民公告查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/notices/{id}": { "get": { "tags": [ "社区公告与活动" ], "summary": "查看公告", "description": "**用途**：查看公告。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：公告详情 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_3ca2e05d20ac", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "公告详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/activities/{id}/my-registration": { "put": { "tags": [ "社区公告与活动" ], "summary": "报名或取消活动", "description": "**用途**：报名或取消活动。\n\n**访问身份**：Resident。\n\n**请求**：`status` 必须 `ACTIVE`/`CANCELLED`；报名可传 `houseId`，取消可传 `reason`。\n\n**成功响应**：报名记录 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "put_8223d4f27559", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "报名记录 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`status` 必须 `ACTIVE`/`CANCELLED`；报名可传 `houseId`，取消可传 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`status` 必须 `ACTIVE`/`CANCELLED`；报名可传 `houseId`，取消可传 `reason`", "properties": { "status": { "type": "string", "description": "业务状态；允许值及状态转换由领域服务校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "reason": { "type": "string", "description": "reason；`status` 必须 `ACTIVE`/`CANCELLED`；报名可传 `houseId`，取消可传 `reason`" } } } } } } } }, "/resident/me/activities": { "get": { "tags": [ "社区公告与活动" ], "summary": "查询活动", "description": "**用途**：查询活动。\n\n**访问身份**：Resident。\n\n**请求**：可选 `limit`, `offset`。\n\n**成功响应**：我的活动 DTO 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_948b336320d9", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "我的活动 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/activities/{id}/roster": { "get": { "tags": [ "社区公告与活动" ], "summary": "查询活动报名名单", "description": "**用途**：查询活动报名名单。\n\n**访问身份**：Staff + 名单 VIEW。\n\n**请求**：可选 `status`。\n\n**成功响应**：名单 DTO 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_a40a7fba39ba", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "名单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/activities/{id}/roster": { "get": { "tags": [ "社区公告与活动" ], "summary": "查询活动报名名单", "description": "**用途**：查询活动报名名单。\n\n**访问身份**：Admin + 名单 VIEW。\n\n**请求**：可选 `status`。\n\n**成功响应**：名单 DTO 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_2e648717c9cd", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "名单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/activities/{id}/roster-export": { "get": { "tags": [ "社区公告与活动" ], "summary": "导出活动报名名单", "description": "**用途**：导出活动报名名单。\n\n**访问身份**：Admin + EXPORT。\n\n**请求**：可选 `status`, `format=csv`。\n\n**成功响应**：默认 JSON 导出 DTO；`format=csv` 或 Accept `text/csv` 返回 CSV 字节 。\n\n**模块规则**：居民仅能读取可见公告；活动名额、截止和重复报名由服务端校验。", "operationId": "get_996566013827", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `status`, `format=csv`" } ], "responses": { "200": { "description": "默认 JSON 导出 DTO；`format=csv` 或 Accept `text/csv` 返回 CSV 字节 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/access-points": { "get": { "tags": [ "门禁" ], "summary": "查询门禁点位", "description": "**用途**：查询门禁点位。\n\n**访问身份**：Admin + 社区授权。\n\n**请求**：`communityId` 必填；可选 `limit`, `offset`。\n\n**成功响应**：设备查询 DTO 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "get_c2432cb90e04", "parameters": [ { "name": "communityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "设备查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "门禁" ], "summary": "创建门禁点位", "description": "**用途**：创建门禁点位。\n\n**访问身份**：Admin + 管理权限。\n\n**请求**：body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`。\n\n**成功响应**：201 点位对象 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "post_c2432cb90e04", "responses": { "201": { "description": "201 点位对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "buildingId": { "type": "string", "description": "buildingId；body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`" }, "name": { "type": "string", "description": "name；body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`" }, "doorNo": { "type": "string", "description": "doorNo；body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`" }, "deviceIdentifier": { "type": "string", "description": "deviceIdentifier；body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`" }, "isEnabled": { "type": "boolean", "description": "isEnabled；body 字段：`communityId`, `buildingId`, `name`, `doorNo`, `deviceIdentifier`, `isEnabled`" } } } } } } } }, "/admin/access-points/{id}": { "patch": { "tags": [ "门禁" ], "summary": "更新门禁点位", "description": "**用途**：更新门禁点位。\n\n**访问身份**：Admin + 管理权限。\n\n**请求**：可传 `name`, `doorNo`, `isEnabled`, `buildingId`。\n\n**成功响应**：点位对象 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "patch_63420143a1b5", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "点位对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可传 `name`, `doorNo`, `isEnabled`, `buildingId`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可传 `name`, `doorNo`, `isEnabled`, `buildingId`", "properties": { "name": { "type": "string", "description": "name；可传 `name`, `doorNo`, `isEnabled`, `buildingId`" }, "doorNo": { "type": "string", "description": "doorNo；可传 `name`, `doorNo`, `isEnabled`, `buildingId`" }, "isEnabled": { "type": "boolean", "description": "isEnabled；可传 `name`, `doorNo`, `isEnabled`, `buildingId`" }, "buildingId": { "type": "string", "description": "buildingId；可传 `name`, `doorNo`, `isEnabled`, `buildingId`" } } } } } } } }, "/admin/access-history": { "get": { "tags": [ "门禁" ], "summary": "查询门禁通行记录", "description": "**用途**：查询门禁通行记录。\n\n**访问身份**：Admin + 查询权限。\n\n**请求**：`communityId`；可选时间/关键词/状态/排序/分页字段。\n\n**成功响应**：历史查询 DTO 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "get_80c0dac693bc", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "历史查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/access-history/export": { "get": { "tags": [ "门禁" ], "summary": "导出门禁通行记录", "description": "**用途**：导出门禁通行记录。\n\n**访问身份**：Admin + EXPORT。\n\n**请求**：`communityId`；可选时间/关键词/状态/排序。\n\n**成功响应**：CSV 文件 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "get_b8fc89a2eecc", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "CSV 文件 ", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/access-points": { "get": { "tags": [ "门禁" ], "summary": "查询门禁点位", "description": "**用途**：查询门禁点位。\n\n**访问身份**：Staff + 小区权限。\n\n**请求**：`communityId` 必填；可选分页。\n\n**成功响应**：点位 DTO 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "get_b0a71181e756", "parameters": [ { "name": "communityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "点位 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/access-points": { "get": { "tags": [ "门禁" ], "summary": "查询门禁点位", "description": "**用途**：查询门禁点位。\n\n**访问身份**：Resident。\n\n**请求**：可选 `houseId`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。", "operationId": "get_6f141643a9f6", "parameters": [ { "name": "houseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/access-points/{id}/open": { "post": { "tags": [ "门禁" ], "summary": "请求门禁设备开门", "description": "**用途**：请求门禁设备开门。\n\n**访问身份**：Resident。\n\n**请求**：`houseId` 与 `requestId`（兼容 `clientRequestId`）。\n\n**成功响应**：开门尝试结果 DTO 。\n\n**模块规则**：开门资格取自当前有效房屋绑定与点位范围；设备结果未知时不得显示成功。\n\n**本接口注意**：开门请求需要稳定 requestId；设备超时或结果未知时保留待核实状态，不自动按成功显示。", "operationId": "post_a4ce716a3b0e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "开门尝试结果 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`houseId` 与 `requestId`（兼容 `clientRequestId`）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`houseId` 与 `requestId`（兼容 `clientRequestId`）", "properties": { "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "requestId": { "type": "string", "description": "请求标识；重试时遵守本接口的幂等约束。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } } } } } } } }, "/admin/fee-rules": { "get": { "tags": [ "物业收费" ], "summary": "查询收费规则", "description": "**用途**：查询收费规则。\n\n**访问身份**：Admin + 财务权限。\n\n**请求**：`communityId` 必填。\n\n**成功响应**：费用规则 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_23a4781eb004", "parameters": [ { "name": "communityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "费用规则 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "put": { "tags": [ "物业收费" ], "summary": "更新收费规则", "description": "**用途**：更新收费规则。\n\n**访问身份**：Admin + 财务权限。\n\n**请求**：body: `communityId`, `feeType`, `monthlyAmountCents`, `isEnabled`。\n\n**成功响应**：更新费用规则 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "put_23a4781eb004", "responses": { "200": { "description": "更新费用规则 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `communityId`, `feeType`, `monthlyAmountCents`, `isEnabled`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `feeType`, `monthlyAmountCents`, `isEnabled`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "feeType": { "type": "string", "description": "feeType；body: `communityId`, `feeType`, `monthlyAmountCents`, `isEnabled`" }, "monthlyAmountCents": { "type": "integer", "description": "monthlyAmountCents；body: `communityId`, `feeType`, `monthlyAmountCents`, `isEnabled`" }, "isEnabled": { "type": "boolean", "description": "isEnabled；body: `communityId`, `feeType`, `monthlyAmountCents`, `isEnabled`" } } } } } } } }, "/admin/bill-imports/preview": { "post": { "tags": [ "物业收费" ], "summary": "预览账单导入", "description": "**用途**：预览账单导入。\n\n**访问身份**：Admin + 财务权限。\n\n**请求**：body: `communityId`, `filename`, `rows`。\n\n**成功响应**：导入预览 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "post_f79c4075a579", "responses": { "200": { "description": "导入预览 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `communityId`, `filename`, `rows`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `filename`, `rows`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "filename": { "type": "string", "description": "图片原始文件名，仅作显示与审计。" }, "rows": { "type": "array", "items": {}, "description": "rows；body: `communityId`, `filename`, `rows`" } } } } } } } }, "/admin/bill-imports/{id}/confirm": { "post": { "tags": [ "物业收费" ], "summary": "确认账单导入", "description": "**用途**：确认账单导入。\n\n**访问身份**：Admin + 财务权限。\n\n**请求**：—。\n\n**成功响应**：导入确认 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "post_e09335a59763", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "导入确认 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bills": { "get": { "tags": [ "物业收费" ], "summary": "查询物业账单", "description": "**用途**：查询物业账单。\n\n**访问身份**：Admin + 财务 VIEW。\n\n**请求**：`communityId` 必填；可选 `houseId`, `feeType`, `status`, 分页。\n\n**成功响应**：账单查询 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_a3c369a7c963", "parameters": [ { "name": "communityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "houseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, { "name": "feeType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId` 必填；可选 `houseId`, `feeType`, `status`, 分页" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "账单查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bills/batch-price": { "patch": { "tags": [ "物业收费" ], "summary": "更新物业账单", "description": "**用途**：更新物业账单。\n\n**访问身份**：Admin + 财务 HANDLE。\n\n**请求**：body: `communityId`, `billIds`, `newAmountCents`, `reason`。\n\n**成功响应**：批量更新 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "patch_6e4b4ed95125", "responses": { "200": { "description": "批量更新 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `communityId`, `billIds`, `newAmountCents`, `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `billIds`, `newAmountCents`, `reason`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "billIds": { "type": "array", "items": {}, "description": "本次处理的账单 ID 列表；服务端核对房屋、金额和归属。" }, "newAmountCents": { "type": "integer", "description": "newAmountCents；body: `communityId`, `billIds`, `newAmountCents`, `reason`" }, "reason": { "type": "string", "description": "reason；body: `communityId`, `billIds`, `newAmountCents`, `reason`" } } } } } } } }, "/resident/bills": { "get": { "tags": [ "物业收费" ], "summary": "查询物业账单", "description": "**用途**：查询物业账单。\n\n**访问身份**：Resident。\n\n**请求**：可选 `houseId`, `communityId`, `status`。\n\n**成功响应**：本人账单 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_812d4675e563", "parameters": [ { "name": "houseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "本人账单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/payments": { "post": { "tags": [ "物业收费" ], "summary": "创建物业缴费单并发起渠道支付", "description": "**用途**：创建物业缴费单并发起渠道支付。\n\n**访问身份**：Resident。\n\n**请求**：必填 `houseId`, `billIds`, `clientRequestId`；可选 `channel`（默认 WECHAT）、`expectedTotalAmountCents`, `communityId`。\n\n**成功响应**：201 合并支付单与渠道启动结果 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。\n\n**本接口注意**：只为当前居民有权处理的账单建单；同一请求号重试只应产生一笔有效结果。真实支付渠道未配置时不得呈现支付成功。", "operationId": "post_6fea40e8a1ea", "responses": { "201": { "description": "201 合并支付单与渠道启动结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `houseId`, `billIds`, `clientRequestId`；可选 `channel`（默认 WECHAT）、`expectedTotalAmountCents`, `communityId`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `houseId`, `billIds`, `clientRequestId`；可选 `channel`（默认 WECHAT）、`expectedTotalAmountCents`, `communityId`", "properties": { "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "billIds": { "type": "array", "items": {}, "description": "本次处理的账单 ID 列表；服务端核对房屋、金额和归属。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "channel": { "type": "string", "description": "channel；必填 `houseId`, `billIds`, `clientRequestId`；可选 `channel`（默认 WECHAT）、`expectedTotalAmountCents`, `communityId`" }, "expectedTotalAmountCents": { "type": "integer", "description": "客户端确认的合计金额，单位为分；服务端重新计算并核对。" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } }, "required": [ "houseId", "billIds", "clientRequestId" ] } } } } } }, "/resident/payments/{id}": { "get": { "tags": [ "物业收费" ], "summary": "查看支付单", "description": "**用途**：查看支付单。\n\n**访问身份**：Resident。\n\n**请求**：可选 query `refresh=1` 查渠道。\n\n**成功响应**：支付单；refresh 时附 `reconciliation` 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_0bb8375216e4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "refresh", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 query `refresh=1` 查渠道" } ], "responses": { "200": { "description": "支付单；refresh 时附 `reconciliation` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/callbacks/payments/{channel}": { "post": { "tags": [ "物业收费" ], "summary": "接收支付渠道异步回调", "description": "**用途**：接收支付渠道异步回调。\n\n**访问身份**：渠道回调。\n\n**请求**：原始 request body 必须为 bytes；签名头由 adapter 验证。\n\n**成功响应**：微信成功 `204` 空体；其他已支持渠道返回渠道结果。禁止前端调用。 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。\n\n**本接口注意**：渠道专用服务端入口，使用原始请求字节验签；前端不可调用，也不可模拟回调确认到账。\n\n支付渠道服务端回调，不供前端直接调用。", "operationId": "post_edaca41ae4f8", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" }, "description": "路径参数 channel。" } ], "responses": { "204": { "description": "微信支付回调成功，空响应体" }, "200": { "description": "微信成功 `204` 空体；其他已支持渠道返回渠道结果。禁止前端调用。 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "原始 request body 必须为 bytes；签名头由 adapter 验证", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/admin/offline-receipts": { "post": { "tags": [ "居民通用服务" ], "summary": "创建居民通用服务", "description": "**用途**：创建居民通用服务。\n\n**访问身份**：Admin + 财务 HANDLE。\n\n**请求**：body: `communityId`, `houseId`, `billIds`, `amountCents`, `paymentMethod`, `offlineVoucherNo` 等。\n\n**成功响应**：201 收据结果 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "post_b28f5d5ba48f", "responses": { "201": { "description": "201 收据结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `communityId`, `houseId`, `billIds`, `amountCents`, `paymentMethod`, `offlineVoucherNo` 等", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `houseId`, `billIds`, `amountCents`, `paymentMethod`, `offlineVoucherNo` 等", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "billIds": { "type": "array", "items": {}, "description": "本次处理的账单 ID 列表；服务端核对房屋、金额和归属。" }, "amountCents": { "type": "integer", "description": "人民币金额，单位为分。" }, "paymentMethod": { "type": "string", "description": "paymentMethod；body: `communityId`, `houseId`, `billIds`, `amountCents`, `paymentMethod`, `offlineVoucherNo` 等" }, "offlineVoucherNo": { "type": "string", "description": "offlineVoucherNo；body: `communityId`, `houseId`, `billIds`, `amountCents`, `paymentMethod`, `offlineVoucherNo` 等" } } } } } } } }, "/admin/receipts": { "get": { "tags": [ "物业收费" ], "summary": "查询收据", "description": "**用途**：查询收据。\n\n**访问身份**：Admin + 财务 VIEW。\n\n**请求**：可选 `communityId`, `houseId`, `channel`, `startDate`, `endDate`。\n\n**成功响应**：收据查询 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_4fa8299926bd", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "houseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `houseId`, `channel`, `startDate`, `endDate`" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `houseId`, `channel`, `startDate`, `endDate`" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `houseId`, `channel`, `startDate`, `endDate`" } ], "responses": { "200": { "description": "收据查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/receipts": { "get": { "tags": [ "物业收费" ], "summary": "查询收据", "description": "**用途**：查询收据。\n\n**访问身份**：Resident。\n\n**请求**：列表可选 `houseId`。\n\n**成功响应**：收据 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_8069368849e5", "parameters": [ { "name": "houseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" } ], "responses": { "200": { "description": "收据 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/receipts/{id}": { "get": { "tags": [ "物业收费" ], "summary": "查看收据", "description": "**用途**：查看收据。\n\n**访问身份**：Resident。\n\n**请求**：列表可选 `houseId`。\n\n**成功响应**：收据 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_bd853e312c88", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "houseId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" } ], "responses": { "200": { "description": "收据 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/reminders": { "post": { "tags": [ "物业收费" ], "summary": "创建催缴提醒", "description": "**用途**：创建催缴提醒。\n\n**访问身份**：Admin + 财务 HANDLE。\n\n**请求**：body: `communityId`, `houseId`, `billIds`, `reminderType`, `content`。\n\n**成功响应**：201 提醒结果 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "post_434260fe0261", "responses": { "201": { "description": "201 提醒结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `communityId`, `houseId`, `billIds`, `reminderType`, `content`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `houseId`, `billIds`, `reminderType`, `content`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "billIds": { "type": "array", "items": {}, "description": "本次处理的账单 ID 列表；服务端核对房屋、金额和归属。" }, "reminderType": { "type": "string", "description": "reminderType；body: `communityId`, `houseId`, `billIds`, `reminderType`, `content`" }, "content": { "type": "string", "description": "content；body: `communityId`, `houseId`, `billIds`, `reminderType`, `content`" } } } } } } }, "get": { "tags": [ "物业收费" ], "summary": "查询催缴提醒", "description": "**用途**：查询催缴提醒。\n\n**访问身份**：Admin。\n\n**请求**：可选社区/房屋/日期范围。\n\n**成功响应**：提醒列表 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_434260fe0261", "responses": { "200": { "description": "提醒列表 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/reminders": { "get": { "tags": [ "物业收费" ], "summary": "查询催缴提醒", "description": "**用途**：查询催缴提醒。\n\n**访问身份**：Staff。\n\n**请求**：可选 `communityId`。\n\n**成功响应**：提醒列表 DTO 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_e59984ef2231", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "提醒列表 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/reconciliation/report": { "get": { "tags": [ "物业收费" ], "summary": "查询对账报表", "description": "**用途**：查询对账报表。\n\n**访问身份**：Admin + 财务权限。\n\n**请求**：`communityId`；report 可选 `period`, `channel`, 日期；export 可选 `period`, `channel`。\n\n**成功响应**：报表/导出 DTO（当前路由均 JSON） 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_95384c4bd310", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；report 可选 `period`, `channel`, 日期；export 可选 `period`, `channel`" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；report 可选 `period`, `channel`, 日期；export 可选 `period`, `channel`" } ], "responses": { "200": { "description": "报表/导出 DTO（当前路由均 JSON） ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/reconciliation/export": { "get": { "tags": [ "物业收费" ], "summary": "导出对账报表", "description": "**用途**：导出对账报表。\n\n**访问身份**：Admin + 财务权限。\n\n**请求**：`communityId`；report 可选 `period`, `channel`, 日期；export 可选 `period`, `channel`。\n\n**成功响应**：报表/导出 DTO（当前路由均 JSON） 。\n\n**模块规则**：金额使用整数分；支付与核销需保持幂等，渠道结果未知不能当作已支付。", "operationId": "get_5bb03dc06f6c", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；report 可选 `period`, `channel`, 日期；export 可选 `period`, `channel`" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；report 可选 `period`, `channel`, 日期；export 可选 `period`, `channel`" } ], "responses": { "200": { "description": "报表/导出 DTO（当前路由均 JSON） ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-menus/upload": { "post": { "tags": [ "助餐与结算" ], "summary": "上传助餐菜单图片", "description": "**用途**：上传助餐菜单图片。\n\n**访问身份**：Admin/Supplier + 菜单操作权限。\n\n**请求**：JSON 的 `data` 必填（base64 图片）；可选 `filename`, `contentType`；也可发送原始图片 bytes。\n\n**成功响应**：201 上传结果 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_db653cb28d0d", "responses": { "201": { "description": "201 上传结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "JSON 的 `data` 必填（base64 图片）；可选 `filename`, `contentType`；也可发送原始图片 bytes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON 的 `data` 必填（base64 图片）；可选 `filename`, `contentType`；也可发送原始图片 bytes", "properties": { "data": { "type": "string", "description": "图片内容的 base64 字符串；服务端校验真实图片格式和大小。" }, "filename": { "type": "string", "description": "图片原始文件名，仅作显示与审计。" }, "contentType": { "type": "string", "description": "声明的图片 MIME；服务端还会核对文件内容。" } }, "required": [ "data" ] } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/supplier/meal-menus/upload": { "post": { "tags": [ "助餐与结算" ], "summary": "上传助餐菜单图片", "description": "**用途**：上传助餐菜单图片。\n\n**访问身份**：Admin/Supplier + 菜单操作权限。\n\n**请求**：JSON 的 `data` 必填（base64 图片）；可选 `filename`, `contentType`；也可发送原始图片 bytes。\n\n**成功响应**：201 上传结果 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_9866bdb457c0", "responses": { "201": { "description": "201 上传结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "JSON 的 `data` 必填（base64 图片）；可选 `filename`, `contentType`；也可发送原始图片 bytes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON 的 `data` 必填（base64 图片）；可选 `filename`, `contentType`；也可发送原始图片 bytes", "properties": { "data": { "type": "string", "description": "图片内容的 base64 字符串；服务端校验真实图片格式和大小。" }, "filename": { "type": "string", "description": "图片原始文件名，仅作显示与审计。" }, "contentType": { "type": "string", "description": "声明的图片 MIME；服务端还会核对文件内容。" } }, "required": [ "data" ] } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/admin/meal-menus": { "post": { "tags": [ "助餐与结算" ], "summary": "创建助餐菜单", "description": "**用途**：创建助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）。\n\n**成功响应**：201 草稿 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_bfbf01b6421a", "responses": { "201": { "description": "201 草稿 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）", "properties": { "vendorId": { "type": "string", "description": "vendorId；body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } } } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐菜单", "description": "**用途**：查询助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：可选 `vendorId`, `communityId`, `status`, `year`。\n\n**成功响应**：菜单列表 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_bfbf01b6421a", "parameters": [ { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `vendorId`, `communityId`, `status`, `year`" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "可选 `vendorId`, `communityId`, `status`, `year`" } ], "responses": { "200": { "description": "菜单列表 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/supplier/meal-menus": { "post": { "tags": [ "助餐与结算" ], "summary": "创建助餐菜单", "description": "**用途**：创建助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）。\n\n**成功响应**：201 草稿 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_549a185ee5c9", "responses": { "201": { "description": "201 草稿 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）", "properties": { "vendorId": { "type": "string", "description": "vendorId；body: `vendorId`, `communityId`, 周次、供应日、套餐和照片字段（领域校验）" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } } } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐菜单", "description": "**用途**：查询助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：可选 `vendorId`, `communityId`, `status`, `year`。\n\n**成功响应**：菜单列表 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_549a185ee5c9", "parameters": [ { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `vendorId`, `communityId`, `status`, `year`" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "可选 `vendorId`, `communityId`, `status`, `year`" } ], "responses": { "200": { "description": "菜单列表 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-menus/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐菜单", "description": "**用途**：查看助餐菜单。\n\n**访问身份**：token 可选；领域服务按有/无 token 返回允许内容。\n\n**请求**：—。\n\n**成功响应**：菜单详情 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_d35276755d44", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "菜单详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ {}, { "BearerAuth": [] } ] }, "put": { "tags": [ "助餐与结算" ], "summary": "更新助餐菜单", "description": "**用途**：更新助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：可传 `title`, 日期、供应日、照片、套餐字段。\n\n**成功响应**：更新草稿 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "put_d35276755d44", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新草稿 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可传 `title`, 日期、供应日、照片、套餐字段", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可传 `title`, 日期、供应日、照片、套餐字段", "properties": { "title": { "type": "string", "description": "title；可传 `title`, 日期、供应日、照片、套餐字段" } } } } } } } }, "/supplier/meal-menus/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐菜单", "description": "**用途**：查看助餐菜单。\n\n**访问身份**：token 可选；领域服务按有/无 token 返回允许内容。\n\n**请求**：—。\n\n**成功响应**：菜单详情 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_c226bd671a12", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "菜单详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ {}, { "BearerAuth": [] } ] }, "put": { "tags": [ "助餐与结算" ], "summary": "更新助餐菜单", "description": "**用途**：更新助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：可传 `title`, 日期、供应日、照片、套餐字段。\n\n**成功响应**：更新草稿 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "put_c226bd671a12", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新草稿 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可传 `title`, 日期、供应日、照片、套餐字段", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可传 `title`, 日期、供应日、照片、套餐字段", "properties": { "title": { "type": "string", "description": "title；可传 `title`, 日期、供应日、照片、套餐字段" } } } } } } } }, "/admin/meal-menus/{id}/publish": { "post": { "tags": [ "助餐与结算" ], "summary": "发布助餐菜单", "description": "**用途**：发布助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：—。\n\n**成功响应**：已发布菜单 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_a3eee6b68a05", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "已发布菜单 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/supplier/meal-menus/{id}/publish": { "post": { "tags": [ "助餐与结算" ], "summary": "发布助餐菜单", "description": "**用途**：发布助餐菜单。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：—。\n\n**成功响应**：已发布菜单 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_3bb3dc064a69", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "已发布菜单 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/meal-menus": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐菜单", "description": "**用途**：查询助餐菜单。\n\n**访问身份**：无 Bearer 校验（公开菜单查询）。\n\n**请求**：`communityId`；可选 `startDate`, `limit`。\n\n**成功响应**：菜单 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_85ec7606c948", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `startDate`, `limit`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" } ], "responses": { "200": { "description": "菜单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/meal-menus/current": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐菜单", "description": "**用途**：查询助餐菜单。\n\n**访问身份**：无 Bearer 校验。\n\n**请求**：`communityId`；可选 `date`。\n\n**成功响应**：当前菜单 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_e7f993fc955f", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `date`" } ], "responses": { "200": { "description": "当前菜单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/meal-packages/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐套餐", "description": "**用途**：查看助餐套餐。\n\n**访问身份**：无 Bearer 校验。\n\n**请求**：—。\n\n**成功响应**：套餐详情 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_edd42690117c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "套餐详情 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/meal-orders/quote": { "post": { "tags": [ "助餐与结算" ], "summary": "获取助餐订单报价", "description": "**用途**：获取助餐订单报价。\n\n**访问身份**：无 Bearer 校验。\n\n**请求**：body: `communityId`, `dailyCount`, `weeks`。\n\n**成功响应**：报价 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_5527688dce25", "responses": { "200": { "description": "报价 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "description": "body: `communityId`, `dailyCount`, `weeks`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `dailyCount`, `weeks`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "dailyCount": { "type": "integer", "description": "dailyCount；body: `communityId`, `dailyCount`, `weeks`" }, "weeks": { "type": "integer", "description": "weeks；body: `communityId`, `dailyCount`, `weeks`" } } } } } } } }, "/resident/meal-orders": { "post": { "tags": [ "助餐与结算" ], "summary": "创建助餐订单", "description": "**用途**：创建助餐订单。\n\n**访问身份**：Resident。\n\n**请求**：body: `clientRequestId`, `communityId`, `houseId`, 联系/配送信息、`dailyCount`, `weeks`, `payMethod`, `expectedTotalAmountCents`。\n\n**成功响应**：201 订单 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_9e616f884d78", "responses": { "201": { "description": "201 订单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `clientRequestId`, `communityId`, `houseId`, 联系/配送信息、`dailyCount`, `weeks`, `payMethod`, `expectedTotalAmountCents`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `clientRequestId`, `communityId`, `houseId`, 联系/配送信息、`dailyCount`, `weeks`, `payMethod`, `expectedTotalAmountCents`", "properties": { "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "dailyCount": { "type": "integer", "description": "dailyCount；body: `clientRequestId`, `communityId`, `houseId`, 联系/配送信息、`dailyCount`, `weeks`, `payMethod`, `expectedTotalAmountCents`" }, "weeks": { "type": "integer", "description": "weeks；body: `clientRequestId`, `communityId`, `houseId`, 联系/配送信息、`dailyCount`, `weeks`, `payMethod`, `expectedTotalAmountCents`" }, "payMethod": { "type": "string", "description": "payMethod；body: `clientRequestId`, `communityId`, `houseId`, 联系/配送信息、`dailyCount`, `weeks`, `payMethod`, `expectedTotalAmountCents`" }, "expectedTotalAmountCents": { "type": "integer", "description": "客户端确认的合计金额，单位为分；服务端重新计算并核对。" } } } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐订单", "description": "**用途**：查询助餐订单。\n\n**访问身份**：Resident。\n\n**请求**：列表可选 `communityId`, `status`。\n\n**成功响应**：本人订单 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_9e616f884d78", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "本人订单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/meal-orders/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐订单", "description": "**用途**：查看助餐订单。\n\n**访问身份**：Resident。\n\n**请求**：列表可选 `communityId`, `status`。\n\n**成功响应**：本人订单 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_aa33783f88f9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "本人订单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-residents": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`；可选 `keyword`, `limit`。\n\n**成功响应**：服务对象列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_ea91cae2ad1e", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `keyword`, `limit`" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" } ], "responses": { "200": { "description": "服务对象列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-orders": { "post": { "tags": [ "助餐与结算" ], "summary": "创建助餐订单", "description": "**用途**：创建助餐订单。\n\n**访问身份**：Staff。\n\n**请求**：body: `clientRequestId`, `customerResidentId`, `communityId`, `houseId`, 联系/配送信息、份数周次及支付字段。\n\n**成功响应**：201 代订订单 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_37fc424f7e6f", "responses": { "201": { "description": "201 代订订单 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `clientRequestId`, `customerResidentId`, `communityId`, `houseId`, 联系/配送信息、份数周次及支付字段", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `clientRequestId`, `customerResidentId`, `communityId`, `houseId`, 联系/配送信息、份数周次及支付字段", "properties": { "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "customerResidentId": { "type": "string", "description": "customerResidentId；body: `clientRequestId`, `customerResidentId`, `communityId`, `houseId`, 联系/配送信息、份数周次及支付字段" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" } } } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐订单", "description": "**用途**：查询助餐订单。\n\n**访问身份**：Staff/Admin。\n\n**请求**：列表：`communityId`，可选 `status`, `orderNo`。\n\n**成功响应**：订单查询 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_37fc424f7e6f", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "orderNo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "列表：`communityId`，可选 `status`, `orderNo`" } ], "responses": { "200": { "description": "订单查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/vendor-meal-orders": { "get": { "tags": [ "居民通用服务" ], "summary": "查询居民通用服务", "description": "**用途**：查询居民通用服务。\n\n**访问身份**：Supplier session。\n\n**请求**：可选 `communityId`, `page`, `pageSize`。\n\n**成功响应**：供应商最小订单摘要分页 。\n\n**模块规则**：居民只能读取和操作本人可见记录；通知与第三方触达结果分别留痕。", "operationId": "get_d405aa87cf45", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "可选 `communityId`, `page`, `pageSize`" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "可选 `communityId`, `page`, `pageSize`" } ], "responses": { "200": { "description": "供应商最小订单摘要分页 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-orders": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐订单", "description": "**用途**：查询助餐订单。\n\n**访问身份**：Staff/Admin。\n\n**请求**：列表：`communityId`，可选 `status`, `orderNo`。\n\n**成功响应**：订单查询 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_578f07d96b1f", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "orderNo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "列表：`communityId`，可选 `status`, `orderNo`" } ], "responses": { "200": { "description": "订单查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-orders/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐订单", "description": "**用途**：查看助餐订单。\n\n**访问身份**：Staff/Admin。\n\n**请求**：列表：`communityId`，可选 `status`, `orderNo`。\n\n**成功响应**：订单查询 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_1ce633479d9c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "orderNo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "列表：`communityId`，可选 `status`, `orderNo`" } ], "responses": { "200": { "description": "订单查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-orders/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐订单", "description": "**用途**：查看助餐订单。\n\n**访问身份**：Staff/Admin。\n\n**请求**：列表：`communityId`，可选 `status`, `orderNo`。\n\n**成功响应**：订单查询 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_9c050b5f5e6d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "orderNo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "列表：`communityId`，可选 `status`, `orderNo`" } ], "responses": { "200": { "description": "订单查询 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-collections": { "post": { "tags": [ "助餐与结算" ], "summary": "登记助餐公司实收", "description": "**用途**：登记助餐公司实收。\n\n**访问身份**：Admin/Staff + 收款权限。\n\n**请求**：body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注。\n\n**成功响应**：201 实收凭据 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_50f5502e419d", "responses": { "201": { "description": "201 实收凭据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注", "properties": { "orderId": { "type": "string", "description": "orderId；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "receiptNo": { "type": "string", "description": "receiptNo；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "companyAccount": { "type": "string", "description": "companyAccount；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "payMethod": { "type": "string", "description": "payMethod；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "amountCents": { "type": "integer", "description": "人民币金额，单位为分。" } } } } } } } }, "/staff/meal-collections": { "post": { "tags": [ "助餐与结算" ], "summary": "登记助餐公司实收", "description": "**用途**：登记助餐公司实收。\n\n**访问身份**：Admin/Staff + 收款权限。\n\n**请求**：body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注。\n\n**成功响应**：201 实收凭据 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_9b2fa1b880f3", "responses": { "201": { "description": "201 实收凭据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注", "properties": { "orderId": { "type": "string", "description": "orderId；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "receiptNo": { "type": "string", "description": "receiptNo；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "companyAccount": { "type": "string", "description": "companyAccount；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "payMethod": { "type": "string", "description": "payMethod；body: `orderId`, `receiptNo`, `companyAccount`, `payMethod`, `amountCents`; 可选备注" }, "amountCents": { "type": "integer", "description": "人民币金额，单位为分。" } } } } } } } }, "/staff/meal-vendors": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`。\n\n**成功响应**：供应商列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_4ece4e383be6", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "供应商列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-handovers": { "post": { "tags": [ "助餐与结算" ], "summary": "登记供餐交接", "description": "**用途**：登记供餐交接。\n\n**访问身份**：Staff。\n\n**请求**：body: 小区/供应商/供应日期/批次/应实数量及交接人字段。\n\n**成功响应**：201 交接记录 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_906b411c6ef8", "responses": { "201": { "description": "201 交接记录 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: 小区/供应商/供应日期/批次/应实数量及交接人字段", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: 小区/供应商/供应日期/批次/应实数量及交接人字段" } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询供餐交接", "description": "**用途**：查询供餐交接。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`；可选 `supplyDate`, `vendorId`。\n\n**成功响应**：交接列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_906b411c6ef8", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "supplyDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`；可选 `supplyDate`, `vendorId`" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `supplyDate`, `vendorId`" } ], "responses": { "200": { "description": "交接列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-assignments/preview": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`, `supplyDate`；可选楼栋/单元。\n\n**成功响应**：派单预览 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_4c5b538d897b", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "supplyDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`, `supplyDate`；可选楼栋/单元" } ], "responses": { "200": { "description": "派单预览 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-assignments": { "post": { "tags": [ "助餐与结算" ], "summary": "分配送餐任务", "description": "**用途**：分配送餐任务。\n\n**访问身份**：Staff。\n\n**请求**：body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`。\n\n**成功响应**：201 派单结果 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_b4510d9c3fcf", "responses": { "201": { "description": "201 派单结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "supplyDate": { "type": "string", "format": "date", "description": "supplyDate；body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`" }, "buildingNo": { "type": "string", "description": "buildingNo；body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`" }, "unitNo": { "type": "string", "description": "unitNo；body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`" }, "staffId": { "type": "string", "description": "staffId；body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`" }, "taskVersions": { "type": "array", "items": {}, "description": "taskVersions；body: `communityId`, `supplyDate`, `buildingNo`, `unitNo`, `staffId`, `taskVersions`" } } } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`；可选 `supplyDate`, `staffId`。\n\n**成功响应**：派单列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_b4510d9c3fcf", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "supplyDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`；可选 `supplyDate`, `staffId`" }, { "name": "staffId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `supplyDate`, `staffId`" } ], "responses": { "200": { "description": "派单列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/meal-assignments/{id}/revoke": { "post": { "tags": [ "助餐与结算" ], "summary": "撤销送餐任务分配", "description": "**用途**：撤销送餐任务分配。\n\n**访问身份**：Staff。\n\n**请求**：可选 `reason`。\n\n**成功响应**：撤销结果 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_a50d4abbe8b7", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "撤销结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可选 `reason`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可选 `reason`", "properties": { "reason": { "type": "string", "description": "reason；可选 `reason`" } } } } } } } }, "/staff/meal-deliveries/complete": { "post": { "tags": [ "助餐与结算" ], "summary": "完成助餐与结算", "description": "**用途**：完成助餐与结算。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`, `clientRequestId`, `deliveries`。\n\n**成功响应**：送达批量结果 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_da76f745acab", "responses": { "200": { "description": "送达批量结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`communityId`, `clientRequestId`, `deliveries`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`communityId`, `clientRequestId`, `deliveries`", "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "deliveries": { "type": "array", "items": {}, "description": "deliveries；`communityId`, `clientRequestId`, `deliveries`" } } } } } } } }, "/staff/meal-deliveries": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`；可选供应日期、员工、状态、楼栋/单元。\n\n**成功响应**：配送列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_78884735b7b3", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "配送列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-options": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：`purpose=menus|settlements`；结算可带 `communityId`。\n\n**成功响应**：选项列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_1f80dfbe62ea", "parameters": [ { "name": "purpose", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`purpose=menus|settlements`；结算可带 `communityId`" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "选项列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/supplier/meal-options": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐与结算", "description": "**用途**：查询助餐与结算。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：`purpose=menus|settlements`；结算可带 `communityId`。\n\n**成功响应**：选项列表 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_aa37dbd20784", "parameters": [ { "name": "purpose", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`purpose=menus|settlements`；结算可带 `communityId`" }, { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "选项列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-settlements/preview": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐结算", "description": "**用途**：查询助餐结算。\n\n**访问身份**：Admin + 结算 VIEW。\n\n**请求**：`communityId`, `vendorId`, `periodValue`；可选 `periodType`, `contractVersion`, sample 参数。\n\n**成功响应**：结算预览 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_d53408ab1a78", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `vendorId`, `periodValue`；可选 `periodType`, `contractVersion`, sample 参数" }, { "name": "periodValue", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `vendorId`, `periodValue`；可选 `periodType`, `contractVersion`, sample 参数" }, { "name": "periodType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `vendorId`, `periodValue`；可选 `periodType`, `contractVersion`, sample 参数" }, { "name": "contractVersion", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `vendorId`, `periodValue`；可选 `periodType`, `contractVersion`, sample 参数" } ], "responses": { "200": { "description": "结算预览 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-settlements": { "post": { "tags": [ "助餐与结算" ], "summary": "创建助餐结算", "description": "**用途**：创建助餐结算。\n\n**访问身份**：Admin + 结算 HANDLE。\n\n**请求**：body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`。\n\n**成功响应**：201 结算批次 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "post_065815626f7e", "responses": { "201": { "description": "201 结算批次 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`", "properties": { "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "vendorId": { "type": "string", "description": "vendorId；body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`" }, "periodType": { "type": "string", "description": "periodType；body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`" }, "periodValue": { "type": "string", "description": "periodValue；body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`" }, "contractVersion": { "type": "string", "description": "contractVersion；body: `clientRequestId`, `communityId`, `vendorId`, `periodType`, `periodValue`, `contractVersion`" } } } } } } }, "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐结算", "description": "**用途**：查询助餐结算。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：可选 `communityId`, `vendorId`, `periodType`, `periodValue`。\n\n**成功响应**：结算批次 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_065815626f7e", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`" }, { "name": "periodType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`" }, { "name": "periodValue", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`" } ], "responses": { "200": { "description": "结算批次 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/supplier/meal-settlements": { "get": { "tags": [ "助餐与结算" ], "summary": "查询助餐结算", "description": "**用途**：查询助餐结算。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：可选 `communityId`, `vendorId`, `periodType`, `periodValue`。\n\n**成功响应**：结算批次 DTO 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_7439ed4b3322", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`" }, { "name": "periodType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`" }, { "name": "periodValue", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`" } ], "responses": { "200": { "description": "结算批次 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-settlements/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐结算", "description": "**用途**：查看助餐结算。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：—。\n\n**成功响应**：结算批次详情 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_4ec60f783f37", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "结算批次详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/supplier/meal-settlements/{id}": { "get": { "tags": [ "助餐与结算" ], "summary": "查看助餐结算", "description": "**用途**：查看助餐结算。\n\n**访问身份**：Admin/Supplier。\n\n**请求**：—。\n\n**成功响应**：结算批次详情 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_65b62d845bcd", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "结算批次详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/meal-settlements/export": { "get": { "tags": [ "助餐与结算" ], "summary": "导出助餐结算", "description": "**用途**：导出助餐结算。\n\n**访问身份**：Admin/Supplier + export scope。\n\n**请求**：可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`。\n\n**成功响应**：CSV bytes 或 JSON 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_32581864c339", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "periodType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "periodValue", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" } ], "responses": { "200": { "description": "CSV bytes 或 JSON ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/supplier/meal-settlements/export": { "get": { "tags": [ "助餐与结算" ], "summary": "导出助餐结算", "description": "**用途**：导出助餐结算。\n\n**访问身份**：Admin/Supplier + export scope。\n\n**请求**：可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`。\n\n**成功响应**：CSV bytes 或 JSON 。\n\n**模块规则**：订单、交接、配送和结算分属不同状态；供餐方只读查看本方订单与交接。", "operationId": "get_358024c37265", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "vendorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "periodType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "periodValue", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `vendorId`, `periodType`, `periodValue`, `batchId`, `format=csv|json`" } ], "responses": { "200": { "description": "CSV bytes 或 JSON ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/bathing/packages": { "get": { "tags": [ "助浴" ], "summary": "查询助浴套餐", "description": "**用途**：查询助浴套餐。\n\n**访问身份**：Resident。\n\n**请求**：`communityId`；可选 `targetDate`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_458b59a5abb9", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "targetDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`；可选 `targetDate`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/bathing/appointments": { "get": { "tags": [ "助浴" ], "summary": "查询助浴预约", "description": "**用途**：查询助浴预约。\n\n**访问身份**：Resident。\n\n**请求**：可选 `communityId`, `status`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_c076ba9cb97c", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "助浴" ], "summary": "创建助浴预约", "description": "**用途**：创建助浴预约。\n\n**访问身份**：Resident。\n\n**请求**：必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`。\n\n**成功响应**：201 预约对象 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_c076ba9cb97c", "responses": { "201": { "description": "201 预约对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`", "properties": { "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "packageCode": { "type": "string", "description": "packageCode；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "serviceDate": { "type": "string", "format": "date", "description": "serviceDate；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "timeSlot": { "type": "string", "description": "timeSlot；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "expectedPackageVersion": { "type": "integer", "description": "下单前读取的套餐版本；变更时须重新确认报价。" }, "expectedPriceCents": { "type": "integer", "description": "下单时确认的套餐价格，单位为分。" }, "isProxyBooking": { "type": "boolean", "description": "是否由家属代约；代约时需提供实际受益人信息。" }, "beneficiaryName": { "type": "string", "description": "beneficiaryName；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "beneficiaryPhone": { "type": "string", "description": "beneficiaryPhone；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "proxyRelationship": { "type": "string", "description": "proxyRelationship；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "elderCondition": { "type": "string", "description": "elderCondition；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" }, "specialNotes": { "type": "string", "description": "specialNotes；必填 `clientRequestId`, `communityId`, `houseId`, `packageCode`, `serviceDate`, `timeSlot`, `expectedPackageVersion`, `expectedPriceCents`；代约可传 `isProxyBooking`, `beneficiaryName`, `beneficiaryPhone`, `proxyRelationship`, `elderCondition`, `specialNotes`" } }, "required": [ "clientRequestId", "communityId", "houseId", "packageCode", "serviceDate", "timeSlot", "expectedPackageVersion", "expectedPriceCents" ] } } } } } }, "/resident/bathing/appointments/{id}": { "get": { "tags": [ "助浴" ], "summary": "查看助浴预约", "description": "**用途**：查看助浴预约。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：预约详情 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_c73aae914b84", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "预约详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/bathing/appointments/{id}/confirm": { "post": { "tags": [ "助浴" ], "summary": "确认助浴预约", "description": "**用途**：确认助浴预约。\n\n**访问身份**：Resident + 合法确认人。\n\n**请求**：可选 `rating`（1–5 星）、`feedbackNotes`, `clientRequestId`；服务端验证确认人和订单状态。\n\n**成功响应**：确认结果 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_dae291f36da4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "确认结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可选 `rating`（1–5 星）、`feedbackNotes`, `clientRequestId`；服务端验证确认人和订单状态", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可选 `rating`（1–5 星）、`feedbackNotes`, `clientRequestId`；服务端验证确认人和订单状态", "properties": { "rating": { "type": "integer", "description": "rating；可选 `rating`（1–5 星）、`feedbackNotes`, `clientRequestId`；服务端验证确认人和订单状态" }, "feedbackNotes": { "type": "string", "description": "feedbackNotes；可选 `rating`（1–5 星）、`feedbackNotes`, `clientRequestId`；服务端验证确认人和订单状态" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } } } } } } } }, "/resident/bathing/appointments/{id}/attachments/{attachmentId}": { "get": { "tags": [ "助浴" ], "summary": "下载助浴预约私有附件", "description": "**用途**：下载助浴预约私有附件。\n\n**访问身份**：Resident + 附件授权。\n\n**请求**：—。\n\n**成功响应**：私有图片 bytes，`no-store` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_4e417f38a50e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "订单内的附件 ID；下载时仍需订单归属和读取权限。" } ], "responses": { "200": { "description": "私有图片 bytes，`no-store` ", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/bathing/appointments": { "get": { "tags": [ "助浴" ], "summary": "查询助浴预约", "description": "**用途**：查询助浴预约。\n\n**访问身份**：Staff。\n\n**请求**：可选社区/状态/服务日/被派员工。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_9f629d37e7c5", "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/bathing/appointments/{id}": { "get": { "tags": [ "助浴" ], "summary": "查看助浴预约", "description": "**用途**：查看助浴预约。\n\n**访问身份**：Staff。\n\n**请求**：—。\n\n**成功响应**：预约详情 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_6e287a86a5d9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "预约详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/bathing/appointments/{id}/check-in": { "post": { "tags": [ "助浴" ], "summary": "助浴预约到场打卡", "description": "**用途**：助浴预约到场打卡。\n\n**访问身份**：当前受派 Staff。\n\n**请求**：必填 `latitude`, `longitude`；可选 `address`, `clientRequestId`。\n\n**成功响应**：打卡结果 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_bbc4d781d567", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "打卡结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `latitude`, `longitude`；可选 `address`, `clientRequestId`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `latitude`, `longitude`；可选 `address`, `clientRequestId`", "properties": { "latitude": { "type": "number", "description": "到场定位纬度。" }, "longitude": { "type": "number", "description": "到场定位经度。" }, "address": { "type": "string", "description": "address；必填 `latitude`, `longitude`；可选 `address`, `clientRequestId`" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } }, "required": [ "latitude", "longitude" ] } } } } } }, "/staff/bathing/appointments/{id}/attachments": { "post": { "tags": [ "助浴" ], "summary": "创建助浴预约", "description": "**用途**：创建助浴预约。\n\n**访问身份**：当前受派 Staff。\n\n**请求**：JSON body 的 `data` 为 base64 图片；可传 `filename`/`fileName`, `contentType`/`mimeType`, `clientRequestId`；也可发送原始图片 bytes。\n\n**成功响应**：201 附件引用（不返回对象 URL） 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_c83f5e03443a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "201": { "description": "201 附件引用（不返回对象 URL） ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "JSON body 的 `data` 为 base64 图片；可传 `filename`/`fileName`, `contentType`/`mimeType`, `clientRequestId`；也可发送原始图片 bytes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON body 的 `data` 为 base64 图片；可传 `filename`/`fileName`, `contentType`/`mimeType`, `clientRequestId`；也可发送原始图片 bytes", "properties": { "data": { "type": "string", "description": "图片内容的 base64 字符串；服务端校验真实图片格式和大小。" }, "filename": { "type": "string", "description": "图片原始文件名，仅作显示与审计。" }, "fileName": { "type": "string", "description": "图片原始文件名的兼容字段。" }, "contentType": { "type": "string", "description": "声明的图片 MIME；服务端还会核对文件内容。" }, "mimeType": { "type": "string", "description": "声明的图片 MIME；服务端还会核对文件内容。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } }, "required": [ "data" ] } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/staff/bathing/appointments/{id}/attachments/{attachmentId}": { "get": { "tags": [ "助浴" ], "summary": "下载助浴预约私有附件", "description": "**用途**：下载助浴预约私有附件。\n\n**访问身份**：Staff + 附件授权。\n\n**请求**：—。\n\n**成功响应**：私有图片 bytes，`no-store` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_cfd81c2cbc51", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "订单内的附件 ID；下载时仍需订单归属和读取权限。" } ], "responses": { "200": { "description": "私有图片 bytes，`no-store` ", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/bathing/appointments/{id}/complete": { "post": { "tags": [ "助浴" ], "summary": "完成助浴预约", "description": "**用途**：完成助浴预约。\n\n**访问身份**：当前受派 Staff。\n\n**请求**：可选 `notes`, `clientRequestId`；照片和居民确认由服务端检查。\n\n**成功响应**：完工结果 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_618c2805a891", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "完工结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可选 `notes`, `clientRequestId`；照片和居民确认由服务端检查", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可选 `notes`, `clientRequestId`；照片和居民确认由服务端检查", "properties": { "notes": { "type": "string", "description": "notes；可选 `notes`, `clientRequestId`；照片和居民确认由服务端检查" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } } } } } } } }, "/repairs/meta": { "get": { "tags": [ "维修" ], "summary": "查询维修工单元数据", "description": "**用途**：查询维修工单元数据。\n\n**访问身份**：无。\n\n**请求**：—。\n\n**成功响应**：报修元数据 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_4517bfc82ee6", "responses": { "200": { "description": "报修元数据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/repairs/meta": { "get": { "tags": [ "维修" ], "summary": "查询维修工单元数据", "description": "**用途**：查询维修工单元数据。\n\n**访问身份**：无。\n\n**请求**：—。\n\n**成功响应**：报修元数据 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_ad13747eb9b0", "responses": { "200": { "description": "报修元数据 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/repairs": { "post": { "tags": [ "维修" ], "summary": "创建维修工单", "description": "**用途**：创建维修工单。\n\n**访问身份**：Resident。\n\n**请求**：必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`。\n\n**成功响应**：201 工单 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_2e032db025ce", "responses": { "201": { "description": "201 工单 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`", "properties": { "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "houseId": { "type": "string", "description": "目标房屋 ID；服务端核对人房关系或岗位辖区。" }, "category": { "type": "string", "description": "category；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "timeSlot": { "type": "string", "description": "timeSlot；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "preferredDate": { "type": "string", "format": "date", "description": "preferredDate；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "description": { "type": "string", "description": "description；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "subcategory": { "type": "string", "description": "subcategory；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "repairTargetType": { "type": "string", "description": "repairTargetType；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "locationAddress": { "type": "string", "description": "locationAddress；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "contactName": { "type": "string", "description": "contactName；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "contactPhone": { "type": "string", "description": "contactPhone；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "urgency": { "type": "string", "description": "urgency；必填 `clientRequestId`, `communityId`, `houseId`, `category`, `timeSlot`, `preferredDate`, `description`；可选 `subcategory`, `repairTargetType`, `locationAddress`, `contactName`, `contactPhone`, `urgency`, `photoKeys`" }, "photoKeys": { "type": "array", "items": {}, "description": "提交报修前已上传的照片引用列表。" } }, "required": [ "clientRequestId", "communityId", "houseId", "category", "timeSlot", "preferredDate", "description" ] } } } } }, "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Resident。\n\n**请求**：可选 `status`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_2e032db025ce", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/repairs/{id}": { "get": { "tags": [ "维修" ], "summary": "查看维修工单", "description": "**用途**：查看维修工单。\n\n**访问身份**：Resident + 订单归属。\n\n**请求**：—。\n\n**成功响应**：工单详情/进度 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_5a4ac5de08c7", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "工单详情/进度 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/repairs/upload-photo": { "post": { "tags": [ "维修" ], "summary": "上传维修工单照片", "description": "**用途**：上传维修工单照片。\n\n**访问身份**：Resident。\n\n**请求**：JSON body 的 `data` 为 base64 图片；可传 `filename`/`fileName`, `contentType`/`mimeType`；也可发送原始图片 bytes。\n\n**成功响应**：201 上传引用 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_b98700ec45c5", "responses": { "201": { "description": "201 上传引用 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "JSON body 的 `data` 为 base64 图片；可传 `filename`/`fileName`, `contentType`/`mimeType`；也可发送原始图片 bytes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "JSON body 的 `data` 为 base64 图片；可传 `filename`/`fileName`, `contentType`/`mimeType`；也可发送原始图片 bytes", "properties": { "data": { "type": "string", "description": "图片内容的 base64 字符串；服务端校验真实图片格式和大小。" }, "filename": { "type": "string", "description": "图片原始文件名，仅作显示与审计。" }, "fileName": { "type": "string", "description": "图片原始文件名的兼容字段。" }, "contentType": { "type": "string", "description": "声明的图片 MIME；服务端还会核对文件内容。" }, "mimeType": { "type": "string", "description": "声明的图片 MIME；服务端还会核对文件内容。" } }, "required": [ "data" ] } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/resident/repairs/{id}/attachments/{attachmentId}": { "get": { "tags": [ "维修" ], "summary": "下载维修工单私有附件", "description": "**用途**：下载维修工单私有附件。\n\n**访问身份**：Resident + 附件授权。\n\n**请求**：—。\n\n**成功响应**：私有图片 bytes，`no-store` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_23744155ef9c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "订单内的附件 ID；下载时仍需订单归属和读取权限。" } ], "responses": { "200": { "description": "私有图片 bytes，`no-store` ", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/repairs/{id}/confirm-completion": { "post": { "tags": [ "维修" ], "summary": "业主或指定代表确认维修完工", "description": "**用途**：业主或指定代表确认维修完工。\n\n**访问身份**：该单合法业主/代表。\n\n**请求**：必填 `expectedVersion`, `photoVersion`, `clientRequestId`。\n\n**成功响应**：确认结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。\n\n**本接口注意**：家庭维修仅当前有效业主确认；公区维修仅被指定的业主代表确认。代约人不能凭代约身份确认。", "operationId": "post_85494d3ce17a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "确认结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `expectedVersion`, `photoVersion`, `clientRequestId`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `expectedVersion`, `photoVersion`, `clientRequestId`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "photoVersion": { "type": "integer", "description": "当前完工照片版本；确认时须与所见照片一致。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } }, "required": [ "expectedVersion", "photoVersion", "clientRequestId" ] } } } } } }, "/resident/repairs/{id}/rating": { "post": { "tags": [ "维修" ], "summary": "评价维修工单", "description": "**用途**：评价维修工单。\n\n**访问身份**：合法订单居民。\n\n**请求**：body 由评价服务校验。\n\n**成功响应**：评价结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_b6ef97dc6b43", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "评价结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 由评价服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 由评价服务校验" } } } } } }, "/staff/repairs": { "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Staff/Admin + 工单 VIEW。\n\n**请求**：可选 `communityId`, `status`, `category`, `urgency`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_882a09ab6b97", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `category`, `urgency`" }, { "name": "urgency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `category`, `urgency`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs": { "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Staff/Admin + 工单 VIEW。\n\n**请求**：可选 `communityId`, `status`, `category`, `urgency`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_408550e34b00", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `category`, `urgency`" }, { "name": "urgency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `category`, `urgency`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/repairs/{id}": { "get": { "tags": [ "维修" ], "summary": "查看维修工单", "description": "**用途**：查看维修工单。\n\n**访问身份**：Staff/Admin + 工单范围。\n\n**请求**：—。\n\n**成功响应**：工单详情 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_69d405b4ac4b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "工单详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/{id}": { "get": { "tags": [ "维修" ], "summary": "查看维修工单", "description": "**用途**：查看维修工单。\n\n**访问身份**：Staff/Admin + 工单范围。\n\n**请求**：—。\n\n**成功响应**：工单详情 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_b86c9dcc7c99", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "工单详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/eligible-public-confirmers": { "get": { "tags": [ "维修" ], "summary": "查询可指定的公区维修业主代表", "description": "**用途**：查询可指定的公区维修业主代表。\n\n**访问身份**：Admin + 社区权限。\n\n**请求**：`communityId`。\n\n**成功响应**：可选确认人列表 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_d5bea34e0057", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "可选确认人列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/{id}/public-confirmer": { "post": { "tags": [ "维修" ], "summary": "指定公区维修业主代表", "description": "**用途**：指定公区维修业主代表。\n\n**访问身份**：Admin + 工单 HANDLE。\n\n**请求**：必填 `residentId`, `expectedVersion`, `clientRequestId`；residentId 必须是本小区当前已认证业主。\n\n**成功响应**：设置结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。\n\n**本接口注意**：只能从本小区当前已认证业主中指定代表；指定与撤换留痕，代表再对该公区工单确认完工。", "operationId": "post_72cfa9ecc501", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "设置结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `residentId`, `expectedVersion`, `clientRequestId`；residentId 必须是本小区当前已认证业主", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `residentId`, `expectedVersion`, `clientRequestId`；residentId 必须是本小区当前已认证业主", "properties": { "residentId": { "type": "string", "description": "目标居民 ID；服务端校验是否具有该小区当前有效的业主资格。" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } }, "required": [ "residentId", "expectedVersion", "clientRequestId" ] } } } } } }, "/admin/repairs/{id}/verify": { "post": { "tags": [ "维修" ], "summary": "核验维修工单", "description": "**用途**：核验维修工单。\n\n**访问身份**：Admin + 派工权限。\n\n**请求**：必填 `verificationNotes`, `expectedVersion`；可选 `urgency`。\n\n**成功响应**：核实结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_e4c995225fbd", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "核实结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `verificationNotes`, `expectedVersion`；可选 `urgency`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `verificationNotes`, `expectedVersion`；可选 `urgency`", "properties": { "verificationNotes": { "type": "string", "description": "verificationNotes；必填 `verificationNotes`, `expectedVersion`；可选 `urgency`" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "urgency": { "type": "string", "description": "urgency；必填 `verificationNotes`, `expectedVersion`；可选 `urgency`" } }, "required": [ "verificationNotes", "expectedVersion" ] } } } } } }, "/admin/repairs/{id}/revoke-dispatch": { "post": { "tags": [ "维修" ], "summary": "撤销维修派工", "description": "**用途**：撤销维修派工。\n\n**访问身份**：Admin + 派工权限。\n\n**请求**：必填 `reason`, `expectedVersion`。\n\n**成功响应**：撤销派工结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_1710afd44d82", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "撤销派工结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `reason`, `expectedVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `reason`, `expectedVersion`", "properties": { "reason": { "type": "string", "description": "reason；必填 `reason`, `expectedVersion`" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } }, "required": [ "reason", "expectedVersion" ] } } } } } }, "/admin/repairs/followups": { "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Admin + 对应模块授权。\n\n**请求**：查询参数含 `communityId`, 时间范围；export 使用 `requestId`。\n\n**成功响应**：列表/汇总/CSV 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_7242be1259ea", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "requestId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "请求标识；重试时遵守本接口的幂等约束。" } ], "responses": { "200": { "description": "列表/汇总/CSV ", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/summary": { "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Admin + 对应模块授权。\n\n**请求**：查询参数含 `communityId`, 时间范围；export 使用 `requestId`。\n\n**成功响应**：列表/汇总/CSV 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_af4b7ff23f66", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "requestId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "请求标识；重试时遵守本接口的幂等约束。" } ], "responses": { "200": { "description": "列表/汇总/CSV ", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/export": { "get": { "tags": [ "维修" ], "summary": "导出维修工单", "description": "**用途**：导出维修工单。\n\n**访问身份**：Admin + 对应模块授权。\n\n**请求**：查询参数含 `communityId`, 时间范围；export 使用 `requestId`。\n\n**成功响应**：列表/汇总/CSV 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_453c0a434714", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "requestId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "请求标识；重试时遵守本接口的幂等约束。" } ], "responses": { "200": { "description": "列表/汇总/CSV ", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/escort/bookings": { "post": { "tags": [ "陪诊" ], "summary": "创建陪诊预约", "description": "**用途**：创建陪诊预约。\n\n**访问身份**：Resident。\n\n**请求**：预约 body 由服务校验。\n\n**成功响应**：201 预约 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "post_08b9ee6b76e0", "responses": { "201": { "description": "201 预约 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "预约 body 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "预约 body 由服务校验" } } } } }, "get": { "tags": [ "陪诊" ], "summary": "查询陪诊预约", "description": "**用途**：查询陪诊预约。\n\n**访问身份**：Resident。\n\n**请求**：可选 `status`, `limit`, `offset`。\n\n**成功响应**：本人预约列表 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "get_08b9ee6b76e0", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "本人预约列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/escort-bookings": { "post": { "tags": [ "陪诊" ], "summary": "创建陪诊预约", "description": "**用途**：创建陪诊预约。\n\n**访问身份**：Resident。\n\n**请求**：预约 body 由服务校验。\n\n**成功响应**：201 预约 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "post_a11fc4886b00", "responses": { "201": { "description": "201 预约 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "预约 body 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "预约 body 由服务校验" } } } } }, "get": { "tags": [ "陪诊" ], "summary": "查询陪诊预约", "description": "**用途**：查询陪诊预约。\n\n**访问身份**：Resident。\n\n**请求**：可选 `status`, `limit`, `offset`。\n\n**成功响应**：本人预约列表 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "get_a11fc4886b00", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "单页数量；通用分页接口允许 1–100。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "从零开始的偏移量。" } ], "responses": { "200": { "description": "本人预约列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/escort/bookings/{id}": { "get": { "tags": [ "陪诊" ], "summary": "查看陪诊预约", "description": "**用途**：查看陪诊预约。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：本人预约详情与交接状态 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "get_1f688584d6eb", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "本人预约详情与交接状态 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/escort-bookings/{id}": { "get": { "tags": [ "陪诊" ], "summary": "查看陪诊预约", "description": "**用途**：查看陪诊预约。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：本人预约详情与交接状态 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "get_52aa13228e00", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "本人预约详情与交接状态 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/escort/handovers": { "get": { "tags": [ "陪诊" ], "summary": "查询陪诊预约", "description": "**用途**：查询陪诊预约。\n\n**访问身份**：Admin + 社区授权。\n\n**请求**：`communityId`；可选 `status`。\n\n**成功响应**：交接列表 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "get_acde3315e8df", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "交接列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/escort/handovers/{id}": { "get": { "tags": [ "陪诊" ], "summary": "查看陪诊预约", "description": "**用途**：查看陪诊预约。\n\n**访问身份**：Admin + 社区授权。\n\n**请求**：—。\n\n**成功响应**：交接详情 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "get_d55d2d60f9d8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "交接详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/escort/handovers/{id}/send": { "post": { "tags": [ "陪诊" ], "summary": "发送陪诊预约给福行", "description": "**用途**：发送陪诊预约给福行。\n\n**访问身份**：Admin + 交接 HANDLE。\n\n**请求**：`expectedVersion`。\n\n**成功响应**：发送尝试结果；不代表对方收单 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。", "operationId": "post_c935c42f9778", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "发送尝试结果；不代表对方收单 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" } } } } } } } }, "/admin/escort/handovers/{id}/verify": { "post": { "tags": [ "陪诊" ], "summary": "人工核对福行收单结果", "description": "**用途**：人工核对福行收单结果。\n\n**访问身份**：Admin + 交接 HANDLE。\n\n**请求**：必填 `expectedVersion`, `clientRequestId`, `decision`, `evidenceRef`；决定为 RECEIVED 时还需 `fuxingReceiptNo`。\n\n**成功响应**：人工核对结果 。\n\n**模块规则**：福行收单须有真实回执或人工核对凭据；发送超时为未知结果，不盲目重发。\n\n**本接口注意**：人工确认已收单时需真实福行回执编号与凭据引用；未知结果不可擅自记为已收。", "operationId": "post_051d33ee677b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "人工核对结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `expectedVersion`, `clientRequestId`, `decision`, `evidenceRef`；决定为 RECEIVED 时还需 `fuxingReceiptNo`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `expectedVersion`, `clientRequestId`, `decision`, `evidenceRef`；决定为 RECEIVED 时还需 `fuxingReceiptNo`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "decision": { "type": "string", "description": "审核或核对决定；仅接受该接口定义的状态值。" }, "evidenceRef": { "type": "string", "description": "人工核对凭据引用；不应放原始个人资料或密钥。" }, "fuxingReceiptNo": { "type": "string", "description": "福行确认收单时提供的真实回执编号。" } }, "required": [ "expectedVersion", "clientRequestId", "decision", "evidenceRef" ] } } } } } }, "/cleaning/quote": { "get": { "tags": [ "保洁" ], "summary": "获取保洁服务报价", "description": "**用途**：获取保洁服务报价。\n\n**访问身份**：无。\n\n**请求**：query: `communityId`, `serviceType`, `areaSqm`, `serviceDate`。\n\n**成功响应**：报价 DTO 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_c29492204232", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "serviceType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "query: `communityId`, `serviceType`, `areaSqm`, `serviceDate`" }, { "name": "areaSqm", "in": "query", "required": false, "schema": { "type": "number" }, "description": "query: `communityId`, `serviceType`, `areaSqm`, `serviceDate`" }, { "name": "serviceDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "query: `communityId`, `serviceType`, `areaSqm`, `serviceDate`" } ], "responses": { "200": { "description": "报价 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/cleaning/schedules": { "get": { "tags": [ "保洁" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：无。\n\n**请求**：query: `communityId`, `serviceType`, `serviceDate`。\n\n**成功响应**：可预约时段 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_02c53bdc28c8", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "serviceType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "query: `communityId`, `serviceType`, `serviceDate`" }, { "name": "serviceDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "query: `communityId`, `serviceType`, `serviceDate`" } ], "responses": { "200": { "description": "可预约时段 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/resident/cleaning/bookings": { "get": { "tags": [ "保洁" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：本人预约列表 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_1ceaef19b3cb", "responses": { "200": { "description": "本人预约列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "保洁" ], "summary": "创建保洁服务", "description": "**用途**：创建保洁服务。\n\n**访问身份**：Resident。\n\n**请求**：预约 body 由服务校验。\n\n**成功响应**：201 预约 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_1ceaef19b3cb", "responses": { "201": { "description": "201 预约 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "预约 body 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "预约 body 由服务校验" } } } } } }, "/resident/cleaning/bookings/{id}/completion-photo": { "get": { "tags": [ "保洁" ], "summary": "读取保洁服务完工照片", "description": "**用途**：读取保洁服务完工照片。\n\n**访问身份**：Resident + 当前 OWNER。\n\n**请求**：`photoVersion`。\n\n**成功响应**：私有图片 bytes，`no-store` 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_0799e0f524af", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "photoVersion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "当前完工照片版本；确认时须与所见照片一致。" } ], "responses": { "200": { "description": "私有图片 bytes，`no-store` ", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/resident/cleaning/bookings/{id}/confirm-completion": { "post": { "tags": [ "保洁" ], "summary": "业主确认保洁完工照片", "description": "**用途**：业主确认保洁完工照片。\n\n**访问身份**：Resident + 当前 OWNER。\n\n**请求**：`expectedVersion`, `photoVersion`, `clientRequestId`。\n\n**成功响应**：确认结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。\n\n**本接口注意**：确认人须是当前业主，photoVersion 必须对应其看见的完工照片。", "operationId": "post_981c3035e11d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "确认结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`expectedVersion`, `photoVersion`, `clientRequestId`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`expectedVersion`, `photoVersion`, `clientRequestId`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "photoVersion": { "type": "integer", "description": "当前完工照片版本；确认时须与所见照片一致。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } } } } } } } }, "/staff/cleaning/work-orders": { "get": { "tags": [ "保洁" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：Staff。\n\n**请求**：可选 `communityId`, `status`。\n\n**成功响应**：本人工作单 DTO 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_cb3d4b73765a", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "本人工作单 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/cleaning/residents": { "get": { "tags": [ "住户与房屋" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`。\n\n**成功响应**：服务对象列表 。\n\n**模块规则**：列表、审核和更正均按居民关系或物业小区辖区校验；房屋 ID 本身不构成授权。", "operationId": "get_1751676cdea7", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "服务对象列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/cleaning/bookings": { "get": { "tags": [ "保洁" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：Staff。\n\n**请求**：`communityId`；可选 `status`。\n\n**成功响应**：预约列表 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_e80455f37f93", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "预约列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/cleaning/bookings/phone": { "post": { "tags": [ "保洁" ], "summary": "登记保洁电话预约", "description": "**用途**：登记保洁电话预约。\n\n**访问身份**：Staff。\n\n**请求**：电话预约 body 由服务校验。\n\n**成功响应**：201 预约 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_16714a37613b", "responses": { "201": { "description": "201 预约 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "电话预约 body 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "电话预约 body 由服务校验" } } } } } }, "/staff/cleaning/bookings/{id}/candidates": { "get": { "tags": [ "保洁" ], "summary": "查看保洁服务", "description": "**用途**：查看保洁服务。\n\n**访问身份**：Staff。\n\n**请求**：—。\n\n**成功响应**：可派人员列表 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_32d2977e4de0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "可派人员列表 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/staff/cleaning/bookings/{id}/verify": { "post": { "tags": [ "保洁" ], "summary": "核验保洁服务", "description": "**用途**：核验保洁服务。\n\n**访问身份**：Staff + 对应流程权限。\n\n**请求**：版本与请求字段由各领域服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_aac32189e467", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "版本与请求字段由各领域服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "版本与请求字段由各领域服务校验" } } } } } }, "/staff/cleaning/bookings/{id}/assign": { "post": { "tags": [ "保洁" ], "summary": "指派保洁服务", "description": "**用途**：指派保洁服务。\n\n**访问身份**：Staff + 对应流程权限。\n\n**请求**：版本与请求字段由各领域服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_f550e096a250", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "版本与请求字段由各领域服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "版本与请求字段由各领域服务校验" } } } } } }, "/staff/cleaning/bookings/{id}/check-in": { "post": { "tags": [ "保洁" ], "summary": "保洁服务到场打卡", "description": "**用途**：保洁服务到场打卡。\n\n**访问身份**：Staff + 对应流程权限。\n\n**请求**：版本与请求字段由各领域服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_40a7f5184e7c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "版本与请求字段由各领域服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "版本与请求字段由各领域服务校验" } } } } } }, "/staff/cleaning/bookings/{id}/complete": { "post": { "tags": [ "保洁" ], "summary": "完成保洁服务", "description": "**用途**：完成保洁服务。\n\n**访问身份**：Staff + 对应流程权限。\n\n**请求**：版本与请求字段由各领域服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_af5d9b29f188", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "版本与请求字段由各领域服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "版本与请求字段由各领域服务校验" } } } } } }, "/staff/cleaning/bookings/{id}/completion-photos": { "post": { "tags": [ "保洁" ], "summary": "上传保洁服务完工照片", "description": "**用途**：上传保洁服务完工照片。\n\n**访问身份**：Staff。\n\n**请求**：`data` (base64) 必填；可传 `expectedVersion`, `clientRequestId`, 文件名/MIME。\n\n**成功响应**：201 照片版本/结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_dfeb9dfa4892", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "201": { "description": "201 照片版本/结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`data` (base64) 必填；可传 `expectedVersion`, `clientRequestId`, 文件名/MIME", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`data` (base64) 必填；可传 `expectedVersion`, `clientRequestId`, 文件名/MIME", "properties": { "data": { "type": "string", "description": "图片内容的 base64 字符串；服务端校验真实图片格式和大小。" }, "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } }, "required": [ "data" ] } } } } } }, "/admin/cleaning/catalog": { "get": { "tags": [ "保洁" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：Admin + 清洁业务 VIEW。\n\n**请求**：`communityId`；bookings 可选 status。\n\n**成功响应**：目录/预约 DTO 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_a63c076cad28", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "目录/预约 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/cleaning/bookings": { "get": { "tags": [ "保洁" ], "summary": "查询保洁服务", "description": "**用途**：查询保洁服务。\n\n**访问身份**：Admin + 清洁业务 VIEW。\n\n**请求**：`communityId`；bookings 可选 status。\n\n**成功响应**：目录/预约 DTO 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "get_48c309d82e5d", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "目录/预约 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/cleaning/settings": { "put": { "tags": [ "保洁" ], "summary": "更新保洁服务", "description": "**用途**：更新保洁服务。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：body 字段按设置/价格/排期服务校验。\n\n**成功响应**：更新结果/201 新价格规则 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "put_dee4c0654484", "responses": { "200": { "description": "更新结果/201 新价格规则 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 字段按设置/价格/排期服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 字段按设置/价格/排期服务校验" } } } } } }, "/admin/cleaning/prices": { "post": { "tags": [ "保洁" ], "summary": "创建保洁服务", "description": "**用途**：创建保洁服务。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：body 字段按设置/价格/排期服务校验。\n\n**成功响应**：更新结果/201 新价格规则 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_ab9341036b9f", "responses": { "201": { "description": "更新结果/201 新价格规则 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 字段按设置/价格/排期服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 字段按设置/价格/排期服务校验" } } } } } }, "/admin/cleaning/prices/{id}": { "patch": { "tags": [ "保洁" ], "summary": "更新保洁服务", "description": "**用途**：更新保洁服务。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：body 字段按设置/价格/排期服务校验。\n\n**成功响应**：更新结果/201 新价格规则 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "patch_17f080de6239", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "更新结果/201 新价格规则 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 字段按设置/价格/排期服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 字段按设置/价格/排期服务校验" } } } } } }, "/admin/cleaning/schedules": { "post": { "tags": [ "保洁" ], "summary": "创建保洁服务", "description": "**用途**：创建保洁服务。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：body 字段按设置/价格/排期服务校验。\n\n**成功响应**：更新结果/201 新价格规则 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_e9babbf23a46", "responses": { "201": { "description": "更新结果/201 新价格规则 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 字段按设置/价格/排期服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 字段按设置/价格/排期服务校验" } } } } } }, "/admin/cleaning/bookings/{id}/archive": { "post": { "tags": [ "保洁" ], "summary": "归档保洁服务", "description": "**用途**：归档保洁服务。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：归档 body 由服务校验。\n\n**成功响应**：归档结果 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_6fe2aeb03de9", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "归档结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "归档 body 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "归档 body 由服务校验" } } } } } }, "/admin/cleaning/settlements/export": { "post": { "tags": [ "保洁" ], "summary": "导出保洁服务", "description": "**用途**：导出保洁服务。\n\n**访问身份**：Admin + EXPORT。\n\n**请求**：body 内社区、日期、request ID 由服务校验。\n\n**成功响应**：CSV 下载 。\n\n**模块规则**：完工照片与当前业主确认须对应同一订单和版本；缺少凭据时不得归档。", "operationId": "post_5439c1bf921f", "responses": { "200": { "description": "CSV 下载 ", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "body 内社区、日期、request ID 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "body 内社区、日期、request ID 由服务校验" } } } } } }, "/admin/bathing/packages": { "get": { "tags": [ "助浴" ], "summary": "查询助浴套餐", "description": "**用途**：查询助浴套餐。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`；可选 `packageCode`, `status`, `targetDate`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_451b41a57bcf", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "packageCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `packageCode`, `status`, `targetDate`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "targetDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`；可选 `packageCode`, `status`, `targetDate`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "助浴" ], "summary": "创建助浴套餐", "description": "**用途**：创建助浴套餐。\n\n**访问身份**：Admin + 助浴 HANDLE。\n\n**请求**：package body 交由目录服务校验。\n\n**成功响应**：201 套餐对象 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_451b41a57bcf", "responses": { "201": { "description": "201 套餐对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "package body 交由目录服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "package body 交由目录服务校验" } } } } } }, "/admin/bathing/packages/{id}": { "get": { "tags": [ "助浴" ], "summary": "查看助浴套餐", "description": "**用途**：查看助浴套餐。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：—。\n\n**成功响应**：套餐对象 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_c417d6aea936", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "套餐对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/packages/effective": { "get": { "tags": [ "助浴" ], "summary": "查询助浴套餐", "description": "**用途**：查询助浴套餐。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：query `communityId`, `packageCode`, `targetDate`。\n\n**成功响应**：有效价格 DTO 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_d6667d6d3ad0", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "packageCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "query `communityId`, `packageCode`, `targetDate`" }, { "name": "targetDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "query `communityId`, `packageCode`, `targetDate`" } ], "responses": { "200": { "description": "有效价格 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/qualifications": { "get": { "tags": [ "助浴" ], "summary": "查询助浴人员资质", "description": "**用途**：查询助浴人员资质。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`；可选 `staffId`, `status`, `validOnDate`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_44c7432fbbbd", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "staffId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `staffId`, `status`, `validOnDate`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "validOnDate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`；可选 `staffId`, `status`, `validOnDate`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "助浴" ], "summary": "创建助浴人员资质", "description": "**用途**：创建助浴人员资质。\n\n**访问身份**：Admin + 助浴 HANDLE。\n\n**请求**：qualification body 交由目录服务校验。\n\n**成功响应**：201 资质对象 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_44c7432fbbbd", "responses": { "201": { "description": "201 资质对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "qualification body 交由目录服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "qualification body 交由目录服务校验" } } } } } }, "/admin/bathing/qualifications/verify": { "get": { "tags": [ "助浴" ], "summary": "查询助浴人员资质", "description": "**用途**：查询助浴人员资质。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`, `staffId`, `serviceDate`。\n\n**成功响应**：资格校验 DTO 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_87ff531df1e9", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "staffId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `staffId`, `serviceDate`" }, { "name": "serviceDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`, `staffId`, `serviceDate`" } ], "responses": { "200": { "description": "资格校验 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/schedules": { "get": { "tags": [ "助浴" ], "summary": "查询助浴排班", "description": "**用途**：查询助浴排班。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`；可选员工/日期/时段/状态。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_3ac49ee698e9", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "助浴" ], "summary": "创建助浴排班", "description": "**用途**：创建助浴排班。\n\n**访问身份**：Admin + 助浴 HANDLE。\n\n**请求**：schedule body 交由目录服务校验。\n\n**成功响应**：201 排班对象 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_3ac49ee698e9", "responses": { "201": { "description": "201 排班对象 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "schedule body 交由目录服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "schedule body 交由目录服务校验" } } } } } }, "/admin/bathing/schedules/check": { "get": { "tags": [ "助浴" ], "summary": "查询助浴排班", "description": "**用途**：查询助浴排班。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`, `staffId`, `scheduleDate`, `timeSlot`。\n\n**成功响应**：可用性 DTO 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_3ed5bd06b8ac", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "staffId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `staffId`, `scheduleDate`, `timeSlot`" }, { "name": "scheduleDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`, `staffId`, `scheduleDate`, `timeSlot`" }, { "name": "timeSlot", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `staffId`, `scheduleDate`, `timeSlot`" } ], "responses": { "200": { "description": "可用性 DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/schedules/available-staff": { "get": { "tags": [ "助浴" ], "summary": "查询助浴排班", "description": "**用途**：查询助浴排班。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`, `scheduleDate`, `timeSlot`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_927a3bf7052a", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "scheduleDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`, `scheduleDate`, `timeSlot`" }, { "name": "timeSlot", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`communityId`, `scheduleDate`, `timeSlot`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/pilot-readiness": { "get": { "tags": [ "助浴" ], "summary": "查询助浴", "description": "**用途**：查询助浴。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：`communityId`；可选 `targetDate`。\n\n**成功响应**：readiness DTO 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_97700265dafb", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "targetDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`communityId`；可选 `targetDate`" } ], "responses": { "200": { "description": "readiness DTO ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/appointments": { "get": { "tags": [ "助浴" ], "summary": "查询助浴预约", "description": "**用途**：查询助浴预约。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：可选 `communityId`, `status`, `serviceDate`, `assignedStaffId`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_ff32d51c873e", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" }, { "name": "serviceDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "可选 `communityId`, `status`, `serviceDate`, `assignedStaffId`" }, { "name": "assignedStaffId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "可选 `communityId`, `status`, `serviceDate`, `assignedStaffId`" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/appointments/overdue-alerts": { "get": { "tags": [ "助浴" ], "summary": "查询助浴预约", "description": "**用途**：查询助浴预约。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：可选 `communityId`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_23e24773692e", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/appointments/{id}": { "get": { "tags": [ "助浴" ], "summary": "查看助浴预约", "description": "**用途**：查看助浴预约。\n\n**访问身份**：Admin + 助浴 VIEW。\n\n**请求**：—。\n\n**成功响应**：预约详情 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_1bc9e461e3eb", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "预约详情 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/appointments/{id}/verify-phone": { "post": { "tags": [ "助浴" ], "summary": "核验助浴预约电话", "description": "**用途**：核验助浴预约电话。\n\n**访问身份**：Admin/对应管家权限。\n\n**请求**：动作 body 由业务服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_a8a198c51275", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "动作 body 由业务服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "动作 body 由业务服务校验" } } } } } }, "/admin/bathing/appointments/{id}/assign": { "post": { "tags": [ "助浴" ], "summary": "指派助浴预约", "description": "**用途**：指派助浴预约。\n\n**访问身份**：Admin/对应管家权限。\n\n**请求**：动作 body 由业务服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_a4b165a44343", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "动作 body 由业务服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "动作 body 由业务服务校验" } } } } } }, "/admin/bathing/appointments/{id}/archive": { "post": { "tags": [ "助浴" ], "summary": "归档助浴预约", "description": "**用途**：归档助浴预约。\n\n**访问身份**：Admin/对应管家权限。\n\n**请求**：动作 body 由业务服务校验。\n\n**成功响应**：操作结果 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "post_92c809a695ce", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "操作结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "动作 body 由业务服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "动作 body 由业务服务校验" } } } } } }, "/admin/bathing/appointments/export": { "get": { "tags": [ "助浴" ], "summary": "导出助浴预约", "description": "**用途**：导出助浴预约。\n\n**访问身份**：Admin + EXPORT。\n\n**请求**：`communityId`。\n\n**成功响应**：CSV（不含原图） 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_ec2ec721da80", "parameters": [ { "name": "communityId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "CSV（不含原图） ", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/bathing/appointments/{id}/attachments/{attachmentId}": { "get": { "tags": [ "助浴" ], "summary": "下载助浴预约私有附件", "description": "**用途**：下载助浴预约私有附件。\n\n**访问身份**：Admin + 附件读取授权。\n\n**请求**：—。\n\n**成功响应**：私有图片 bytes，`no-store` 。\n\n**模块规则**：照片、签名及完工凭据按订单归属鉴权；未满足确认条件不得完工。", "operationId": "get_f44dc0391d6e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "订单内的附件 ID；下载时仍需订单归属和读取权限。" } ], "responses": { "200": { "description": "私有图片 bytes，`no-store` ", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/schedules": { "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Admin + 派工权限。\n\n**请求**：列表可选小区/员工/日期/时段；写入 schedule body。\n\n**成功响应**：`{list,total}` / 201 排班 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_4417aa2b07a6", "responses": { "200": { "description": "`{list,total}` / 201 排班 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "维修" ], "summary": "创建维修工单", "description": "**用途**：创建维修工单。\n\n**访问身份**：Admin + 派工权限。\n\n**请求**：列表可选小区/员工/日期/时段；写入 schedule body。\n\n**成功响应**：`{list,total}` / 201 排班 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_4417aa2b07a6", "responses": { "201": { "description": "`{list,total}` / 201 排班 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "列表可选小区/员工/日期/时段；写入 schedule body", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "列表可选小区/员工/日期/时段；写入 schedule body" } } } } } }, "/admin/repairs/dispatch/suggestions": { "post": { "tags": [ "维修" ], "summary": "生成维修派工建议", "description": "**用途**：生成维修派工建议。\n\n**访问身份**：Admin + 派工权限。\n\n**请求**：`orderIds` 数组。\n\n**成功响应**：`{ suggestions, total }` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_34fd531568a4", "responses": { "200": { "description": "`{ suggestions, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "suggestions": { "type": "array", "items": {}, "description": "suggestions；具体结构以服务端业务响应为准。" }, "total": { "type": "string", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`orderIds` 数组", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`orderIds` 数组", "properties": { "orderIds": { "type": "array", "items": {}, "description": "orderIds；`orderIds` 数组" } } } } } } } }, "/admin/repairs/dispatch/confirm": { "post": { "tags": [ "维修" ], "summary": "确认批量维修派工", "description": "**用途**：确认批量维修派工。\n\n**访问身份**：Admin + 派工权限。\n\n**请求**：`items` 数组。\n\n**成功响应**：`{ results, total }` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_589cda568ceb", "responses": { "200": { "description": "`{ results, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "results": { "type": "array", "items": {}, "description": "results；具体结构以服务端业务响应为准。" }, "total": { "type": "string", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`items` 数组", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`items` 数组", "properties": { "items": { "type": "array", "items": {}, "description": "items；`items` 数组" } } } } } } } }, "/staff/repairs/{id}/check-in": { "post": { "tags": [ "维修" ], "summary": "维修工单到场打卡", "description": "**用途**：维修工单到场打卡。\n\n**访问身份**：当前受派 Staff。\n\n**请求**：必填 `expectedVersion`, `clientRequestId`, `latitude`, `longitude`；可选 `address`。\n\n**成功响应**：到场打卡结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_8452b5adec0c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "到场打卡结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `expectedVersion`, `clientRequestId`, `latitude`, `longitude`；可选 `address`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `expectedVersion`, `clientRequestId`, `latitude`, `longitude`；可选 `address`", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" }, "latitude": { "type": "number", "description": "到场定位纬度。" }, "longitude": { "type": "number", "description": "到场定位经度。" }, "address": { "type": "string", "description": "address；必填 `expectedVersion`, `clientRequestId`, `latitude`, `longitude`；可选 `address`" } }, "required": [ "expectedVersion", "clientRequestId", "latitude", "longitude" ] } } } } } }, "/staff/repairs/{id}/complete": { "post": { "tags": [ "维修" ], "summary": "维修师傅最终结单", "description": "**用途**：维修师傅最终结单。\n\n**访问身份**：当前受派 Staff。\n\n**请求**：必填 `expectedVersion`, `photoVersion`, `clientRequestId`；须已有合法业主/代表确认。\n\n**成功响应**：完工结单结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。\n\n**本接口注意**：师傅仅在照片及合法确认齐全后结单；重复提交不能重复增加完工数。", "operationId": "post_79209df1c272", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "完工结单结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "必填 `expectedVersion`, `photoVersion`, `clientRequestId`；须已有合法业主/代表确认", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "必填 `expectedVersion`, `photoVersion`, `clientRequestId`；须已有合法业主/代表确认", "properties": { "expectedVersion": { "type": "integer", "description": "提交前读取的对象版本；版本已变化时重新读取再办理。" }, "photoVersion": { "type": "integer", "description": "当前完工照片版本；确认时须与所见照片一致。" }, "clientRequestId": { "type": "string", "description": "本次业务请求的稳定标识；超时重试复用原值及原请求内容。" } }, "required": [ "expectedVersion", "photoVersion", "clientRequestId" ] } } } } } }, "/staff/repairs/{id}/completion-photos": { "post": { "tags": [ "维修" ], "summary": "上传维修工单完工照片", "description": "**用途**：上传维修工单完工照片。\n\n**访问身份**：当前受派 Staff。\n\n**请求**：`data` base64 必填；文件名/MIME、版本和 request ID 由领域服务处理。\n\n**成功响应**：201 照片关联结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_acd424571c05", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "201": { "description": "201 照片关联结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "`data` base64 必填；文件名/MIME、版本和 request ID 由领域服务处理", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "`data` base64 必填；文件名/MIME、版本和 request ID 由领域服务处理", "properties": { "data": { "type": "string", "description": "图片内容的 base64 字符串；服务端校验真实图片格式和大小。" } }, "required": [ "data" ] } } } } } }, "/staff/repairs/my-tasks": { "get": { "tags": [ "维修" ], "summary": "查询维修工单", "description": "**用途**：查询维修工单。\n\n**访问身份**：Staff。\n\n**请求**：可选 `status`。\n\n**成功响应**：`{ list, total }` 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "get_9935b43bba58", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "业务状态；允许值及状态转换由领域服务校验。" } ], "responses": { "200": { "description": "`{ list, total }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "list": { "type": "array", "items": {}, "description": "当前查询可见范围内的记录。" }, "total": { "type": "integer", "description": "符合筛选条件的记录总数。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/repairs/{id}/followup": { "post": { "tags": [ "维修" ], "summary": "登记维修回访", "description": "**用途**：登记维修回访。\n\n**访问身份**：Admin/管家授权。\n\n**请求**：回访 body 由服务校验。\n\n**成功响应**：回访/归档结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_68325dd88852", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "回访/归档结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "回访 body 由服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "回访 body 由服务校验" } } } } } }, "/admin/repairs/notifications/dispatch": { "post": { "tags": [ "维修" ], "summary": "处理维修派工通知", "description": "**用途**：处理维修派工通知。\n\n**访问身份**：Admin + 派单权限。\n\n**请求**：可选 `limit`。\n\n**成功响应**：通知投递处理结果 。\n\n**模块规则**：家庭工单由当前业主确认；公区工单由后台指定的本小区认证业主代表确认，再由师傅结单。", "operationId": "post_d22d8a5cbb9f", "responses": { "200": { "description": "通知投递处理结果 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "可选 `limit`", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "可选 `limit`", "properties": { "limit": { "type": "integer", "description": "单页数量；通用分页接口允许 1–100。" } } } } } } } }, "/shop/catalog": { "get": { "tags": [ "社区商店" ], "summary": "查询社区商店", "description": "**用途**：查询社区商店。\n\n**访问身份**：Resident。\n\n**请求**：当前小区上下文由认证绑定解析。\n\n**成功响应**：商品目录 。\n\n**模块规则**：目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "operationId": "get_3895588328f2", "responses": { "200": { "description": "商品目录 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/shop/placements/{id}/destination": { "get": { "tags": [ "社区商店" ], "summary": "获取社区商店跳转地址", "description": "**用途**：获取社区商店跳转地址。\n\n**访问身份**：Resident。\n\n**请求**：—。\n\n**成功响应**：允许跳转的 destination DTO（外部交易状态不在响应中保证） 。\n\n**模块规则**：目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "operationId": "get_0f70a044c84e", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "允许跳转的 destination DTO（外部交易状态不在响应中保证） ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/shop/catalog": { "get": { "tags": [ "社区商店" ], "summary": "查询社区商店", "description": "**用途**：查询社区商店。\n\n**访问身份**：Admin + 小区 VIEW。\n\n**请求**：查询小区参数。\n\n**成功响应**：后台目录 。\n\n**模块规则**：目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "operationId": "get_220bdfa68e08", "responses": { "200": { "description": "后台目录 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/admin/shop/catalog/{communityId}": { "put": { "tags": [ "社区商店" ], "summary": "更新社区商店", "description": "**用途**：更新社区商店。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：目录更新 body（版本字段由领域服务校验）。\n\n**成功响应**：更新目录 。\n\n**模块规则**：目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "operationId": "put_e7cca2fda4b6", "parameters": [ { "name": "communityId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" } ], "responses": { "200": { "description": "更新目录 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "目录更新 body（版本字段由领域服务校验）", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "目录更新 body（版本字段由领域服务校验）" } } } } } }, "/admin/shop/placements": { "post": { "tags": [ "社区商店" ], "summary": "创建社区商店", "description": "**用途**：创建社区商店。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：投放字段由领域服务校验。\n\n**成功响应**：201/更新投放 。\n\n**模块规则**：目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "operationId": "post_bbe962f8db13", "responses": { "201": { "description": "201/更新投放 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "投放字段由领域服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "投放字段由领域服务校验" } } } } } }, "/admin/shop/placements/{id}": { "put": { "tags": [ "社区商店" ], "summary": "更新社区商店", "description": "**用途**：更新社区商店。\n\n**访问身份**：Admin + HANDLE。\n\n**请求**：投放字段由领域服务校验。\n\n**成功响应**：201/更新投放 。\n\n**模块规则**：目录和跳转地址由服务端按小区校验；外部交易不由本系统确认。", "operationId": "put_94c76acc784c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "目标资源 ID。" } ], "responses": { "200": { "description": "201/更新投放 ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "投放字段由领域服务校验", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "投放字段由领域服务校验" } } } } } }, "/dashboard/communities": { "get": { "tags": [ "数据大屏" ], "summary": "查询数据大屏", "description": "**用途**：查询数据大屏。\n\n**访问身份**：Admin/授权 Staff。\n\n**请求**：—。\n\n**成功响应**：`{ list: [{id,name}] }` 。\n\n**模块规则**：只读汇总必须遵守小区范围；统计应能与源业务记录复核。", "operationId": "get_2b2122a4250b", "responses": { "200": { "description": "`{ list: [{id,name}] }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "目标资源 ID。" }, "name": { "type": "string", "description": "name；具体结构以服务端业务响应为准。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/dashboard/summary": { "get": { "tags": [ "数据大屏" ], "summary": "查询数据大屏", "description": "**用途**：查询数据大屏。\n\n**访问身份**：Admin/授权 Staff。\n\n**请求**：query 必填 `communityId`, `from`, `to`。\n\n**成功响应**：`{ communityId, from, to, generatedAt, timeZone, blocks }` 。\n\n**模块规则**：只读汇总必须遵守小区范围；统计应能与源业务记录复核。", "operationId": "get_6356dc64bea2", "parameters": [ { "name": "communityId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "description": "query 必填 `communityId`, `from`, `to`" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "query 必填 `communityId`, `from`, `to`" } ], "responses": { "200": { "description": "`{ communityId, from, to, generatedAt, timeZone, blocks }` ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "communityId": { "type": "string", "description": "目标小区 ID；服务端按当前会话的小区权限再次校验。" }, "from": { "type": "string", "description": "from；具体结构以服务端业务响应为准。" }, "to": { "type": "string", "description": "to；具体结构以服务端业务响应为准。" }, "generatedAt": { "type": "string", "description": "generatedAt；具体结构以服务端业务响应为准。" }, "timeZone": { "type": "string", "description": "timeZone；具体结构以服务端业务响应为准。" }, "blocks": { "type": "object", "additionalProperties": true, "description": "blocks 结构由所属业务接口定义。" } } } } } }, "default": { "description": "错误；具体状态码和 code 见共同约定及领域服务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "从对应作用端登录接口取得的会话 token；居民、员工、管理员不可互换。" } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "ResidentBinding": { "type": "object", "description": "当前居民的一条房屋认证关系记录。", "required": [ "id", "residentId", "houseId", "communityId", "relationType", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "认证关系 ID。" }, "residentId": { "type": "string", "description": "当前登录居民 ID。" }, "houseId": { "type": "string", "description": "房屋 ID。" }, "communityId": { "type": "string", "description": "小区 ID。" }, "communityName": { "type": "string", "description": "小区展示名。" }, "buildingNo": { "type": "string", "description": "楼栋号。" }, "unitNo": { "type": "string", "description": "单元号。" }, "roomNo": { "type": "string", "description": "室号。" }, "relationType": { "type": "string", "enum": [ "OWNER", "FAMILY", "TENANT" ], "description": "与该房屋的关系。" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "REJECTED", "REVOKED" ], "description": "认证审核状态。" }, "proofMaterialId": { "type": "string", "nullable": true, "description": "证明材料引用；可能为空。" }, "rejectReason": { "type": "string", "nullable": true, "description": "拒绝原因；仅在相关状态下有值。" }, "createdAt": { "type": "string", "format": "date-time", "description": "申请创建时间。" }, "updatedAt": { "type": "string", "format": "date-time", "description": "最近更新时间。" } } }, "Resident": { "type": "object", "required": [ "id", "phone", "name", "status", "isSenior", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "phone": { "type": "string" }, "name": { "type": "string" }, "wechatOpenid": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "FROZEN", "DISABLED" ] }, "isSenior": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "StaffAccount": { "type": "object", "required": [ "id", "username", "name", "phone", "role", "isRootAdmin", "status", "authVersion", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" }, "position": { "type": "string", "nullable": true }, "isRootAdmin": { "type": "boolean" }, "vendorId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "DELETED" ] }, "authVersion": { "type": "integer" }, "modules": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "StaffJurisdiction": { "type": "object", "required": [ "id", "staffId", "communityId", "createdAt" ], "properties": { "id": { "type": "string" }, "staffId": { "type": "string" }, "communityId": { "type": "string" }, "buildingId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } }