Codex
110 lines
9.2 KiB
Markdown
110 lines
9.2 KiB
Markdown
# 2026-08-10 M08-D 后台运营总览 API
|
|
|
|
| 方法 | 路径 | 权限 | 结果 |
|
|
|---|---|---|---|
|
|
| GET | `/admin-api/statistics` | `store.operation.read` 且门店在授权范围，或租户/平台管理权限 | 与小程序管理端共享同一统计仓储，返回最长 93 天的订单、成功实收、会员、房态、支付渠道、每日收入和验券汇总。 |
|
|
| GET | `/admin-api/stores` | 既有门店读权限与数据范围 | 运营总览只展示当前账号有权查看的门店，用于统计门店选择。 |
|
|
|
|
后台 API 基地址仍固定为 `/admin-api`。新增别名不复制统计逻辑，不降低鉴权；实收只累计 `SUCCEEDED` 支付，房态为查询时快照，订单和验券按各自创建时间口径。
|
|
|
|
## 门店与房间管理增量
|
|
|
|
| 方法 | 路径 | 变更 |
|
|
|---|---|---|
|
|
| GET | `/admin-api/stores` | 增加 `businessHours`、`wifiConfigured`、经纬度、联系电话、Wi-Fi SSID、通知地址和排序；不返回 Wi-Fi 密码。 |
|
|
| POST/PUT | `/admin-api/stores[/:id]` | `wifiPassword` 改为可省略；创建时省略写入空值，更新时省略使用 `COALESCE` 保持原密码。 |
|
|
| GET/POST/PUT/PATCH/DELETE | `/admin-api/stores/:storeId/rooms`、`/admin-api/rooms/**` | Vue 后台接入既有房间列表、创建、编辑、状态、停用时段和归档接口，权限契约不变。 |
|
|
|
|
## 订单运营增量
|
|
|
|
| 方法 | 路径 | 变更 |
|
|
|---|---|---|
|
|
| GET | `/admin-api/orders` | 新增后台别名，支持 `page`、`pageSize`、`status`、`storeId`，复用订单仓储的租户和授权门店范围。 |
|
|
| GET | `/admin-api/orders/:orderId` | 新增后台详情别名，返回服务端金额、时段、门店/房间和最近支付摘要。 |
|
|
| GET | `/admin-api/orders/:orderId/history` | 新增后台状态流水别名，复用经理数据范围校验。 |
|
|
| POST | `/admin-api/orders/:orderId/actions|note|adjust-time|renew|change-room` | Vue 后台接入既有受控写接口；服务端继续校验状态机、金额、时段冲突、权限和幂等。 |
|
|
|
|
## 资金运营增量
|
|
|
|
- 无新后端路由；Vue 后台接入既有 `/admin-api/pay/refund`、`/pay/reconciliation`、`/pay/collection-account`、`/pay/profit-share-receiver`、`/pay/profit-share-policy` 和 `/pay/profit-shares`。
|
|
- 收款账户与接收方凭据只提交环境引用；列表继续只返回商户号、脱敏标识和授权状态，不返回私钥或真实接收方账户。
|
|
- 客户端生成一次性幂等键，但退款金额、可退余额、分账比例、授权与生产 Mock 门禁继续完全由服务端判定。
|
|
|
|
## 团购与第三方平台运营增量
|
|
|
|
| 方法 | 路径 | 变更 |
|
|
|---|---|---|
|
|
| GET | `/admin-api/third-party/records` | Vue 后台接入既有直订与核销记录，支持平台、门店和状态过滤。 |
|
|
| GET | `/admin-api/third-party/setup` | 新增管理员安全读取接口，返回平台模式、环境凭据引用是否配置、过滤后的非敏感设置和资源映射；要求租户管理或平台管理员权限。 |
|
|
| PUT | `/admin-api/third-party/config`、`/admin-api/third-party/mappings` | Vue 后台接入既有配置与映射写接口，继续验证租户资源和环境凭据引用。 |
|
|
| POST | `/admin-api/group-vouchers/redeem`、`/admin-api/group-vouchers/redeem-manual` | 补齐管理员后台 API/人工验券入口，与小程序管理端共享金额、权限、幂等和券码脱敏逻辑。 |
|
|
|
|
## 会员与员工用户管理增量
|
|
|
|
| 方法 | 路径 | 变更 |
|
|
|---|---|---|
|
|
| GET | `/admin-api/members`、`/admin-api/members/:id` | Vue 后台接入既有会员聚合与详情接口，读取余额、权益、订单、充值和最近流水，权限范围不变。 |
|
|
| GET | `/admin-api/users?userType=STAFF` | 新增可选 STAFF-only 过滤参数；只接受固定枚举 `STAFF`，确保全部角色员工视图不混入顾客。 |
|
|
| POST/PATCH | `/admin-api/staff`、`/admin-api/users/:id` | Vue 后台接入既有员工创建、资料、角色、门店和状态写接口，继续撤销权限变化后的会话并写审计。 |
|
|
| POST | `/admin-api/users/:id/reset-sessions` | Vue 后台接入既有会话重置入口。 |
|
|
|
|
## 设备运营增量
|
|
|
|
- 无新后端路由；Vue 后台接入既有 `/admin-api/devices`、`/device-topology`、`/device-channels`、`/device-links`、`/devices/:id/maintenance` 与 `/device-control/**`。
|
|
- 所有读写继续使用租户和授权门店范围；控制目标唯一、设备类型、房间归属、危险操作和 MQTT 命令状态继续由服务端校验。
|
|
|
|
## 多小程序与租户配置增量
|
|
|
|
| 方法 | 路径 | 权限与变更 |
|
|
|---|---|---|
|
|
| GET | `/admin-api/platform-apps` | `tenant.manage` 或平台管理权限；仅返回当前租户绑定及非敏感品牌配置。 |
|
|
| PUT | `/admin-api/platform-apps/:id/config` | 租户管理员可更新当前租户已有绑定，默认门店强制同租户并写审计。 |
|
|
| POST | `/admin-api/platform-apps/bind` | 仅 `platform.manage`/平台管理员可新增逻辑应用或当前租户绑定。 |
|
|
|
|
所有 schema 均不接受或返回 AppSecret、支付密钥和证书。
|
|
|
|
## 广告与装修管理增量
|
|
|
|
| 方法 | 路径 | 权限与变更 |
|
|
|---|---|---|
|
|
| GET/POST | `/admin-api/media/images` | 新增素材安全列表；上传继续校验图片并压缩，门店运营必须指定授权门店，只有租户/平台管理员可创建租户公共素材。 |
|
|
| GET/POST | `/admin-api/decorations` | 新增指定门店的装修版本列表；创建继续生成不可变草稿版本并校验组件白名单。 |
|
|
| POST | `/admin-api/decorations/:id/publish` | 发布指定门店版本并自动归档上一发布版，支持历史版本重新发布。 |
|
|
| GET/POST/PUT | `/admin-api/advertisements[/:id]` | 新增广告更新；写入同时校验原广告范围、目标范围和图片素材范围，门店管理员只能维护授权门店广告。 |
|
|
|
|
响应新增广告 `imageAssetId`，用于无损编辑既有记录；素材和装修列表上限分别为 200/100 条，均按租户和授权门店裁剪。
|
|
|
|
## 加盟申请与跟进运营增量
|
|
|
|
| 方法 | 路径 | 权限与变更 |
|
|
|---|---|---|
|
|
| POST | `/app-api/franchise-applications` | 按 `x-wechat-appid`/可选 `tenant-id` 解析有效租户，支持匿名或当前租户登录用户提交，`clientRequestId` 幂等。 |
|
|
| GET | `/admin-api/franchise-applications` | `tenant.manage` 或平台管理权限；支持状态、负责人、关键字和分页，平台跨租户必须显式请求 tenantId。 |
|
|
| GET | `/admin-api/franchise-applications/:id` | 返回申请详情与实际操作人跟进历史，严格按目标租户读取。 |
|
|
| PATCH | `/admin-api/franchise-applications/:id/assignee` | 负责人必须是线索所属租户的有效 STAFF 用户；支持取消分派。 |
|
|
| POST | `/admin-api/franchise-applications/:id/follow-ups` | 新增电话、微信、面谈或备注记录，更新下次跟进时间，并执行 `NEW → CONTACTED → QUALIFIED → CONVERTED/REJECTED` 受控流转。 |
|
|
|
|
联系电话只进入受权限保护的业务表和响应，不写入审计 metadata；`CONVERTED` 表示已签约待开通，不创建租户，真实开通编排留在 M10-C。
|
|
|
|
## 审计日志与系统配置增量
|
|
|
|
| 方法 | 路径 | 权限与变更 |
|
|
|---|---|---|
|
|
| GET | `/admin-api/audit-logs` | `tenant.manage` 或平台管理权限；支持操作、资源类型、操作人、关键字、时间和分页筛选，默认 30 天、最长 366 天。响应掩码 IP，并递归过滤 token、密码、密钥、证书、手机号、OpenID、接收方和券码等 metadata。 |
|
|
| GET | `/admin-api/system/overview` | 返回目标租户基本信息、门店/用户/活动会话/应用绑定/当日审计计数和最新 schema 迁移；租户管理员只能读取本租户。 |
|
|
| PUT | `/admin-api/system/tenant` | 租户管理员可维护本租户名称和有效 IANA 时区；只有平台管理员可以显式指定其他 tenantId 或变更租户 `ACTIVE/DISABLED`，写入 `TENANT_SYSTEM_CONFIG_UPDATED` 审计。 |
|
|
|
|
平台管理员跨租户操作必须显式提供 `tenantId`，省略时仍只作用于其当前会话租户；分页参数在路由和仓储层双重钳制。
|
|
|
|
## 后台登录与可撤销会话增量
|
|
|
|
| 方法 | 路径 | 权限与变更 |
|
|
|---|---|---|
|
|
| POST | `/admin-api/auth/login` | 以租户代码、规范化登录名和密码登录；仅有效 STAFF 管理角色可用，连续失败 5 次锁定 15 分钟，成功/失败均留审计。每 IP 每分钟最多 10 次。 |
|
|
| POST | `/admin-api/auth/refresh` | 使用绑定 session UUID 的随机刷新令牌换取新访问/刷新令牌；数据库只保存 SHA-256，更新使用旧哈希条件保证单次轮换并拒绝重放。每 IP 每分钟最多 30 次。 |
|
|
| GET | `/admin-api/auth/me` | 返回脱敏当前用户和服务端计算的 roles、capabilities、storeIds、menus，不返回手机号和凭据。 |
|
|
| POST | `/admin-api/auth/logout` | 撤销当前服务端会话；后续访问令牌立即失效。 |
|
|
| PUT | `/admin-api/auth/credentials/:userId` | `tenant.manage` 或平台管理权限；为目标租户有效 STAFF 设置唯一登录名和强密码，密码最少 12 位且含字母、数字和特殊字符，更新后撤销该用户全部活动会话。 |
|
|
|
|
访问令牌保持现有 JWT 契约，刷新令牌不写明文数据库；Vue 客户端同一时刻只发起一次续期请求，续期或重试仍为 401 时清理本地会话并返回登录页。
|