已完成用户APP首期功能开发

交付用户端首期页面、配套接口、后台资源及测试文档。用户APP构建、静态分析和三个管理后台构建通过；完整测试仍有2项失败，后端模型注释检查未通过，详见交付记录。

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

@@ -125,6 +125,25 @@
 - 支付密码独立于登录密码，仅允许六位数字，使用 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和幂等号，不含令牌及图片字节。恢复不会自动提交；未知提交结果须沿用原请求号。删除草稿只清理本地记录，不删除可能已经关联工单的照片文件。