platforms/docs/11-数据接口与安全.md

# 数据接口与安全规范

## 1. 核心数据域

### 数据模型强制约定

- 主表命名使用领域模块前缀，具体前缀以 [技术实现规划](10-技术实现规划.md) 的“数据模型与命名强制规范”为准；禁止跨模块使用无前缀的通用表名。
- 同一实体的数据库表、Go/Flutter/Vue 模型文件、模型类型和 OpenAPI/AsyncAPI Schema 必须使用相同的模块前缀与单数实体词根。例如 `org_gas_station`、`org_gas_station.go` 和 `OrgGasStation` 属于同一实体；禁止使用 `org_gas_stations`、`GasStations` 等复数或不同词根。
- 每个主表必须以 `identity` 字段作为 UUID V7 主键。所有关联字段使用 `<实体名>_identity` 命名，业务编号仅作展示和检索，不作为主键或跨表关联依据。
- 表、字段、索引、约束、枚举及接口模型必须有中文注释；涉及金额、单位、状态、定位、脱敏和留存的数据须在注释中明确口径。

| 数据域 | 核心实体 | 关键约束 |
| --- | --- | --- |
| 身份组织 | `idn_account`、`idn_role`、`idn_permission`、`org_gas_station`、`org_service_area`、`org_service_person`、`org_user_service_relation`、`org_invitation_qr_code`、`idn_emergency_contact` | 手机号/账号唯一；角色和数据范围均生效；紧急联系人授权范围、二维码归因和服务关系历史单独记录 |
| 设备 | `dev_device`、`dev_device_binding`、`dev_device_group`、`dev_cylinder`、`dev_telemetry`、`dev_command` | 设备序列号唯一；绑定有有效期与历史；命令含幂等键与回执；气瓶信息保留来源和有效期 |
| 安全 | `saf_rule`、`saf_event`、`saf_repair_request`、`saf_inspection`、`saf_rectification` | 事件编号唯一；等级、状态、SLA、证据、操作者完整可追溯；报修图片/定位需有采集时间 |
| 商品交易 | `cat_category`、`cat_product`、`cat_sku`、`cat_cart`、`cat_coupon`、`ord_order`、`ord_payment`、`ord_invoice` | 金额使用最小货币单位整数；库存扣减有事务/预占规则；预约时段、库存快照和开票状态可追溯 |
| 履约 | `ord_service_task`、`dsp_assignment`、`ord_delivery_track`、`dsp_delivery_track_point` | 任务状态转换受限；定位、轨迹和证据均有采集时间 |
| 资金与押金 | `wal_wallet_ledger`、`wal_deposit`、`wal_deposit_refund`、`wal_settlement`、`wal_withdrawal`、`wal_reconciliation` | `wal_wallet_ledger` 为唯一钱包事实流水；金额方向、关联对象和余额快照可校验；退押金保留验收、扣减和退款去向 |
| 用气统计 | `dev_usage_stat`、`dev_usage_report` | 明确统计周期、单位、来源、计算版本和最后更新时间；报表导出留痕 |
| 内容审计 | `cms_content`、`audit_operation_log` | 内容发布有版本；敏感维护操作的审计日志追加写入并设置留存期限 |

## 2. API 约定

- 外部 HTTP 接口采用 `/api/v1` 版本前缀，JSON 格式，UTC 时间 ISO 8601；金额传最小货币单位，枚举使用稳定代码。
- 写操作携带 `Idempotency-Key`；响应带 `request_id`；异步动作返回业务任务/命令 ID，而非伪造同步成功。
- 分页使用游标优先；敏感字段按角色脱敏；下载使用短效签名 URL 和用途审计。
- 错误码分为认证、权限、参数、状态冲突、限流、外部依赖和系统异常；前端不能依据错误文案判断流程。

### 关键接口族（逻辑级）

| 域 | 示例能力 |
| --- | --- |
| 认证 | 登录、验证码、令牌刷新、注销、协议同意、角色切换 |
| 设备 | 绑定/解绑申请、设备列表/详情、命令创建/查询、遥测历史、群组控制、气瓶信息、自动关闭时间、共享授权 |
| 安全 | 事件列表/详情、确认、派单、检查提交、整改提交、复检、规则管理、一键报修、紧急联系人与紧急通知 |
| 商城 | 商品/分类、购物车、优惠试算、气瓶预约订单、库存查询、支付、合同、售后、电子发票 |
| 履约 | 任务列表、接单、导航、到达、检查表、完成、异常、改派 |
| 配送轨迹 | 轨迹点上报、任务轨迹查询、用户简化轨迹查询、预计到达、轨迹异常和轨迹导出审批 |
| 资金与押金 | 充值、余额支付密码、流水、提现申请、押金汇总、退瓶退押金、审核、对账、结算 |
| 用气统计 | 月度/年度统计、报表明细、导出任务 |
| 邀请注册 | 邀请二维码创建/查询/停用、短链接解析、扫码校验、注册归因、气站/配送点服务关系建立 |

## 3. IoT 协议与可靠性

- 设备厂商 V1.8 二进制帧保持 `0x5E` 起始、`0x5B` 结束、大端序、数据包 AES-128 与 LRC8 规则不变，并作为 MQTT payload 传输；Topic 使用 `devices/{deviceId}/{up|down|ack}`，QoS 1，下行命令禁止 retained。
- `iot-server` 使用 Mochi MQTT v2 内嵌 Broker，只处理 MQTT 会话、每设备认证/Topic ACL 和设备协议；`iot-gateway` 是不保存业务事实的无状态上下行轻网关；命令、幂等、Outbox、原始上行和回执事实由 API 持久化，Worker 负责可重试投递。
- 协议封面版本与变更记录冲突时以最新 V1.8 变更记录和绿色标注为兼容实现依据；重复子标识等歧义必须保留原始报文并按设备型号配置解析，不得静默猜测。

- 设备采用 MQTT over TLS，设备身份使用每设备证书或短期轮换令牌；禁止共享默认密钥。
- 上行消息至少包含设备 ID、协议版本、消息 ID、设备时间、服务端接收时间、指标值、质量标记和固件版本。
- 下行命令包含命令 ID、幂等键、期望状态、过期时间、签名/鉴权信息；设备回传已收到、执行中、成功/失败与错误码。
- 规则计算以服务端接收时间为准并保留设备时间；乱序、重复、缺失遥测应有容错和告警策略。
- 自动关阀须优先在设备本地具备安全兜底逻辑，云端规则作为补充；网络中断不能成为失去基本安全保护的单点原因。

## 3.1 邀请注册二维码安全要求

- 二维码载荷仅为随机、签名且可撤销的邀请码或短链接，不得直接包含组织管理员身份、用户信息、地址、长期访问令牌或 API 密钥。
- 服务端解析后校验二维码状态、归属气站/配送点、有效期、使用次数、服务区域、风险策略和用户登录状态；所有校验均在服务端完成。
- 同一用户多次扫码不重复创建账户；服务关系的首次建立、变更和归因要有幂等键及完整审计。用户已有服务关系时，页面应告知影响并要求确认。
- 对二维码生成、下载、分享链接访问、扫码、注册、失败原因、停用和重新生成记录审计；支持按二维码、组织、人员和活动查询转化漏斗。
- 邀请短链接应具备 HTTPS、频率限制、反爬/风控校验和安全跳转白名单；二维码泄露后可由所属气站、配送点或平台立即停用。

## 3.2 配送轨迹数据与隐私要求

- 轨迹数据至少包括配送任务 ID、订单 ID、配送员 ID、定位时间、服务端接收时间、坐标、定位精度、来源、任务状态和完整性标记。位置点不可用订单创建时间替代。
- 客户端按后台配置的间隔、距离变化和状态节点采集；服务端进行去重、乱序校正、异常速度/精度标记和幂等写入。弱网补传保留原始定位时间和补传标记。
- 用户端只返回本人订单所需的简化轨迹、最近有效位置、预计到达和事件节点；配送点/气站/平台按组织和职责获取更详细数据。精确轨迹回放及导出应审批并记录用途。
- 轨迹属于敏感定位数据，传输与存储加密、最小化留存、访问审计；订单完结后按留存策略降精度展示或限制访问。严禁将配送员非履约时间的位置用于无关用途。

### 3.3 移动端离线、定位与现场证据要求

- 服务端 App 只有在任务执行期间可采集后台定位；定位权限撤销、后台运行受限、精度不足或长时间无位置时必须提示服务人员并向任务记录写入状态，不得伪造实时轨迹。
- 离线队列中的任务材料、定位点、照片/视频元数据、签名、扫描结果和收款确认必须本地加密。补传请求携带原始采集时间、服务端接收时间、`identity`、幂等键、来源和完整性标记；服务端按任务状态和证据哈希进行去重、乱序校正和冲突处置。
- 定位、签名和现场证据的采集开关、保留时长、可见角色、精度降级与导出权限由平台配置；客户端展示或本地删除不能绕过服务端留存、审计和安全事件证据义务。

### 3.4 服务端 App 工单、取证与结算要求

| 场景 | 核心实体 | 必要数据与规则 |
| --- | --- | --- |
| 人员准入与打卡 | `idn_service_person_credential`、`idn_service_person_vehicle`、`idn_service_person_check_in`、`saf_training_attempt` | 角色、证件有效期、车辆、上/下班位置、培训题目版本与结果必须可追溯；未通过准入/培训不可开始任务 |
| 安检与隐患 | `saf_inspection`、`saf_inspection_item_result`、`saf_inspection_photo`、`saf_user_signature`、`saf_hazard` | 检查项、风险等级、定位/时间水印、签名、隐患状态和整改证据绑定同一任务；高风险事件与关阀/通知动作关联 |
| 维修工单 | `ord_service_task`、`ord_repair_evidence`、`ord_repair_material`、`ord_repair_receipt` | 维修前中后证据、材料、价格快照、应收/实收、签字和支付差异可追溯；不能由服务人员修改订单定价 |
| 安装工单 | `ord_installation_condition`、`ord_installation_material`、`ord_installation_step`、`ord_installation_test`、`ord_installation_receipt` | 使用条件、备料、安装步骤、测试、前期安检、设备激活和收款按顺序记录；不合格或测试失败不能完成/激活 |
| 配送与回收 | `dsp_delivery_cylinder_scan`、`dsp_delivery_evidence`、`dsp_delivery_payment_confirmation`、`dsp_cylinder_return` | 气瓶/设备编码、蓝牙/扫码来源、随瓶安检照片视频、收款确认、空瓶回收、押金和库存状态均与配送任务关联 |
| 服务收入 | `wal_service_income`、`wal_withdrawal`、`wal_bank_card` | 收入由已完成且符合结算规则的任务生成；`wal_withdrawal` 是所有钱包提现的唯一实体，以可提现余额、银行卡验证、审核和打款回执为准 |

- 现场照片、视频、电子签字、蓝牙扫描、定位和收款确认属于取证数据。必须记录原始采集时间、服务端接收时间、任务、操作者、来源、完整性标记和对象存储哈希；客户端离线补传不得覆盖原始采集时间。
- 强制取证项由任务类型、设备型号、风险等级和组织规则确定。服务端在工单完成前校验必填检查项、照片/视频数量、签字、地理围栏、材料和支付状态，前端按钮禁用不能替代服务端校验。
- 收款、押金、退款和服务收入均以不可变流水为准。配送员/安装维修员仅能提交确认材料，不得创建、修改或删除资金事实；出现金额不一致、重复提交或离线补传冲突时进入对账异常。

## 4. 安全、隐私与合规

- 平台、气站和配送点三个受控管理后台的列表可以只读展示记录主键 `ID`，用于数据库问题定位；任何写操作、详情定位、关联选择、日志和跨服务传递仍统一使用 `identity`。服务端不得接受客户端指定新记录的 `id` 或 `identity`，创建时必须在逻辑层生成 UUID V7 `identity`。

- 登录令牌短期有效，刷新令牌可撤销；后台高权限账号启用 MFA、IP/设备策略。平台后台管理的平台、气站、配送、员工和业主账号密码按当前实施口径仅要求不少于 6 个字符，不附加复杂度校验。
- 用户端和工作人员端对受保护请求的 HTTP 401 及稳定鉴权失效业务码采用统一会话失效处理；并发失效只清理一次，迟到旧请求不得清除新会话。重新登录可恢复原站内页面，但任何产生副作用的写请求都不得自动重放。
- 用户端携带鉴权的请求遇到 HTTP 401 或鉴权业务码 `1301`—`1314`、`1715` 时，应按请求实际携带的令牌触发幂等会话失效；迟到的旧请求不得清除后来建立的新会话。客户端先清空内存状态并跳转登录，再尽力删除安全存储中的旧令牌。
- 登录前目标页只能保存为站内绝对路径，禁止接受带协议、主机、反斜杠、协议相对形式或登录/注册循环的跳转值。重新登录不得自动重放支付、下单、退款、工单等产生副作用的请求。
- 权限校验在服务端执行，前端菜单隐藏不构成权限控制。按角色、站点、区域、对象归属联合鉴权。
- 手机号、地址、身份证明、收款账户、定位、视频为敏感数据：传输 TLS、存储加密/字段加密、访问留痕、最小化留存。默认响应继续脱敏；仅已通过平台总后台 JWT 和对应菜单权限校验的管理员，可在用户、工作人员和平台账户的列表与详情中查看姓名、显示名称和主手机号明文。用户地址资源另设最小范围例外：仅 `/user_address` 的受控列表与详情接口可向具备对应菜单权限的平台管理员返回完整地址及经纬度，用于地址维护和编辑回填。配送订单联系人另设业务后台例外：平台订单详情可返回联系人姓名和联系电话明文；配送点后台的启用管理员可在严格限定当前配送点订单范围后，于列表和详情查看联系人快照明文。平台订单列表、气站端、用户端和工作人员端继续脱敏。上述例外不放宽身份证明、头像、资质编号或收款账户的脱敏规则。
- 所有支付回调验证签名与金额、订单、商户号一致性；合同文件使用可信第三方原文与哈希存证。渠道回调入口为 `/heqi/payment-return/v1/{alipay|wechat}/notify`，不使用用户 JWT；必须完成渠道证书验签、商户/appid、平台支付单号、金额、币种和状态校验后才可在数据库事务中推进业务。重复通知必须幂等，原始敏感报文只保存摘要。
- `payment_order` 是统一支付尝试事实；`payment_refund` 与 `payment_refund_item` 保存用户退款申请及明细。审批通过与钱包入账必须同事务完成。
- 图片/视频上传做文件类型、大小、病毒/恶意内容检测；访问采用短期授权，不使用公开桶。
- 设备控制、告警等级调整、资金审核、数据导出、账号注销等高风险操作要求二次确认和审计。

## 5. 备份与灾备

- PostgreSQL 至少每日全量、持续 WAL 归档并定期演练恢复；安全事件、订单和资金数据定义更严格 RPO/RTO。
- 对象存储启用版本/生命周期策略，合同和安全证据按合规期限留存；备份不得绕开数据加密和访问控制。
- 关键服务多实例部署，MQTT、数据库、消息队列和对象存储须有明确高可用方案和故障演练计划。

### 5.1 远程依赖与迁移安全

- 当前 API 按项目部署约定仅从对应 YAML 读取 PostgreSQL、Redis、字段加密密钥及支付/IoT 内部令牌，不接受环境变量覆盖。配置文件必须采用严格访问权限并由部署流程受控分发；不得出现在日志、测试报告或公开构建产物中。
- 远程 Redis 应使用 TLS；PostgreSQL 应启用服务端证书校验，并由部署环境限制来源网络。开发 Mock 验证码和 Mock 支付不得在生产配置启用。
- 资金、退款、支付及审计表不得由通用迁移命令直接删除。发现旧表时迁移必须中止，先完成数据盘点、备份、映射、双写或兼容读取方案，经财务和审计确认后执行专用迁移。
- 远程集成测试使用隔离数据库、独立 Redis DB/命名空间和测试前缀；不得清空共享实例，也不得物理删除资金、安全事件或审计事实作为清理手段。

## 6. 移动 Client API 安全实施约定

- 用户端和工作人员端分别使用 `user_app`、`service_app` JWT client claim；服务端逐请求校验 client、账户启用状态、岗位、组织和对象归属。
- 验证码由 `/auth/verification-code` 创建，Redis 保存五分钟、验证成功即删除，并按手机号及来源 IP 限流；响应只返回请求 `identity` 和有效期。开发 Mock 验证码从 `Global` 配置读取，生产必须关闭。
- 银行卡号、身份证号、预留手机号使用 `Global.FieldEncryptionKey` 经 HKDF 派生独立 AES-GCM 加密键和 HMAC 指纹键；接口列表只返回末四位掩码。开发占位密钥不得用于生产。
- 支付密码独立于登录密码，仅允许六位数字，使用 bcrypt 保存；连续失败达到阈值后在 Redis 短时锁定。绑卡、解绑、余额支付和提现均要求支付密码或限定用途的一次性验证码。
- 公共上传接口 `/upload/file` 必须携带平台、气站、配送点、用户或工作人员任一合法 JWT；图片/PDF 最大 10MB，视频上限从配置读取。上传只返回资源 URI，业务接口负责建立关联并记录操作者、采集与接收时间。
- 平台账户资料头像使用专用 `/upload/avatar` 上传入口，仅允许真实 JPG/PNG、最大 2MB、最大 4096×4096，并在服务端完成扩展名、MIME、尺寸和完整图片解码校验。后台头像读取通过 `/heqi/platform/v1/{staff_account|user_account|platform_account}/:identity/avatar` 受 JWT、菜单和对象角色权限保护；用户 App 仅可通过 `/heqi/client/v1/user/auth/avatar` 读取当前登录用户自己的头像。通用列表及详情响应继续移除 `avatar` 字段，头像文件目录不得作为公开静态目录。平台总后台的工作人员、用户和平台账户列表可对当前可视记录调用受控接口展示缩略图，必须限制并发、按页缓存、离页取消请求并释放本地 Blob URL。普通资料更新未提交 `avatar` 时保持原头像，只有明确上传或恢复默认头像时才修改该字段。
- 用户 App 地址维护的最小例外：`GET /heqi/client/v1/user/addresses` 仅在用户 JWT 和账户归属过滤后返回本人的完整地址、收货联系人、联系电话及坐标，供本人编辑和下单使用；App 列表遮蔽手机号中间四位。此例外不允许读取他人地址，也不改变订单列表、其他终端资源的脱敏规则。地址新增可携带 request_no 幂等号，编辑、归档及默认切换均先锁本账户并校验对象归属；归档保留历史订单快照。
- 充值、支付、提现、工单证据、轨迹点、内容确认等写入均携带幂等号；资金入账在数据库事务内锁定钱包并同时写不可变流水。
- 用户商城结算可提交 expected_payable_amount（整数分）作为报价确认，金额始终由数据库单价和数量计算。价格变化返回 2401 并回滚，库存不足或下架返回 2402。金额乘加先检查溢出；请求最多100项，每项1至999件。本人同请求号已创建订单优先恢复，不再依赖当前地址和库存；此行为不会返回他人订单。
- 用户商城订单的取消/收货动作由 allowed_actions 发布，客户端确认后提交，服务端锁定本人订单再校验。取消仅允许订单状态16，状态22重试不再返库存；收货仅允许订单状态18且物流20，物流30重试不覆盖首次收货时间。取消或退款中的订单不能凭旧物流状态确认收货。
- 用户工单列表兼容原数组与原字段，新增 `status_name`、`allowed_actions`，仅返回本人且未归档记录，移除内部主键。取消沿用既有32/18/11/21/34状态范围，22重复返回成功；确认仅允许34，23重复返回成功且不覆盖首次完成时间。两种动作在事务内锁定本人工单，其他用户、归档和非法状态均拒绝。App详情当前复用本人列表查询，不另外开放人员隐私或照片静态链接。
- 报修创建新增可选fault_type（leak/valve/alarm/other），contact_name/contact_phone由服务端从本人地址取快照，历史空联系人回退本人账户，不能任意提交他人地址。创建事务按账户串行；本人重复request_no返回首次工单，不因原地址已归档或预约时间已过而重复创建。首次创建拒绝空白描述、空白/过长请求号和过去预约时间。新增cs_ticket字段使用migrate-ticket-contact定向迁移，原接口兼容省略fault_type和address_identity。
- 报修照片使用用户JWT保护的POST ticket-photos，真实JPG/PNG、每张2MiB以内、4096像素边界，内容摘要绑定账户目录保证重复上传复用。POST tickets可附photos（最多3项，旧客户端允许省略），只关联本人已上传资源并与工单同事务；非法照片整体回滚。读取通过GET tickets/:identity/photos/:photoIdentity同时校验本人、工单和证据关联，返回private/no-store，禁止将ticket-photos文件夹映射为公开静态资源。
- 用户添加照片复用cs_ticket_evidence，evidence_type=reported、source=user_camera/user_gallery、integrity_status=capture_time_unknown。此类记录的captured_at暂存客户端添加时间，API明确输出added_at，不能被解释为已验证原始拍摄时间；longitude/latitude未采集则为空，不能伪造现场位置。后续原始时间/定位能力须保留来源和完整性标记，不能覆盖工作人员原有证据语义。
- 钱包可提现余额是当前总余额的子集，始终满足 `0 <= 可提现余额 <= 总余额`。普通消费扣减总余额后，必须同步把可提现余额限制在剩余总余额以内。
- 提现申请在同一数据库事务内锁定钱包、同时预扣总余额和可提现余额并写入不可变流水；驳回只返还该申请实际预扣的两类余额，完成打款只确认外部结果，不得再次扣款。
- 商品详情 `GET /heqi/client/v1/user/public/products/:identity` 为匿名只读接口，只读取启用且未删除商品及关联的启用图片/属性。售罄仍可查看，下架/不存在返回1112。响应白名单不包含内部主键或订单数据。详情价格不作为交易授权，结算重新读价，创建订单仍校验库存、报价、归属及幂等号。
- 收藏`GET shop/favorites`、`GET/PUT shop/favorites/items/:identity`均使用用户JWT。identity为商品公开标识；EcFavorite以(user_account_id,ec_product_id)唯一关联，取消设置status=3，已收藏status=1。PUT接受favorite布尔值及原revision，相同目标无写入，过期版本返回2404；版本为收藏UUID与正整数序号，每次状态变化递增。下架商品不允许新增收藏，但已收藏内容继续展示并允许取消；列表用available禁用加购，不伪造销量、优惠或规格。上限1000条有效收藏；所有字段和表有中文数据库注释。
- 推荐`GET shop/recommendations`要求用户JWT；参数source为cart（默认）或favorites，page为1至10000，page_size为1至20（默认2）。返回items、page、page_size、has_more；item字段为identity、name、price_amount（整数分）、stock_quantity、image_url、category_name。排除本人有效购物车、已删除/停用/无库存商品；favorites另排除本人有效收藏，同场景关联分类优先。账户ID只由JWT读取，不接收调用方传入；分类排序表名为固定枚举，图片/分类批量查询。接口只读，无数据库迁移或外部推荐服务。客户端丢弃跨账号迟到响应，加购继续使用原购物车条件版本接口。
- 商城订单详情`GET shop/orders/:identity`要求用户JWT，查询绑定订单公开identity与当前账户，跨账户与不存在均返回1112。只公开订单号、业务状态/允许动作、成交明细、收货联系人/地址快照、商品/优惠/应付整数分金额、实际支付/发货/收货时间、备注和物流公司/单号。明细名称及商品公开identity来自成交JSON快照，单价为sale_amount；不联查当前商品替换历史值，也不直接输出完整原始快照或内部主键。列表与详情共享shopOrderState动作定义，详情写操作仍复用原状态校验接口。没有已记录的付款时间时不显示“实付成功”，缺失资料不编造。
- 收藏列表支持既有page/page_size分页协议。状态写入按账户锁串行，不接受他人关系主键。客户端仅广播服务端已确认状态，若账号已切换则丢弃旧请求的迟到结果；取消收藏不影响购物车或订单。
- 购物车 `GET shop/cart`、`GET/PUT shop/cart/items/:identity` 均要求用户JWT，identity为商品公开标识；数据库按当前账户关联条目。PUT提交quantity（0—999）、selected和读取时的revision，零数量归档。相同目标重试不写入，过期目标返回2403；新增/增加数量受库存限制，最多100条有效商品。revision由购物车公开UUID和微秒精度更新时间构成，归档仍保留版本，旧重试不能复活已删除商品。全选/批量删除逐项提交，部分失败后重读真实状态。
- POST shop/orders可为每个item附cart_revision；服务端核对本人有效勾选条目的版本和数量，并在订单事务中归档，任何价格/库存/版本失败均回滚。多商品按公开identity固定顺序锁定，拒绝重复商品、零或负数量。金额仍为整数分，expected_payable_amount、request_no及旧单商品调用兼容；已创建请求优先返回原订单。未配置押金、优惠与配送费用时不将设计样例金额写入订单。
- `GET /heqi/client/v1/user/deposits` 只依据当前 JWT 用户查询押金汇总和明细，支持 `all/using/refunding/returned` 状态筛选；不接受客户端传入的用户标识。总后台 `/deposit_policy` 允许维护规则，`/deposit_record` 只读，避免后台通用表单直接改写资金事实。
- `POST /heqi/client/v1/user/deposit-returns` 只锁定本人使用中押金和本人完整地址，校验预约时段、四项确认与幂等号。后台退瓶处理按 `10待上门→20待验收→30待退款→40已完成` 单向流转；扣减不得超过原押金。退款时锁定钱包和押金记录，余额、押金状态、申请状态及不可变 `deposit_refund` 流水同事务提交。
- `GET /heqi/client/v1/user/gas/order-options` 只返回JWT用户有效供气合同下未被未完成订单占用的合同气瓶，以及服务端合同价、押金规则、本人地址和可预约时段。缺押金规则的规格必须返回明确不可下单原因，客户端不得推测金额。
- `POST /heqi/client/v1/user/gas/orders` 接收地址、合同气瓶公开标识集合、预约时间、客户端预期金额和幂等号；服务端重新校验归属、占用、价格、押金及金额后创建待支付订单。下单时以 `gasorder_deposit` 锁定每只气瓶的押金规则快照；余额或第三方支付成功后，在同一事务内生成 `deposit_record`。取消未支付订单同时释放气瓶占用并取消待支付押金快照。
- 报修草稿照片通过 `GET /heqi/client/v1/user/ticket-photos/:name` 读取；JWT校验后用当前账户构造文件目录，仅接受内容摘要文件名，不能由请求指定账户目录。响应禁止公开缓存。草稿在平台安全存储中按API地址和认证账户隔离，仅含表单、地址快照、照片URI和幂等号，不含令牌及图片字节。恢复不会自动提交；未知提交结果须沿用原请求号。删除草稿只清理本地记录，不删除可能已经关联工单的照片文件。