diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/01-登录页.png b/doc/服务端APP-安全检查端-最新参考产品设计/01-登录页.png new file mode 100644 index 0000000..3700219 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/01-登录页.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/02-岗位申请.png b/doc/服务端APP-安全检查端-最新参考产品设计/02-岗位申请.png new file mode 100644 index 0000000..05a0d27 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/02-岗位申请.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/03-作业前检查.png b/doc/服务端APP-安全检查端-最新参考产品设计/03-作业前检查.png new file mode 100644 index 0000000..02f2e1a Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/03-作业前检查.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/04-准入阻断.png b/doc/服务端APP-安全检查端-最新参考产品设计/04-准入阻断.png new file mode 100644 index 0000000..d471f70 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/04-准入阻断.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/05-每日安全培训.png b/doc/服务端APP-安全检查端-最新参考产品设计/05-每日安全培训.png new file mode 100644 index 0000000..aa1ae59 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/05-每日安全培训.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/06-安检工作台.png b/doc/服务端APP-安全检查端-最新参考产品设计/06-安检工作台.png new file mode 100644 index 0000000..42e9a20 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/06-安检工作台.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/07-消息中心.png b/doc/服务端APP-安全检查端-最新参考产品设计/07-消息中心.png new file mode 100644 index 0000000..e4c213c Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/07-消息中心.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/08-安检任务列表.png b/doc/服务端APP-安全检查端-最新参考产品设计/08-安检任务列表.png new file mode 100644 index 0000000..3885582 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/08-安检任务列表.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/09-安检任务详情.png b/doc/服务端APP-安全检查端-最新参考产品设计/09-安检任务详情.png new file mode 100644 index 0000000..e0c6005 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/09-安检任务详情.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/10-到场与围栏校验.png b/doc/服务端APP-安全检查端-最新参考产品设计/10-到场与围栏校验.png new file mode 100644 index 0000000..9eba2c5 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/10-到场与围栏校验.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/11-用气设备清单.png b/doc/服务端APP-安全检查端-最新参考产品设计/11-用气设备清单.png new file mode 100644 index 0000000..3aa8e8c Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/11-用气设备清单.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/12-用气环境清单.png b/doc/服务端APP-安全检查端-最新参考产品设计/12-用气环境清单.png new file mode 100644 index 0000000..fdc07c5 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/12-用气环境清单.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/13-现场照片与视频.png b/doc/服务端APP-安全检查端-最新参考产品设计/13-现场照片与视频.png new file mode 100644 index 0000000..b6e3bf0 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/13-现场照片与视频.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/14-用户签名.png b/doc/服务端APP-安全检查端-最新参考产品设计/14-用户签名.png new file mode 100644 index 0000000..68f491a Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/14-用户签名.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/15-合格结果确认.png b/doc/服务端APP-安全检查端-最新参考产品设计/15-合格结果确认.png new file mode 100644 index 0000000..c281062 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/15-合格结果确认.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/16-不合格与风险分级.png b/doc/服务端APP-安全检查端-最新参考产品设计/16-不合格与风险分级.png new file mode 100644 index 0000000..bad47ce Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/16-不合格与风险分级.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/17-一级高风险处置.png b/doc/服务端APP-安全检查端-最新参考产品设计/17-一级高风险处置.png new file mode 100644 index 0000000..ea89a54 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/17-一级高风险处置.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/18-整改通知单.png b/doc/服务端APP-安全检查端-最新参考产品设计/18-整改通知单.png new file mode 100644 index 0000000..8be5b56 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/18-整改通知单.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/19-安检完成.png b/doc/服务端APP-安全检查端-最新参考产品设计/19-安检完成.png new file mode 100644 index 0000000..0227b37 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/19-安检完成.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/20-隐患列表.png b/doc/服务端APP-安全检查端-最新参考产品设计/20-隐患列表.png new file mode 100644 index 0000000..db6412c Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/20-隐患列表.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/21-隐患详情.png b/doc/服务端APP-安全检查端-最新参考产品设计/21-隐患详情.png new file mode 100644 index 0000000..e6244fb Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/21-隐患详情.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/22-整改任务.png b/doc/服务端APP-安全检查端-最新参考产品设计/22-整改任务.png new file mode 100644 index 0000000..b86509c Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/22-整改任务.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/23-复检执行.png b/doc/服务端APP-安全检查端-最新参考产品设计/23-复检执行.png new file mode 100644 index 0000000..a55bf65 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/23-复检执行.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/24-用户拒检记录.png b/doc/服务端APP-安全检查端-最新参考产品设计/24-用户拒检记录.png new file mode 100644 index 0000000..2d9cfd8 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/24-用户拒检记录.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/25-区域抽查地图.png b/doc/服务端APP-安全检查端-最新参考产品设计/25-区域抽查地图.png new file mode 100644 index 0000000..6d6e6f3 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/25-区域抽查地图.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/26-安检记录.png b/doc/服务端APP-安全检查端-最新参考产品设计/26-安检记录.png new file mode 100644 index 0000000..dcc410c Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/26-安检记录.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/27-安检记录详情.png b/doc/服务端APP-安全检查端-最新参考产品设计/27-安检记录详情.png new file mode 100644 index 0000000..60d58bb Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/27-安检记录详情.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/28-统计看板.png b/doc/服务端APP-安全检查端-最新参考产品设计/28-统计看板.png new file mode 100644 index 0000000..43bf423 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/28-统计看板.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/29-钱包.png b/doc/服务端APP-安全检查端-最新参考产品设计/29-钱包.png new file mode 100644 index 0000000..2704bff Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/29-钱包.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/30-提现申请与记录.png b/doc/服务端APP-安全检查端-最新参考产品设计/30-提现申请与记录.png new file mode 100644 index 0000000..2d9fc81 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/30-提现申请与记录.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/31-银行卡管理.png b/doc/服务端APP-安全检查端-最新参考产品设计/31-银行卡管理.png new file mode 100644 index 0000000..8915331 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/31-银行卡管理.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/32-离线草稿与冲突.png b/doc/服务端APP-安全检查端-最新参考产品设计/32-离线草稿与冲突.png new file mode 100644 index 0000000..6aa8181 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/32-离线草稿与冲突.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/33-个人中心.png b/doc/服务端APP-安全检查端-最新参考产品设计/33-个人中心.png new file mode 100644 index 0000000..fd73b43 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/33-个人中心.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/34-个人资料与资质.png b/doc/服务端APP-安全检查端-最新参考产品设计/34-个人资料与资质.png new file mode 100644 index 0000000..00310ce Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/34-个人资料与资质.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/35-推荐二维码.png b/doc/服务端APP-安全检查端-最新参考产品设计/35-推荐二维码.png new file mode 100644 index 0000000..56b5f8c Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/35-推荐二维码.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/36-设置与通知.png b/doc/服务端APP-安全检查端-最新参考产品设计/36-设置与通知.png new file mode 100644 index 0000000..0cbe749 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/36-设置与通知.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/37-服务支持中心.png b/doc/服务端APP-安全检查端-最新参考产品设计/37-服务支持中心.png new file mode 100644 index 0000000..aa84ad5 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/37-服务支持中心.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/38-安检知识库与视频教程.png b/doc/服务端APP-安全检查端-最新参考产品设计/38-安检知识库与视频教程.png new file mode 100644 index 0000000..1d6507a Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/38-安检知识库与视频教程.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/39-远程专家会诊.png b/doc/服务端APP-安全检查端-最新参考产品设计/39-远程专家会诊.png new file mode 100644 index 0000000..2d54a10 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/39-远程专家会诊.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/40-问题反馈与投诉.png b/doc/服务端APP-安全检查端-最新参考产品设计/40-问题反馈与投诉.png new file mode 100644 index 0000000..5c89ed3 Binary files /dev/null and b/doc/服务端APP-安全检查端-最新参考产品设计/40-问题反馈与投诉.png differ diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/产品设计说明_安全检查端APP_v1.0.md b/doc/服务端APP-安全检查端-最新参考产品设计/产品设计说明_安全检查端APP_v1.0.md new file mode 100644 index 0000000..e2c83d3 --- /dev/null +++ b/doc/服务端APP-安全检查端-最新参考产品设计/产品设计说明_安全检查端APP_v1.0.md @@ -0,0 +1,95 @@ +# 安全检查端 APP 最新产品设计说明 v1.0 + +## 1. 文档定位 + +本目录 40 张 PNG 是安全检查端目标产品设计。设计依据为原安全检查端产品图、当前 `apps/service_app` ticket 能力、服务端 App 需求、核心安检与整改复检流程。图片是后续开发与验收基准，不代表当前接口和页面已经全部完成。 + +## 2. 设计原则 + +- 保留任务、检查、取证、签名、隐患、风险分级、整改、复检、拒检、记录、钱包和个人中心能力。 +- 主色 `#2563EB`，背景 `#F7F8FA`，成功绿色、提醒橙色、一级高风险红色；禁止紫色及紫色渐变。 +- 不使用 AI 元素、AI 助手、聊天机器人或相关说明文案；远程会诊仅指人工专家协同。 +- 使用正式、简洁、易扫描的移动端布局；统一 20px 边距、最大 8px 圆角、细描边和标准图标。 +- 一级高风险必须先现场管控、通知抢险并完成移交；客户端不能自行关闭高风险隐患。 +- 拒检只记录事实和证据，不得伪造合格或不合格结果。 +- 证据、签名与检查数据离线加密，服务端确认成功后才改变最终状态。 + +## 3. 页面清单 + +| 编号 | 页面 | 核心功能 | +| --- | --- | --- | +| 01 | 登录页 | 账号密码登录、协议确认 | +| 02 | 岗位申请 | 安检员岗位、区域、组织与资质申请 | +| 03 | 作业前检查 | 出勤、资质、培训、设备、定位和网络 | +| 04 | 准入阻断 | 资质、打卡、培训和设备阻断处理 | +| 05 | 每日安全培训 | 必修题目、学习进度和结果留痕 | +| 06 | 安检工作台 | 今日任务、复检、高风险和快捷入口 | +| 07 | 消息中心 | 任务、安全、整改、复检和结算消息 | +| 08 | 安检任务列表 | 待安检、进行中、待复检、完成筛选 | +| 09 | 安检任务详情 | 用户、地址、范围、历史和作业要求 | +| 10 | 到场与围栏校验 | 导航、距离、定位精度与到场确认 | +| 11 | 用气设备清单 | 表阀、管道、灶具、热水器和检漏 | +| 12 | 用气环境清单 | 通风、周边、烟道、报警器和取证 | +| 13 | 现场照片与视频 | 必拍项、问题证据、时间与定位水印 | +| 14 | 用户签名 | 结果告知、确认事项和手写签名 | +| 15 | 合格结果确认 | 合格汇总、记录单、通知和完成 | +| 16 | 不合格与风险分级 | 一级、二级、三级风险和整改要求 | +| 17 | 一级高风险处置 | 关阀、通风、疏散、警戒、抢险移交 | +| 18 | 整改通知单 | 隐患、期限、要求、签名与送达状态 | +| 19 | 安检完成 | 记录、隐患、整改单和复检任务归档 | +| 20 | 隐患列表 | 风险、逾期、整改和复检筛选 | +| 21 | 隐患详情 | 证据、要求、进度、用户与关联任务 | +| 22 | 整改任务 | 用户资料、初审、联系和复检安排 | +| 23 | 复检执行 | 前后对比、复检项、测量、证据和结论 | +| 24 | 用户拒检记录 | 原因、联系、证据、见证人和改约 | +| 25 | 区域抽查地图 | 模糊点位、路线、风险和抽查任务 | +| 26 | 安检记录 | 合格、隐患、拒检和历史筛选 | +| 27 | 安检记录详情 | 时间线、结果、证据、文档和隐患进度 | +| 28 | 统计看板 | 安检量、合格率、风险、复检与质量 | +| 29 | 钱包 | 安检、复检、奖励和收支明细 | +| 30 | 提现申请与记录 | 金额、银行卡、手续费与提现状态 | +| 31 | 银行卡管理 | 实名卡片、新增、解绑和安全校验 | +| 32 | 离线草稿与冲突 | 检查项、证据、附件、版本和同步 | +| 33 | 个人中心 | 资料、钱包、工具、支持和设置入口 | +| 34 | 个人资料与资质 | 安检员、组织、证照、能力和到期提醒 | +| 35 | 推荐二维码 | 官方安检预约二维码与使用记录 | +| 36 | 设置与通知 | 任务、隐患、复检、高风险、权限和账号 | +| 37 | 服务支持中心 | 人工客服、安检中心、抢险电话和请求 | +| 38 | 安检知识库与视频教程 | 规范、案例、视频、法规和学习进度 | +| 39 | 远程专家会诊 | 人工专家视频、语音、资料和意见留痕 | +| 40 | 问题反馈与投诉 | 功能、数据、结算、投诉和附件提交 | + +## 4. 当前实现对照 + +| 范围 | 当前状态 | 后续开发要求 | +| --- | --- | --- | +| 登录与角色 | 已有真实登录与角色识别 | 补岗位申请、审核与资质状态 | +| 作业前检查 | 已有 `/preflight` 与考勤 | 补安检设备自检、培训、阻断细项与处理入口 | +| 安检任务 | 已有 ticket 列表、详情、开始、异常、恢复 | 补安检专用字段、围栏、设备与环境清单、拒检和复检状态机 | +| 取证与提交 | 已有图片证据、结果提交和加密草稿 | 补视频、用户签名、风险分级、整改单、隐患与复检闭环 | +| 钱包 | 已有钱包查询 | 补安检收入、提现、银行卡和结算状态 | +| 记录与统计 | 仅有通用记录入口 | 补完整记录、关联隐患、统计、导出和抽查地图 | +| 个人中心 | 已有基础资料和草稿入口 | 补资质、知识库、人工支持、二维码、会诊和反馈 | + +## 5. 风险与状态机要求 + +- 延续 `/heqi/client/v1/staff/tickets` 现有接口，不修改已有字段语义。 +- 安检状态建议覆盖：待到场、执行中、待签名、待评定、已完成、异常暂停、拒检、待整改、待复检、已关闭。 +- 风险分级固定为：一级高风险立即处置，二级中风险限期整改，三级低风险提出建议。 +- 一级高风险的关阀、通风、疏散、警戒、通知和移交均需单独时间戳和证据；未完成移交不能结束任务。 +- 每个检查项保存结果、说明、测量值、照片、视频、操作者、设备时间和服务端时间。 +- 整改通知单、隐患和复检任务必须由同一服务端事务关联，避免重复或孤立记录。 +- 拒检需要原因、联系记录、现场证据、见证信息和后续安排，结果字段保持为空。 +- 区域地图仅显示业务所需的模糊点位，进入任务详情后再按权限查看精确地址。 + +## 6. 验收重点 + +- 40 个页面和安检主链路可连续操作，正常、隐患、一级高风险、拒检和离线分支完整。 +- 设备、环境、取证、签名、风险、整改单、隐患和复检数据前后一致。 +- 一级高风险不能被普通完成动作绕过；安全通知不能被用户关闭。 +- 复检通过后才能关闭隐患，资料初审不得代替现场复检。 +- Android 常用尺寸下无文字遮挡、越界和底部导航覆盖。 + +## 7. 图片校对方式 + +图片按编号即业务顺序。修改时直接指出“文件名 + 位置 + 期望内容”，所有调整继续保存在本目录，不覆盖原产品设计。 diff --git a/doc/服务端APP-安全检查端-最新参考产品设计/操作日志_安全检查端APP产品设计优化_20260906.md b/doc/服务端APP-安全检查端-最新参考产品设计/操作日志_安全检查端APP产品设计优化_20260906.md new file mode 100644 index 0000000..76dcce0 --- /dev/null +++ b/doc/服务端APP-安全检查端-最新参考产品设计/操作日志_安全检查端APP产品设计优化_20260906.md @@ -0,0 +1,19 @@ +# 安全检查端 APP 产品设计优化操作日志 + +操作时间：2026-09-06 + +操作类型：新增 + +影响模块：服务端 APP 安全检查岗位产品设计 + +操作前状态：原安全检查端界面包含紫色主题和旧式布局，安检、隐患、整改、复检、拒检与高风险处置链路不完整；当前客户端只实现通用 ticket 列表、详情、开始、异常、恢复、结果提交和证据草稿的部分能力。 + +具体操作：在新目录中生成 40 张目标产品设计图，补齐准入、任务、到场、设备、环境、取证、签名、合格、不合格、风险分级、一级高风险、整改、复检、拒检、地图、记录、钱包、离线、资质、人工支持、知识库、人工专家和反馈页面。 + +操作后状态：原目录未修改；最新目录可独立用于逐页评审和后续开发。 + +代码变更：本次未修改业务代码，仅新增产品设计图片与 Markdown 文档。 + +验证结果：PNG 数量 40；图片可读取；文件名按业务顺序编号；未使用紫色与 AI 元素。 + +风险评估：设计包含尚未实现的目标能力；开发时必须重点验证一级高风险强制流程、隐患事务一致性、拒检真实性、复检关闭条件和离线证据同步。 diff --git a/doc/服务端APP-安装端-最新参考产品设计/01-登录页.png b/doc/服务端APP-安装端-最新参考产品设计/01-登录页.png new file mode 100644 index 0000000..3700219 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/01-登录页.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/02-岗位申请.png b/doc/服务端APP-安装端-最新参考产品设计/02-岗位申请.png new file mode 100644 index 0000000..1619d3e Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/02-岗位申请.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/03-作业前检查.png b/doc/服务端APP-安装端-最新参考产品设计/03-作业前检查.png new file mode 100644 index 0000000..a00fdd8 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/03-作业前检查.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/04-准入阻断.png b/doc/服务端APP-安装端-最新参考产品设计/04-准入阻断.png new file mode 100644 index 0000000..898a0b2 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/04-准入阻断.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/05-每日安全培训.png b/doc/服务端APP-安装端-最新参考产品设计/05-每日安全培训.png new file mode 100644 index 0000000..aa1ae59 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/05-每日安全培训.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/06-安装维修工作台.png b/doc/服务端APP-安装端-最新参考产品设计/06-安装维修工作台.png new file mode 100644 index 0000000..e56994a Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/06-安装维修工作台.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/07-消息中心.png b/doc/服务端APP-安装端-最新参考产品设计/07-消息中心.png new file mode 100644 index 0000000..755a729 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/07-消息中心.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/08-工单列表.png b/doc/服务端APP-安装端-最新参考产品设计/08-工单列表.png new file mode 100644 index 0000000..15fc90a Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/08-工单列表.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/09-新装工单详情.png b/doc/服务端APP-安装端-最新参考产品设计/09-新装工单详情.png new file mode 100644 index 0000000..1906464 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/09-新装工单详情.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/10-维修工单详情.png b/doc/服务端APP-安装端-最新参考产品设计/10-维修工单详情.png new file mode 100644 index 0000000..a532e14 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/10-维修工单详情.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/11-使用条件确认.png b/doc/服务端APP-安装端-最新参考产品设计/11-使用条件确认.png new file mode 100644 index 0000000..73a9ca6 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/11-使用条件确认.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/12-条件不合格与整改.png b/doc/服务端APP-安装端-最新参考产品设计/12-条件不合格与整改.png new file mode 100644 index 0000000..433edf5 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/12-条件不合格与整改.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/13-准备材料.png b/doc/服务端APP-安装端-最新参考产品设计/13-准备材料.png new file mode 100644 index 0000000..ef5f9e9 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/13-准备材料.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/14-执行安装与取证.png b/doc/服务端APP-安装端-最新参考产品设计/14-执行安装与取证.png new file mode 100644 index 0000000..d88b66b Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/14-执行安装与取证.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/15-安装测试.png b/doc/服务端APP-安装端-最新参考产品设计/15-安装测试.png new file mode 100644 index 0000000..2e8868a Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/15-安装测试.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/16-测试失败处理.png b/doc/服务端APP-安装端-最新参考产品设计/16-测试失败处理.png new file mode 100644 index 0000000..358ac65 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/16-测试失败处理.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/17-前期安检.png b/doc/服务端APP-安装端-最新参考产品设计/17-前期安检.png new file mode 100644 index 0000000..c6014f6 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/17-前期安检.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/18-用户签名.png b/doc/服务端APP-安装端-最新参考产品设计/18-用户签名.png new file mode 100644 index 0000000..4ef3845 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/18-用户签名.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/19-收款确认.png b/doc/服务端APP-安装端-最新参考产品设计/19-收款确认.png new file mode 100644 index 0000000..920ffc9 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/19-收款确认.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/20-安装完成.png b/doc/服务端APP-安装端-最新参考产品设计/20-安装完成.png new file mode 100644 index 0000000..77b4df4 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/20-安装完成.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/21-维修执行与取证.png b/doc/服务端APP-安装端-最新参考产品设计/21-维修执行与取证.png new file mode 100644 index 0000000..cadb9d7 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/21-维修执行与取证.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/22-维修安全检查.png b/doc/服务端APP-安装端-最新参考产品设计/22-维修安全检查.png new file mode 100644 index 0000000..f6b935e Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/22-维修安全检查.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/23-异常上报与恢复.png b/doc/服务端APP-安装端-最新参考产品设计/23-异常上报与恢复.png new file mode 100644 index 0000000..241cecf Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/23-异常上报与恢复.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/24-巡检及复检任务.png b/doc/服务端APP-安装端-最新参考产品设计/24-巡检及复检任务.png new file mode 100644 index 0000000..d00047d Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/24-巡检及复检任务.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/25-作业记录.png b/doc/服务端APP-安装端-最新参考产品设计/25-作业记录.png new file mode 100644 index 0000000..f7ad461 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/25-作业记录.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/26-记录详情.png b/doc/服务端APP-安装端-最新参考产品设计/26-记录详情.png new file mode 100644 index 0000000..87066eb Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/26-记录详情.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/27-统计看板.png b/doc/服务端APP-安装端-最新参考产品设计/27-统计看板.png new file mode 100644 index 0000000..73b0b18 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/27-统计看板.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/28-钱包.png b/doc/服务端APP-安装端-最新参考产品设计/28-钱包.png new file mode 100644 index 0000000..7e34c67 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/28-钱包.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/29-提现申请与记录.png b/doc/服务端APP-安装端-最新参考产品设计/29-提现申请与记录.png new file mode 100644 index 0000000..2d9fc81 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/29-提现申请与记录.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/30-银行卡管理.png b/doc/服务端APP-安装端-最新参考产品设计/30-银行卡管理.png new file mode 100644 index 0000000..8915331 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/30-银行卡管理.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/31-离线草稿与同步记录.png b/doc/服务端APP-安装端-最新参考产品设计/31-离线草稿与同步记录.png new file mode 100644 index 0000000..b37a2d4 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/31-离线草稿与同步记录.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/32-个人中心.png b/doc/服务端APP-安装端-最新参考产品设计/32-个人中心.png new file mode 100644 index 0000000..a2f2997 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/32-个人中心.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/33-个人资料与资质.png b/doc/服务端APP-安装端-最新参考产品设计/33-个人资料与资质.png new file mode 100644 index 0000000..21a1b72 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/33-个人资料与资质.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/34-推荐二维码.png b/doc/服务端APP-安装端-最新参考产品设计/34-推荐二维码.png new file mode 100644 index 0000000..af58d33 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/34-推荐二维码.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/35-设置与通知.png b/doc/服务端APP-安装端-最新参考产品设计/35-设置与通知.png new file mode 100644 index 0000000..8df33d1 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/35-设置与通知.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/36-服务支持中心.png b/doc/服务端APP-安装端-最新参考产品设计/36-服务支持中心.png new file mode 100644 index 0000000..bdca8c8 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/36-服务支持中心.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/37-维修知识库与视频教程.png b/doc/服务端APP-安装端-最新参考产品设计/37-维修知识库与视频教程.png new file mode 100644 index 0000000..8f28211 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/37-维修知识库与视频教程.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/38-远程专家会诊.png b/doc/服务端APP-安装端-最新参考产品设计/38-远程专家会诊.png new file mode 100644 index 0000000..6ed7f3a Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/38-远程专家会诊.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/39-备件领用.png b/doc/服务端APP-安装端-最新参考产品设计/39-备件领用.png new file mode 100644 index 0000000..475e269 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/39-备件领用.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/40-电子保修卡与用户回访.png b/doc/服务端APP-安装端-最新参考产品设计/40-电子保修卡与用户回访.png new file mode 100644 index 0000000..d54b2a2 Binary files /dev/null and b/doc/服务端APP-安装端-最新参考产品设计/40-电子保修卡与用户回访.png differ diff --git a/doc/服务端APP-安装端-最新参考产品设计/产品设计说明_安装维修端APP_v1.0.md b/doc/服务端APP-安装端-最新参考产品设计/产品设计说明_安装维修端APP_v1.0.md new file mode 100644 index 0000000..dc6b0dd --- /dev/null +++ b/doc/服务端APP-安装端-最新参考产品设计/产品设计说明_安装维修端APP_v1.0.md @@ -0,0 +1,92 @@ +# 安装维修端 APP 最新产品设计说明 v1.0 + +## 1. 文档定位 + +本目录 40 张 PNG 是安装维修端的目标产品设计，供后续 Flutter 页面、交互和接口开发使用。设计依据包括原安装端产品图、当前 `apps/service_app` 实现、服务端 App 需求与核心业务流程文档。图片表示目标状态，不代表当前代码已经完成对应功能。 + +## 2. 设计原则 + +- 保留现有安装、维修、巡检、复检、取证、签名、收款、钱包和个人中心等业务能力，不因 UI 优化删除功能。 +- 主色为 `#2563EB`，背景为 `#F7F8FA`；绿色用于成功，橙色用于提醒，红色用于高风险与失败。 +- 禁止紫色、紫蓝渐变、AI 图形、AI 助手、聊天机器人和相关文案。 +- 页面采用正式、简洁、可扫描的移动端布局；统一 20px 页面边距、最大 8px 圆角、细描边和标准图标。 +- 高风险操作、收款、结算、任务完成以服务端最终确认结果为准；客户端重复提交必须幂等。 +- 现场照片、视频与签名先加密保存，离线时进入草稿队列，成功同步前不得视为已提交。 + +## 3. 页面清单 + +| 编号 | 页面 | 核心功能 | +| --- | --- | --- | +| 01 | 登录页 | 账号密码登录、环境切换提示、协议确认 | +| 02 | 岗位申请 | 安装维修员岗位、组织、资质材料申请 | +| 03 | 作业前检查 | 出勤、资质、工具、定位、网络检查 | +| 04 | 准入阻断 | 展示阻断原因并引导逐项处理 | +| 05 | 每日安全培训 | 必修题目、进度、结果留痕 | +| 06 | 安装维修工作台 | 今日任务、统计、快捷入口、风险提醒 | +| 07 | 消息中心 | 工单、安全、系统与结算消息 | +| 08 | 工单列表 | 新装、维修、巡检、复检筛选与搜索 | +| 09 | 新装工单详情 | 用户、地址、计划、材料与作业要求 | +| 10 | 维修工单详情 | 故障描述、历史记录、风险与执行入口 | +| 11 | 使用条件确认 | 场地、管线、通风、电源等条件核验 | +| 12 | 条件不合格与整改 | 不合格项、证据、整改要求与改约 | +| 13 | 准备材料 | 材料清单、库存、缺件与领用 | +| 14 | 执行安装与取证 | 安装步骤、过程照片与离线暂存 | +| 15 | 安装测试 | 气密、点火、压力和运行测试 | +| 16 | 测试失败处理 | 失败项、异常上报、返工和终止 | +| 17 | 前期安检 | 安装前设备与环境安全检查 | +| 18 | 用户签名 | 结果告知、手写签名与时间留痕 | +| 19 | 收款确认 | 应收、已付、线下凭证与对账 | +| 20 | 安装完成 | 记录归档、保修卡、回访和下一任务 | +| 21 | 维修执行与取证 | 故障处理步骤、前中后取证 | +| 22 | 维修安全检查 | 修复后检漏、试运行与风险确认 | +| 23 | 异常上报与恢复 | 异常原因、证据、暂停、恢复与幂等 | +| 24 | 巡检及复检任务 | 巡检、整改复检与计划安排 | +| 25 | 作业记录 | 历史作业筛选、状态和结果 | +| 26 | 记录详情 | 完整时间线、证据、签名与文档 | +| 27 | 统计看板 | 作业量、准时率、质量和收入趋势 | +| 28 | 钱包 | 余额、收入分类与收支明细 | +| 29 | 提现申请与记录 | 提现金额、银行卡、手续费与状态 | +| 30 | 银行卡管理 | 实名卡片、新增、解绑和安全校验 | +| 31 | 离线草稿与同步记录 | 草稿、附件、冲突和同步结果 | +| 32 | 个人中心 | 个人、钱包、工具、支持与设置入口 | +| 33 | 个人资料与资质 | 组织、服务区域、证照与到期提醒 | +| 34 | 推荐二维码 | 官方服务申请二维码与使用记录 | +| 35 | 设置与通知 | 通知、权限、离线保护和账号安全 | +| 36 | 服务支持中心 | 人工客服、组织电话、服务请求和 FAQ | +| 37 | 维修知识库与视频教程 | 规范、案例、视频和学习进度 | +| 38 | 远程专家会诊 | 人工专家视频、语音、资料和意见留痕 | +| 39 | 备件领用 | 备件申请、扫码、库存与归还 | +| 40 | 电子保修卡与用户回访 | 保修范围、状态、回访和服务记录 | + +## 4. 当前实现对照 + +| 范围 | 当前状态 | 后续开发要求 | +| --- | --- | --- | +| 登录与角色 | 已有真实登录与角色识别 | 补岗位申请、审核状态与异常提示 | +| 作业前检查 | 已有 `/preflight` 与考勤调用 | 补培训、资质到期、工具设备细项与阻断引导 | +| 工单列表与详情 | 已有 ticket 列表、详情、开始、异常、恢复 | 按 08 至 24 页面拆分状态机和专用表单 | +| 取证与提交 | 已有证据上传、结果提交和加密草稿 | 补视频、签名、材料、测试、收款、失败恢复与冲突处理 | +| 钱包 | 已有钱包查询 | 补明细、提现、银行卡管理和服务端审核状态 | +| 记录与统计 | 仅有通用记录入口 | 补记录详情、筛选、统计指标与导出 | +| 个人中心 | 已有基础资料和草稿入口 | 补资质、知识库、人工支持、二维码、备件、保修与回访 | + +## 5. 关键接口与数据要求 + +- 继续复用 `/heqi/client/v1/staff` 根路径和现有身份模型，不破坏既有接口。 +- 新增接口应按岗位权限返回可见字段，禁止客户端自行推断高风险结果、结算结果或任务完成状态。 +- 工单操作至少包含 `start`、`exception`、`recover`、条件核验、材料领用、过程取证、测试、签名、收款、结果提交和完成确认。 +- 每次状态变更携带幂等键、设备标识、定位、客户端时间和版本号；服务端返回最终状态与可执行动作。 +- 证据对象需要类型、文件哈希、拍摄时间、定位、任务编号、上传状态和服务端文件标识。 +- 离线草稿采用本地加密、分片重试、冲突比较和用户可见的同步结果。 + +## 6. 验收重点 + +- 40 个页面功能入口、状态文案和返回路径完整。 +- 正常、阻断、失败、离线、冲突、重复提交和服务端拒绝均有明确界面反馈。 +- 安装、维修、巡检、复检四类任务不会共用错误字段或错误流程。 +- 金额、签名、取证、风险和完成状态均以后端确认结果为准。 +- Android 常用尺寸下无文字遮挡、越界、按钮错位或底部导航覆盖。 + +## 7. 图片校对方式 + +图片按编号即业务顺序。修改时以“文件名 + 位置 + 期望内容”提出，避免覆盖旧产品设计目录。 diff --git a/doc/服务端APP-安装端-最新参考产品设计/操作日志_安装维修端APP产品设计优化_20260906.md b/doc/服务端APP-安装端-最新参考产品设计/操作日志_安装维修端APP产品设计优化_20260906.md new file mode 100644 index 0000000..1dcaba6 --- /dev/null +++ b/doc/服务端APP-安装端-最新参考产品设计/操作日志_安装维修端APP产品设计优化_20260906.md @@ -0,0 +1,19 @@ +# 安装维修端 APP 产品设计优化操作日志 + +操作时间：2026-09-06 + +操作类型：新增 + +影响模块：服务端 APP 安装维修岗位产品设计 + +操作前状态：原产品设计存在旧式页面、紫色元素、部分流程缺页；当前 Flutter 客户端仅覆盖通用登录、准入、任务、取证、记录和个人中心的部分能力。 + +具体操作：在新目录中生成 40 张目标产品设计图，统一视觉系统，补齐安装、维修、巡检、复检、取证、测试、签名、收款、离线、钱包、人工支持、备件与保修回访页面；新增开发对照说明。 + +操作后状态：原目录未修改；最新目录可独立用于逐页评审和后续开发。 + +代码变更：本次未修改业务代码，仅新增产品设计图片与 Markdown 文档。 + +验证结果：PNG 数量 40；图片可读取；文件名按业务顺序编号；未使用紫色与 AI 元素。 + +风险评估：图片为目标状态，部分接口和页面尚未实现；开发时必须以服务端状态机和接口返回为准，并补充异常、离线和幂等测试。 diff --git a/doc/服务端APP-配送端-最新参考产品设计/01-登录页.png b/doc/服务端APP-配送端-最新参考产品设计/01-登录页.png new file mode 100644 index 0000000..3700219 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/01-登录页.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/02-岗位申请.png b/doc/服务端APP-配送端-最新参考产品设计/02-岗位申请.png new file mode 100644 index 0000000..0382c1f Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/02-岗位申请.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/03-作业前检查.png b/doc/服务端APP-配送端-最新参考产品设计/03-作业前检查.png new file mode 100644 index 0000000..71e6cd9 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/03-作业前检查.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/04-准入阻断.png b/doc/服务端APP-配送端-最新参考产品设计/04-准入阻断.png new file mode 100644 index 0000000..b3e638f Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/04-准入阻断.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/05-每日安全培训.png b/doc/服务端APP-配送端-最新参考产品设计/05-每日安全培训.png new file mode 100644 index 0000000..3e01918 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/05-每日安全培训.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/06-配送工作台.png b/doc/服务端APP-配送端-最新参考产品设计/06-配送工作台.png new file mode 100644 index 0000000..b314a8f Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/06-配送工作台.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/07-消息中心.png b/doc/服务端APP-配送端-最新参考产品设计/07-消息中心.png new file mode 100644 index 0000000..e7554f9 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/07-消息中心.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/08-配送订单列表.png b/doc/服务端APP-配送端-最新参考产品设计/08-配送订单列表.png new file mode 100644 index 0000000..19f788c Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/08-配送订单列表.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/09-配送订单详情.png b/doc/服务端APP-配送端-最新参考产品设计/09-配送订单详情.png new file mode 100644 index 0000000..1ff3774 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/09-配送订单详情.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/10-接单与改派.png b/doc/服务端APP-配送端-最新参考产品设计/10-接单与改派.png new file mode 100644 index 0000000..ab608da Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/10-接单与改派.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/11-按时间排单.png b/doc/服务端APP-配送端-最新参考产品设计/11-按时间排单.png new file mode 100644 index 0000000..ca8cf29 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/11-按时间排单.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/12-按路线排单.png b/doc/服务端APP-配送端-最新参考产品设计/12-按路线排单.png new file mode 100644 index 0000000..0e80405 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/12-按路线排单.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/13-导航与到达.png b/doc/服务端APP-配送端-最新参考产品设计/13-导航与到达.png new file mode 100644 index 0000000..2606884 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/13-导航与到达.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/14-围栏异常处理.png b/doc/服务端APP-配送端-最新参考产品设计/14-围栏异常处理.png new file mode 100644 index 0000000..cbbbe94 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/14-围栏异常处理.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/15-气瓶扫描录入.png b/doc/服务端APP-配送端-最新参考产品设计/15-气瓶扫描录入.png new file mode 100644 index 0000000..18c1af1 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/15-气瓶扫描录入.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/16-扫描异常拦截.png b/doc/服务端APP-配送端-最新参考产品设计/16-扫描异常拦截.png new file mode 100644 index 0000000..621cbe5 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/16-扫描异常拦截.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/17-随瓶安检.png b/doc/服务端APP-配送端-最新参考产品设计/17-随瓶安检.png new file mode 100644 index 0000000..803b31f Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/17-随瓶安检.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/18-安检不合格与整改.png b/doc/服务端APP-配送端-最新参考产品设计/18-安检不合格与整改.png new file mode 100644 index 0000000..2f31d5a Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/18-安检不合格与整改.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/19-配送取证.png b/doc/服务端APP-配送端-最新参考产品设计/19-配送取证.png new file mode 100644 index 0000000..16074a9 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/19-配送取证.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/20-收款确认.png b/doc/服务端APP-配送端-最新参考产品设计/20-收款确认.png new file mode 100644 index 0000000..ce29083 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/20-收款确认.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/21-签收确认.png b/doc/服务端APP-配送端-最新参考产品设计/21-签收确认.png new file mode 100644 index 0000000..54c46bd Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/21-签收确认.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/22-配送完成.png b/doc/服务端APP-配送端-最新参考产品设计/22-配送完成.png new file mode 100644 index 0000000..1714d2d Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/22-配送完成.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/23-空瓶回收任务.png b/doc/服务端APP-配送端-最新参考产品设计/23-空瓶回收任务.png new file mode 100644 index 0000000..17bbb84 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/23-空瓶回收任务.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/24-蓝牙设备连接.png b/doc/服务端APP-配送端-最新参考产品设计/24-蓝牙设备连接.png new file mode 100644 index 0000000..e540a27 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/24-蓝牙设备连接.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/25-空瓶扫描与确认.png b/doc/服务端APP-配送端-最新参考产品设计/25-空瓶扫描与确认.png new file mode 100644 index 0000000..546ea02 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/25-空瓶扫描与确认.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/26-回收异常处理.png b/doc/服务端APP-配送端-最新参考产品设计/26-回收异常处理.png new file mode 100644 index 0000000..555a7a2 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/26-回收异常处理.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/27-配送轨迹与补传.png b/doc/服务端APP-配送端-最新参考产品设计/27-配送轨迹与补传.png new file mode 100644 index 0000000..8a1237c Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/27-配送轨迹与补传.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/28-服务用户列表.png b/doc/服务端APP-配送端-最新参考产品设计/28-服务用户列表.png new file mode 100644 index 0000000..1870fae Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/28-服务用户列表.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/29-服务用户详情.png b/doc/服务端APP-配送端-最新参考产品设计/29-服务用户详情.png new file mode 100644 index 0000000..c29e719 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/29-服务用户详情.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/30-配送记录.png b/doc/服务端APP-配送端-最新参考产品设计/30-配送记录.png new file mode 100644 index 0000000..3de7bfd Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/30-配送记录.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/31-配送记录详情.png b/doc/服务端APP-配送端-最新参考产品设计/31-配送记录详情.png new file mode 100644 index 0000000..3e89015 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/31-配送记录详情.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/32-统计看板.png b/doc/服务端APP-配送端-最新参考产品设计/32-统计看板.png new file mode 100644 index 0000000..90329c7 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/32-统计看板.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/33-钱包.png b/doc/服务端APP-配送端-最新参考产品设计/33-钱包.png new file mode 100644 index 0000000..aa0607e Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/33-钱包.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/34-提现申请与记录.png b/doc/服务端APP-配送端-最新参考产品设计/34-提现申请与记录.png new file mode 100644 index 0000000..13e0853 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/34-提现申请与记录.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/35-银行卡管理.png b/doc/服务端APP-配送端-最新参考产品设计/35-银行卡管理.png new file mode 100644 index 0000000..8915331 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/35-银行卡管理.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/36-离线队列与冲突.png b/doc/服务端APP-配送端-最新参考产品设计/36-离线队列与冲突.png new file mode 100644 index 0000000..c0643b4 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/36-离线队列与冲突.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/37-个人中心.png b/doc/服务端APP-配送端-最新参考产品设计/37-个人中心.png new file mode 100644 index 0000000..12f0b59 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/37-个人中心.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/38-个人资料车辆与资质.png b/doc/服务端APP-配送端-最新参考产品设计/38-个人资料车辆与资质.png new file mode 100644 index 0000000..f6e420c Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/38-个人资料车辆与资质.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/39-设置与通知.png b/doc/服务端APP-配送端-最新参考产品设计/39-设置与通知.png new file mode 100644 index 0000000..833cb2e Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/39-设置与通知.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/40-推荐二维码.png b/doc/服务端APP-配送端-最新参考产品设计/40-推荐二维码.png new file mode 100644 index 0000000..1c3fd1d Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/40-推荐二维码.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/41-服务支持中心.png b/doc/服务端APP-配送端-最新参考产品设计/41-服务支持中心.png new file mode 100644 index 0000000..1eeb867 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/41-服务支持中心.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/42-配送知识库与视频教程.png b/doc/服务端APP-配送端-最新参考产品设计/42-配送知识库与视频教程.png new file mode 100644 index 0000000..58bd800 Binary files /dev/null and b/doc/服务端APP-配送端-最新参考产品设计/42-配送知识库与视频教程.png differ diff --git a/doc/服务端APP-配送端-最新参考产品设计/产品设计说明_配送端APP_v1.0.md b/doc/服务端APP-配送端-最新参考产品设计/产品设计说明_配送端APP_v1.0.md new file mode 100644 index 0000000..76c4d8e --- /dev/null +++ b/doc/服务端APP-配送端-最新参考产品设计/产品设计说明_配送端APP_v1.0.md @@ -0,0 +1,95 @@ +# 配送端 APP 最新产品设计说明 v1.0 + +## 1. 文档定位 + +本目录 42 张 PNG 是配送端目标产品设计。设计以原配送端产品图、当前 `apps/service_app` 配送能力、服务端 App 需求和核心配送流程为依据。图片用于开发验收，不表示所有接口和页面已经实现。 + +## 2. 设计原则 + +- 保留订单、排单、路线、到场、气瓶、随瓶安检、取证、收款、签收、空瓶回收、轨迹、用户和钱包能力。 +- 主色 `#2563EB`，背景 `#F7F8FA`，成功绿色、提醒橙色、高风险红色；禁止紫色及紫色渐变。 +- 不使用 AI 元素、AI 助手、聊天机器人或相关说明文案。 +- 采用正式、简洁、密度适中的移动端界面；统一 20px 边距、最大 8px 圆角、标准图标和清晰状态标签。 +- 气瓶、押金、收款、签收、库存、轨迹和任务完成以服务端确认结果为准。 +- 关键操作支持幂等、离线暂存、自动重试和冲突处理。 + +## 3. 页面清单 + +| 编号 | 页面 | 核心功能 | +| --- | --- | --- | +| 01 | 登录页 | 账号密码登录、协议确认 | +| 02 | 岗位申请 | 配送员岗位、配送点、车辆与资质申请 | +| 03 | 作业前检查 | 出勤、资质、车辆、设备、定位和网络 | +| 04 | 准入阻断 | 资质、打卡、培训、车辆与设备阻断处理 | +| 05 | 每日安全培训 | 配送安全题目、进度和结果 | +| 06 | 配送工作台 | 今日订单、统计、快捷入口和安全提醒 | +| 07 | 消息中心 | 订单、路线、安全、系统和结算消息 | +| 08 | 配送订单列表 | 待配送、进行中、异常、完成筛选 | +| 09 | 配送订单详情 | 用户、地址、商品、气瓶与付款信息 | +| 10 | 接单与改派 | 接单、拒单原因、改派申请和审核 | +| 11 | 按时间排单 | 时间窗、顺序、冲突和批量确认 | +| 12 | 按路线排单 | 地图路线、里程、站点和顺序调整 | +| 13 | 导航与到达 | 导航、用户联系、到场与围栏校验 | +| 14 | 围栏异常处理 | 超距、定位异常、证据和人工审核 | +| 15 | 气瓶扫描录入 | 瓶码、规格、状态、订单匹配与录入 | +| 16 | 扫描异常拦截 | 重复、错瓶、无效瓶与不可提交原因 | +| 17 | 随瓶安检 | 环境、连接、设备和风险检查 | +| 18 | 安检不合格与整改 | 不合格项、处置、证据与终止配送 | +| 19 | 配送取证 | 配送前中后、瓶体、安装、安检照片视频 | +| 20 | 收款确认 | 应收、线上、线下凭证与异常对账 | +| 21 | 签收确认 | 签收码、用户签名、交付清单和拒签 | +| 22 | 配送完成 | 订单、库存、押金、轨迹和签收归档 | +| 23 | 空瓶回收任务 | 回收数量、地址、计划与状态 | +| 24 | 蓝牙设备连接 | 智能瓶阀搜索、配对、权限和故障 | +| 25 | 空瓶扫描与确认 | 空瓶码、状态、押金核算和回收确认 | +| 26 | 回收异常处理 | 错瓶、损坏、押金争议和证据 | +| 27 | 配送轨迹与补传 | 实时轨迹、缺口、离线缓存和补传 | +| 28 | 服务用户列表 | 授权用户、片区、状态和搜索 | +| 29 | 服务用户详情 | 脱敏资料、用气、安检、配送和评价 | +| 30 | 配送记录 | 历史订单、状态、时间和筛选 | +| 31 | 配送记录详情 | 时间线、瓶码、取证、收款、签收和轨迹 | +| 32 | 统计看板 | 配送量、准时率、里程、异常和收入 | +| 33 | 钱包 | 余额、配送收入、奖励和明细 | +| 34 | 提现申请与记录 | 金额、银行卡、手续费和提现状态 | +| 35 | 银行卡管理 | 实名卡片、新增、解绑和安全校验 | +| 36 | 离线队列与冲突 | 轨迹、证据、签收、草稿和版本冲突 | +| 37 | 个人中心 | 车辆、资质、钱包、统计和支持入口 | +| 38 | 个人资料车辆与资质 | 配送员、车辆、证照和到期提醒 | +| 39 | 设置与通知 | 派单、路线、轨迹、安全、权限和账号 | +| 40 | 推荐二维码 | 人员招募或服务推广二维码与记录 | +| 41 | 服务支持中心 | 人工客服、配送点、抢险电话和工单 | +| 42 | 配送知识库与视频教程 | 规范、气瓶、安检、设备和学习进度 | + +## 4. 当前实现对照 + +| 范围 | 当前状态 | 后续开发要求 | +| --- | --- | --- | +| 登录与角色 | 已有真实登录与配送角色识别 | 补岗位申请、审核与设备绑定 | +| 作业前检查 | 已有 `/preflight` 和考勤 | 补车辆、培训、服务区域和设备细项 | +| 配送订单 | 已有列表、详情、开始、异常、恢复 | 补接单改派、排单、状态动作和专用详情字段 | +| 轨迹与到场 | 已有轨迹追加和到场接口 | 补持续轨迹、围栏异常、离线补传与冲突处理 | +| 签收提交 | 已有配送签收提交 | 补瓶码、安检、取证、收款、拒签、空瓶和押金完整链路 | +| 钱包 | 已有钱包查询 | 补收入分类、提现、银行卡和结算审核 | +| 记录与个人 | 已有通用入口 | 补用户、记录详情、统计、资质、知识库与人工支持 | + +## 5. 接口与状态机要求 + +- 延续 `/heqi/client/v1/staff/delivery/orders` 现有接口，不修改已有字段语义。 +- 订单状态建议覆盖：待接单、已接单、已排单、配送中、已到达、气瓶已核验、安检完成、待收款、待签收、已完成、异常暂停、已取消。 +- 每个动作由服务端返回 `allowed_actions`，客户端不得只按本地页面推断下一步。 +- 气瓶扫描必须校验瓶码、规格、所属站点、库存状态、原订单和重复提交。 +- 围栏、轨迹、照片和视频需要设备时间、服务端时间、定位精度、文件哈希与上传状态。 +- 收款和押金分别核算，线上与线下金额不可混淆；差额必须进入对账审核。 +- 签收码与用户签名二选一时仍需记录使用方式、验证结果和服务端回执。 + +## 6. 验收重点 + +- 42 个页面和配送主链路可连续操作，返回、取消、异常和重试路径完整。 +- 订单金额、气瓶数量、空瓶押金、签收信息和库存变动前后一致。 +- 无网络时轨迹、取证和签收可安全暂存，恢复后可见同步结果。 +- 高风险随瓶安检不允许继续配送，必须先处置或走审核流程。 +- Android 常用尺寸下无文字遮挡、越界和底部导航覆盖。 + +## 7. 图片校对方式 + +图片按编号即业务顺序。修改时直接指出“文件名 + 位置 + 期望内容”，所有调整继续保存在本目录，不覆盖原产品设计。 diff --git a/doc/服务端APP-配送端-最新参考产品设计/操作日志_配送端APP产品设计优化_20260906.md b/doc/服务端APP-配送端-最新参考产品设计/操作日志_配送端APP产品设计优化_20260906.md new file mode 100644 index 0000000..dc91a53 --- /dev/null +++ b/doc/服务端APP-配送端-最新参考产品设计/操作日志_配送端APP产品设计优化_20260906.md @@ -0,0 +1,19 @@ +# 配送端 APP 产品设计优化操作日志 + +操作时间：2026-09-06 + +操作类型：新增 + +影响模块：服务端 APP 配送岗位产品设计 + +操作前状态：原配送设计视觉不统一，完整配送、空瓶回收、轨迹补传和异常状态不足；当前客户端只实现配送列表、详情、开始、异常、恢复、轨迹追加、到场和签收提交的部分能力。 + +具体操作：在新目录中生成 42 张目标产品设计图，补齐排单、导航、气瓶、随瓶安检、取证、收款、签收、空瓶回收、蓝牙设备、轨迹、用户、钱包、离线、资质、人工支持和知识库；校正日期、金额合计、高风险开关和配送步骤。 + +操作后状态：原目录未修改；最新目录可独立用于逐页评审和开发验收。 + +代码变更：本次未修改业务代码，仅新增产品设计图片与 Markdown 文档。 + +验证结果：PNG 数量 42；图片可读取；文件名按业务顺序编号；未使用紫色与 AI 元素。 + +风险评估：设计包含尚未实现的目标能力；开发时需重点验证瓶码幂等、围栏误差、轨迹补传、金额对账、拒签和库存一致性。 diff --git a/doc/用户端APP-最新参考产品设计/01-登录页.png b/doc/用户端APP-最新参考产品设计/01-登录页.png new file mode 100644 index 0000000..c82b0b0 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/01-登录页.png differ diff --git a/doc/用户端APP-最新参考产品设计/02-1-安全案例.png b/doc/用户端APP-最新参考产品设计/02-1-安全案例.png new file mode 100644 index 0000000..a31ddec Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/02-1-安全案例.png differ diff --git a/doc/用户端APP-最新参考产品设计/02-2-法律法规.png b/doc/用户端APP-最新参考产品设计/02-2-法律法规.png new file mode 100644 index 0000000..a42c9b0 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/02-2-法律法规.png differ diff --git a/doc/用户端APP-最新参考产品设计/02-3-气价信息.png b/doc/用户端APP-最新参考产品设计/02-3-气价信息.png new file mode 100644 index 0000000..d9d1c9e Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/02-3-气价信息.png differ diff --git a/doc/用户端APP-最新参考产品设计/02-智能角阀功能介绍.png b/doc/用户端APP-最新参考产品设计/02-智能角阀功能介绍.png new file mode 100644 index 0000000..9312b45 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/02-智能角阀功能介绍.png differ diff --git a/doc/用户端APP-最新参考产品设计/03-首页.png b/doc/用户端APP-最新参考产品设计/03-首页.png new file mode 100644 index 0000000..f8a8187 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/03-首页.png differ diff --git a/doc/用户端APP-最新参考产品设计/04-智能角阀控制.png b/doc/用户端APP-最新参考产品设计/04-智能角阀控制.png new file mode 100644 index 0000000..0dbd8b9 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/04-智能角阀控制.png differ diff --git a/doc/用户端APP-最新参考产品设计/05-一键报修.png b/doc/用户端APP-最新参考产品设计/05-一键报修.png new file mode 100644 index 0000000..72e1b43 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/05-一键报修.png differ diff --git a/doc/用户端APP-最新参考产品设计/06-1-扫码添加确认.png b/doc/用户端APP-最新参考产品设计/06-1-扫码添加确认.png new file mode 100644 index 0000000..4da5066 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/06-1-扫码添加确认.png differ diff --git a/doc/用户端APP-最新参考产品设计/06-2-蓝牙连接设备.png b/doc/用户端APP-最新参考产品设计/06-2-蓝牙连接设备.png new file mode 100644 index 0000000..042407d Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/06-2-蓝牙连接设备.png differ diff --git a/doc/用户端APP-最新参考产品设计/06-3-手动输入设备码.png b/doc/用户端APP-最新参考产品设计/06-3-手动输入设备码.png new file mode 100644 index 0000000..8e45cd3 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/06-3-手动输入设备码.png differ diff --git a/doc/用户端APP-最新参考产品设计/07-气瓶基本信息.png b/doc/用户端APP-最新参考产品设计/07-气瓶基本信息.png new file mode 100644 index 0000000..8cb0147 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/07-气瓶基本信息.png differ diff --git a/doc/用户端APP-最新参考产品设计/08-设备分组控制.png b/doc/用户端APP-最新参考产品设计/08-设备分组控制.png new file mode 100644 index 0000000..6532c22 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/08-设备分组控制.png differ diff --git a/doc/用户端APP-最新参考产品设计/09-安全告警与报警器.png b/doc/用户端APP-最新参考产品设计/09-安全告警与报警器.png new file mode 100644 index 0000000..6553056 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/09-安全告警与报警器.png differ diff --git a/doc/用户端APP-最新参考产品设计/10-紧急联系人.png b/doc/用户端APP-最新参考产品设计/10-紧急联系人.png new file mode 100644 index 0000000..d0b2bc3 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/10-紧急联系人.png differ diff --git a/doc/用户端APP-最新参考产品设计/11-燃气商城.png b/doc/用户端APP-最新参考产品设计/11-燃气商城.png new file mode 100644 index 0000000..045ecb0 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/11-燃气商城.png differ diff --git a/doc/用户端APP-最新参考产品设计/12-商品详情.png b/doc/用户端APP-最新参考产品设计/12-商品详情.png new file mode 100644 index 0000000..17495bb Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/12-商品详情.png differ diff --git a/doc/用户端APP-最新参考产品设计/13-购物车.png b/doc/用户端APP-最新参考产品设计/13-购物车.png new file mode 100644 index 0000000..8353655 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/13-购物车.png differ diff --git a/doc/用户端APP-最新参考产品设计/14-提交订单.png b/doc/用户端APP-最新参考产品设计/14-提交订单.png new file mode 100644 index 0000000..cba071e Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/14-提交订单.png differ diff --git a/doc/用户端APP-最新参考产品设计/15-我的收藏.png b/doc/用户端APP-最新参考产品设计/15-我的收藏.png new file mode 100644 index 0000000..eaa6051 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/15-我的收藏.png differ diff --git a/doc/用户端APP-最新参考产品设计/16-押金管理.png b/doc/用户端APP-最新参考产品设计/16-押金管理.png new file mode 100644 index 0000000..d1adaf4 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/16-押金管理.png differ diff --git a/doc/用户端APP-最新参考产品设计/17-退瓶退押金.png b/doc/用户端APP-最新参考产品设计/17-退瓶退押金.png new file mode 100644 index 0000000..2999f86 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/17-退瓶退押金.png differ diff --git a/doc/用户端APP-最新参考产品设计/18-气瓶下单.png b/doc/用户端APP-最新参考产品设计/18-气瓶下单.png new file mode 100644 index 0000000..d219bf7 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/18-气瓶下单.png differ diff --git a/doc/用户端APP-最新参考产品设计/19-支付确认.png b/doc/用户端APP-最新参考产品设计/19-支付确认.png new file mode 100644 index 0000000..21bd6a8 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/19-支付确认.png differ diff --git a/doc/用户端APP-最新参考产品设计/20-订单中心.png b/doc/用户端APP-最新参考产品设计/20-订单中心.png new file mode 100644 index 0000000..538a8a5 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/20-订单中心.png differ diff --git a/doc/用户端APP-最新参考产品设计/21-订单详情.png b/doc/用户端APP-最新参考产品设计/21-订单详情.png new file mode 100644 index 0000000..9ba6050 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/21-订单详情.png differ diff --git a/doc/用户端APP-最新参考产品设计/22-配送详情.png b/doc/用户端APP-最新参考产品设计/22-配送详情.png new file mode 100644 index 0000000..ef4d241 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/22-配送详情.png differ diff --git a/doc/用户端APP-最新参考产品设计/23-配送轨迹.png b/doc/用户端APP-最新参考产品设计/23-配送轨迹.png new file mode 100644 index 0000000..a996f02 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/23-配送轨迹.png differ diff --git a/doc/用户端APP-最新参考产品设计/24-电子发票.png b/doc/用户端APP-最新参考产品设计/24-电子发票.png new file mode 100644 index 0000000..7701b33 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/24-电子发票.png differ diff --git a/doc/用户端APP-最新参考产品设计/25-个人中心.png b/doc/用户端APP-最新参考产品设计/25-个人中心.png new file mode 100644 index 0000000..fe14582 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/25-个人中心.png differ diff --git a/doc/用户端APP-最新参考产品设计/26-我的记录.png b/doc/用户端APP-最新参考产品设计/26-我的记录.png new file mode 100644 index 0000000..30d1587 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/26-我的记录.png differ diff --git a/doc/用户端APP-最新参考产品设计/27-用气统计.png b/doc/用户端APP-最新参考产品设计/27-用气统计.png new file mode 100644 index 0000000..ffaee1a Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/27-用气统计.png differ diff --git a/doc/用户端APP-最新参考产品设计/28-我的钱包.png b/doc/用户端APP-最新参考产品设计/28-我的钱包.png new file mode 100644 index 0000000..d56148c Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/28-我的钱包.png differ diff --git a/doc/用户端APP-最新参考产品设计/29-地址管理.png b/doc/用户端APP-最新参考产品设计/29-地址管理.png new file mode 100644 index 0000000..d884d72 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/29-地址管理.png differ diff --git a/doc/用户端APP-最新参考产品设计/30-消息中心.png b/doc/用户端APP-最新参考产品设计/30-消息中心.png new file mode 100644 index 0000000..5b8e81e Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/30-消息中心.png differ diff --git a/doc/用户端APP-最新参考产品设计/31-设置.png b/doc/用户端APP-最新参考产品设计/31-设置.png new file mode 100644 index 0000000..05a0fbf Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/31-设置.png differ diff --git a/doc/用户端APP-最新参考产品设计/32-供气合同.png b/doc/用户端APP-最新参考产品设计/32-供气合同.png new file mode 100644 index 0000000..f66eef5 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/32-供气合同.png differ diff --git a/doc/用户端APP-最新参考产品设计/33-家庭成员与设备共享.png b/doc/用户端APP-最新参考产品设计/33-家庭成员与设备共享.png new file mode 100644 index 0000000..fd40853 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/33-家庭成员与设备共享.png differ diff --git a/doc/用户端APP-最新参考产品设计/34-我的设备.png b/doc/用户端APP-最新参考产品设计/34-我的设备.png new file mode 100644 index 0000000..b23afd6 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/34-我的设备.png differ diff --git a/doc/用户端APP-最新参考产品设计/35-安全记录详情.png b/doc/用户端APP-最新参考产品设计/35-安全记录详情.png new file mode 100644 index 0000000..d3d59ba Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/35-安全记录详情.png differ diff --git a/doc/用户端APP-最新参考产品设计/36-申请售后.png b/doc/用户端APP-最新参考产品设计/36-申请售后.png new file mode 100644 index 0000000..89c333a Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/36-申请售后.png differ diff --git a/doc/用户端APP-最新参考产品设计/37-邀请注册.png b/doc/用户端APP-最新参考产品设计/37-邀请注册.png new file mode 100644 index 0000000..8fe53f2 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/37-邀请注册.png differ diff --git a/doc/用户端APP-最新参考产品设计/38-余额充值.png b/doc/用户端APP-最新参考产品设计/38-余额充值.png new file mode 100644 index 0000000..656289d Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/38-余额充值.png differ diff --git a/doc/用户端APP-最新参考产品设计/39-余额提现.png b/doc/用户端APP-最新参考产品设计/39-余额提现.png new file mode 100644 index 0000000..2077ed4 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/39-余额提现.png differ diff --git a/doc/用户端APP-最新参考产品设计/40-银行卡管理.png b/doc/用户端APP-最新参考产品设计/40-银行卡管理.png new file mode 100644 index 0000000..55f2930 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/40-银行卡管理.png differ diff --git a/doc/用户端APP-最新参考产品设计/41-个人资料.png b/doc/用户端APP-最新参考产品设计/41-个人资料.png new file mode 100644 index 0000000..257e51c Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/41-个人资料.png differ diff --git a/doc/用户端APP-最新参考产品设计/42-报修工单详情.png b/doc/用户端APP-最新参考产品设计/42-报修工单详情.png new file mode 100644 index 0000000..c0ce7cf Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/42-报修工单详情.png differ diff --git a/doc/用户端APP-最新参考产品设计/43-1-安全宣传.png b/doc/用户端APP-最新参考产品设计/43-1-安全宣传.png new file mode 100644 index 0000000..5c745eb Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/43-1-安全宣传.png differ diff --git a/doc/用户端APP-最新参考产品设计/43-2-安全视频.png b/doc/用户端APP-最新参考产品设计/43-2-安全视频.png new file mode 100644 index 0000000..104cff0 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/43-2-安全视频.png differ diff --git a/doc/用户端APP-最新参考产品设计/43-3-法律法规.png b/doc/用户端APP-最新参考产品设计/43-3-法律法规.png new file mode 100644 index 0000000..ae3120d Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/43-3-法律法规.png differ diff --git a/doc/用户端APP-最新参考产品设计/43-4-平台公告.png b/doc/用户端APP-最新参考产品设计/43-4-平台公告.png new file mode 100644 index 0000000..2f62da3 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/43-4-平台公告.png differ diff --git a/doc/用户端APP-最新参考产品设计/43-安全内容中心.png b/doc/用户端APP-最新参考产品设计/43-安全内容中心.png new file mode 100644 index 0000000..dd98157 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/43-安全内容中心.png differ diff --git a/doc/用户端APP-最新参考产品设计/44-自动关阀设置.png b/doc/用户端APP-最新参考产品设计/44-自动关阀设置.png new file mode 100644 index 0000000..cc120ba Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/44-自动关阀设置.png differ diff --git a/doc/用户端APP-最新参考产品设计/45-电子保修卡.png b/doc/用户端APP-最新参考产品设计/45-电子保修卡.png new file mode 100644 index 0000000..eafaeb6 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/45-电子保修卡.png differ diff --git a/doc/用户端APP-最新参考产品设计/46-设备健康月报.png b/doc/用户端APP-最新参考产品设计/46-设备健康月报.png new file mode 100644 index 0000000..b42bb98 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/46-设备健康月报.png differ diff --git a/doc/用户端APP-最新参考产品设计/47-安全知识考试.png b/doc/用户端APP-最新参考产品设计/47-安全知识考试.png new file mode 100644 index 0000000..0533b0e Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/47-安全知识考试.png differ diff --git a/doc/用户端APP-最新参考产品设计/48-服务评价.png b/doc/用户端APP-最新参考产品设计/48-服务评价.png new file mode 100644 index 0000000..d8674e3 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/48-服务评价.png differ diff --git a/doc/用户端APP-最新参考产品设计/49-预约安全巡检.png b/doc/用户端APP-最新参考产品设计/49-预约安全巡检.png new file mode 100644 index 0000000..874df47 Binary files /dev/null and b/doc/用户端APP-最新参考产品设计/49-预约安全巡检.png differ diff --git a/doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.0.md b/doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.0.md new file mode 100644 index 0000000..efed6a6 --- /dev/null +++ b/doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.0.md @@ -0,0 +1,122 @@ +# 用户端 App 最新参考产品设计 + +> 本版本保留早期逐稿确认记录。用户已于 2026-09-05 将流程调整为“每种页面类型生成一张并直接保存”；完整页面清单与当前规则请查看 `产品设计说明_用户端APP_v1.1.md`。 + +## 1. 设计目标 + +- 以 `doc/用户端APP-产品设计` 中的业务功能和页面流程为基础逐类优化，不删除后续规划功能。 +- 视觉与现有用户端 Design System 保持一致，主色使用 `#2563EB`，背景使用 `#F7F8FA`。 +- 界面采用正式移动 App 的信息层级、间距和交互组件，不使用紫色、渐变、Emoji、玻璃拟态、三维装饰或夸张 AI 风格元素。 +- 每类页面先生成三个独立候选，仅保存用户明确选定的版本。 + +## 2. 已选页面 + +| 序号 | 页面类型 | 来源参考 | 入选文件 | 状态 | +| --- | --- | --- | --- | --- | +| 01 | 登录页 | `../用户端APP-产品设计/1.jpg` | `01-登录页.png` | 已选择方案 1 | +| 02 | 智能角阀功能介绍 | `../用户端APP-产品设计/2.jpg`、`3.jpg` | `02-智能角阀功能介绍.png` | 已选择方案 1 | +| 03 | 首页与设备概览 | 当前真实首页、`../用户端APP-产品设计/4.jpg`、`4-1.jpg` | `03-首页.png` | 已选择方案 1 并完成公告区优化 | +| 04 | 智能角阀设备详情与控制 | `03-首页.png`、`../用户端APP-产品设计/4.jpg`、`4-6.jpg` | `04-智能角阀控制.png` | 已选择方案 1 | +| 05 | 一键报修 | `04-智能角阀控制.png`、`../用户端APP-产品设计/4-3.jpg`、`4-4.jpg` | `05-一键报修.png` | 已选择方案 2 | +| 06-1 | 扫码添加确认 | `03-首页.png`、`../用户端APP-产品设计/4-5.jpg` | `06-1-扫码添加确认.png` | 添加设备必需流程 | +| 06-2 | 蓝牙连接设备 | `03-首页.png`、`../用户端APP-产品设计/4-7.jpg` | `06-2-蓝牙连接设备.png` | 添加设备必需流程 | +| 06-3 | 手动输入设备码 | `03-首页.png`、`../用户端APP-产品设计/4-5.jpg`、`4-7.jpg` | `06-3-手动输入设备码.png` | 添加设备必需流程 | + +## 3. 产品设计依据 + +新版产品设计必须同时合并三类依据，任何一类已有能力都不得因视觉改版被删除： + +1. 原产品设计图：`doc/用户端APP-产品设计` 中的完整页面和交互流程。 +2. 当前真实用户端：`apps/user_app` 已实现的登录、首页、商城、订单和个人中心能力。 +3. 正式需求文档：`docs/03-用户端App需求.md` 中已明确的首期功能和后续迭代能力。 + +### 3.1 当前已实现能力 + +- 登录、注册、会话恢复和登录后返回原目标页。 +- 首页安全内容、安全公告、内容详情和当前服务归属；服务归属分别展示所属气站与服务配送点。 +- 商城商品列表、购买确认、地址选择、订单创建和余额支付。 +- 商城订单、供气订单、退款记录、服务工单，以及支付宝、微信支付和退款申请入口。 +- 个人资料、头像、钱包余额、地址管理、供气合同、钱包流水、申请维修和退出登录。 + +### 3.2 原设计及需求文档保留能力 + +- 智能角阀列表、设备详情、在线/离线、开关状态、电量、环境压力、温度、自动关阀时间、燃气检测和最后更新时间。 +- 扫码添加、手动输入、蓝牙连接、设备校验、安装地址、设备昵称和重复绑定校验。 +- 单设备开关阀、操作确认、命令回执、失败/超时状态，以及高风险事件禁止开阀。 +- 厨房、热水器、暖气等设备分组，全开、全关、编辑、删除和逐设备失败明细。 +- 气瓶规格、钢瓶号、充装日期、充装单位、充装数量、有效期、制造厂和异常提示。 +- 可燃气体报警器列表、最近告警、安全提示、触发报警、紧急电话、一键报修和处理进度。 +- 报修类型、故障描述、语音输入、联系人、地址、当前位置和最多三张现场照片。 +- 商城分类、搜索、收藏、数量调整、商品详情、购物车、库存、配送费、预约时段和支付方式。 +- 订单状态、配送轨迹、确认收货、售后、退款、评价和电子发票。 +- 钱包、押金、消息、用气统计、收藏、客服、紧急联系人、家庭共享、通知与通用设置。 + +### 3.3 导航与页面组织原则 + +- 保留当前真实 App 的“首页、商城、订单、我的”四栏结构，避免底部导航过度拥挤。 +- 智能角阀作为首页核心设备模块及独立详情流程；收藏放入商城和“我的”，不因取消独立底栏入口而删除功能。 +- 当前已实现功能在设计稿中按真实可用状态呈现；后续能力按完整交互流程设计，但开发时必须等待真实接口，不使用静态成功结果冒充上线能力。 + +## 4. 登录页功能范围 + +- 手机号输入。 +- 验证码登录与获取验证码。 +- 密码登录切换。 +- 记住登录状态。 +- 忘记密码。 +- 用户协议与隐私政策入口。 + +## 5. 设计规范 + +- 品牌主色：`#2563EB`。 +- 成功色：`#16875D`。 +- 警告色：`#B86400`。 +- 危险色：`#C7352A`。 +- 页面背景：`#F7F8FA`。 +- 最小触控区域：48dp。 +- 常规按钮高度：52dp。 +- 间距使用 4dp 基础网格。 +- 圆角优先使用 10dp、12dp、16dp。 + +### 5.1 智能角阀功能介绍 + +- 保留功能介绍、安全案例、法律法规和气价信息四类内容入口。 +- 功能介绍保留远程开关阀门、实时状态监控、安全报警提醒和定时关阀设置。 +- 使用统一线性图标，移除 Emoji、浏览器浮层、系统状态栏和截图侧边控件。 + +### 5.2 首页与设备概览 + +- 保留“当前服务归属”，分别显示所属气站与服务配送点。 +- 首页增加厨房智能角阀概览，展示在线状态、开关状态、电量、环境压力、温度、可燃气体状态和最后更新时间。 +- 提供扫码添加、蓝牙连接、分组控制和一键报修快捷入口。 +- 提供安全记录、最近告警和气瓶信息入口，高风险开阀操作进入设备详情后执行。 +- 安全公告使用圆角描边列表卡，展示真实中文摘要、日期和“查看全部”入口。 +- 保留当前“首页、商城、订单、我的”四栏底部导航。 + +### 5.3 智能角阀设备详情与控制 + +- 展示在线状态、当前开关状态、设备状态说明和最后更新时间。 +- 展示电量、环境压力、温度、可燃气体、关阀时间和使用气瓶六项设备数据。 +- 开阀前明确校验设备在线、燃气泄漏和传感器状态，不允许绕过安全检查。 +- 以单一主按钮执行开阀操作，并提示现场通风和远离明火。 +- 保留安全记录、气瓶详情和一键报修入口；设备命令开发时必须展示最终回执或超时待确认状态。 + +### 5.4 一键报修 + +- 使用“故障信息、联系与地址、确认提交”三步引导，减少长表单一次性填写压力。 +- 支持燃气泄漏、阀门故障、报警器故障和其他问题四类故障。 +- 支持故障描述、语音输入和最多三张现场照片，照片记录拍摄时间及当前位置。 +- 保留脱敏联系电话、报修地址、定位状态和紧急电话入口。 +- 报修提交结果以服务端工单为准，失败时保留已填写内容，避免用户重复录入。 + +### 5.5 添加设备 + +- 扫码添加、手动输入和蓝牙连接是三种并存的必需方式，不作为互相替代的视觉候选。 +- 扫码识别后展示设备编号、设备昵称、安装地址、安装位置和校验结果，再由用户确认绑定。 +- 蓝牙连接展示附近设备、信号强度、连接状态、重新搜索、权限开启和连接帮助。 +- 手动输入提供设备编号格式提示、编号位置示例、校验失败处理和其他添加方式入口。 +- 绑定前统一校验设备归属、激活状态、服务区域和重复绑定；权限失败不得阻塞手动输入。 + +## 6. 后续流程 + +其余页面继续按“原始产品设计图 → 同一功能内容的三个布局候选 → 用户选择 → 保存入选稿”的顺序推进。不同业务方式或流程状态必须分别保留，不得作为互斥候选。全部视觉方案完成后，再据此更新 Flutter 用户端界面和相关功能。 diff --git a/doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.1.md b/doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.1.md new file mode 100644 index 0000000..44b10cb --- /dev/null +++ b/doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.1.md @@ -0,0 +1,131 @@ +# 用户端 App 最新参考产品设计说明 v1.1 + +## 1. 本次交付 + +- 交付目录：`doc/用户端APP-最新参考产品设计`。 +- 共保留 49 个主编号页面组；“添加设备”包含三个并存流程，“智能角阀功能介绍”包含四个独立标签状态，“安全内容中心”包含五个独立分类状态，因此目录内共有 58 张 PNG 设计图。 +- 本轮按用户最新要求执行：每种页面类型只生成一张，不再等待逐张选稿；后续按用户对具体图片的反馈定向修改。 +- 本轮仅交付产品设计图片与说明文档，不修改 Flutter 代码，不把后续规划能力标记为已经上线。 + +## 2. 设计依据 + +新版设计同时对照以下三类资料： + +1. 原产品设计：`doc/用户端APP-产品设计`。 +2. 当前用户端 App：`apps/user_app` 中已经存在的登录、首页、商城、订单、钱包、地址、合同与工单能力。 +3. 正式需求：`docs/03-用户端App需求.md` 中的首期边界与后续设备、安全、押金、消息、发票等能力。 +4. 开发实施文档：`docs/项目文档_用户端APP全量功能开发_v1.0.md`，用于落实页面路由、UI 优化、接口、数据模型、测试与分阶段交付。 + +设计稿保留完整产品方向，但开发时必须继续区分“当前真实可用”和“等待 Client API 落地”两种状态。设备控制、安全事件、押金、消息、发票、收藏、紧急联系人、账户注销及完整售后等未落地能力，不得用静态成功页面冒充真实业务结果。 + +## 3. 视觉规范 + +- 主色：`#2563EB`。 +- 背景：`#F7F8FA`。 +- 成功色：`#16875D`。 +- 警告色：`#B86400`。 +- 危险色：`#C7352A`。 +- 组件：白色卡片、1px 浅灰边框、10dp/12dp/16dp 圆角、4dp 基础间距网格、扁平线性图标。 +- 导航：一级页面使用“首页、商城、订单、我的”四栏底部导航；二级页面使用返回导航，不重复放底栏。 +- 禁止项：紫色、渐变、AI 元素、Emoji、玻璃拟态、三维装饰、发光、浏览器栏、手机外壳和系统状态栏。 +- 安全原则：危险告警不可关闭；开阀必须经过在线、权限、告警和传感器校验；离线、超时或失败不得伪造成成功。 + +## 4. 页面清单 + +### 4.1 入口、首页与设备 + +| 文件 | 页面类型 | 关键功能 | +| --- | --- | --- | +| `01-登录页.png` | 登录 | 手机号验证码、密码登录、协议、记住状态、忘记密码 | +| `02-智能角阀功能介绍.png` | 首次安全宣导 | 功能介绍、安全案例、法规、安全注意事项与阅读确认 | +| `02-1-安全案例.png` | 安全案例标签 | 泄漏自动关阀案例、设备离线案例、处理过程与安全提醒 | +| `02-2-法律法规.png` | 法律法规标签 | 国家法规、国家标准、地方指引、平台规则与外链提示 | +| `02-3-气价信息.png` | 气价信息标签 | 服务归属、气瓶规格价格、更新时间、押金与配送费说明 | +| `03-首页.png` | 首页 | 服务归属、安全公告、设备概览、快捷服务、四栏导航 | +| `04-智能角阀控制.png` | 角阀详情与控制 | 在线状态、遥测、安全检查、开关阀、命令结果入口 | +| `05-一键报修.png` | 报修提交 | 故障类型、语音、照片、联系人、地址、定位与紧急电话 | +| `06-1-扫码添加确认.png` | 扫码添加 | 扫码结果、设备校验、昵称、安装地址与确认绑定 | +| `06-2-蓝牙连接设备.png` | 蓝牙添加 | 附近设备、信号、权限、连接状态与失败引导 | +| `06-3-手动输入设备码.png` | 手动添加 | 设备码格式、编号位置、校验与其他添加方式 | +| `07-气瓶基本信息.png` | 气瓶信息 | 规格、钢瓶号、充装、制造、有效期、来源与异常提示 | +| `08-设备分组控制.png` | 设备分组 | 厨房/热水/暖气分组、全开全关、编辑删除与失败明细 | +| `09-安全告警与报警器.png` | 安全告警 | 报警器列表、在线状态、最近告警、测试、紧急电话 | +| `10-紧急联系人.png` | 紧急联系人 | 联系顺序、告警通知、查看/控制权限与编辑 | + +### 4.2 商城、押金与购买 + +| 文件 | 页面类型 | 关键功能 | +| --- | --- | --- | +| `11-燃气商城.png` | 商城首页 | 搜索、分类、商品、收藏、购物车与库存状态 | +| `12-商品详情.png` | 商品详情 | 轮播主图、规格、配送、服务、押金、收藏与购买 | +| `13-购物车.png` | 购物车 | 单选全选、数量、失效商品、押金提示与结算 | +| `14-提交订单.png` | 商城结算 | 地址、配送时间、商品、费用、发票、备注和支付方式 | +| `15-我的收藏.png` | 收藏 | 分类、取消收藏、加入购物车与下架保留 | +| `16-押金管理.png` | 押金管理 | 押金汇总、使用中、退款中、已退回与规则 | +| `17-退瓶退押金.png` | 退瓶退款 | 气瓶选择、上门回收、状态确认、预计退款与审核规则 | +| `18-气瓶下单.png` | 气瓶购买 | 气站、规格数量、库存、配送时段、换气免重复押金 | +| `19-支付确认.png` | 支付 | 微信/支付宝/余额、支付密码、优惠与订单明细 | + +### 4.3 订单、配送与售后 + +| 文件 | 页面类型 | 关键功能 | +| --- | --- | --- | +| `20-订单中心.png` | 订单中心 | 气瓶/商城/报修切换、状态筛选与常用操作 | +| `21-订单详情.png` | 订单详情 | 商品、费用、支付、合同、履约、人员、进度与售后 | +| `22-配送详情.png` | 配送详情 | 配送员、车辆资质、订单、受控联系与安全交付 | +| `23-配送轨迹.png` | 配送轨迹 | 最近位置、路线进度、预计时间、更新时间与历史节点 | +| `24-电子发票.png` | 发票申请 | 订单、可开票金额、抬头、税号、邮箱与申请状态 | +| `35-安全记录详情.png` | 安全事件 | 风险等级、自动关阀、证据、时间线、复检与不可删除 | +| `36-申请售后.png` | 售后申请 | 类型、原因、方案、图像/视频、联系人与退款审核 | +| `42-报修工单详情.png` | 报修详情 | 工单进度、故障证据、工程师、改期、记录与联系 | +| `48-服务评价.png` | 服务评价 | 总体/分项评分、标签、凭证与安全交付确认 | +| `49-预约安全巡检.png` | 巡检预约 | 服务内容、设备、日期时段、联系人、周期巡检与须知 | + +### 4.4 个人中心、账户与消息 + +| 文件 | 页面类型 | 关键功能 | +| --- | --- | --- | +| `25-个人中心.png` | 个人中心 | 资料、钱包、订单、设备、安全家庭与常用功能入口 | +| `26-我的记录.png` | 记录中心 | 用气、设备、告警、报修、押金与发票统一追溯 | +| `27-用气统计.png` | 用气统计 | 日周月年、用气趋势、构成、安全趋势与明细 | +| `28-我的钱包.png` | 钱包 | 余额、押金、优惠券、充值、提现、账单与资金安全 | +| `29-地址管理.png` | 地址 | 默认地址、编辑、服务范围校验与新增 | +| `30-消息中心.png` | 消息 | 安全、订单、服务、公告、已读与跳转对象 | +| `31-设置.png` | 设置 | 账号、通知、权限、支付密码、协议、退出与注销入口 | +| `32-供气合同.png` | 合同 | 待签/生效/到期、查看、下载、变更与续签 | +| `33-家庭成员与设备共享.png` | 家庭共享 | 成员、设备、查看/控制权限、邀请与撤销 | +| `34-我的设备.png` | 设备总览 | 搜索、筛选、分组、在线/离线、快捷控制与添加 | +| `37-邀请注册.png` | 邀请注册 | 气站二维码、服务地址、服务关系与异常校验 | +| `38-余额充值.png` | 充值 | 套餐、自定义金额、渠道支付、限额与回调说明 | +| `39-余额提现.png` | 提现 | 到账卡、金额、手续费、支付密码、审核与受限资金 | +| `40-银行卡管理.png` | 银行卡 | 储蓄卡、默认到账卡、实名验证与解除绑定 | +| `41-个人资料.png` | 资料编辑 | 头像、昵称、手机号、认证、服务关系与默认地址 | + +### 4.5 内容、安全设置与扩展能力 + +| 文件 | 页面类型 | 关键功能 | +| --- | --- | --- | +| `43-安全内容中心.png` | 内容中心 | 全部内容聚合、宣传、视频、法规、公告、外链风险与版本确认 | +| `43-1-安全宣传.png` | 安全宣传 | 宣传文章、阅读状态、分类筛选、专题学习与平台发布信息 | +| `43-2-安全视频.png` | 安全视频 | 推荐视频、视频分类、时长、阅读状态与继续学习 | +| `43-3-法律法规.png` | 法律法规 | 法规检索、适用层级筛选、版本与生效日期、外部链接风险提示 | +| `43-4-平台公告.png` | 平台公告 | 公告检索、类型筛选、重要公告、已读状态与所属气站/区域展示 | +| `44-自动关阀设置.png` | 定时关阀 | 规则、重复周期、提前提醒、执行记录与告警优先 | +| `45-电子保修卡.png` | 保修卡 | 保修状态、范围、服务商、维修记录与凭证 | +| `46-设备健康月报.png` | 健康月报 | 健康评分、在线率、异常、预测、来源与更新时间 | +| `47-安全知识考试.png` | 安全考试 | 题目、计时、进度、及格规则与危险题约束 | + +## 5. 核心业务约束 + +- “扫码添加、蓝牙连接、手动输入”是并存方式，不是三选一视觉候选。 +- 所属气站与服务配送点分开显示；无配送点时显示气站直接服务。 +- 设备开阀、群组全开、定时控制都不能绕过高风险告警、设备离线和权限限制。 +- 气瓶订单与普通商城订单共用支付能力，但气瓶订单必须保留气站、气瓶规格、换气、押金和预约时段规则。 +- 商品金额、气瓶押金、配送费、优惠与可开票金额分别展示；押金不能作为普通商品收入开票。 +- 配送位置必须展示最近更新时间；无有效位置时显示“暂未获取位置”，不伪造实时轨迹。 +- 余额充值以支付渠道回调为准，提现与退款以服务端审核和资金流水为准。 +- 用户、联系人、配送员、银行卡和证件信息使用脱敏展示。 + +## 6. 后续修改方式 + +用户可直接按文件名提出修改，例如“修改 `23-配送轨迹.png` 的地图占比”或“修改 `31-设置.png` 的通知分组”。每次修改只调整指定页面及其必要的关联说明，不重做已确认的其他图片。 diff --git a/doc/用户端APP-最新参考产品设计/操作日志_用户端APP产品设计优化_20260905.md b/doc/用户端APP-最新参考产品设计/操作日志_用户端APP产品设计优化_20260905.md new file mode 100644 index 0000000..560c9e2 --- /dev/null +++ b/doc/用户端APP-最新参考产品设计/操作日志_用户端APP产品设计优化_20260905.md @@ -0,0 +1,114 @@ +# 用户端 App 产品设计优化操作日志 + +操作时间：2026-09-05 21:44:12 +操作类型：新增、修改 +影响模块：用户端 App 产品设计资料 + +操作前状态：新版参考目录仅包含已确认的登录页和智能角阀功能介绍页，首页候选稿尚未确认。 +具体操作：以当前真实用户端首页为视觉基准，合并原产品设计及正式需求中的设备、安全和服务功能；根据用户标注优化安全公告区域；用户确认后保存入选稿并更新设计说明。 +操作后状态：已新增正式首页设计稿，产品设计说明已记录首页功能范围和选稿状态。 +代码变更：无代码变更。 +文件变更：新增 `03-首页.png`；更新 `产品设计说明_用户端APP_v1.0.md`；新增本操作日志。 +验证结果：确认图片文件存在且未覆盖其他设计稿；公告区域完整显示两条中文公告、日期和查看全部入口；四栏底部导航完整可见。 +风险评估：当前交付为产品设计图片，不代表智能设备接口已经上线；后续开发必须使用真实接口和命令回执，不得以静态成功结果替代。 + +--- + +操作时间：2026-09-05 21:48:32 +操作类型：新增、修改 +影响模块：智能角阀设备详情与控制 + +操作前状态：已完成首页设备概览，智能角阀详情页尚未确定。 +具体操作：基于已确认首页、原角阀控制设计和正式需求生成三个方案；按用户选择保存方案一。 +操作后状态：已形成智能角阀详情与控制页设计稿。 +代码变更：无代码变更。 +文件变更：新增 `04-智能角阀控制.png`；更新 `产品设计说明_用户端APP_v1.0.md`。 +验证结果：设备六项数据、安全检查、开阀操作、气瓶详情、安全记录和一键报修入口均完整显示。 +风险评估：开阀属于高风险操作，后续实现必须依赖服务端权限、风险检查、幂等命令和最终设备回执。 + +--- + +操作时间：2026-09-05 22:14:22 +操作类型：新增、修改 +影响模块：用户端一键报修 + +操作前状态：现有 App 仅提供简化的问题描述和工单提交，原设计包含更完整的报修信息。 +具体操作：合并当前工单能力、原报修流程和正式需求，生成三个方案并按用户选择保存引导式方案。 +操作后状态：已形成包含故障、照片、联系与地址、紧急提示的分步报修设计。 +代码变更：无代码变更。 +文件变更：新增 `05-一键报修.png`；更新 `产品设计说明_用户端APP_v1.0.md`。 +验证结果：故障类型、描述、语音、照片、联系人、地址、定位、紧急提示和下一步操作均完整可见。 +风险评估：照片、定位和语音涉及权限与隐私，后续实现需按使用时申请权限并避免日志记录敏感数据。 + +--- + +操作时间：2026-09-05 22:18:00 +操作类型：新增、修改 +影响模块：用户端添加设备流程 + +操作前状态：扫码、蓝牙和手动输入被错误作为同一页面的互斥设计候选。 +具体操作：按用户纠正，将三张图重新定义为添加设备的三个必需流程页面并全部保存；同步修订后续选稿规则。 +操作后状态：添加设备包含扫码确认、蓝牙连接和手动输入三个完整入口。 +代码变更：无代码变更。 +文件变更：新增 `06-1-扫码添加确认.png`、`06-2-蓝牙连接设备.png`、`06-3-手动输入设备码.png`；更新产品设计说明。 +验证结果：三张来源图片均已复制到最新参考产品设计目录，页面功能彼此补充而非互相替代。 +风险评估：后续候选必须保持业务内容一致，仅比较布局、层级和交互表达；不得因选稿删除扫码、蓝牙或手动输入能力。 + +--- + +操作时间：2026-09-05 23:30:00 +操作类型：新增、扩展 +影响模块：用户端 App 全量产品设计参考 + +操作前状态：目录仅完成登录、首次宣导、首页、角阀控制、报修和添加设备流程；其余商城、押金、订单履约、个人中心及扩展能力尚无统一新版设计稿。 +具体操作：按用户最新要求取消逐页三方案选稿，改为每种页面类型直接生成一张；同时对照原产品设计、当前用户端能力和 `docs/03-用户端App需求.md`，补全设备、安全、商城、气瓶购买、押金、订单、配送、售后、钱包、地址、消息、合同、家庭共享、内容中心及扩展页面。 +操作后状态：形成 49 个编号页面类型，其中添加设备包含三个并存流程，共 51 张 PNG；新增 `产品设计说明_用户端APP_v1.1.md` 作为完整索引。 +代码变更：无代码变更。 +文件变更：新增 `07-气瓶基本信息.png` 至 `49-预约安全巡检.png` 对应页面；新增 `产品设计说明_用户端APP_v1.1.md`。 +行为变化：设计交付流程由“每类三稿、逐张选择”调整为“每类一稿、直接落盘、按文件名定向返修”；三种设备添加方式继续作为独立业务流程保留。 +验证结果：共检查 51 张 PNG，全部可读取；主体图片尺寸为 853×1844，少量为 852×1846、885×1777 或 929×1693，均保持移动端竖屏比例；文件名唯一，未覆盖原产品设计目录；页面清单与设计说明已同步。 +边界验证：设计稿中未把后续规划功能标记为当前真实上线能力；支付、充值、提现、退款、设备命令、告警与配送轨迹均保留服务端回执、审核、失败或更新时间约束。 +风险评估：本次图片用于产品与开发参考，部分设备、安全、押金、消息、发票、收藏、紧急联系人及完整售后能力仍需等待 Client API；实现时禁止使用静态成功响应。图片中文字与真实业务字段仍需在开发前由产品和合规复核，紧急电话、服务范围、费用和协议版本必须由后台配置。 + +--- + +操作时间：2026-09-06 00:20:00 +操作类型：新增、补全 +影响模块：首次安全宣导标签页 + +操作前状态：`02-智能角阀功能介绍.png` 仅呈现“功能介绍”标签内容，“安全案例、法律法规、气价信息”只有入口，缺少独立内容状态设计。 +具体操作：沿用原弹层结构、四标签导航和蓝白视觉规范，分别生成安全案例、法律法规和气价信息三个标签状态。 +操作后状态：首次宣导四个标签均有对应设计图，可按同一页面的标签切换实现。 +代码变更：无代码变更。 +文件变更：新增 `02-1-安全案例.png`、`02-2-法律法规.png`、`02-3-气价信息.png`；更新 `产品设计说明_用户端APP_v1.1.md`。 +验证结果：三张新增图片均可读取，尺寸为 852×1846 或 853×1844；标签选中状态正确，未覆盖原 `02-智能角阀功能介绍.png`。 +风险评估：法规版本、地方适用范围、气价、押金和配送费必须由后台配置并带更新时间；设计稿中的金额仅作为结构示例，实际展示以服务端返回为准。 + +--- + +操作时间：2026-09-06 00:40:00 +操作类型：新增、补全 +影响模块：安全内容中心分类页 + +操作前状态：`43-安全内容中心.png` 仅呈现“全部”聚合状态，“安全宣传、安全视频、法律法规、平台公告”只有分类入口，缺少独立内容状态设计。 +具体操作：基于原安全内容中心的顶部导航、分类标签和蓝白视觉规范，结合用户端实际安全内容能力，分别生成安全宣传、安全视频、法律法规和平台公告四个分类页；各页保留检索、筛选、阅读状态、发布来源和日期等真实业务字段。 +操作后状态：安全内容中心五个分类状态均有对应设计图，可按同一页面的分类切换实现。 +代码变更：无代码变更。 +文件变更：新增 `43-1-安全宣传.png`、`43-2-安全视频.png`、`43-3-法律法规.png`、`43-4-平台公告.png`；更新 `产品设计说明_用户端APP_v1.1.md`。 +行为变化：补齐四个分类标签对应的完整内容页，不再仅将标签作为静态入口。 +验证结果：四张新增图片均可读取，尺寸均为 853×1844；文件哈希互不重复，未覆盖原 `43-安全内容中心.png`；目录内 PNG 总数更新为 58。 +风险评估：法规版本、生效日期、公告范围、视频时长、阅读状态及内容发布时间必须以后端数据为准；外部法规链接仍需保留跳转风险提示与域名校验。 + +--- + +操作时间：2026-09-06 11:28:15 +操作类型：新增、扩展 +影响模块：用户端 App 全量产品设计开发文档 + +操作前状态：最新参考产品设计目录已有 49 个主编号页面组、58 张设计图及设计说明，但缺少一份逐页面连接 Flutter 路由、Client API、数据模型、平台配置与验收测试的统一开发文档。 +具体操作：对照全部设计图、当前用户端代码、现有用户 Client API、平台内容配置及正式需求，新增全量功能开发文档；按 49 个页面组登记路由、现状、接口扩展和实施范围，并补充 UI 规范、数据模型、状态机、安全、测试、灰度与回滚要求。 +操作后状态：产品设计具备统一开发实施基线，现有能力与待开发能力已明确分开，可按阶段开展 UI 优化和接口补全。 +代码变更：无代码变更。 +文件变更：新增 `docs/项目文档_用户端APP全量功能开发_v1.0.md`；更新 `docs/README.md`、`doc/用户端APP-最新参考产品设计/产品设计说明_用户端APP_v1.1.md` 和本操作日志。 +验证结果：开发文档共 650 行，49 个主编号页面组、58 张设计图均已登记；文档包含项目概述、目录结构、核心文件、路由、Client API、数据模型、状态机、测试、交付阶段、风险与维护指南。 +风险评估：文档中的新增接口和数据实体属于目标设计，不代表已经上线；气价来源、安全视频性质、设备协议、支付渠道、退押规则、地图服务、发票服务和巡检规则仍需在对应阶段开发前完成业务确认。 diff --git a/docs/README.md b/docs/README.md index 7a3f693..2dcbff9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,14 @@ | [11-数据接口与安全](11-数据接口与安全.md) | 数据域、接口约定、物联网协议、安全及合规要求 | | [12-验收与迭代规划](12-验收与迭代规划.md) | MVP 边界、验收标准、非功能要求与版本路线图 | +## 专题实施文档 + +| 文档 | 用途 | +| --- | --- | +| [用户端 App 全量功能开发](项目文档_用户端APP全量功能开发_v1.0.md) | 将最新 58 张用户端产品设计图落实为页面路由、UI 规范、Client API、数据模型、测试和分阶段交付方案 | +| [用户端 App 全量开发 AI 提示词](开发提示词_用户端APP全量功能开发_v1.0.md) | 可直接交给开发 AI 使用，包含项目路径、设计与需求事实源、开发批次、接口规则、视觉验收、测试和交付要求 | +| [服务端 App 三岗位全量功能开发](项目文档_服务端APP三岗位全量功能开发_v1.0.md) | 将安装维修、配送、安全检查共 122 张最新设计图落实为角色路由、UI、Staff Client API、状态机、离线、安全、测试和交付方案 | + ## 阅读与维护规则 - “应/必须”表示上线验收项；“建议”表示增强项；“可选”表示扩展能力。 diff --git a/docs/开发提示词_用户端APP全量功能开发_v1.0.md b/docs/开发提示词_用户端APP全量功能开发_v1.0.md new file mode 100644 index 0000000..fe325c0 --- /dev/null +++ b/docs/开发提示词_用户端APP全量功能开发_v1.0.md @@ -0,0 +1,274 @@ +# 用户端 App 全量功能开发 AI 提示词 v1.0 + +## 1. 使用方式 + +在 Codex 或其他具备本机代码访问能力的开发 AI 中，将工作目录设为 `D:\5k\platforms`，然后把第 3 节“主提示词”完整发送给 AI。 + +首次运行从 A1 批次开始。后续继续开发时仍可使用同一提示词，AI 应读取进度文档后从第一个未完成批次继续，不重复已完成工作。 + +## 2. 路径速查 + +### 2.1 代码路径 + +| 内容 | 绝对路径 | +| --- | --- | +| 项目根目录 | `D:\5k\platforms` | +| 仓库开发规范 | `D:\5k\platforms\AGENTS.md` | +| Flutter 用户端 | `D:\5k\platforms\apps\user_app` | +| Flutter 共享设计系统 | `D:\5k\platforms\apps\heqi_design_system` | +| 用户端路由 | `D:\5k\platforms\apps\user_app\lib\app\router.dart` | +| 用户端 API Repository | `D:\5k\platforms\apps\user_app\lib\data\repositories\client_repository.dart` | +| 用户端 HTTP 客户端 | `D:\5k\platforms\apps\user_app\lib\data\services\api_client.dart` | +| 用户端领域模型 | `D:\5k\platforms\apps\user_app\lib\domain\models\client_models.dart` | +| 用户端 UI | `D:\5k\platforms\apps\user_app\lib\ui` | +| 用户端测试 | `D:\5k\platforms\apps\user_app\test` | +| Go API | `D:\5k\platforms\backend\api` | +| 用户端 Client API 逻辑 | `D:\5k\platforms\backend\api\internal\logic\client\user` | +| Client API 路由 | `D:\5k\platforms\backend\api\internal\routers\client.go` | +| 数据模型 | `D:\5k\platforms\backend\api\internal\models` | +| 模拟数据 | `D:\5k\platforms\backend\api\internal\seed\mock.go` | +| 平台配置后台 | `D:\5k\platforms\frontend\platform_admin` | + +### 2.2 产品设计与文档路径 + +| 优先级 | 内容 | 绝对路径 | +| ---: | --- | --- | +| 1 | 用户端全量开发主文档 | `D:\5k\platforms\docs\项目文档_用户端APP全量功能开发_v1.0.md` | +| 2 | 最新产品设计图，49 个编号组、58 张 PNG | `D:\5k\platforms\doc\用户端APP-最新参考产品设计` | +| 3 | 最新设计说明 | `D:\5k\platforms\doc\用户端APP-最新参考产品设计\产品设计说明_用户端APP_v1.1.md` | +| 4 | 用户端正式需求 | `D:\5k\platforms\docs\03-用户端App需求.md` | +| 5 | 核心跨系统流程 | `D:\5k\platforms\docs\02-核心业务流程.md` | +| 6 | 接口、安全和隐私规则 | `D:\5k\platforms\docs\11-数据接口与安全.md` | +| 7 | 验收场景 | `D:\5k\platforms\docs\12-验收与迭代规划.md` | +| 8 | 技术与命名规范 | `D:\5k\platforms\docs\10-技术实现规划.md` | +| 9 | 移动端设计系统 | `D:\5k\platforms\docs\13-移动端Design-System.md` | +| 10 | 原产品设计，仅用于核对历史功能 | `D:\5k\platforms\doc\用户端APP-产品设计` | + +业务规则发生冲突时，以安全、支付、权限、隐私等服务端规则和正式需求为准；页面布局、信息层级和视觉样式以“最新参考产品设计”为准。原设计只用于确认是否遗漏历史功能，不能覆盖已经确认的新设计。 + +## 3. 主提示词 + +````text +你现在负责“瓶安芯用户端 App”全量开发。不要只输出计划、审计报告或示例代码，要在现有仓库中实际完成代码、接口、测试、视觉核对和文档更新。 + +一、工作目录与目标 + +- 仓库根目录：D:\5k\platforms +- Flutter 用户端：D:\5k\platforms\apps\user_app +- 共享设计系统：D:\5k\platforms\apps\heqi_design_system +- Go API：D:\5k\platforms\backend\api +- 平台配置后台：D:\5k\platforms\frontend\platform_admin +- 用户端 API 根路径：/heqi/client/v1/user +- 目标：将 58 张最新产品设计图逐步开发为真实可操作的 Flutter 页面，并同步补齐所需 Go Client API、数据库模型、后台配置和自动化测试。 + +二、开始前必须完整阅读 + +1. D:\5k\platforms\AGENTS.md +2. D:\5k\platforms\docs\README.md +3. D:\5k\platforms\docs\项目文档_用户端APP全量功能开发_v1.0.md +4. D:\5k\platforms\doc\用户端APP-最新参考产品设计\产品设计说明_用户端APP_v1.1.md +5. D:\5k\platforms\docs\03-用户端App需求.md +6. D:\5k\platforms\docs\02-核心业务流程.md +7. D:\5k\platforms\docs\10-技术实现规划.md +8. D:\5k\platforms\docs\11-数据接口与安全.md +9. D:\5k\platforms\docs\12-验收与迭代规划.md +10. D:\5k\platforms\docs\13-移动端Design-System.md + +设计参考目录：D:\5k\platforms\doc\用户端APP-最新参考产品设计 + +原设计目录：D:\5k\platforms\doc\用户端APP-产品设计 + +每开发一个页面，必须先打开最新目录中同编号 PNG，确认布局、文案层级、状态、控件和导航；原设计只用于检查历史功能是否漏掉。不要凭记忆或仅根据文件名制作页面。 + +三、事实源优先级 + +1. 当前任务中的明确要求。 +2. 人身安全、设备控制、资金、合同、权限、隐私和审计等服务端规则。 +3. docs/03、docs/02、docs/10、docs/11、docs/12 的正式约束。 +4. 项目文档_用户端APP全量功能开发_v1.0.md。 +5. 用户端APP-最新参考产品设计中的图片和 v1.1 说明。 +6. 当前代码实现。 +7. 原产品设计。 + +视觉冲突按最新设计处理；业务冲突按服务端规则处理。任何会影响数据兼容、接口或业务口径的冲突都要写入开发进度和操作日志，不能静默选择。 + +四、当前真实基线 + +当前 Flutter 已经有登录、注册、首页、商城、订单、个人中心、合同记录、钱包记录、会话恢复和四栏底部导航，但页面数量远少于 58 张设计图。当前 ClientRepository 已接入公开内容、商品、用户资料、头像、钱包、地址、商城订单、燃气订单、合同、工单、流水、退款、支付、服务归属、创建地址、创建工单和创建商城订单等基础能力。 + +当前大量业务对象仍通过通用 ClientRecord 和 raw Map 承载。新增页面应逐步使用强类型 DTO、领域模型、Repository 和 ViewModel，但旧页面完成迁移与回归前不能删除兼容代码。 + +设备控制、安全事件、押金、消息、发票、收藏、紧急联系人、账户注销和完整售后等能力尚未全部落地。不能用静态成功页、延时动画、硬编码金额或本地修改状态冒充服务端实现。 + +五、开发账号与本地环境 + +仅在本地 Mock 数据环境使用： + +- 用户手机号：13800000001 +- 登录密码：Mock@123456 +- Mock 数据来源：D:\5k\platforms\backend\api\internal\seed\mock.go +- 本地 API：http://127.0.0.1:12426 +- Android 模拟器访问宿主机：http://10.0.2.2:12426 + +若 Mock 数据尚未写入，先检查数据库配置和已有数据，再在 D:\5k\platforms\backend\api 中使用与后端相同的本地环境配置执行 `go run ./cmd/cli/main.go mock-data`；该命令必须幂等，不能清库或覆盖用户数据。不得把 Mock 账号、密码或模拟支付逻辑带入生产配置和 Release 功能入口。 + +六、不可破坏的规则 + +- 先执行 git status，保留工作区中已有和未跟踪的设计图、文档及用户改动，不清理、不重置、不覆盖无关文件。 +- 保持 apps/user_app、apps/heqi_design_system 和现有技术栈，不新建另一套 App，不整体重写。 +- 保留 /login、/register、/home、/shop、/orders、/me 和现有 Client API 的向下兼容性。 +- 所有金额使用整数分；所有公开资源使用 identity，客户端不提交数据库自增 ID。 +- 状态、权限、金额、库存、设备控制、支付和安全判断由服务端确认，前端只展示服务端结果和 allowed_actions。 +- 写操作必须幂等；设备命令请求成功不等于执行成功，没有最终回执时只能显示“处理中”或“待确认”。 +- 高风险告警未解除时不能开阀，任何群控、自动规则或客户端缓存都不能绕过。 +- 支付、退款、提现、押金、合同、安全事件、设备命令和敏感访问必须可审计。 +- 手机号、地址、证件、银行卡、定位、照片、视频和合同执行最小权限、脱敏和受控访问。 +- 不物理删除资金、安全、订单、设备命令和审计事实。 +- 所有代码注释使用中文；新增 SQL 表和字段都添加准确中文 COMMENT，枚举和 JSON 结构写全。 +- 单个代码文件尽量不超过 1500 行，按功能拆分，不堆进 router.dart、client_repository.dart 或单个页面。 + +七、UI 实施要求 + +- 最新视觉参考：D:\5k\platforms\doc\用户端APP-最新参考产品设计 +- 主色 #2563EB，背景 #F7F8FA，成功 #16875D，警告 #B86400，危险 #C7352A。 +- 禁止紫色、渐变、AI 元素、Emoji、玻璃拟态、发光、三维装饰和无业务意义大卡片。 +- 一级导航固定为：首页、商城、订单、我的；二级页使用返回导航，不重复显示底栏。 +- 复用 heqi_design_system 和已有组件，已有能力不得重复实现。 +- 页面必须有 loading、content、empty、error、refreshing；写操作还要有 submitting、conflict、duplicate、unknown-result 和 retry 状态。 +- 图片中的人员、金额、设备状态、日期和成功提示只是设计样例，运行页面必须读取真实接口或明确的测试 Fixture。 +- 不允许把整张设计图当背景图实现页面。所有按钮、列表、Tab、筛选、表单、开关和导航都必须是真实组件并可操作。 +- 视觉比对基准为 390×844，同时验证 320、360、390、430 宽度和 1.3 倍文本缩放。 +- 每完成一页，使用相同数据、视口和状态生成实现截图，与对应设计图并排比较；修复间距、字体、圆角、边框、图标、溢出和底栏遮挡后再标记通过。 + +八、正确的实施方式 + +1. 先检查代码和后端路由，建立“已有、部分、缺失”事实表，不把文档规划误认为当前实现。 +2. 运行改动前基线测试，记录已有失败，不能把旧失败算成本次完成。 +3. 读取或创建 D:\5k\platforms\docs\开发进度_用户端APP全量功能开发.md，找到第一个未完成批次。 +4. 一次只完成一个可独立验收的批次，但必须包含所需 Flutter、Go API、模型、测试和文档，不留下只有 UI 没有真实行为的半成品。 +5. 页面需要新接口时先定义契约、错误码、权限、幂等和状态机，再实现 Go 接口及测试，最后接入 Flutter。 +6. 涉及内容、价格、规则、通知、发票或运营开关时，同时补平台后台配置；不要在 App 中写死运营数据。 +7. 每个批次完成后运行最小充分测试、视觉对照、更新开发进度和中文操作日志，然后继续下一批次。 +8. 发现业务口径未确认时，只暂停受影响动作，继续完成不依赖该口径的页面、模型、只读状态和测试；不得自行固化政策。 + +九、批次顺序 + +A1：公共底座与五个一级页面 + +- 统一主题、公共状态组件、页面脚手架和四栏导航。 +- 按 01-登录页.png、03-首页.png、11-燃气商城.png、20-订单中心.png、25-个人中心.png 优化现有页面。 +- 保持真实登录、服务归属、公开内容、商品、订单、钱包摘要和头像能力。 +- 补强类型基础模型、加载/空/错误状态和对应 Widget 测试。 + +A2：现有业务闭环优化 + +- 开发或完善 14 提交订单、19 支付确认、21 订单详情、28 钱包、29 地址、32 合同、38 充值、39 提现、40 银行卡、41 个人资料、42 报修详情。 +- 保持现有 API 兼容，补详情、分页、地址编辑、支付结果查询、错误码和幂等测试。 + +B：设备与安全闭环 + +- 开发 04 至 10、34、35、44 页面。 +- 打通设备绑定、扫码/蓝牙/手输、遥测、命令回执、告警、紧急联系人、分组控制和定时关阀。 +- 通过 AC-01 至 AC-05、AC-12、AC-15、AC-22、AC-23、AC-25。 + +C：交易、押金与服务履约 + +- 开发或完善 12 至 18、22 至 24、36、48、49 页面。 +- 打通商品详情、购物车、收藏、气瓶下单、押金与退押、配送详情、轨迹、发票、售后、评价和巡检预约。 +- 金额、库存、支付、退押、退款、履约和发票均以服务端事实为准。 + +D：内容、消息与扩展能力 + +- 开发 02 及 02-1 至 02-3、26、27、30、31、33、43 及 43-1 至 43-4、45、46、47 页面。 +- 完成内容版本、气价、阅读确认、消息、家庭共享、保修卡、设备月报和安全考试。 + +不要一次创建 58 个空页面或静态路由。按以上顺序做真实的垂直切片，完成一个批次才进入下一个批次。若进度文档显示某批次已通过，直接从第一个未完成批次继续。 + +十、接口和数据实现要求 + +- 严格按照“项目文档_用户端APP全量功能开发_v1.0.md”第 6 至第 10 节实施 Client API、领域模型、状态机、设备命令、支付和安全规则。 +- 后端路由注册在 backend/api/internal/routers/client.go；业务逻辑放入 backend/api/internal/logic/client/user 的对应领域文件；模型放 backend/api/internal/models。 +- 不把复杂业务继续全部塞进 client_repository.dart。保留兼容门面，逐步拆分 auth、home、device、safety、shop、order、wallet、content 等 Repository。 +- 新页面不得依赖 raw Map 读取关键状态、金额、权限或设备数据。 +- 列表统一分页；详情响应包含 status_code、status_name、version 和 allowed_actions，并兼容现有字段。 +- 修改模型或路由后同步路由测试、契约和平台后台资源；涉及平台后台时执行 contract:sync 和 contract:check。 + +十一、验证命令 + +Flutter 用户端按实际改动执行： + +- cd D:\5k\platforms\apps\user_app +- flutter analyze +- flutter test --no-pub +- flutter build web --release --no-pub --dart-define=API_BASE_URL=http://127.0.0.1:12426 +- 涉及移动插件时再验证 flutter build apk --debug；具备 macOS 环境时验证 iOS Simulator。 + +Go API 按实际改动执行： + +- cd D:\5k\platforms\backend\api +- go test ./... +- go vet ./... +- go build ./cmd/main/main.go + +平台后台发生改动时执行： + +- cd D:\5k\platforms\frontend\platform_admin +- pnpm contract:sync +- pnpm type:check +- pnpm lint +- pnpm contract:check +- pnpm build + +不要用全仓自动修复或格式化掩盖业务改动。测试不能运行时说明具体环境原因，并继续完成能执行的定向检查。 + +十二、进度与交付 + +维护 D:\5k\platforms\docs\开发进度_用户端APP全量功能开发.md，至少记录： + +- 58 张图片逐页状态：未开始、开发中、待接口、已实现、已验收。 +- 页面路由、对应接口、测试文件和视觉截图路径。 +- 当前批次、已完成内容、阻塞项、风险和下一批起点。 + +每个批次新增中文操作日志，记录操作时间、修改文件与函数、变更前后行为、测试结果、边界案例和风险。重大结构或接口变更同步更新项目文档。 + +最终回复必须包含： + +- 本批次实际完成的页面与真实功能。 +- 修改文件和关键行为变化。 +- 新增或变更接口。 +- 实际运行的测试及结果。 +- 视觉比对结果和截图路径。 +- 尚未完成或需要业务确认的内容。 + +十三、现在开始 + +先读取规范、主开发文档、最新设计说明和当前代码，检查 git status 并运行基线测试。随后不要停在分析阶段：如果没有已有进度记录，立即实施 A1“公共底座与五个一级页面”；如果已有进度记录，从第一个未完成批次继续。完成本批次代码、真实接口接入、测试、视觉核对、进度文档和操作日志后再汇报。 +```` + +## 4. 开发顺序说明 + +推荐从 A1 开始，而不是直接制作设备控制或支付页面，原因如下： + +- 登录、首页、商城、订单和个人中心已经具备真实接口基础，可以先建立稳定的 UI、路由和状态组件。 +- 后续 58 张页面都会复用 A1 的主题、列表、状态、金额、错误和导航能力。 +- 先完成真实页面骨架，可以尽早发现设计系统、响应结构和路由兼容问题。 +- 设备、资金与安全能力风险较高，必须等契约、幂等、审计和状态机明确后再接入。 + +## 5. 本地联调速查 + +开发环境 Mock 用户： + +| 项目 | 值 | +| --- | --- | +| 手机号 | `13800000001` | +| 密码 | `Mock@123456` | +| API | `http://127.0.0.1:12426` | +| Android 模拟器 API | `http://10.0.2.2:12426` | + +账号只适用于执行过 `mock-data` 的本地开发库。凭据来源为 `backend/api/internal/seed/mock.go`，不得用于生产环境或写入生产配置。 + +## 6. 变更记录 + +| 版本 | 日期 | 内容 | +| --- | --- | --- | +| v1.0 | 2026-09-07 | 建立用户端 App 全量开发 AI 主提示词，明确路径、事实源、开发批次、真实接口、视觉验收、测试和交付要求 | diff --git a/docs/操作日志_服务端APP三岗位开发文档_20260906.md b/docs/操作日志_服务端APP三岗位开发文档_20260906.md new file mode 100644 index 0000000..1e33269 --- /dev/null +++ b/docs/操作日志_服务端APP三岗位开发文档_20260906.md @@ -0,0 +1,44 @@ +# 操作日志：服务端 App 三岗位开发文档 + +操作时间：2026-09-06 17:49:13 +操作类型：新增 +影响模块：服务端 App 产品设计落地、Flutter 开发规划、Staff Client API 规划 + +## 操作前状态 + +- 安装维修端、配送端、安全检查端最新产品设计图已生成，共 122 张。 +- 已有《服务端 APP 三岗位产品设计与开发》高层说明，但未逐页落到路由、接口、状态和验收。 +- 当前 Flutter 仅有通用任务页面和三栏导航，Go Staff Client API 只覆盖基础登录、准入、任务、配送、钱包和取证能力。 + +## 具体操作 + +- 核对三个最新产品设计目录及岗位产品设计说明。 +- 核对 `apps/service_app` 当前路由、领域模型、Repository 和离线草稿能力。 +- 核对 `backend/api/internal/routers/client.go` 中已注册 Staff Client API。 +- 新增全量开发文档，逐项覆盖 40 个安装维修页面、42 个配送页面和 40 个安全检查页面。 +- 明确蓝色主题、无紫色、无 AI 元素的视觉要求，并记录与旧移动端设计系统的冲突处理。 +- 补充接口规划、状态机、数据模型、离线、安全、测试、阶段计划和完成定义。 + +## 操作后状态 + +- 已形成可供产品、Flutter、后端和测试共同评审的全量开发基线。 +- 文档明确区分“已有、部分、待开发”，未将设计图误记为已实现功能。 +- 未修改现有业务代码、数据库或接口行为。 + +## 文件变更 + +- 新增 `docs/项目文档_服务端APP三岗位全量功能开发_v1.0.md`。 +- 新增 `docs/操作日志_服务端APP三岗位开发文档_20260906.md`。 +- 更新 `docs/README.md` 的专题实施文档索引。 + +## 验证结果 + +- 已检查 Markdown 表格、标题层级、页面数量、角色编码和现有 API 路径。 +- 已确认全量文档小于 1500 行。 +- 未运行 Flutter 或 Go 测试，因为本次只新增文档，不改变可执行代码。 + +## 风险评估 + +- 新增接口均为目标设计，开发前仍需完成产品口径、权限和数据库评审。 +- 旧设计系统中的服务端紫色主题与最新设计冲突，实施 P0 时必须同步代码和文档，并验证用户端主题无回归。 +- 三岗位共享基础设施但业务状态机不同，开发时不可继续扩展为一个通用动态表单。 diff --git a/docs/操作日志_用户端APP开发提示词_20260907.md b/docs/操作日志_用户端APP开发提示词_20260907.md new file mode 100644 index 0000000..3e81e22 --- /dev/null +++ b/docs/操作日志_用户端APP开发提示词_20260907.md @@ -0,0 +1,43 @@ +# 操作日志：用户端 App 开发提示词 + +操作时间：2026-09-07 18:50:44 +操作类型：新增 +影响模块：用户端 App 开发启动、文档索引 + +## 操作前状态 + +- 用户端最新参考产品设计已有 49 个主编号页面组、58 张 PNG。 +- 已有用户端全量功能开发文档，但缺少一份可直接交给开发 AI 执行的总提示词。 +- 当前 Flutter 用户端已有真实登录、首页、商城、订单、个人中心和部分记录能力。 + +## 具体操作 + +- 核对 Flutter 用户端、共享设计系统、Go Client API、数据模型、模拟数据和平台后台路径。 +- 核对最新产品设计说明、正式需求、跨系统流程、安全、验收和全量开发文档。 +- 新增可直接使用的 AI 主提示词，写明事实源优先级、开发批次、接口规则、视觉要求、测试和交付格式。 +- 写入本地 Mock 用户账号来源和联调地址，并明确不得进入生产配置。 +- 更新 `docs/README.md` 专题实施文档索引。 + +## 操作后状态 + +- 开发 AI 可从 `D:\5k\platforms` 直接按提示词开始 A1 批次。 +- 提示词要求先读取现状、保护已有改动，再进行实际编码，不允许只生成计划或静态成功页面。 +- 未修改 Flutter、Go、数据库或平台后台业务代码。 + +## 文件变更 + +- 新增 `docs/开发提示词_用户端APP全量功能开发_v1.0.md`。 +- 新增 `docs/操作日志_用户端APP开发提示词_20260907.md`。 +- 更新 `docs/README.md`。 + +## 验证结果 + +- 已核对全部引用路径存在。 +- 已核对最新设计目录包含 58 张 PNG。 +- 已核对 Mock 用户手机号与密码来源。 +- 本次仅新增文档，未运行 Flutter 或 Go 测试。 + +## 风险评估 + +- 全量功能开发跨越 Flutter、API、数据库和后台配置，必须按批次交付，不能一次创建大量空页面。 +- 设备、安全和资金能力必须先完成服务端契约与审计，禁止由客户端模拟成功。 diff --git a/docs/项目文档_服务端APP三岗位产品设计与开发_v1.0.md b/docs/项目文档_服务端APP三岗位产品设计与开发_v1.0.md new file mode 100644 index 0000000..7db1642 --- /dev/null +++ b/docs/项目文档_服务端APP三岗位产品设计与开发_v1.0.md @@ -0,0 +1,182 @@ +# 项目文档：服务端 APP 三岗位产品设计与开发 v1.0 + +## 1. 项目概述 + +### 1.1 项目名称 + +服务端 APP 安装维修、配送、安全检查三岗位 UI 优化与功能完善。 + +### 1.2 目标 + +以三个“最新参考产品设计”目录为目标界面，升级现有 Flutter `apps/service_app`。保留当前真实登录、角色识别、准入、任务、取证、草稿和接口能力，通过扩展路由、领域状态机、专用页面与服务端接口补齐业务闭环。 + +### 1.3 目标设计目录 + +- `doc/服务端APP-安装端-最新参考产品设计`：40 张页面。 +- `doc/服务端APP-配送端-最新参考产品设计`：42 张页面。 +- `doc/服务端APP-安全检查端-最新参考产品设计`：40 张页面。 + +上述图片是目标状态，不是当前完成状态。各岗位目录中的《产品设计说明》提供逐页功能和验收要求。 + +## 2. 当前系统状态 + +### 2.1 已有能力 + +- Flutter 单应用支持登录后按角色进入安装维修、配送或安全检查岗位。 +- 路由已有 `/login`、`/preflight`、`/tasks/:identity`、`/tasks/:identity/evidence`、`/work`、`/records`、`/me`。 +- 仓储层已有个人资料、作业前检查、钱包、考勤、任务列表与详情。 +- 通用工单已有开始、异常、恢复和结果提交。 +- 配送已有轨迹追加、到达和签收提交。 +- 证据文件可上传，本地草稿具备加密保存基础。 + +### 2.2 主要差距 + +- 当前路由以通用页面为主，无法承载三个岗位各自的完整步骤、字段和异常分支。 +- 后端接口尚未覆盖岗位申请、每日培训、详细资质、排单、气瓶、收款、隐患、整改、复检、提现、知识库、人工支持等目标能力。 +- 任务状态和 `allowed_actions` 不完整，客户端容易出现“页面有按钮但服务端不可执行”的风险。 +- 记录、统计、个人资料、通知和离线冲突仍需领域化。 +- 当前完成状态不能由图片推断，必须以代码、接口和自动化测试为准。 + +## 3. 技术栈与运行环境 + +- 客户端：Flutter、Dart、GoRouter、现有网络与本地存储封装。 +- 服务端：沿用项目现有 `/heqi/client/v1/staff` API 体系。 +- 本地数据：延续现有加密草稿机制，新增附件队列、重试、冲突版本和清理策略。 +- 运行环境：项目当前 Flutter 与 Android 构建环境；不得为本次 UI 优化替换应用框架。 + +## 4. 目录结构建议 + +```text +apps/service_app/lib/ +├── app/ +│ ├── router.dart # 现有路由入口，扩展岗位子路由 +│ └── dependencies.dart # 仓储、草稿、会话等依赖 +├── data/ +│ ├── models/ # 任务、证据、风险、气瓶、结算模型 +│ └── repositories/ +│ └── service_repository.dart # 保留现有方法并扩展岗位接口 +├── domain/ +│ ├── installation/ # 安装维修状态与动作 +│ ├── delivery/ # 配送与空瓶状态与动作 +│ ├── inspection/ # 安检、隐患、整改和复检 +│ └── shared/ # 身份、准入、钱包、通知、离线 +└── ui/ + ├── design_system/ # 颜色、文字、间距、按钮、状态标签 + ├── features/shared/ # 登录、准入、消息、钱包、个人中心 + ├── features/installation/ # 安装维修专用页面 + ├── features/delivery/ # 配送专用页面 + └── features/inspection/ # 安检专用页面 +``` + +原则：通过新增目录、页面和方法扩展现有实现；保留公共接口与现有路由兼容层，避免一次性重写。 + +## 5. 共享设计系统 + +| 项目 | 规范 | +| --- | --- | +| 主色 | `#2563EB` | +| 页面背景 | `#F7F8FA` | +| 成功 | `#16875D` | +| 提醒 | `#B86400` | +| 危险 | `#C7352A` | +| 页面边距 | 20px 视觉基准，代码按 Flutter 逻辑像素适配 | +| 圆角 | 最大 8px，除头像、状态点、开关等固有圆形控件 | +| 图标 | Material 或项目既有图标库，禁止手绘占位符 | +| 禁止项 | 紫色、紫色渐变、光晕、AI 图形、AI 文案、装饰性大卡片 | + +## 6. 路由与模块规划 + +### 6.1 共享路由 + +- 登录、岗位申请、作业前检查、准入阻断、每日培训。 +- 消息、钱包、提现、银行卡、离线队列、个人资料、二维码、设置、人工支持、知识库和反馈。 +- 共享页面通过角色配置切换标题、字段、权限和接口，不硬编码岗位文案。 + +### 6.2 安装维修模块 + +- 工单列表与详情、使用条件、材料、安装、测试、前期安检、签名、收款、完成。 +- 维修执行、安全检查、异常恢复、巡检、复检、备件、保修和回访。 + +### 6.3 配送模块 + +- 订单、接单改派、时间排单、路线排单、导航到达、围栏异常。 +- 气瓶扫描、随瓶安检、取证、收款、签收、空瓶回收、蓝牙设备和轨迹补传。 +- 服务用户、配送记录与配送统计。 + +### 6.4 安全检查模块 + +- 任务、到场、设备、环境、取证、签名、合格结果和完成。 +- 不合格、风险分级、一级高风险处置、整改通知、隐患、整改、复检和拒检。 +- 区域抽查、安检记录与安检统计。 + +## 7. 服务端接口规划 + +### 7.1 兼容原则 + +- 保留现有路径和响应字段，新增字段均允许旧客户端忽略。 +- 新动作优先添加子资源或动作端点，不改变现有 `start`、`exception`、`recover`、`submit-result` 语义。 +- 所有变更动作接收幂等键并返回服务端版本号、最终状态和 `allowed_actions`。 +- 错误响应返回稳定错误码、用户可读消息、是否可重试和必要的当前资源快照。 + +### 7.2 共享接口组 + +- 岗位申请与审核、角色和组织、资质与到期提醒。 +- 作业前检查、考勤、培训、授权设备和阻断原因。 +- 钱包明细、提现、银行卡、消息、知识库、人工服务请求和反馈。 +- 附件初始化、分片上传、完成确认、校验失败和断点续传。 + +### 7.3 岗位专用接口组 + +- 安装维修：条件、材料、步骤、测试、签名、收款、备件、保修与回访。 +- 配送：接单、改派、排单、气瓶、围栏、安检、收款、签收、空瓶、押金和轨迹。 +- 安检：检查项、测量值、风险分级、抢险联动、整改单、隐患、整改、复检和拒检。 + +## 8. 数据模型要求 + +- 所有任务包含 `id`、`role_code`、`status`、`version`、`allowed_actions`、计划时间、用户与脱敏地址。 +- 所有状态事件包含操作人、角色、设备、客户端时间、服务端时间、定位与幂等键。 +- 证据包含类型、业务步骤、文件哈希、大小、MIME、拍摄时间、定位精度、本地状态和服务端文件标识。 +- 金额使用最小货币单位整数，分别记录商品、押金、优惠、线上、线下、已核验、待核验和差额。 +- 风险字段固定枚举并带规则版本，禁止自由文本替代等级。 +- 数据库新增字段必须提供中文 `COMMENT`；枚举字段列出全部值，JSON 字段说明结构。 + +## 9. 离线与安全 + +- 草稿、附件和签名使用系统安全存储管理的密钥加密，日志不记录明文手机号、地址、签名或文件内容。 +- 离线队列按资源和动作排序；相同幂等键只执行一次。 +- 冲突时展示本地版本、服务端版本和差异，不静默覆盖。 +- 退出登录、切换账号和清理缓存前检查未同步数据并阻断危险操作。 +- 地图列表默认显示模糊点位，精确地址仅在授权任务详情展示。 + +## 10. 分阶段开发计划 + +| 阶段 | 范围 | 完成标准 | +| --- | --- | --- | +| P0 | 共享设计系统、角色路由、准入、状态与错误模型 | 三岗位可登录并进入正确工作台，现有功能无回归 | +| P1 | 三岗位核心任务主链路 | 安装、配送、安检各有一条正常链路端到端完成 | +| P2 | 高风险与异常链路 | 阻断、失败、拒检、一级风险、改派、围栏异常可闭环 | +| P3 | 离线、证据、冲突与幂等 | 弱网、断网、重复提交和版本冲突测试通过 | +| P4 | 钱包、记录、统计、资质与支持 | 目标目录全部页面有对应路由、接口或明确只读状态 | +| P5 | 全量视觉与回归 | 逐页截图比对、无障碍、性能、安全和兼容性验收通过 | + +## 11. 测试策略 + +- 单元测试：金额、风险分级、允许动作、状态转换、幂等和冲突合并。 +- 仓储测试：现有 API 兼容、新接口解析、错误码、重试和超时。 +- Widget 测试：表单校验、按钮状态、长文本、空列表、失败和离线提示。 +- 集成测试：三岗位正常链路及关键异常链路。 +- 安全测试：越权、敏感信息、日志泄露、本地加密、附件伪造和重复提交。 +- 视觉回归：目标图片与相同状态、相同逻辑尺寸的 Flutter 截图并排比较。 + +## 12. 验收与发布 + +- 每张目标图片必须映射到页面、路由、状态、接口和测试，不以“已经画图”代替开发完成。 +- 原有真实登录、任务、取证、草稿和配送接口行为必须保持兼容。 +- 关键接口必须先在测试环境验证，再分岗位灰度发布。 +- 发布前完成数据库变更审核、接口文档、移动端回归、异常演练和回滚方案。 + +## 13. 变更记录 + +| 版本 | 日期 | 内容 | +| --- | --- | --- | +| v1.0 | 2026-09-06 | 建立三岗位目标产品设计与开发对照，明确共享架构、接口、状态机、离线、安全、测试和发布要求 | diff --git a/docs/项目文档_服务端APP三岗位全量功能开发_v1.0.md b/docs/项目文档_服务端APP三岗位全量功能开发_v1.0.md new file mode 100644 index 0000000..5ee948a --- /dev/null +++ b/docs/项目文档_服务端APP三岗位全量功能开发_v1.0.md @@ -0,0 +1,694 @@ +# 服务端 App 三岗位全量功能开发文档 v1.0 + +## 1. 项目概述 + +### 1.1 项目名称 + +瓶安芯服务端 App 安装维修、配送、安全检查三岗位产品设计落地与全量功能开发。 + +### 1.2 文档目标 + +本文档以三个“最新参考产品设计”目录中的 122 张页面设计图为目标界面，结合现有 Flutter `apps/service_app`、Go Staff Client API、正式需求和当前数据库模型，指导研发完成以下工作： + +- 按已确认设计图优化三岗位 UI，保留蓝白、正式、简洁的移动端视觉方向。 +- 保留现有真实登录、角色识别、作业前检查、任务、取证、轨迹、签收、钱包和加密草稿能力。 +- 将通用任务页面扩展为安装维修、配送和安全检查三套独立业务流程。 +- 补齐岗位申请、每日培训、消息、资质、排单、气瓶、收款、隐患、整改、复检、统计、提现、知识库和人工支持等接口闭环。 +- 建立逐设计图的路由、状态、接口、异常处理、测试和发布验收标准。 + +### 1.3 设计事实源 + +| 岗位 | 设计目录 | 页面数量 | 角色编码 | +| --- | --- | ---: | --- | +| 安装维修 | `doc/服务端APP-安装端-最新参考产品设计` | 40 | `installer` | +| 配送 | `doc/服务端APP-配送端-最新参考产品设计` | 42 | `delivery` | +| 安全检查 | `doc/服务端APP-安全检查端-最新参考产品设计` | 40 | `operations` | + +设计图是目标状态，不代表页面、接口或数据库已经实现。图中的人员、地址、金额、日期、任务编号和成功状态均为演示数据，开发时必须以服务端返回结果为准。 + +### 1.4 事实源优先级 + +发生冲突时按以下顺序处理： + +1. 人身安全、资金、隐私、权限和审计等服务端强制规则。 +2. `docs/04-服务端App需求.md`、`docs/02-核心业务流程.md`、`docs/11-数据接口与安全.md`。 +3. 本文档中的接口、状态机、兼容和验收约束。 +4. 三个“最新参考产品设计”目录及其产品设计说明。 +5. 当前 Flutter 与 Go 实现。 + +`docs/13-移动端Design-System.md` 中服务端 App 的紫色主色与本次已确认设计冲突。本项目以蓝色 `#2563EB` 为准，P0 阶段必须同步更新设计系统代码和该文档；用户端现有蓝色主题不得受影响。 + +## 2. 当前实现基线 + +### 2.1 已有 Flutter 能力 + +当前 `apps/service_app` 不是空项目，已经具备以下真实能力： + +- 登录、会话恢复、令牌失效处理和角色识别。 +- `/preflight` 作业前检查及上下班打卡。 +- `/work`、`/records`、`/me` 三栏导航。 +- `/tasks/:identity` 通用任务详情和 `/tasks/:identity/evidence` 通用取证。 +- 安装维修与安检读取 `/tickets`；配送读取 `/delivery/orders`。 +- 工单开始、异常、恢复、结果提交；配送开始、轨迹、到达、异常、恢复和签收。 +- 图片或视频上传、签名媒体类型、定位采集和加密草稿基础。 +- 钱包概览读取。 + +### 2.2 已有 Staff Client API + +基础路径为 `/heqi/client/v1/staff`。以下接口已在 `backend/api/internal/routers/client.go` 注册，必须保持兼容： + +| 方法与路径 | 当前能力 | 说明 | +| --- | --- | --- | +| `POST /auth/verification-code` | 已有 | 工作人员验证码 | +| `POST /auth/login` | 已有 | 密码或验证码登录，仅支持三种岗位角色 | +| `POST /auth/reset-password` | 已有 | 验证码重置密码 | +| `GET /auth/profile` | 已有 | 人员、手机号、岗位、工作状态 | +| `PUT /auth/password` | 已有 | 修改登录密码 | +| `GET /preflight` | 部分 | 账号、角色、组织、资质、出勤已检查；培训、区域、授权设备为 `not_configured` | +| `POST /attendance` | 已有 | 上下班打卡，进行中任务会阻止下班 | +| `GET /tickets`、`GET /tickets/:identity` | 已有 | 安装、维修、安检、复检工单 | +| `POST /tickets/:identity/start` | 已有 | 已分派工单开始执行 | +| `POST /tickets/:identity/exception` | 已有 | 工单异常暂停 | +| `POST /tickets/:identity/recover` | 已有 | 异常工单恢复 | +| `POST /tickets/:identity/submit-result` | 部分 | 结果、结论、证据和签名；不足以承载全部分步表单 | +| `GET /delivery/orders`、`GET /delivery/orders/:identity` | 已有 | 当前配送员订单与明细 | +| `POST /delivery/orders/:identity/start` | 已有 | 开始配送 | +| `POST /delivery/orders/:identity/tracks` | 已有 | 1 至 100 个轨迹点批量追加 | +| `POST /delivery/orders/:identity/arrive` | 已有 | 定位和围栏校验后到达 | +| `POST /delivery/orders/:identity/exception` | 已有 | 配送异常暂停 | +| `POST /delivery/orders/:identity/recover` | 已有 | 配送恢复 | +| `POST /delivery/orders/:identity/submit-receipt` | 部分 | 收件人、签名凭证和完成；未含完整气瓶、安检、收款、空瓶数据 | +| `/wallet`、`/wallet/records` | 已有 | 钱包和流水 | +| `/wallet/recharges` | 已有 | 充值基础接口，工作人员端是否开放由产品权限控制 | +| `/wallet/banks` | 已有 | 银行卡列表、绑定和解绑 | +| `/wallet/withdrawals` | 已有 | 提现列表和申请 | + +### 2.3 主要差距 + +| 范围 | 当前状态 | 开发要求 | +| --- | --- | --- | +| 导航与路由 | 仅三栏和通用任务页 | 按角色配置四栏导航，保留旧路由兼容跳转 | +| 领域模型 | `WorkItem.raw` 承载大量动态字段 | 新页面使用强类型 DTO、领域模型和状态对象 | +| 工单动作 | 客户端对 ticket 动作有本地硬编码 | 服务端为 ticket 补齐 `allowed_actions` 和字符串状态码 | +| 岗位流程 | 安装、维修、安检共用通用详情和取证 | 拆分独立 Feature、ViewModel、Use Case 和状态机 | +| 准入 | 三项仍为 `not_configured` | 接入每日培训、服务区域、授权设备及岗位专用检查 | +| 证据 | 可上传但缺统一会话、哈希和同步明细 | 补分步证据、原始时间、哈希、重试和冲突处理 | +| 资金 | 后端接口较完整，客户端仅钱包概览 | 补流水、提现、银行卡、对账、收款确认页面 | +| 内容与支持 | 未发现对应 Staff API 与页面 | 新增消息、知识库、人工支持、反馈和会诊 | + +## 3. 开发边界与兼容原则 + +- 使用现有 Flutter 单应用和三角色账号体系，不拆成三个安装包。 +- 一个工作人员账号只允许一个服务角色；客户端不得提供本地切换岗位功能。 +- 保留现有 `/work`、`/records`、`/me`、`/tasks/:identity` 和 `submit-result` 等公共入口与接口，新增角色路由后提供兼容重定向。 +- 新接口继续使用 `/heqi/client/v1/staff`，不得更改已有字段语义；新增字段应允许旧客户端忽略。 +- 安装维修与安全检查继续以 `/tickets` 为任务事实源；配送继续以 `/delivery/orders` 为订单事实源。 +- 客户端只展示服务端返回的 `allowed_actions`，不得根据按钮顺序或本地状态猜测可执行动作。 +- 高风险、收款、签收、库存、提现和最终完成必须在线取得服务端确认；断网时只能保存草稿或待同步动作。 +- 所有新增表、字段、枚举和 JSON 数据都必须按项目规范提供中文数据库注释。 + +## 4. UI 优化实施规范 + +### 4.1 视觉基线 + +| 项目 | 目标规范 | +| --- | --- | +| 主色 | `#2563EB`，服务端三岗位统一使用 | +| 页面背景 | `#F7F8FA` | +| 成功 | `#16875D` | +| 提醒 | `#B86400` | +| 高风险与失败 | `#C7352A` | +| 页面边距 | 20dp 视觉基准，小屏可降至 16dp | +| 圆角 | 业务卡片和输入框最大 8dp；头像、状态点和开关可保持固有圆形 | +| 触控区 | 不小于 48dp；主按钮高度 52dp | +| 图标 | 优先 Material Icons 或现有图标库，不使用手绘占位图标 | +| 禁止项 | 紫色、紫色渐变、发光、玻璃拟态、AI 图形、AI 助手、AI 文案、无业务意义装饰 | + +### 4.2 角色导航 + +底部导航与已确认工作台设计保持一致： + +| 角色 | 一级导航 | +| --- | --- | +| 安装维修 | 工单、巡检、记录、我的 | +| 配送 | 订单、任务、用户、我的 | +| 安全检查 | 任务、记录、隐患、我的 | + +导航使用角色配置生成，不在同一 Widget 内堆叠多层岗位判断。二级作业页不显示底部导航，返回时恢复原列表筛选、滚动位置和分页状态。 + +### 4.3 公共组件 + +优先扩展 `apps/heqi_design_system`，角色专用组合组件放入 `apps/service_app/lib/ui/core`： + +| 组件 | 职责 | +| --- | --- | +| `ServiceAppScaffold` | SafeArea、背景、标题栏、底部操作区和键盘避让 | +| `AsyncContent` | 首次加载、刷新、分页、空数据、错误和重试 | +| `RoleNavigationBar` | 三角色四栏导航配置 | +| `StatusPill` | 状态文字、图标和语义色，不只依赖颜色 | +| `TaskSummaryHeader` | 编号、类型、SLA、地址、用户和允许动作 | +| `ChecklistSection` | 版本化检查项、必填、测量值、结果和问题说明 | +| `EvidencePicker` | 图片、视频、签名、拍摄时间、定位和上传状态 | +| `MoneyBreakdown` | 应收、线上、线下、押金、差额和核验状态 | +| `TimelineView` | 任务、隐患、整改、复检、轨迹和审核事件 | +| `SyncStatusBar` | 草稿、上传、失败、冲突和最后同步时间 | +| `RiskActionPanel` | 风险等级、强制动作、阻断原因和人工升级 | + +不得重复造已有组件，不得在卡片中再嵌套装饰性卡片。首页以可扫描信息和快捷动作优先，一屏只保留一个主操作。 + +### 4.4 页面状态与适配 + +每个异步页面必须覆盖 `initial/loading/content/empty/error/refreshing/offline/conflict/submitting`。写操作还必须覆盖重复提交、服务端拒绝、结果未知和成功回执。 + +- 以 390×844 逻辑像素进行主视觉比对，同时测试 320、360、390、430 宽度。 +- 文本缩放 1.3 倍后，任务编号、风险、金额、状态和按钮不得遮挡或截断关键含义。 +- 底部操作区需避开系统手势区和软键盘，长表单允许滚动至错误字段。 +- 地图、相机、扫码、蓝牙、定位和通知权限被拒绝时必须提供明确恢复入口。 +- 暗色主题如保留，主色也必须为蓝色，不得回退到紫色。 + +## 5. Flutter 架构与目录规划 + +```text +apps/service_app/lib/ +├── app/ +│ ├── router.dart # 根路由、鉴权、准入和兼容跳转 +│ ├── role_navigation.dart # 三角色一级导航配置 +│ └── dependencies.dart # Repository、平台适配器和会话依赖 +├── data/ +│ ├── dto/ # 请求、响应和分页 DTO +│ ├── repositories/ +│ │ ├── staff_repository.dart # 资料、准入、消息、资金和内容 +│ │ ├── installation_repository.dart # 安装维修、巡检、备件和保修 +│ │ ├── delivery_repository.dart # 配送、气瓶、空瓶、轨迹和用户 +│ │ └── inspection_repository.dart # 安检、隐患、整改和复检 +│ ├── offline/ # 加密草稿、附件队列、冲突和清理 +│ └── services/ # HTTP、定位、扫码、蓝牙、通知和文件 +├── domain/ +│ ├── shared/ # 人员、资质、准入、钱包和消息 +│ ├── installation/ # 安装维修状态机和 Use Case +│ ├── delivery/ # 配送状态机和 Use Case +│ └── inspection/ # 风险、隐患、整改和复检 Use Case +└── ui/ + ├── core/ # 主题和公共状态组件 + └── features/ + ├── shared/ # 登录、准入、消息、钱包、我的和支持 + ├── installation/ # 安装维修 40 页对应 Feature + ├── delivery/ # 配送 42 页对应 Feature + └── inspection/ # 安全检查 40 页对应 Feature +``` + +迁移时先保留 `ServiceRepository` 作为兼容门面，再把实现逐步转发至四个领域 Repository。旧页面完成替换和回归前不得删除。 + +## 6. 页面与开发范围 + +状态定义：`已有` 表示主要页面和接口已存在；`部分` 表示只有通用页面或部分 API；`待开发` 表示当前代码中未发现完整页面或接口。 + +### 6.1 安装维修端 40 页 + +| 编号与页面 | 建议路由 | 状态 | UI、逻辑与接口工作 | +| --- | --- | --- | --- | +| 01 登录页 | `/login` | 部分 | 对齐蓝白登录设计、密码/验证码、协议、忘记密码和字段级错误 | +| 02 岗位申请 | `/role-application` | 待开发 | 组织、岗位、证照、审核进度及申请接口 | +| 03 作业前检查 | `/preflight` | 部分 | 接入培训、区域、授权设备、工具和定位检查 | +| 04 准入阻断 | `/preflight/blocked` | 部分 | 按阻断码提供打卡、补资质、培训、设备处理入口 | +| 05 每日安全培训 | `/training/daily` | 待开发 | 题目版本、进度、作答、及格和留痕 | +| 06 安装维修工作台 | `/installation/work` | 待开发 | 在岗、待办、整改、优先工单、草稿和消息摘要 | +| 07 消息中心 | `/messages?role=installer` | 待开发 | 工单、安全、系统、结算分类及已读状态 | +| 08 工单列表 | `/installation/tickets` | 部分 | 新装、维修筛选，分页、搜索、SLA、空态和刷新 | +| 09 新装工单详情 | `/installation/tickets/:identity` | 部分 | 用户、脱敏地址、计划、要求、历史、动作和版本 | +| 10 维修工单详情 | `/installation/tickets/:identity` | 部分 | 故障、历史维修、风险、材料及允许动作 | +| 11 使用条件确认 | `/installation/tickets/:identity/steps/conditions` | 待开发 | 版本化场地、管线、通风、电源检查清单 | +| 12 条件不合格与整改 | `/installation/tickets/:identity/steps/rectification` | 待开发 | 不合格项、证据、整改、改约和异常分支 | +| 13 准备材料 | `/installation/tickets/:identity/steps/materials` | 待开发 | 材料需求、库存、扫码、领用、缺件和替代审批 | +| 14 执行安装与取证 | `/installation/tickets/:identity/steps/install` | 部分 | 分步骤施工、前中后证据、草稿和同步 | +| 15 安装测试 | `/installation/tickets/:identity/steps/test` | 待开发 | 气密、点火、压力、运行测试及测量单位 | +| 16 测试失败处理 | `/installation/tickets/:identity/steps/test-failure` | 待开发 | 失败项、返工、暂停、上报和禁止完成 | +| 17 前期安检 | `/installation/tickets/:identity/steps/safety` | 待开发 | 设备、环境和检漏清单，引用规则版本 | +| 18 用户签名 | `/installation/tickets/:identity/steps/signature` | 部分 | 告知内容版本、手写签名、签名人和时间留痕 | +| 19 收款确认 | `/installation/tickets/:identity/steps/payment` | 待开发 | 应收拆分、线上状态、线下凭证、差额审核 | +| 20 安装完成 | `/installation/tickets/:identity/completion` | 部分 | 服务端完成回执、保修卡、回访和下一任务 | +| 21 维修执行与取证 | `/installation/tickets/:identity/steps/repair` | 部分 | 故障处理步骤、零件、前中后取证和结论 | +| 22 维修安全检查 | `/installation/tickets/:identity/steps/repair-safety` | 待开发 | 修复后检漏、试运行、结果和失败阻断 | +| 23 异常上报与恢复 | `/installation/tickets/:identity/exception` | 部分 | 原因码、说明、证据、暂停、审核和恢复版本校验 | +| 24 巡检及复检任务 | `/installation/inspections` | 部分 | 巡检、复检列表、计划、整改关联和专用步骤 | +| 25 作业记录 | `/installation/records` | 部分 | 已完成、异常、取消筛选和分页 | +| 26 记录详情 | `/installation/records/:identity` | 待开发 | 时间线、步骤、证据、签名、款项和文档 | +| 27 统计看板 | `/installation/statistics` | 待开发 | 作业量、准时率、质量、返工、收入及口径说明 | +| 28 钱包 | `/wallet` | 部分 | 钱包、收入分类、余额限制和流水入口 | +| 29 提现申请与记录 | `/wallet/withdrawals` | 部分 | 金额、到账卡、手续费、支付密码和审核状态 | +| 30 银行卡管理 | `/wallet/banks` | 部分 | 实名卡、绑定、默认卡、解绑二次确认和错误码 | +| 31 离线草稿与同步记录 | `/sync` | 部分 | 草稿、附件、重试、冲突、失败原因和清理保护 | +| 32 个人中心 | `/me` | 部分 | 资料、资质、钱包、统计、支持和设置入口 | +| 33 个人资料与资质 | `/me/profile` | 部分 | 组织、区域、证照、能力、到期提醒和受控编辑 | +| 34 推荐二维码 | `/me/referral` | 待开发 | 服务申请二维码、有效期、来源和使用记录 | +| 35 设置与通知 | `/settings` | 待开发 | 通知、权限、离线保护、密码、协议和退出 | +| 36 服务支持中心 | `/support` | 待开发 | 人工客服、组织电话、抢险电话、服务请求和 FAQ | +| 37 维修知识库与视频教程 | `/knowledge?role=installer` | 待开发 | 规范、案例、视频、搜索、收藏和学习进度 | +| 38 远程专家会诊 | `/expert-consultations` | 待开发 | 人工专家音视频、资料授权、会诊意见和审计 | +| 39 备件领用 | `/installation/spares` | 待开发 | 申请、扫码、库存、领用、消耗、退回和审批 | +| 40 电子保修卡与用户回访 | `/installation/warranties` | 待开发 | 保修范围、期限、状态、维修历史、回访和评价 | + +### 6.2 配送端 42 页 + +| 编号与页面 | 建议路由 | 状态 | UI、逻辑与接口工作 | +| --- | --- | --- | --- | +| 01 登录页 | `/login` | 部分 | 复用共享登录，按设计统一品牌和错误状态 | +| 02 岗位申请 | `/role-application` | 待开发 | 配送点、车辆、驾驶及从业资质、审核进度 | +| 03 作业前检查 | `/preflight` | 部分 | 出勤、培训、车辆、设备、区域、定位和网络 | +| 04 准入阻断 | `/preflight/blocked` | 部分 | 展示车辆、资质、培训、设备等阻断原因和处理入口 | +| 05 每日安全培训 | `/training/daily` | 待开发 | 配送题库、版本、作答、及格和留痕 | +| 06 配送工作台 | `/delivery/work` | 待开发 | 在岗、订单统计、今日路线、待办、异常和快捷入口 | +| 07 消息中心 | `/messages?role=delivery` | 待开发 | 订单、路线、安全、系统、结算消息和对象跳转 | +| 08 配送订单列表 | `/delivery/orders` | 部分 | 状态筛选、分页、SLA、距离、搜索和允许动作 | +| 09 配送订单详情 | `/delivery/orders/:identity` | 部分 | 用户、脱敏联系、地址、商品、气瓶、付款和状态时间线 | +| 10 接单与改派 | `/delivery/orders/:identity/assignment` | 待开发 | 接单、拒单原因、改派申请、审核和重新加载状态 | +| 11 按时间排单 | `/delivery/schedule?mode=time` | 待开发 | 时间窗、顺序、冲突、锁定版本和批量确认 | +| 12 按路线排单 | `/delivery/schedule?mode=route` | 待开发 | 地图站点、里程、路线建议、人工调序和版本冲突 | +| 13 导航与到达 | `/delivery/orders/:identity/arrival` | 部分 | 外部导航、受控联系、定位质量、围栏和到达回执 | +| 14 围栏异常处理 | `/delivery/orders/:identity/geofence-exception` | 部分 | 超距、定位异常、证据、人工审核和重试 | +| 15 气瓶扫描录入 | `/delivery/orders/:identity/cylinders` | 待开发 | 扫码、规格、所属、库存、订单匹配和重复校验 | +| 16 扫描异常拦截 | `/delivery/orders/:identity/cylinders/errors` | 待开发 | 错瓶、重复、失效、召回、无库存和处置建议 | +| 17 随瓶安检 | `/delivery/orders/:identity/safety-check` | 待开发 | 环境、连接、设备、检漏和规则版本 | +| 18 安检不合格与整改 | `/delivery/orders/:identity/safety-issue` | 待开发 | 风险分级、证据、整改、拒绝交付和异常上报 | +| 19 配送取证 | `/delivery/orders/:identity/evidence` | 部分 | 配送前中后、瓶体、安装、安检照片视频和同步 | +| 20 收款确认 | `/delivery/orders/:identity/payment` | 待开发 | 应收、押金、线上、线下、凭证和差额对账 | +| 21 签收确认 | `/delivery/orders/:identity/receipt` | 部分 | 签收码或签名、交付清单、拒签和服务端验证 | +| 22 配送完成 | `/delivery/orders/:identity/completion` | 部分 | 库存、押金、轨迹、签收和收款全部确认后完成 | +| 23 空瓶回收任务 | `/delivery/returns` | 待开发 | 回收地址、计划、数量、押金和状态 | +| 24 蓝牙设备连接 | `/delivery/devices/pairing` | 待开发 | 权限、扫描、配对、超时、固件兼容和故障 | +| 25 空瓶扫描与确认 | `/delivery/returns/:identity/cylinders` | 待开发 | 空瓶码、状态、所属、押金核算和回收确认 | +| 26 回收异常处理 | `/delivery/returns/:identity/exception` | 待开发 | 错瓶、损坏、争议、证据和人工审核 | +| 27 配送轨迹与补传 | `/delivery/tracks` | 部分 | 轨迹段、缺口、离线缓存、批量补传和重复点去重 | +| 28 服务用户列表 | `/delivery/customers` | 待开发 | 仅授权片区用户、搜索、标签和服务状态 | +| 29 服务用户详情 | `/delivery/customers/:identity` | 待开发 | 脱敏资料、用气、安检、配送、评价和访问审计 | +| 30 配送记录 | `/delivery/records` | 部分 | 历史订单、状态、时间、片区和分页 | +| 31 配送记录详情 | `/delivery/records/:identity` | 待开发 | 时间线、瓶码、取证、收款、签收、空瓶和轨迹 | +| 32 统计看板 | `/delivery/statistics` | 待开发 | 配送量、准时率、里程、异常、回收和收入 | +| 33 钱包 | `/wallet` | 部分 | 配送收入、奖励、余额、限制和流水 | +| 34 提现申请与记录 | `/wallet/withdrawals` | 部分 | 复用共享资金接口和审核状态 | +| 35 银行卡管理 | `/wallet/banks` | 部分 | 复用共享实名卡、绑定和解绑流程 | +| 36 离线队列与冲突 | `/sync` | 部分 | 轨迹、证据、签收、草稿、失败和版本冲突 | +| 37 个人中心 | `/me` | 部分 | 车辆、资质、钱包、统计、知识库和支持入口 | +| 38 个人资料车辆与资质 | `/me/profile` | 部分 | 人员、车辆、证照、到期提醒和审核状态 | +| 39 设置与通知 | `/settings` | 待开发 | 派单、路线、轨迹、安全、权限、密码和退出 | +| 40 推荐二维码 | `/me/referral` | 待开发 | 招募或服务推广场景、有效期和记录 | +| 41 服务支持中心 | `/support` | 待开发 | 人工客服、配送点、抢险电话和服务请求 | +| 42 配送知识库与视频教程 | `/knowledge?role=delivery` | 待开发 | 规范、气瓶、安检、设备、视频和学习进度 | + +### 6.3 安全检查端 40 页 + +| 编号与页面 | 建议路由 | 状态 | UI、逻辑与接口工作 | +| --- | --- | --- | --- | +| 01 登录页 | `/login` | 部分 | 复用共享登录并统一蓝白视觉 | +| 02 岗位申请 | `/role-application` | 待开发 | 安检中心、区域、组织、资质和审核状态 | +| 03 作业前检查 | `/preflight` | 部分 | 出勤、资质、培训、安检设备、区域、定位和网络 | +| 04 准入阻断 | `/preflight/blocked` | 部分 | 按原因提供资质、打卡、培训和设备处理入口 | +| 05 每日安全培训 | `/training/daily` | 待开发 | 安检题库、版本、及格规则和结果留痕 | +| 06 安检工作台 | `/inspection/work` | 待开发 | 在岗、待安检、复检、高风险、快捷入口和消息 | +| 07 消息中心 | `/messages?role=operations` | 待开发 | 任务、风险、整改、复检、系统和结算消息 | +| 08 安检任务列表 | `/inspection/tasks` | 部分 | 待到场、执行中、待复检、完成筛选和分页 | +| 09 安检任务详情 | `/inspection/tasks/:identity` | 部分 | 用户、地址、范围、历史、要求、版本和动作 | +| 10 到场与围栏校验 | `/inspection/tasks/:identity/arrival` | 待开发 | 导航、距离、定位精度、围栏、异常和到场回执 | +| 11 用气设备清单 | `/inspection/tasks/:identity/steps/devices` | 待开发 | 表阀、管道、灶具、热水器、检漏和测量值 | +| 12 用气环境清单 | `/inspection/tasks/:identity/steps/environment` | 待开发 | 通风、烟道、周边、报警器、规则和问题说明 | +| 13 现场照片与视频 | `/inspection/tasks/:identity/evidence` | 部分 | 必拍项、问题证据、原始时间、定位和上传状态 | +| 14 用户签名 | `/inspection/tasks/:identity/signature` | 部分 | 告知内容、手写签名、拒签处理和留痕 | +| 15 合格结果确认 | `/inspection/tasks/:identity/qualified` | 部分 | 汇总、记录单、用户通知和服务端完成确认 | +| 16 不合格与风险分级 | `/inspection/tasks/:identity/risk-assessment` | 待开发 | 一级、二级、三级固定枚举和规则版本 | +| 17 一级高风险处置 | `/inspection/tasks/:identity/high-risk` | 待开发 | 关阀、通风、疏散、警戒、通知、抢险移交和强制阻断 | +| 18 整改通知单 | `/inspection/tasks/:identity/notice` | 待开发 | 隐患、期限、要求、签名、送达状态和文档 | +| 19 安检完成 | `/inspection/tasks/:identity/completion` | 部分 | 记录、隐患、通知单、复检任务和最终回执 | +| 20 隐患列表 | `/inspection/hazards` | 待开发 | 风险、逾期、整改、复检、搜索和分页 | +| 21 隐患详情 | `/inspection/hazards/:identity` | 待开发 | 证据、整改要求、进度、用户、任务和审计时间线 | +| 22 整改任务 | `/inspection/rectifications/:identity` | 待开发 | 用户资料、整改材料初审、联系和复检安排 | +| 23 复检执行 | `/inspection/reinspections/:identity` | 部分 | 前后对比、检查项、测量、证据、结论和关闭条件 | +| 24 用户拒检记录 | `/inspection/tasks/:identity/refusal` | 待开发 | 原因、联系记录、现场证据、见证人和后续安排 | +| 25 区域抽查地图 | `/inspection/map` | 待开发 | 模糊点位、路线、风险、抽查任务和精确地址授权 | +| 26 安检记录 | `/inspection/records` | 部分 | 合格、隐患、拒检、复检和历史筛选 | +| 27 安检记录详情 | `/inspection/records/:identity` | 待开发 | 时间线、结果、证据、文档、隐患和复检进度 | +| 28 统计看板 | `/inspection/statistics` | 待开发 | 安检量、合格率、风险、整改、复检和质量 | +| 29 钱包 | `/wallet` | 部分 | 安检、复检、奖励、余额和流水 | +| 30 提现申请与记录 | `/wallet/withdrawals` | 部分 | 复用共享提现接口及审核状态 | +| 31 银行卡管理 | `/wallet/banks` | 部分 | 复用共享银行卡接口及安全校验 | +| 32 离线草稿与冲突 | `/sync` | 部分 | 检查项、证据、附件、版本、冲突和重试 | +| 33 个人中心 | `/me` | 部分 | 资料、钱包、工具、知识库、支持和设置入口 | +| 34 个人资料与资质 | `/me/profile` | 部分 | 组织、区域、证照、能力、有效期和审核状态 | +| 35 推荐二维码 | `/me/referral` | 待开发 | 官方安检预约二维码、有效期和使用记录 | +| 36 设置与通知 | `/settings` | 待开发 | 任务、隐患、复检、高风险、权限、密码和退出 | +| 37 服务支持中心 | `/support` | 待开发 | 人工客服、安检中心、抢险电话和服务请求 | +| 38 安检知识库与视频教程 | `/knowledge?role=operations` | 待开发 | 规范、案例、法规、视频、搜索和学习进度 | +| 39 远程专家会诊 | `/expert-consultations` | 待开发 | 人工专家音视频、资料授权、意见和审计 | +| 40 问题反馈与投诉 | `/feedback` | 待开发 | 功能、数据、结算、投诉、附件、进度和结果 | + +## 7. Staff Client API 完善方案 + +### 7.1 通用约定 + +- 基础路径保持 `/heqi/client/v1/staff`。 +- 对象统一使用公开 `identity`，客户端不得接收或提交数据库自增主键。 +- 列表统一支持 `page`、`page_size`、`status_code`、`keyword`；兼容期保留已有裸数组结构，可通过新增 `view=page` 返回分页对象。 +- 时间使用 RFC 3339，金额使用整数分，距离使用米，压力和浓度必须同时返回单位。 +- 写接口通过 `Idempotency-Key` 或 `request_no` 幂等；响应返回 `resource_version`、`status_code` 和 `allowed_actions`。 +- 已有数字状态字段继续返回，同时非破坏性新增字符串 `status_code` 和 `status_name`；新 UI 不再硬编码数字状态。 +- 错误响应必须提供稳定 `error_code`、中文安全文案、`retryable`、字段错误和必要的当前资源快照。 +- 所有接口先校验当前账号角色、组织、任务归属和数据范围，再读取或变更数据。 + +### 7.2 共享接口 + +下表中“保留”表示当前已存在，“扩展”表示保持路径并补字段，“新增”表示本次需要实现。 + +| 方法与路径 | 类型 | 用途 | +| --- | --- | --- | +| `POST /auth/login`、`GET /auth/profile` | 扩展 | 补头像受控地址、组织、资质摘要、功能开关和通知摘要 | +| `POST /role-applications` | 新增 | 提交岗位、组织、车辆或资质申请 | +| `GET /role-applications/current` | 新增 | 当前申请、审核节点、驳回原因和可修改字段 | +| `GET /preflight` | 扩展 | 补培训、服务区域、授权设备及岗位专用检查 | +| `GET /training/daily` | 新增 | 今日课程、题目版本、及格规则和历史进度 | +| `POST /training/daily/:identity/submit` | 新增 | 幂等提交答案并返回结果和准入变化 | +| `GET /messages` | 新增 | 分类、已读、业务对象和分页 | +| `POST /messages/:identity/read` | 新增 | 单条已读 | +| `POST /messages/read-all` | 新增 | 按分类批量已读 | +| `GET /credentials` | 新增 | 当前资质、状态、到期时间和审核信息 | +| `PUT /auth/profile` | 新增 | 仅更新服务端允许编辑的个人字段 | +| `GET /statistics` | 新增 | 按岗位、日期和服务组织返回带口径的指标 | +| `GET /contents` | 新增 | 知识库、视频、规范、案例和 FAQ | +| `POST /contents/:identity/progress` | 新增 | 学习进度、完成和阅读确认 | +| `GET /support/contacts` | 新增 | 客服、所属组织和抢险电话配置 | +| `GET /support/requests`、`POST /support/requests` | 新增 | 人工服务请求和进度 | +| `GET /expert-consultations`、`POST /expert-consultations` | 新增 | 人工专家会诊申请、授权资料和状态 | +| `GET /referrals/current` | 新增 | 当前岗位可用二维码及有效期 | +| `GET /feedback`、`POST /feedback` | 新增 | 反馈、投诉、附件和处理进度 | +| `/wallet`、`/wallet/records` | 保留 | 钱包和流水，补岗位收入来源字段 | +| `/wallet/banks`、`/wallet/withdrawals` | 保留 | 银行卡和提现，客户端补齐页面即可 | + +### 7.3 安装维修接口 + +| 方法与路径 | 类型 | 用途 | +| --- | --- | --- | +| `GET /tickets`、`GET /tickets/:identity` | 扩展 | 分页、字符串状态、工作流、SLA、历史和 `allowed_actions` | +| `POST /tickets/:identity/start`、`exception`、`recover` | 扩展 | 补幂等键、版本、定位、原因码和动作回执 | +| `GET /tickets/:identity/workflow` | 新增 | 返回任务类型、步骤、完成度、规则版本和当前步骤 | +| `GET /tickets/:identity/checklists/:step_code` | 新增 | 版本化条件、安装测试或安全检查清单 | +| `PUT /tickets/:identity/checklists/:step_code` | 新增 | 保存结果、测量值、问题、证据引用和草稿版本 | +| `GET /tickets/:identity/materials` | 新增 | 需求、库存、已领、已用和待归还材料 | +| `POST /tickets/:identity/material-issues` | 新增 | 申请或扫码领用备件，返回库存事务结果 | +| `POST /tickets/:identity/evidences` | 新增 | 分步绑定已上传证据，校验数量、类型、时间和哈希 | +| `POST /tickets/:identity/signatures` | 新增 | 告知版本、签名、签名人、时间和拒签原因 | +| `POST /tickets/:identity/payment-confirmations` | 新增 | 线上查询、线下凭证、金额差额和审核状态 | +| `POST /tickets/:identity/submit-result` | 扩展 | 保留现有聚合提交，增加步骤完整性与版本校验 | +| `GET /installation/inspections` | 新增 | 巡检和复检任务专用列表 | +| `GET /installation/spares`、`POST /installation/spares/issues` | 新增 | 备件可用库存、领用、消耗和归还 | +| `GET /installation/warranties` | 新增 | 电子保修卡及关联维修、回访记录 | +| `POST /installation/warranties/:identity/follow-ups` | 新增 | 回访结果、问题和后续任务 | + +### 7.4 配送接口 + +| 方法与路径 | 类型 | 用途 | +| --- | --- | --- | +| `GET /delivery/orders`、`GET /delivery/orders/:identity` | 扩展 | 分页、商品、气瓶、押金、收款、计划、状态和动作 | +| `POST /delivery/orders/:identity/start` | 扩展 | 幂等、版本、车辆和路线批次 | +| `POST /delivery/orders/:identity/accept` | 新增 | 接单并返回调度版本 | +| `POST /delivery/orders/:identity/reassignment-requests` | 新增 | 拒单或改派原因、证据和审核状态 | +| `GET /delivery/schedule`、`PUT /delivery/schedule` | 新增 | 时间或路线排单、乐观锁和冲突明细 | +| `GET /delivery/routes/current` | 新增 | 今日路线、站点、里程、缺口和最后轨迹时间 | +| `POST /delivery/orders/:identity/tracks` | 扩展 | 保留批量轨迹，补轨迹段、设备、幂等和去重结果 | +| `POST /delivery/orders/:identity/arrive` | 扩展 | 返回距离、阈值、定位质量和审核要求 | +| `POST /delivery/orders/:identity/geofence-exceptions` | 新增 | 超距或定位异常证据和人工审核 | +| `POST /delivery/cylinders/validate-scan` | 新增 | 校验瓶码、规格、所属、库存、召回和重复状态 | +| `PUT /delivery/orders/:identity/cylinders` | 新增 | 绑定实瓶和数量，使用资源版本防并发覆盖 | +| `PUT /delivery/orders/:identity/safety-check` | 新增 | 随瓶安检检查项、风险和处置 | +| `POST /delivery/orders/:identity/evidences` | 新增 | 分阶段配送证据绑定 | +| `POST /delivery/orders/:identity/payment-confirmations` | 新增 | 商品、押金、线上、线下和差额对账 | +| `POST /delivery/orders/:identity/submit-receipt` | 扩展 | 保留现有签收，补签收码、交付清单、拒签和前置校验 | +| `GET /delivery/returns`、`GET /delivery/returns/:identity` | 新增 | 空瓶回收任务与详情 | +| `POST /delivery/returns/:identity/confirm` | 新增 | 空瓶扫描、状态、押金和库存回收事务 | +| `POST /delivery/returns/:identity/exception` | 新增 | 错瓶、损坏和押金争议 | +| `GET /delivery/customers`、`GET /delivery/customers/:identity` | 新增 | 当前授权片区用户及脱敏详情 | + +### 7.5 安全检查接口 + +| 方法与路径 | 类型 | 用途 | +| --- | --- | --- | +| `GET /tickets`、`GET /tickets/:identity` | 扩展 | 安检、复检专用字段、工作流、字符串状态和动作 | +| `POST /tickets/:identity/arrive` | 新增 | 定位质量、围栏距离和到场回执 | +| `GET /tickets/:identity/checklists/devices` | 新增 | 版本化用气设备检查项 | +| `GET /tickets/:identity/checklists/environment` | 新增 | 版本化用气环境检查项 | +| `PUT /tickets/:identity/checklists/:step_code` | 新增 | 结果、测量值、说明、证据和版本 | +| `POST /tickets/:identity/evidences` | 新增 | 现场照片、视频、签名和问题证据 | +| `POST /tickets/:identity/risk-assessments` | 新增 | 固定风险等级、规则版本和建议动作 | +| `POST /tickets/:identity/high-risk-actions` | 新增 | 逐项记录关阀、通风、疏散、警戒、通知和移交 | +| `POST /tickets/:identity/refusals` | 新增 | 拒检原因、联系、证据、见证和后续安排，结论保持为空 | +| `POST /tickets/:identity/complete` | 新增 | 原子完成任务并创建隐患、整改单和复检计划 | +| `GET /inspection/hazards`、`GET /inspection/hazards/:identity` | 新增 | 隐患列表、详情、证据、状态和时间线 | +| `POST /inspection/hazards/:identity/rectification-reviews` | 新增 | 整改材料初审，只改变初审状态 | +| `POST /inspection/hazards/:identity/reinspection-schedules` | 新增 | 创建或改期复检任务 | +| `POST /inspection/reinspections/:identity/submit` | 新增 | 前后对比、检查项、证据和复检结论 | +| `GET /inspection/map` | 新增 | 按权限返回模糊点位和任务摘要 | + +## 8. 核心接口契约示例 + +### 8.1 作业前检查 + +```json +{ + "role_code": "operations", + "work_status": "on_duty", + "can_work": false, + "checks": { + "account": {"status": "passed"}, + "role": {"status": "passed", "role_code": "operations"}, + "organization": {"status": "passed", "identity": "...", "name": "武侯安检中心"}, + "credential": {"status": "passed", "expired_at": "2027-12-31T23:59:59+08:00"}, + "attendance": {"status": "passed", "work_status": "on_duty"}, + "daily_training": {"status": "blocked", "reason_code": "training_required", "action": "open_daily_training"}, + "service_area": {"status": "passed"}, + "authorized_device": {"status": "passed"} + } +} +``` + +兼容期内 `not_configured` 不作为新阻断条件；只有服务端启用规则并返回 `blocked` 时客户端才阻止进入工作台。 + +### 8.2 任务详情与允许动作 + +```json +{ + "identity": "01K...", + "number": "AJ202609060021", + "role_code": "operations", + "business_type": "inspection", + "status": 18, + "status_code": "assigned", + "status_name": "已分派", + "resource_version": 7, + "current_step": "arrival", + "allowed_actions": ["arrive", "report_exception"], + "workflow": { + "template_identity": "01K...", + "template_version": 3, + "completed_steps": [] + } +} +``` + +### 8.3 幂等动作响应 + +```json +{ + "identity": "01K...", + "status_code": "in_progress", + "resource_version": 8, + "allowed_actions": ["save_checklist", "upload_evidence", "report_exception"], + "idempotency_replayed": false, + "server_time": "2026-09-06T17:49:13+08:00" +} +``` + +### 8.4 统一业务错误 + +```json +{ + "error_code": "RESOURCE_VERSION_CONFLICT", + "message": "任务已被更新，请刷新后继续", + "retryable": false, + "field_errors": {}, + "current_resource_version": 9, + "allowed_actions": ["refresh"] +} +``` + +客户端只根据 `error_code` 驱动流程，中文 `message` 用于展示，不解析服务端英文或中文文案判断业务状态。 + +## 9. 领域状态机与强制规则 + +### 9.1 安装维修 + +```text +已分派 -> 执行中 -> 待用户确认 -> 已完成 + | | + +-> 异常暂停 <-+ +异常暂停 -> 执行中 +``` + +- 安装、维修必须具备施工前、施工中、施工后证据和用户签名。 +- 条件不合格、测试失败或高风险结果不得直接进入待确认或已完成。 +- 备件领用、消耗和退回必须形成库存事务，客户端不能直接修改库存余额。 +- 电子保修卡只能由已完成安装或满足规则的维修事实生成。 + +### 9.2 配送 + +```text +待接单 -> 已接单 -> 已排单 -> 配送中 -> 已到达 + -> 气瓶已核验 -> 安检完成 + -> 待收款 -> 待签收 -> 已完成 +任一执行态 -> 异常暂停 -> 原执行态 +``` + +- 现有数字状态 `20 -> 33 -> 34 -> 23` 保持兼容；新增细分状态通过字符串码和扩展事件表达，避免破坏旧系统。 +- 气瓶必须先校验再绑定订单，错瓶、召回瓶、重复瓶或非可用库存一律阻断。 +- 轨迹缺失允许补传，但不得伪造时间；围栏异常必须记录定位精度和人工审核结论。 +- 收款、押金、空瓶和签收全部确认后才允许完成配送。 + +### 9.3 安全检查 + +```text +已分派 -> 已到场 -> 检查中 -> 待评定 + -> 合格 -> 已完成 + -> 不合格 -> 隐患待整改 -> 待复检 -> 已关闭 + -> 一级高风险 -> 现场管控 -> 抢险移交 -> 隐患待整改 + -> 用户拒检 -> 拒检归档/改约 +``` + +- 风险枚举固定为 `level_1_high`、`level_2_medium`、`level_3_low`，不得使用自由文本替代等级。 +- 一级高风险必须逐项完成现场管控和抢险移交，普通完成接口不能绕过。 +- 拒检只记录事实，不写合格或不合格结论。 +- 整改单、隐患和复检任务必须在同一服务端事务中关联，复检通过后才能关闭隐患。 + +## 10. 数据模型与数据库规划 + +优先复用现有 `staff_account`、`staff_credential`、`staff_attendance`、`cs_ticket`、`cs_ticket_evidence`、`gasorder_basic`、轨迹、钱包和银行卡模型。仅在现有语义无法表达时新增表。 + +| 建议模型 | 职责 | +| --- | --- | +| `staff_role_application` | 岗位、组织、车辆、资质申请及审核历史 | +| `staff_daily_training`、`staff_training_attempt` | 课程版本、答题、结果和准入记录 | +| `staff_message`、`staff_message_read` | 岗位消息、业务对象和已读状态 | +| `staff_workflow_instance`、`staff_step_record` | 任务模板版本、步骤状态、表单和资源版本 | +| `staff_payment_confirmation` | 应收、线上、线下、押金、差额和审核 | +| `delivery_order_cylinder` | 配送订单实瓶、扫码校验和库存事务关联 | +| `delivery_return_task`、`delivery_return_cylinder` | 空瓶回收、瓶况、押金和异常 | +| `inspection_hazard` | 风险等级、隐患、期限、状态和关联任务 | +| `inspection_rectification_notice` | 整改要求、送达、签名和文档 | +| `inspection_reinspection` | 复检计划、结果、证据和隐患关闭 | +| `staff_support_request`、`expert_consultation` | 人工支持、会诊授权、意见和审计 | +| `installation_spare_transaction` | 备件申请、领用、消耗、退回和审批 | +| `installation_warranty_follow_up` | 保修卡关联回访、问题和后续任务 | + +迁移必须包含表级 `COMMENT` 和逐字段中文 `COMMENT`。枚举注释列出全部取值，JSON 字段说明结构、版本和示例；唯一键覆盖 `request_no` 或幂等键，资源表增加版本字段用于乐观锁。 + +## 11. 离线、附件与冲突 + +- 草稿、检查项、签名和附件元数据继续使用系统安全存储管理的密钥加密。 +- 每个草稿记录 `account_identity`、`role_code`、业务对象、步骤、模板版本、资源版本和更新时间。 +- 图片、视频和签名记录 SHA-256、MIME、大小、原始采集时间、定位、上传状态和服务端文件标识。 +- 队列按同一资源的动作顺序执行；相同 `request_no` 只允许成功一次。 +- 网络恢复后先拉取服务端版本，再执行待同步动作；版本冲突必须展示差异，不静默覆盖。 +- 登录退出、切换账号、清理缓存和卸载提示前检查未同步数据；不得将甲账号草稿展示给乙账号。 +- 最终完成、高风险处置确认、签收、库存、资金和提现不能离线伪成功，只显示“待同步”或“待确认”。 + +## 12. 安全、权限与隐私 + +- 精确地址、手机号、身份证、银行卡、签名、证照和现场证据按角色与任务归属最小化返回。 +- 列表默认脱敏；进入授权任务详情后按业务需要展示，访问写入审计日志。 +- 地图默认返回模糊点位，精确坐标仅对当前授权任务和规定时间窗开放。 +- 日志、埋点、崩溃报告和错误信息不得记录令牌、明文密码、完整手机号、完整地址、签名或附件内容。 +- 上传校验扩展名、真实 MIME、大小、病毒扫描、业务归属和短期访问授权。 +- 金额、库存、风险和状态转换均由服务端事务校验，客户端参数不能直接增加余额、减少库存或关闭隐患。 +- 深链和推送只携带业务类型、公开 `identity` 和短期签名；页面打开后重新鉴权并读取当前状态。 + +## 13. 分阶段实施计划 + +| 阶段 | 开发范围 | 完成标准 | +| --- | --- | --- | +| P0 视觉与契约基线 | 服务端主题改蓝、8dp 角色组件、状态码、错误模型、API 契约测试 | 无紫色；旧接口和用户端主题无回归 | +| P1 共享骨架 | 角色导航、登录、岗位申请、准入、培训、消息、资料、设置 | 三角色登录后进入正确工作台并通过准入守卫 | +| P2 安装维修主链路 | 01 至 24 核心工单、取证、签名、收款和异常 | 新装、维修、巡检、复检各至少一条端到端链路通过 | +| P3 配送主链路 | 01 至 27 订单、排单、轨迹、气瓶、安检、签收和空瓶 | 正常配送、围栏异常、错瓶、拒签和回收链路通过 | +| P4 安检主链路 | 01 至 25 检查、风险、整改单、隐患、整改、复检和拒检 | 合格、不合格、一级高风险、拒检和复检链路通过 | +| P5 扩展能力 | 记录、统计、钱包、资质、二维码、知识库、支持、会诊、备件和保修 | 122 张设计图均有真实路由与数据状态 | +| P6 离线与质量 | 附件队列、冲突、幂等、安全、性能、视觉与兼容回归 | 弱网、断网、重复提交、冲突和权限测试通过 | + +每个阶段采用接口契约先行：后端提供可运行接口及契约测试，Flutter 再接入真实数据。设计图中的静态数据不得长期保留在生产页面。 + +## 14. 测试与验收 + +### 14.1 自动化测试 + +- Go 单元测试：角色与组织权限、状态转换、风险分级、围栏距离、气瓶校验、金额、库存、幂等和事务回滚。 +- 路由测试：现有 Staff 路由继续存在，新路由方法和鉴权中间件完整。 +- Flutter 单元测试：DTO 解析、字符串状态、允许动作、金额格式、离线队列和冲突策略。 +- Widget 测试：加载、空态、错误、长文本、表单校验、按钮禁用、权限拒绝和键盘避让。 +- 集成测试：三角色正常链路及关键异常链路，真实登录和模拟业务数据均可重复执行。 +- 视觉回归：以三个最新设计目录为基准，在固定数据和固定尺寸下逐页截图比对。 + +### 14.2 必测业务场景 + +| 岗位 | 正常场景 | 异常场景 | +| --- | --- | --- | +| 安装维修 | 新装、维修、巡检、复检、签名、收款、完成 | 条件不合格、测试失败、缺件、异常恢复、重复提交 | +| 配送 | 接单、排单、到达、扫码、安检、收款、签收、空瓶回收 | 围栏异常、错瓶、召回瓶、用户不在、拒签、轨迹缺口、押金争议 | +| 安全检查 | 合格安检、隐患、整改、复检、关闭 | 一级高风险、用户拒检、逾期整改、复检不通过、离线冲突 | + +### 14.3 逐页验收 + +每张设计图必须映射到以下六项，缺一项不得标记完成： + +1. 可访问路由和正确返回路径。 +2. 真实或契约模拟的接口数据，不使用写死成功结果。 +3. 正常、加载、空、错误、离线和无权限状态。 +4. 服务端状态与 `allowed_actions` 驱动的操作按钮。 +5. 对应 Widget、仓储或集成测试。 +6. 与目标图同尺寸的截图及差异评审记录。 + +## 15. 预计变更范围 + +| 目录或文件 | 主要变更 | +| --- | --- | +| `apps/heqi_design_system/lib/src/tokens.dart` | 服务端主色改蓝；保留公开 Token 名称 | +| `apps/heqi_design_system/lib/src/theme.dart` | 服务端明暗主题去紫色，补角色紧凑样式 | +| `apps/service_app/lib/app/router.dart` | 角色路由、守卫、四栏导航和旧路由兼容 | +| `apps/service_app/lib/app/dependencies.dart` | 注册拆分后的 Repository 和平台能力适配器 | +| `apps/service_app/lib/data` | DTO、领域 Repository、附件和离线同步 | +| `apps/service_app/lib/domain` | 三岗位模型、状态机和 Use Case | +| `apps/service_app/lib/ui/features` | 122 张设计图对应共享与岗位页面 | +| `backend/api/internal/routers/client.go` | 非破坏性注册新增 Staff Client API | +| `backend/api/internal/logic/client/staff` | 共享、安装、配送、安检领域逻辑拆分 | +| `backend/api/internal/models` | 复用现有模型并新增确有必要的领域表 | +| `docs/13-移动端Design-System.md` | 同步服务端蓝色和角色组件规范 | + +单个代码文件尽量不超过 1500 行。后端应按 `shared.go`、`installation.go`、`delivery.go`、`inspection.go`、`support.go` 等职责拆分；Flutter 页面、ViewModel 和状态对象分文件组织。 + +## 16. 完成定义 + +- 三个目标目录的 122 张设计图全部有路由、真实状态、接口和测试映射。 +- 页面无紫色、紫色渐变、AI 元素或与正式作业无关的装饰。 +- 三岗位导航、页面标题、字段、检查项和异常分支不会串岗。 +- 现有真实登录、打卡、工单、配送、钱包、证据和草稿能力无回归。 +- 所有写动作幂等，冲突可见；最终状态由服务端确认。 +- 一级高风险、错瓶、资金差额、拒签和测试失败均不能绕过阻断。 +- 常用 Android 尺寸、文本缩放、弱网、断网和权限拒绝测试通过。 +- API、数据库、代码注释、操作日志和项目文档同步更新。 + +## 17. 风险与待评审项 + +- 岗位申请是工作人员自助申请还是后台创建后补资料，需要产品与组织权限负责人确认；未确认前不得开放越权注册。 +- 设计中的收入、奖励、提现和推荐二维码需要后台配置来源、结算规则和开关，不应由客户端写死。 +- 路线优化、蓝牙设备协议、视频会诊和地图服务涉及外部能力，开发前需确认供应商、权限和失败降级方案。 +- 安装端“巡检”与安全检查端“安检”的责任边界需由业务负责人确认，数据表可关联但状态机不能混用。 +- 图片中的日期和业务编号为设计示例，测试数据应使用相对日期或固定测试时钟，避免上线后展示过期内容。 + +## 18. 变更记录 + +| 版本 | 日期 | 内容 | +| --- | --- | --- | +| v1.0 | 2026-09-06 | 根据安装维修 40 页、配送 42 页和安全检查 40 页产品设计建立全量开发文档，明确现状、页面路由、UI、接口、状态机、离线、安全、测试和分阶段交付要求 | diff --git a/docs/项目文档_用户端APP全量功能开发_v1.0.md b/docs/项目文档_用户端APP全量功能开发_v1.0.md new file mode 100644 index 0000000..299e602 --- /dev/null +++ b/docs/项目文档_用户端APP全量功能开发_v1.0.md @@ -0,0 +1,650 @@ +# 用户端 App 全量功能开发文档 v1.0 + +## 1. 项目概述 + +### 1.1 项目名称 + +瓶安芯用户端 App 产品设计落地与全量功能开发。 + +### 1.2 文档目标 + +本文档以 `doc/用户端APP-最新参考产品设计` 中 49 个主编号页面组、58 张 PNG 设计图为视觉事实源，结合现有 Flutter 用户端、Go Client API、平台总后台及正式需求，指导研发完成以下工作： + +- 按设计图统一优化用户端 UI，不改变已经确认的蓝白视觉方向。 +- 保留现有真实登录、内容、商城、订单、合同、工单、钱包和地址能力。 +- 补齐设备控制、安全闭环、押金、消息、发票、收藏、家庭共享和扩展服务能力。 +- 完善用户端 Client API、平台后台配置、数据模型、状态机和异常处理。 +- 建立逐页面验收、接口测试、Widget 测试和关键业务集成测试。 + +### 1.3 事实源优先级 + +发生冲突时按以下顺序处理： + +1. 安全、支付、隐私、合同和设备控制的服务端规则。 +2. `docs/03-用户端App需求.md`、`docs/02-核心业务流程.md` 和 `docs/11-数据接口与安全.md`。 +3. 本文档定义的接口与实施约束。 +4. `doc/用户端APP-最新参考产品设计` 中对应页面设计图。 +5. 当前 Flutter 页面实现。 + +设计图决定页面布局、信息层级和交互入口，不得用设计图中的示例金额、状态、日期或成功结果替代服务端事实。 + +### 1.4 当前状态 + +当前用户端已经具备以下真实基础能力： + +- 手机号密码和验证码登录、注册、找回密码及会话失效处理。 +- 首页公开内容、当前服务归属和下拉刷新。 +- 公开商品列表、商城订单创建、订单列表、取消、支付、退款和确认收货。 +- 供气合同列表、燃气订单列表、取消、支付和退款。 +- 工单列表、创建、确认和取消。 +- 用户资料、头像读取、地址列表与新增。 +- 钱包余额、流水、充值、支付密码、银行卡和提现。 +- 已发布内容查询和阅读确认。 + +当前用户端主要使用通用 `ClientRecord` 承载多个业务对象，页面集中在登录、首页、商城、订单、我的和两个记录列表，尚未形成与 58 张设计图对应的完整路由、领域模型和页面模块。 + +### 1.5 技术栈与运行环境 + +| 层级 | 当前技术 | 开发要求 | +| --- | --- | --- | +| 用户端 | Flutter、Dart 3.12、Material 3 | Android、iOS、Web 共用业务层，平台能力通过适配器隔离 | +| 路由 | `go_router` | 保留 `StatefulShellRoute.indexedStack` 四栏导航，二级页使用独立路由 | +| UI 基础 | `heqi_design_system` | 统一复用颜色、间距、圆角、按钮、状态和消息组件 | +| 网络 | `http`、现有 `ApiClient` | 保留统一响应解析、错误码和会话失效逻辑 | +| 安全存储 | `flutter_secure_storage` | 仅保存令牌及必要敏感临时凭据 | +| 支付 | `fluwx`、`tobias`、Web JSAPI | 客户端回传不推进支付事实，必须查询服务端状态 | +| 后端 | Go、Gin、GORM、PostgreSQL、Redis | 新接口继续放在 `/heqi/client/v1/user`，保持 v1 向下兼容 | +| 管理后台 | Vue 3、TypeScript、Arco Design | 补齐内容、通知、价格、规则和扩展服务配置 | + +本地运行： + +```bash +cd apps/user_app +flutter pub get +flutter run --dart-define=API_BASE_URL=http://10.0.2.2:12426 +``` + +Release 环境必须通过 `--dart-define=API_BASE_URL=https://...` 注入 HTTPS API 地址。 + +## 2. 目录结构规划 + +在不破坏现有代码的前提下逐步扩展为按业务模块组织的结构： + +```text +platforms/ +├── apps/ +│ ├── heqi_design_system/ # 多端共用设计 Token 和基础组件 +│ └── user_app/ +│ ├── lib/ +│ │ ├── app/ # 启动、依赖、路由和根级守卫 +│ │ ├── data/ +│ │ │ ├── dto/ # Client API 请求与响应 DTO +│ │ │ ├── repositories/ # 领域仓储实现 +│ │ │ └── services/ # HTTP、扫码、蓝牙、定位、推送和支付适配 +│ │ ├── domain/ +│ │ │ ├── models/ # 用户、设备、安全、内容、订单和资金模型 +│ │ │ └── use_cases/ # 控阀、下单、退款、退押等关键业务编排 +│ │ └── ui/ +│ │ ├── core/ # 主题、公共状态页和可访问性组件 +│ │ └── features/ # 按页面域拆分的 UI 和 ViewModel +│ ├── test/ # 单元、Widget 和契约测试 +│ └── integration_test/ # 核心用户旅程测试 +├── backend/ +│ └── api/internal/ +│ ├── models/ # 数据模型与迁移 +│ ├── logic/client/user/ # 用户端 Client API 业务逻辑 +│ └── routers/client.go # 用户端路由注册 +├── frontend/platform_admin/ # 平台内容、规则和运营配置后台 +├── doc/用户端APP-最新参考产品设计/ # 58 张视觉事实源 +└── docs/ # 需求、技术、接口、验收和项目文档 +``` + +迁移原则：先新增强类型 DTO、领域模型和 Feature，不一次性删除 `ClientRecord`；旧页面完成迁移和回归后再清理无引用代码。 + +## 3. UI 优化实施规范 + +### 3.1 视觉基线 + +- 用户端主色使用 `HeqiColors.consumerPrimary`，值为 `#2563EB`。 +- 背景使用 `#F7F8FA`，成功、警告、危险色继续使用设计系统 Token。 +- 间距以 4dp 为基础网格，页面水平安全边距默认 16dp。 +- 触控区域不得小于 48dp，主按钮高度使用 52dp。 +- 一级页面保留“首页、商城、订单、我的”四栏底部导航；二级页面只保留返回导航。 +- 禁止新增紫色、渐变、AI 元素、玻璃拟态、发光、Emoji 和无业务意义装饰。 +- 业务图标优先使用 Material Icons；商品、宣传和视频封面必须使用真实后台资源。 + +### 3.2 公共组件 + +在 `heqi_design_system` 或用户端 `ui/core` 中扩展以下组件，已存在的组件不得重复实现： + +| 组件 | 用途 | +| --- | --- | +| `AppScaffold` | 统一 SafeArea、页面背景、标题栏和最大内容宽度 | +| `AsyncContent` | 统一 `initial/loading/content/empty/error/refreshing` 状态 | +| `StatusPill` | 订单、安全、设备、资金和阅读状态标签 | +| `SectionHeader` | 标题、说明和“查看全部”入口 | +| `ServiceRelationCard` | 所属气站与服务配送点展示 | +| `DeviceStatusCard` | 在线、阀门、电量、告警和更新时间 | +| `MoneyBreakdown` | 商品、优惠、运费、押金、退款和应付金额拆分 | +| `TimelineView` | 订单、配送、工单、安全事件和审核进度 | +| `SensitiveText` | 手机号、银行卡、证件和人员信息脱敏展示 | +| `EvidencePicker` | 图片、视频、定位和采集时间的受控取证 | +| `RiskConfirmationSheet` | 开阀、群控、解绑、退押和资金操作二次确认 | + +### 3.3 页面状态要求 + +每个异步页面必须覆盖： + +- 首次加载、骨架或进度状态。 +- 正常内容、下拉刷新和分页加载。 +- 空数据及明确的下一步入口。 +- 网络失败、权限失败、会话失效和服务不可用。 +- 写操作提交中、成功、失败、冲突、重复请求和结果待确认。 + +不得用 Toast 或静态成功页代替服务端最终状态。设备命令、支付、退款、提现和退押在无最终回执时只能显示“处理中”或“待确认”。 + +### 3.4 适配与无障碍 + +- 以 390×844 逻辑像素作为设计比对基准，同时验证 320、360、390、430 宽度。 +- 文本缩放 1.3 倍时不得遮挡按钮、价格、状态和安全提示。 +- 状态不能只依赖颜色，必须同时提供图标或文字。 +- Tab、筛选、底部操作区和软键盘出现时不得导致内容重叠。 +- Android 返回键、iOS 返回手势和 Web 浏览器前进后退必须保持路由一致。 + +## 4. 页面、路由与开发范围 + +状态说明：`保留优化` 表示已有主要 API 或页面；`接口扩展` 表示已有领域能力但不足以完成设计；`新增闭环` 表示需要新增用户端、Client API 和后台配置。 + +### 4.1 入口、首页与设备 + +| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 | +| --- | --- | --- | --- | --- | +| 01 | `01-登录页.png` | `/login` | 保留优化 | 对齐验证码/密码切换、协议、记住状态、忘记密码和错误定位 | +| 02 | `02-智能角阀功能介绍.png`、`02-1-安全案例.png`、`02-2-法律法规.png`、`02-3-气价信息.png` | `/onboarding/safety?tab=` | 接口扩展 | 内容版本、强制阅读、展示频率、气价信息和根级守卫 | +| 03 | `03-首页.png` | `/home` | 保留优化 | 合并服务归属、内容、设备摘要、快捷服务和公告入口 | +| 04 | `04-智能角阀控制.png` | `/devices/:identity` | 新增闭环 | 状态、遥测、安全检查、开关阀命令和最终回执 | +| 05 | `05-一键报修.png` | `/repairs/new` | 接口扩展 | 故障分类、证据、语音转写、地址、定位和紧急提示 | +| 06 | `06-1-扫码添加确认.png`、`06-2-蓝牙连接设备.png`、`06-3-手动输入设备码.png` | `/devices/add/:method` | 新增闭环 | 三种并存入口、设备校验、绑定确认和失败恢复 | +| 07 | `07-气瓶基本信息.png` | `/cylinders/:identity` | 新增闭环 | 气瓶规格、充装、制造、有效期、来源和异常提示 | +| 08 | `08-设备分组控制.png` | `/devices/groups` | 新增闭环 | 分组 CRUD、成员维护、逐设备群控结果和失败明细 | +| 09 | `09-安全告警与报警器.png` | `/safety/alarms` | 新增闭环 | 报警器状态、告警、测试、联动关阀和紧急电话 | +| 10 | `10-紧急联系人.png` | `/safety/contacts` | 新增闭环 | 联系顺序、通知渠道、设备查看/控制授权和审计 | + +### 4.2 商城、押金与购买 + +| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 | +| --- | --- | --- | --- | --- | +| 11 | `11-燃气商城.png` | `/shop` | 保留优化 | 分类、搜索、商品卡、库存、收藏和购物车数量 | +| 12 | `12-商品详情.png` | `/shop/products/:identity` | 接口扩展 | 图片、规格、服务、售后、库存、收藏、加购和购买 | +| 13 | `13-购物车.png` | `/cart` | 接口扩展 | 选择、数量、删除、失效商品、价格试算和结算 | +| 14 | `14-提交订单.png` | `/checkout` | 接口扩展 | 地址、预约、优惠、费用、发票、备注和支付方式 | +| 15 | `15-我的收藏.png` | `/favorites` | 新增闭环 | 收藏列表、取消、下架保留和加入购物车 | +| 16 | `16-押金管理.png` | `/deposits` | 新增闭环 | 押金汇总、明细、使用中、退款中和已退回 | +| 17 | `17-退瓶退押金.png` | `/deposits/refund` | 新增闭环 | 对象选择、上门回收、验收、扣减和退款去向 | +| 18 | `18-气瓶下单.png` | `/gas-orders/new` | 新增闭环 | 气站、规格、库存、配送时段、换气和押金试算 | +| 19 | `19-支付确认.png` | `/payments/:identity` | 保留优化 | 渠道选择、余额密码、调起渠道和支付状态轮询 | + +### 4.3 订单、配送与售后 + +| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 | +| --- | --- | --- | --- | --- | +| 20 | `20-订单中心.png` | `/orders` | 保留优化 | 气瓶/商城/报修聚合、状态筛选和可用操作 | +| 21 | `21-订单详情.png` | `/orders/:business/:identity` | 接口扩展 | 商品、金额、支付、合同、履约、人员和售后入口 | +| 22 | `22-配送详情.png` | `/orders/:business/:identity/delivery` | 接口扩展 | 配送员、车辆资质、受控联系、预约和交付状态 | +| 23 | `23-配送轨迹.png` | `/orders/:business/:identity/tracks` | 接口扩展 | 最近位置、简化轨迹、预计时间、更新时间和历史节点 | +| 24 | `24-电子发票.png` | `/invoices` | 新增闭环 | 可开票订单、抬头、申请、状态、预览和下载授权 | +| 35 | `35-安全记录详情.png` | `/safety/events/:identity` | 新增闭环 | 风险等级、关阀结果、证据、时间线、整改和复检 | +| 36 | `36-申请售后.png` | `/after-sales/new` | 接口扩展 | 类型、原因、方案、证据、联系人和退款审核 | +| 42 | `42-报修工单详情.png` | `/repairs/:identity` | 接口扩展 | 工单详情、进度、证据、工程师、改期、取消和确认 | +| 48 | `48-服务评价.png` | `/reviews/new` | 新增闭环 | 总体/分项评分、标签、凭证和安全交付确认 | +| 49 | `49-预约安全巡检.png` | `/inspections/new` | 新增闭环 | 服务、设备、日期时段、联系人、周期规则和取消改期 | + +### 4.4 个人中心、账户与消息 + +| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 | +| --- | --- | --- | --- | --- | +| 25 | `25-个人中心.png` | `/me` | 保留优化 | 资料、钱包、订单、设备、安全家庭和常用入口 | +| 26 | `26-我的记录.png` | `/records` | 接口扩展 | 用气、设备、告警、报修、押金和发票聚合索引 | +| 27 | `27-用气统计.png` | `/usage` | 新增闭环 | 日周月年趋势、构成、安全趋势、明细和数据口径 | +| 28 | `28-我的钱包.png` | `/wallet` | 保留优化 | 余额、可提现余额、押金、充值、提现、银行卡和账单 | +| 29 | `29-地址管理.png` | `/addresses` | 接口扩展 | 列表、新增、编辑、删除、默认地址和服务范围校验 | +| 30 | `30-消息中心.png` | `/messages` | 新增闭环 | 安全、订单、服务、公告、已读和对象跳转 | +| 31 | `31-设置.png` | `/settings` | 接口扩展 | 账号、通知、权限、支付密码、协议、退出和注销 | +| 32 | `32-供气合同.png` | `/contracts` | 接口扩展 | 列表、详情、下载、签署、变更、到期和续签 | +| 33 | `33-家庭成员与设备共享.png` | `/family` | 新增闭环 | 成员邀请、设备范围、查看/控制授权和撤销 | +| 34 | `34-我的设备.png` | `/devices` | 新增闭环 | 搜索、筛选、分组、在线状态、快捷控制和添加 | +| 37 | `37-邀请注册.png` | `/invite/:token` | 接口扩展 | 邀请解析、登录/注册、地址确认、归属建立和异常提示 | +| 38 | `38-余额充值.png` | `/wallet/recharge` | 保留优化 | 套餐、自定义金额、渠道、限额和结果轮询 | +| 39 | `39-余额提现.png` | `/wallet/withdraw` | 保留优化 | 到账卡、金额、手续费、支付密码、审核和受限余额 | +| 40 | `40-银行卡管理.png` | `/wallet/banks` | 保留优化 | 列表、绑定、默认到账卡、实名校验和解绑二次确认 | +| 41 | `41-个人资料.png` | `/me/profile` | 接口扩展 | 头像、昵称、手机号、认证、服务归属和默认地址 | + +### 4.5 内容、安全设置与扩展能力 + +| 编号 | 页面与设计图 | 建议路由 | 开发状态 | 主要工作 | +| --- | --- | --- | --- | --- | +| 43 | `43-安全内容中心.png`、`43-1-安全宣传.png`、`43-2-安全视频.png`、`43-3-法律法规.png`、`43-4-平台公告.png` | `/safety-content?tab=` | 接口扩展 | 宣传、视频、法规、公告、搜索、筛选、详情和阅读状态 | +| 44 | `44-自动关阀设置.png` | `/devices/:identity/close-schedules` | 新增闭环 | 规则、周期、提前提醒、启停、执行记录和告警优先 | +| 45 | `45-电子保修卡.png` | `/devices/:identity/warranty` | 新增闭环 | 保修期限、范围、服务商、维修记录和凭证 | +| 46 | `46-设备健康月报.png` | `/devices/:identity/reports/:period` | 新增闭环 | 健康评分、在线率、异常、趋势、来源和更新时间 | +| 47 | `47-安全知识考试.png` | `/safety/exams/:identity` | 新增闭环 | 题目版本、计时、进度、及格规则、提交和结果 | + +## 5. Flutter 实施方案 + +### 5.1 分层与状态 + +- UI 只负责渲染与收集输入，不直接拼接接口请求。 +- 每个 Feature 使用独立 ViewModel，保持现有 `ChangeNotifier` 模式，状态对象不可变。 +- Repository 返回强类型领域模型；新页面不得继续通过 `raw` Map 读取关键业务字段。 +- 开阀、群控、支付、退款、退押和提现放入 Use Case，统一处理幂等号、二次确认和状态轮询。 +- 相机、相册、扫码、蓝牙、定位、推送、文件下载和支付均定义抽象接口，并分别提供 Android、iOS、Web 适配。 + +### 5.2 路由与守卫 + +- 根级公开路由：登录、注册、邀请解析、公开商品、公开内容。 +- 登录保护路由：设备、订单、钱包、地址、合同、工单、消息、共享和个人资料。 +- 首次宣导守卫在登录成功且会话恢复后执行；未完成当前强制版本阅读时跳转 `/onboarding/safety`。 +- 登录回跳只接受站内绝对路径，禁止外部 URL、协议相对路径和登录循环。 +- 推送和深链只携带业务类型、对象 `identity` 和短期签名上下文，页面打开后重新读取服务端状态。 + +### 5.3 缓存策略 + +| 数据 | 缓存策略 | +| --- | --- | +| 内容、法规和公告 | 按内容版本和 ETag 缓存；后台上下架后允许失效 | +| 商品和分类 | 短时缓存；提交订单前必须重新询价和校验库存 | +| 服务归属 | 登录后缓存，切换地址、扫码邀请或服务关系变更后失效 | +| 设备遥测 | 仅保存最后展示快照，必须显示采集时间和数据延迟 | +| 订单、支付、资金、安全事件 | 本地只缓存展示数据，不得覆盖服务端事实 | +| 图片和视频 | 使用受控 URL、磁盘缓存上限和过期清理，不持久化敏感取证资源 | + +## 6. Client API 设计 + +### 6.1 通用约定 + +- 基础路径继续使用 `/heqi/client/v1/user`，现有接口不得改名或改变已有字段语义。 +- 列表统一支持 `page`、`page_size`，响应包含 `items`、`page`、`page_size`、`total`；现有裸数组接口在兼容期继续返回原结构，新页面通过新增分页接口或 `view=page` 使用分页结构。 +- 查询对象统一使用 UUID V7 `identity`，禁止向客户端暴露数据库自增主键。 +- 时间使用 RFC 3339，金额使用整数分，数量使用明确单位。 +- 写接口通过 `Idempotency-Key` 或请求体 `request_no` 保证幂等。 +- 错误响应使用稳定业务码、中文安全文案和可选 `details`；前端不得解析英文错误文案驱动流程。 +- 设备、资金、安全事件、合同和隐私数据全部执行服务端对象归属校验。 + +### 6.2 保留的现有接口 + +以下接口继续保持兼容，并按设计需要补充非破坏性字段： + +| 接口族 | 现有能力 | +| --- | --- | +| `/auth/*` | 验证码、注册、登录、找回密码、资料、头像和修改密码 | +| `/public/gas-stations`、`/public/delivery-points` | 注册及邀请流程的服务组织选择 | +| `/public/contents` | 已发布内容列表和 `content_type` 筛选 | +| `/contents/read-confirmations` | 内容版本阅读确认 | +| `/public/products` | 已发布商品列表 | +| `/service-relation` | 当前所属气站和服务配送点 | +| `/gas/contracts`、`/gas/orders/*` | 供气合同、燃气订单、取消、支付和退款 | +| `/shop/orders/*` | 商城订单创建、列表、取消、支付、退款和确认收货 | +| `/tickets/*` | 工单列表、创建、确认和取消 | +| `/refunds` | 用户退款列表 | +| `/wallet/*` | 钱包、流水、充值、支付密码、银行卡和提现 | + +### 6.3 内容与宣导接口 + +| 方法与路径 | 用途 | 实施类型 | +| --- | --- | --- | +| `GET /public/contents` | 增加关键词、分类、置顶、发布时间和服务范围筛选 | 扩展 | +| `GET /public/contents/:identity` | 内容详情，返回正文、媒体、版本和外链信息 | 新增 | +| `GET /contents/read-statuses` | 批量返回当前用户对内容版本的已读状态 | 新增 | +| `POST /contents/read-confirmations` | 保留现有阅读确认，增加展示场景字段 | 兼容扩展 | +| `GET /onboarding/current` | 返回当前宣导版本、标签、强制标志和展示频率 | 新增 | +| `GET /gas-prices/current` | 按服务归属返回气瓶价格、押金、配送费和更新时间 | 新增 | + +内容类型保留现有 `notice`、`agreement`，新增 `onboarding`、`safety_case`、`safety_article`、`safety_video`、`regulation` 和 `price_notice`。未知历史类型不得静默转换。 + +### 6.4 设备与安全接口 + +| 方法与路径 | 用途 | +| --- | --- | +| `GET /devices` | 本人及已授权设备列表、筛选和设备摘要 | +| `GET /devices/:identity` | 设备详情、在线状态、阀门状态和最后更新时间 | +| `GET /devices/:identity/telemetry` | 当前遥测和趋势数据 | +| `POST /devices/verify` | 扫码或手工设备码预校验 | +| `POST /devices/bindings` | 确认安装地址、昵称和服务关系后绑定 | +| `DELETE /devices/:identity/binding` | 受限解绑，返回阻断原因和冷静期 | +| `POST /devices/:identity/commands` | 创建开阀、关阀或测试命令 | +| `GET /device-commands/:identity` | 查询命令投递、设备回执、失败或超时状态 | +| `GET/POST/PUT/DELETE /device-groups` | 设备分组及成员维护 | +| `POST /device-groups/:identity/commands` | 群控并返回逐设备结果 | +| `GET /devices/:identity/cylinder` | 当前关联气瓶及充装、制造和有效期信息 | +| `GET /alarm-devices` | 报警器列表、状态和最近告警 | +| `POST /alarm-devices/:identity/tests` | 发起报警器测试并查询结果 | +| `GET /safety/events` | 当前用户安全事件列表 | +| `GET /safety/events/:identity` | 事件详情、证据、处置和复检状态 | +| `POST /safety/events/:identity/rechecks` | 申请复检 | +| `GET/POST/PUT/DELETE /emergency-contacts` | 紧急联系人管理 | +| `PUT /emergency-contacts/:identity/permissions` | 通知顺序和设备查看/控制授权 | +| `GET/POST/PUT/DELETE /devices/:identity/close-schedules` | 自动关阀规则管理 | +| `GET /devices/:identity/close-schedules/executions` | 定时规则执行历史 | + +设备命令响应必须包含 `command_identity`、`command_type`、`command_status`、`requested_at`、`sent_at`、`acknowledged_at`、`failure_code` 和 `failure_message`。`command_status` 至少支持 `pending`、`sent`、`acknowledged`、`failed`、`timeout`、`cancelled`。 + +### 6.5 商城、气瓶、押金和支付接口 + +| 方法与路径 | 用途 | +| --- | --- | +| `GET /public/categories` | 商城一级分类和排序 | +| `GET /public/products` | 扩展关键词、分类、库存和分页，不破坏现有列表 | +| `GET /public/products/:identity` | 商品图片、规格、属性、服务和售后详情 | +| `GET/POST/PUT/DELETE /cart/items` | 购物车查询、加入、改量和删除 | +| `POST /cart/quote` | 库存、优惠、运费、服务费和押金试算 | +| `GET/POST/DELETE /favorites` | 收藏列表、添加和取消 | +| `POST /shop/orders/quote` | 商城结算前服务端询价 | +| `POST /gas/orders/quote` | 气站、气瓶规格、库存、换气和押金试算 | +| `POST /gas/orders` | 创建气瓶预约订单 | +| `GET /deposits` | 押金汇总和明细 | +| `POST /deposit-refunds/quote` | 按设备、气瓶和状态计算预计退款 | +| `POST /deposit-refunds` | 创建退瓶退押申请 | +| `GET /deposit-refunds/:identity` | 回收、验收、扣减和退款进度 | +| `GET /payments/:identity` | 查询统一支付尝试状态 | + +金额响应至少拆分 `goods_amount`、`discount_amount`、`delivery_fee`、`service_fee`、`deposit_amount`、`payable_amount`。押金不能计入普通商品可开票收入。 + +### 6.6 订单、配送、售后和服务接口 + +| 方法与路径 | 用途 | +| --- | --- | +| `GET /orders` | 统一聚合商城、气瓶和报修订单摘要 | +| `GET /orders/:business/:identity` | 统一订单详情和允许操作 | +| `GET /orders/:business/:identity/delivery` | 配送人员、车辆、预约和交付状态 | +| `GET /orders/:business/:identity/tracks` | 本人订单的简化轨迹和历史节点 | +| `GET /tickets/:identity` | 用户工单详情、进度和证据 | +| `POST /tickets/:identity/reschedule` | 在规则允许时申请改期 | +| `POST /after-sales` | 创建完整售后申请 | +| `GET /after-sales/:identity` | 售后审核、退货、退款和处理记录 | +| `GET /invoices/eligible-orders` | 查询可开票订单和金额 | +| `POST /invoices` | 创建发票申请 | +| `GET /invoices/:identity` | 开具、作废、红冲和文件状态 | +| `POST /invoices/:identity/download-ticket` | 获取短期预览或下载凭证 | +| `POST /reviews` | 创建订单或服务评价，保证一单一次有效评价 | +| `GET /inspection-services` | 可预约巡检服务、规则和费用 | +| `POST /inspection-appointments` | 创建巡检预约 | +| `PUT /inspection-appointments/:identity` | 在规则允许时改期 | +| `DELETE /inspection-appointments/:identity` | 在规则允许时取消 | + +轨迹响应只返回当前订单履约所需位置，不返回配送员非履约时间的个人轨迹。 + +### 6.7 用户、消息、共享与扩展接口 + +| 方法与路径 | 用途 | +| --- | --- | +| `PUT/DELETE /addresses/:identity` | 编辑、删除地址并校验默认地址约束 | +| `POST /addresses/:identity/default` | 设置默认地址 | +| `GET /messages` | 按安全、订单、服务和公告筛选消息 | +| `POST /messages/read` | 批量标记已读 | +| `GET/PUT /notification-preferences` | 通知偏好；安全通知不可关闭 | +| `GET /records/summary` | 我的记录各业务分类数量与最近记录 | +| `GET /usage-statistics` | 按日周月年返回用气量、单位、口径和更新时间 | +| `GET/POST/DELETE /family-members` | 家庭成员邀请、接受和移除 | +| `PUT /family-members/:identity/device-permissions` | 授予或撤销设备查看/控制权限 | +| `GET /devices/:identity/warranty` | 电子保修卡和维修历史 | +| `GET /devices/:identity/health-reports` | 健康月报列表和详情 | +| `GET /safety/exams/current` | 当前考试、题目版本和及格规则 | +| `POST /safety/exams/:identity/attempts` | 创建答题尝试 | +| `POST /safety/exam-attempts/:identity/submit` | 幂等提交并返回结果 | +| `POST /account/cancellation-requests` | 账号注销申请和阻断原因 | + +## 7. 数据模型规划 + +### 7.1 内容域 + +现有 `cms_content` 保留 `content_type`、`title`、`body`、`version_no` 和 `publish_status`，通过迁移增加： + +- `summary`：列表摘要。 +- `category_code`：内容二级分类。 +- `cover_uri`：受控封面资源。 +- `video_uri`、`video_duration_seconds`：视频资源和时长。 +- `external_url`、`external_domain`：法规或外部资料链接及展示域名。 +- `published_at`、`effective_at`：发布时间和法规生效时间。 +- `is_pinned`、`must_read`、`sort_no`：置顶、强制阅读和排序。 +- `source_name`：发布来源。 + +新增 `cms_content_scope` 保存内容适用的平台、气站、配送点和服务区域；新增 `cms_content_media` 保存多媒体资源、排序、类型和完整性信息。阅读记录继续使用 `cms_content_read`，唯一约束保持“用户 + 内容 + 版本”。 + +### 7.2 用户、设备与安全域 + +| 实体 | 职责与关键字段 | +| --- | --- | +| `usr_device_binding` | 用户、设备、地址、昵称、绑定状态、来源和时间 | +| `usr_device_group` | 用户设备分组、名称、用途和排序 | +| `usr_device_group_member` | 分组和设备唯一关系 | +| `usr_emergency_contact` | 联系人、脱敏电话、通知顺序和启用状态 | +| `usr_device_share` | 所有者、成员、设备、查看/控制权限、有效期和撤销时间 | +| `dev_close_schedule` | 设备、执行时间、重复周期、提醒、时区和启停状态 | +| `dev_close_schedule_execution` | 每次调度、命令、回执和失败原因 | +| `saf_event` | 风险等级、来源设备、状态、自动关阀结果和 SLA | +| `saf_event_evidence` | 证据类型、受控 URI、采集时间、来源和哈希 | +| `dev_usage_stat` | 周期、用量、单位、数据来源、计算版本和更新时间 | +| `dev_health_report` | 报告周期、健康评分、在线率、异常和生成版本 | +| `dev_warranty` | 保修起止时间、范围、服务商和关联设备 | + +### 7.3 交易、资金与服务域 + +| 实体 | 职责与关键字段 | +| --- | --- | +| `ec_favorite` | 用户与商品唯一收藏关系，下架后保留历史 | +| `wal_deposit` | 押金对象、规格、数量、单价、原始金额和状态 | +| `wal_deposit_refund` | 退押申请、预计金额、验收、扣减、实际退款和去向 | +| `ord_invoice` | 购买方、订单范围、可开票金额、状态和第三方回执 | +| `ord_invoice_file` | 发票文件、哈希、短期授权和版本 | +| `ord_after_sale` | 售后类型、原因、方案、审核和退款关系 | +| `ord_service_review` | 订单、服务人员、评分、标签和安全确认 | +| `ord_inspection_appointment` | 服务、设备、地址、日期、时段、周期和状态 | +| `msg_notification` | 消息类型、接收用户、对象、标题、正文、优先级和发送状态 | +| `msg_notification_read` | 用户消息阅读时间和设备信息 | +| `msg_notification_preference` | 用户通知渠道与免打扰配置 | + +所有新增迁移必须为表和字段提供中文数据库 COMMENT；枚举字段 COMMENT 必须列出所有允许值，JSON 字段必须说明结构。 + +## 8. 平台总后台完善 + +平台后台不能只保留通用 `cms_content` 的“公告、协议”选择，需要扩展以下运营能力： + +- 内容管理：类型、摘要、正文、封面、视频、法规链接、版本、适用范围、排序、置顶、强制阅读、草稿、发布和下架。 +- 气价管理：气站、气瓶规格、商品价格、押金、配送费、有效期和变更记录。 +- 安全规则：告警等级、自动关阀、开阀限制、紧急电话、通知升级和 SLA。 +- 设备规则：绑定限制、分组上限、定时关阀、保修模板和健康报告口径。 +- 消息与推送：模板、渠道、对象范围、跳转目标、发送状态和失败重试。 +- 巡检服务：服务内容、可预约区域、时间段、周期、费用、改期和取消规则。 +- 考试管理：题库、版本、考试时长、及格线、危险题约束和发布状态。 + +后台修改上述配置必须记录操作前后值、操作者、原因和发布时间。已被订单、报告、考试或阅读确认引用的版本不得物理删除。 + +## 9. 关键状态机与业务约束 + +### 9.1 设备命令 + +```text +pending -> sent -> acknowledged + -> failed + -> timeout +pending/sent -> cancelled（仅服务端允许且设备尚未执行） +``` + +开阀前服务端必须校验账户、设备归属、共享权限、在线状态、未解除高风险事件、传感器状态和安装条件。前端按钮禁用不能替代服务端校验。 + +### 9.2 订单与支付 + +- 订单状态和支付状态分离；订单创建成功不代表支付成功。 +- 支付回调重复到达不得重复扣款、建单或推进履约。 +- 支付超时、客户端退出或渠道返回未知结果时，页面轮询服务端支付状态。 +- 商品、优惠、库存、押金和运费在提交前重新试算，客户端金额仅供展示。 + +### 9.3 押金退款 + +```text +draft -> submitted -> pickup_pending -> inspecting -> reviewing + -> refunded + -> rejected + -> cancelled +``` + +实际退款必须关联原始押金、回收对象、验收结果、扣减明细、审核记录和退款流水。 + +### 9.4 安全事件 + +```text +open -> acknowledged -> handling -> rectified -> recheck_pending -> closed + \-> escalated +``` + +安全事件不可由用户删除。高风险事件关闭前不得通过单设备、群控或定时规则重新开阀。 + +### 9.5 内容与考试 + +- 内容草稿不能进入用户端；发布新版本后按 `must_read` 和展示频率触发宣导。 +- 法规外链跳转前展示域名与风险提示，只允许 HTTPS 和后台白名单域名。 +- 考试尝试绑定题目版本；计时以服务端时间为准，提交操作幂等。 + +## 10. 安全、隐私与异常处理 + +- 用户只能读取本人、本人订单或明确授权家庭成员范围内的数据。 +- 手机号、联系人、配送员、银行卡和证件默认脱敏；拨号使用受控联系能力。 +- 定位只在用户主动选择地址、报修取证或查看本人配送订单时使用。 +- 图片和视频上传校验扩展名、MIME、文件头、大小、完整解码和恶意内容；下载使用短期授权。 +- 日志、埋点、崩溃信息和剪贴板不得记录令牌、支付密码、完整手机号、地址、银行卡和精确定位。 +- 401 及鉴权业务码继续由现有会话层统一清理，业务页面不得重复弹出英文错误。 +- 429 展示稍后重试和剩余等待时间；409 展示服务端当前状态和刷新入口；未知错误使用统一中文文案并保留 `request_id`。 +- 安全通知不可关闭；普通营销通知可按渠道关闭或进入免打扰时段。 + +## 11. 测试与验收 + +### 11.1 Flutter 测试 + +- Repository 测试：正常、空数据、错误码、分页、字段缺失和兼容旧响应。 +- ViewModel 测试：加载、刷新、提交、防重复点击、失败恢复和会话失效。 +- Widget 测试：Tab、筛选、表单校验、键盘、长文本、文本缩放和无障碍语义。 +- Golden 测试：以设计图归一化到 390×844，对首页、四栏主页面、设备详情、内容中心和订单详情做像素比对。 +- 集成测试：登录回跳、首次宣导、设备绑定、关阀/开阀、下单支付、订单配送、报修、退款、充值、提现和消息深链。 + +### 11.2 后端测试 + +- 路由测试覆盖匿名/登录、错误 Client claim、越权对象、归档对象和跨用户访问。 +- 状态机测试覆盖非法跳转、重复请求、并发更新和超时恢复。 +- 幂等测试覆盖订单、支付、退款、充值、提现、退押、报修、设备命令、内容确认和考试提交。 +- 数据测试覆盖金额守恒、押金扣减、钱包流水、库存冻结、命令 Outbox 和审计日志。 +- 上传测试覆盖伪造扩展名、超限文件、损坏媒体、病毒检测失败和过期授权。 + +### 11.3 UI 验收 + +每张设计图至少验证： + +- 页面路由、返回行为和底部导航符合设计层级。 +- 首屏结构、标题、间距、颜色、圆角、图标和主要信息层级与设计一致。 +- 加载、空数据、错误、离线、无权限、禁用和长数据状态均可使用。 +- 金额、单位、时间、更新时间、来源和状态来自真实接口。 +- 危险操作有二次确认、明确阻断原因和最终回执。 +- 320 至 430 宽度、Android、iOS 和 Web 不出现文字截断或控件重叠。 + +### 11.4 必跑命令 + +```bash +cd apps/user_app +flutter analyze +flutter test +flutter build apk --debug +flutter build ios --simulator --no-codesign +flutter build web --release --dart-define=API_BASE_URL=https://api.example.com + +cd backend/api +go test ./... +go vet ./... +go build ./cmd/main +``` + +涉及平台后台时同时执行其类型检查、静态契约检查、单元测试和生产构建。 + +## 12. 分阶段交付 + +### 阶段 A：基础架构与现有功能 UI 对齐 + +- 建立 Feature 目录、强类型 DTO、公共异步状态组件和完整路由骨架。 +- 优化 01、03、11、14、19、20、25、28、29、32、37 至 42 页面。 +- 保持现有 Client API 兼容，补齐详情、分页、地址编辑和支付状态查询。 + +完成标准：现有真实能力全部可用，Release 不出现静态成功功能，核心页面通过 Golden 与回归测试。 + +### 阶段 B：设备安全闭环 + +- 开发 04 至 10、34、35、44 页面。 +- 打通设备绑定、遥测、命令回执、告警、紧急联系人、分组和定时关阀。 +- 完成高风险开阀拦截、自动关阀和审计链路。 + +完成标准：通过 AC-01 至 AC-05、AC-12、AC-15、AC-22 和 AC-25。 + +### 阶段 C：交易、押金与服务履约 + +- 完善 12 至 18、21 至 24、36、48、49 页面。 +- 打通购物车、收藏、气瓶下单、押金、配送详情、轨迹、发票、售后、评价和巡检预约。 + +完成标准：金额、库存、支付、履约、退押、退款和发票均以服务端事实为准，通过 AC-07、AC-11、AC-13、AC-14 和 AC-18。 + +### 阶段 D：内容、消息与增值能力 + +- 完善 02、26、27、30、31、33、43、45、46、47 页面。 +- 打通内容分类、气价、消息、家庭共享、保修、月报和考试后台配置。 + +完成标准：内容版本、阅读确认、通知偏好、授权撤销、报告口径和考试版本可追溯。 + +## 13. 上线与回滚 + +- 新接口、表字段和页面入口使用功能开关按用户、气站或区域灰度。 +- 数据库迁移只新增表或可空字段；扩大枚举时先部署服务端兼容，再部署后台和 App。 +- 旧 API 在至少一个稳定 App 版本周期内保留，禁止先删除再升级客户端。 +- 设备控制、支付、押金和安全事件上线前完成故障演练、审计验证和人工回退流程。 +- 回滚只关闭新入口和新写入，已产生的订单、资金、安全、阅读及审计事实继续可查。 + +## 14. 待确认事项 + +以下事项必须在对应阶段开发前确认： + +1. 气价、押金和配送费的权威来源、适用区域、生效时间及历史版本。 +2. 安全视频是宣教视频还是现场取证视频；两者必须使用不同权限和留存策略。 +3. 法律法规外链白名单、地方适用范围和版本更新责任人。 +4. 智能瓶阀厂商协议、设备证书、离线行为、命令回执和超时语义。 +5. 开阀责任、自动关阀优先级、人工审批和安全事件关闭条件。 +6. 微信、支付宝、余额支付及退款渠道的正式商户配置。 +7. 退瓶验收、押金扣减、退款去向和争议处理规则。 +8. 地图与受控联系供应商、轨迹刷新频率和定位留存周期。 +9. 发票服务商、税务口径、文件授权和红冲流程。 +10. 巡检服务范围、费用、周期、改期和取消规则。 + +未确认事项不得通过前端默认值固化为业务规则。 + +## 15. 核心文件说明 + +| 文件 | 职责 | +| --- | --- | +| `apps/user_app/lib/app/router.dart` | 当前用户端路由、四栏导航和鉴权回跳 | +| `apps/user_app/lib/data/services/api_client.dart` | HTTP、统一响应、业务错误和会话失效 | +| `apps/user_app/lib/data/repositories/client_repository.dart` | 当前用户端 Client API 访问入口 | +| `apps/user_app/lib/domain/models/client_models.dart` | 当前通用记录、用户和钱包模型 | +| `apps/user_app/lib/ui/core/app_theme.dart` | 用户端设计系统主题适配 | +| `apps/heqi_design_system/lib/src/tokens.dart` | 色彩、间距、圆角、尺寸和动效 Token | +| `backend/api/internal/routers/client.go` | 用户端和工作人员端 Client API 路由 | +| `backend/api/internal/logic/client/user/` | 用户端认证、内容、商城、订单、工单和服务归属逻辑 | +| `backend/api/internal/models/` | 现有业务数据模型和迁移注册 | +| `frontend/platform_admin/src/api/resources.ts` | 平台资源字段和内容管理配置 | + +## 16. 维护指南 + +- 新页面先在本文件登记路由、业务对象、接口和验收，再进入开发。 +- 新增接口必须同步请求/响应示例、错误码、鉴权范围和幂等要求。 +- 新增状态值必须同时更新数据库 COMMENT、Go 常量、Flutter 枚举、后台中文映射和测试。 +- 设计修改后只更新受影响页面及关联组件，不无关重构其他模块。 +- 完成一个阶段后更新本文档版本、当前实现状态、测试结果和已知问题。 + +## 17. 变更记录 + +| 版本 | 日期 | 变更内容 | +| --- | --- | --- | +| v1.0 | 2026-09-06 | 根据 58 张最新参考设计图建立全量开发范围、路由、UI 规范、Client API、数据模型、测试和分阶段交付计划 |