platforms/docs/开发提示词_用户端APP全量功能开发_v1.0.md

# 用户端 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 主提示词，明确路径、事实源、开发批次、真实接口、视觉验收、测试和交付要求 |