293 lines
14 KiB
Markdown
293 lines
14 KiB
Markdown
# 云端管理端 — 增量架构设计（4 项功能：前端占位实现）
|
||
|
||
> 版本：v1.0｜架构师：高见远｜基于 PRD + 现有代码事实
|
||
> 关键决策：**4 项功能全部「前端先占位」实现**——本地模型 + 预留接口 TODO 占位，不强制依赖真实后台（后端当前缺 `themeId`/`splashUrl`/`logoUrl` 字段、无图片上传/扫码绑定/门店 save 接口）。
|
||
|
||
---
|
||
|
||
## 1. 实现方案 + 框架选型
|
||
|
||
### 1.1 技术难点分析
|
||
|
||
| 功能 | 难点 | 解决思路 |
|
||
|------|------|----------|
|
||
| 门店主题/皮肤 | 后台缺主题字段，需纯前端内置主题库 + 本地预览 | 主题枚举 + 内置占位资源（纯色块/Assets 图），本地模型存 `themeId`，预留 `setStoreTheme` |
|
||
| 省市级联 | 34 省三级联动数据加载与回显映射 | 复用 `province.json`，封装 `RegionPicker` 组件，结构化存 `code` + 拼接文本，既有文本地址尽力映射 |
|
||
| 扫码绑定 | 跨平台扫码（Android/iOS/鸿蒙），替代老 ScanKit | 引入 `mobile_scanner`（通用、维护活跃），解析后本地查找设备并跳转 |
|
||
| 启动图/Logo | 图片选择 + 手机外框预览，后台无上传接口 | `image_picker` 选图本地预览，`branding` 字段存本地路径，预留 `uploadAsset`/`setStoreBranding` |
|
||
|
||
### 1.2 框架 / 包选型
|
||
|
||
沿用现有栈 **Flutter 3.27.4 + riverpod + go_router + Dio**，不引入新状态框架。新增 2 个能力包：
|
||
|
||
| 包 | 版本（建议） | 用途 |
|
||
|----|------|------|
|
||
| `mobile_scanner` | ^5.2.0 | 跨平台相机扫码 + 相册识别二维码（替代华为 ScanKit） |
|
||
| `image_picker` | ^1.1.2 | 启动图/Logo 图片选择（相册/拍照） |
|
||
|
||
> 注：`mobile_scanner` 需在 `AndroidManifest.xml`/`Info.plist`/`ohos` 配置相机权限，本设计只到「接口与组件占位」层级，权限字符串由工程师按平台补。
|
||
|
||
### 1.3 pubspec.yaml 改动
|
||
|
||
```yaml
|
||
dependencies:
|
||
# 现有：flutter / go_router / flutter_riverpod / dio / intl
|
||
mobile_scanner: ^5.2.0
|
||
image_picker: ^1.1.2
|
||
|
||
flutter:
|
||
assets:
|
||
- assets/data/MCityPiker/province.json
|
||
- assets/theme/ # 新增：内置主题占位图（如 theme_1.png ...）
|
||
```
|
||
|
||
### 1.4 架构模式
|
||
|
||
保持现有 **Widget + Service + Provider** 分层，无新增抽象层：
|
||
- 模型（`lib/models/`）：`StoreInfo` 扩展字段
|
||
- 服务（`lib/services/`）：`OrgService`/`DeviceService` 新增预留 TODO 方法
|
||
- 组件（`lib/widgets/`）：`RegionPicker`、`StoreThemeGrid`、`BrandingEditor`
|
||
- 页面（`lib/screens/`）：门店表单接入、设备扫码入口
|
||
|
||
---
|
||
|
||
## 2. 文件列表（新增 / 修改，相对路径）
|
||
|
||
### 新增文件
|
||
- `lib/data/region_data.dart` — 加载 `province.json` 并解析为 `RegionNode` 树；提供 `provinceName(code)`/`cityName`/`districtName` 反查工具
|
||
- `lib/models/store_theme.dart` — `StoreTheme` 枚举 + 内置主题清单（`StoreThemePresets`）
|
||
- `lib/widgets/region_picker.dart` — 省→市→区三级联动底部弹起选择器
|
||
- `lib/widgets/store_theme_grid.dart` — 主题皮肤网格卡片 + 选中态
|
||
- `lib/widgets/store_theme_preview.dart` — 模拟主页头部预览（依据 `themeId`）
|
||
- `lib/widgets/branding_editor.dart` — 启动图/Logo 卡片：选图 + 手机外框预览
|
||
- `lib/screens/device/device_scan_page.dart` — 扫码页（`mobile_scanner` 封装，含相册识别）
|
||
- `lib/utils/store_local_cache.dart` — 门店扩展字段本地持久化（SharedPreferences 封装，存 `themeId`/`branding` 等）
|
||
|
||
### 修改文件
|
||
- `lib/models/store_info.dart` — 增加 `themeId`/`splashUrl`/`logoUrl`/`provinceCode`/`cityCode`/`districtCode`/`addressDetail` + `fromJson`/`toJson` 兼容
|
||
- `lib/screens/store/store_list_page.dart` — `_StoreFormSheet` 接入 `RegionPicker` + 主题 + `BrandingEditor`；详情 sheet 展示主题/品牌
|
||
- `lib/screens/home/device_list_page.dart` — AppBar 加扫码入口 → 跳 `device_scan_page`
|
||
- `lib/screens/home/device_detail_page.dart` — 加「扫二维码绑定」按钮 → 跳 `device_scan_page`（`mode=bind`）
|
||
- `lib/services/org_service.dart` — 加 `saveStore`/`updateStore`/`setStoreTheme`/`setStoreBranding` TODO
|
||
- `lib/services/device_service.dart` — 加 `bindDeviceByScan` TODO
|
||
- `lib/app/router.dart` — 注册 `/device/scan` 路由（含 `mode` 参数）
|
||
- `pubspec.yaml` — 加依赖 + `assets` 注册（见 1.3）
|
||
|
||
---
|
||
|
||
## 3. 数据模型与接口（类结构）
|
||
|
||
### 3.1 类图（Mermaid classDiagram）
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class StoreInfo {
|
||
+String orgId
|
||
+String name
|
||
+String address
|
||
+String contactPhone
|
||
+String activationCode
|
||
+int status
|
||
+DateTime? expireTime
|
||
+DateTime? createTime
|
||
<<新增>>
|
||
+String? themeId
|
||
+String? splashUrl
|
||
+String? logoUrl
|
||
+String? provinceCode
|
||
+String? cityCode
|
||
+String? districtCode
|
||
+String? addressDetail
|
||
+StoreInfo.fromJson(Map)
|
||
+Map toJson()
|
||
+String get regionText()
|
||
}
|
||
|
||
class RegionNode {
|
||
+String code
|
||
+String name
|
||
+List~RegionNode~ sub
|
||
+RegionNode.fromJson(Map)
|
||
}
|
||
|
||
class StoreTheme {
|
||
<<enum>>
|
||
classic
|
||
ocean
|
||
forest
|
||
sunset
|
||
mono
|
||
+String get id
|
||
+String get label
|
||
+Color get primary
|
||
}
|
||
|
||
class StoreThemePresets {
|
||
<<const>>
|
||
+List~StoreTheme~ all
|
||
+StoreTheme? byId(String)
|
||
}
|
||
|
||
class RegionData {
|
||
-List~RegionNode~ _tree
|
||
+Future~void~ load()
|
||
+List~RegionNode~ get provinces
|
||
+List~RegionNode~ citiesOf(String)
|
||
+List~RegionNode~ districtsOf(String,String)
|
||
+String nameOf(String)
|
||
+String tryMapAddress(String)~List~String?~
|
||
}
|
||
|
||
class StoreLocalCache {
|
||
+Future~void~ saveTheme(String orgId, String themeId)
|
||
+Future~String?~ getTheme(String orgId)
|
||
+Future~void~ saveBranding(String orgId, String splashUrl, String logoUrl)
|
||
+Future~Map?~ getBranding(String orgId)
|
||
+Future~void~ saveRegion(String orgId, String p, String c, String d, String detail)
|
||
}
|
||
|
||
class OrgService {
|
||
+Future~void~ saveStore(Map) // TODO 对接 POST /sys/store/save
|
||
+Future~void~ updateStore(Map) // TODO 对接 POST /sys/store/update
|
||
+Future~void~ setStoreTheme(String,String) // TODO POST /sys/store/theme
|
||
+Future~void~ setStoreBranding(String,String,String) // TODO POST /sys/store/branding
|
||
}
|
||
|
||
class DeviceService {
|
||
+Future~void~ bindDeviceByScan(String scanPayload, String storeId, String? groupId) // TODO POST /device/bind
|
||
}
|
||
|
||
class DeviceScanPage {
|
||
+String mode // 'query' | 'bind'
|
||
+String? storeId
|
||
+String? groupId
|
||
}
|
||
|
||
StoreInfo "1" *-- "1" StoreTheme : themeId 关联
|
||
RegionData "1" *-- "0..*" RegionNode : 树
|
||
OrgService ..> StoreInfo : 读写
|
||
DeviceService ..> DeviceScanPage : 扫码结果
|
||
```
|
||
|
||
### 3.2 关键模型说明
|
||
|
||
**StoreInfo 新增字段**（全部可空，向后兼容既有后端响应）：
|
||
```dart
|
||
String? themeId; // 主题枚举 id，如 'ocean'
|
||
String? splashUrl; // 启动图本地路径 / 远程 URL（占位）
|
||
String? logoUrl; // Logo 本地路径 / 远程 URL（占位）
|
||
String? provinceCode; // 省 code（6 位）
|
||
String? cityCode; // 市 code
|
||
String? districtCode; // 区 code
|
||
String? addressDetail; // 街道/门牌等详情文本
|
||
// 拼接展示：regionText = 省名+市名+区名+addressDetail
|
||
```
|
||
|
||
**预留 Service 方法签名（含 TODO）**：
|
||
```dart
|
||
// OrgService — 当前后端无门店 save/update/theme/branding 接口
|
||
Future<void> saveStore(Map<String, dynamic> data) async {
|
||
// TODO(后端): POST /sys/store/save，body 含 themeId/splashUrl/logoUrl/省市区
|
||
// 前端占位：仅写 StoreLocalCache，不发起真实请求
|
||
}
|
||
Future<void> setStoreTheme(String orgId, String themeId) async {
|
||
// TODO(后端): POST /sys/store/setTheme {orgId, themeId}
|
||
}
|
||
Future<void> setStoreBranding(String orgId, String splashUrl, String logoUrl) async {
|
||
// TODO(后端): POST /sys/store/setBranding {orgId, splashUrl, logoUrl}
|
||
// 注意：真实上传需先调 uploadAsset 拿 URL
|
||
}
|
||
|
||
// DeviceService — 当前后端无扫码绑定接口
|
||
Future<void> bindDeviceByScan(String scanPayload, String storeId, String? groupId) async {
|
||
// TODO(后端): POST /device/bind {scanPayload, storeId, groupId}
|
||
// 前端占位：本地匹配设备后用 updateDevice 写 groupId/storeName
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 程序调用流程（时序，文字描述）
|
||
|
||
### 4.1 门店编辑 — 省市区 + 主题 + 品牌（主流程）
|
||
1. 用户点「新增/编辑门店」→ `_StoreFormSheet` 打开。
|
||
2. 点「地址」→ `RegionPicker` 从 `RegionData`（已加载 `province.json`）弹起三级选择 → 存 `provinceCode/cityCode/districtCode` + 回填文本到 `addressDetail`。
|
||
3. 点「主题皮肤」→ `StoreThemeGrid` 展示 `StoreThemePresets.all` → 选 `themeId` → `StoreThemePreview` 实时预览模拟头部。
|
||
4. 点「启动图/Logo」→ `BrandingEditor` 调 `image_picker` 选图 → 手机外框预览 → 存本地路径到 `splashUrl/logoUrl`。
|
||
5. 点「保存」→ `_StoreFormSheet._save()` 组装 data → 调 `OrgService.saveStore`（占位写 `StoreLocalCache`，并留 `setStoreTheme`/`setStoreBranding` TODO）→ 关闭 sheet，`_loadData()` 刷新。
|
||
|
||
### 4.2 设备扫码 — 查询模式
|
||
1. 设备列表 AppBar 扫码图标 → `context.go('/device/scan?mode=query')`。
|
||
2. `DeviceScanPage` 用 `mobile_scanner` 实时扫码（或相册识别）→ 得到 `scanPayload`（设备标识，如 mac/sn）。
|
||
3. 本地用 `DeviceService.fetchDevices(mac:...)` 或列表缓存查找 → 命中则 `context.go('/device/:id')` 跳详情；未命中提示「未找到设备」。
|
||
|
||
### 4.3 设备扫码 — 绑定模式
|
||
1. 设备详情「扫二维码绑定」→ `context.go('/device/scan?mode=bind&deviceId=xxx')`。
|
||
2. 扫码得到目标门店/分组码 → 弹窗确认「绑定到当前门店/分组」→ `DeviceService.bindDeviceByScan`（占位：本地 `updateDevice` 写 `groupId`/`storeName`，留真实 POST TODO）。
|
||
3. 返回详情，展示更新后的归属。
|
||
|
||
### 4.4 既有门店地址回显
|
||
- 打开编辑既有门店：`_StoreFormSheet.initState` 若 `store.provinceCode` 非空 → `RegionPicker` 直接定位；若为空但有旧文本 `address` → `RegionData.tryMapAddress()` 尽力用关键词匹配省/市/区，匹配不到则仅填 `addressDetail` 文本。
|
||
|
||
---
|
||
|
||
## 5. 有序任务列表（按实现顺序，含依赖）
|
||
|
||
> 规则：不超过 5 个任务，每任务 ≥3 文件，首个为基础设施。
|
||
|
||
| 任务 | 名称 | 源文件 | 依赖 | 优先级 |
|
||
|------|------|--------|------|--------|
|
||
| **T01** | 项目基础设施（依赖 + assets + 数据/主题基座） | `pubspec.yaml`、`lib/data/region_data.dart`、`lib/models/store_theme.dart`、`lib/utils/store_local_cache.dart` | — | P0 |
|
||
| **T02** | 扩展 StoreInfo 模型 + 预留 Service 接口 | `lib/models/store_info.dart`、`lib/services/org_service.dart`、`lib/services/device_service.dart` | T01 | P0 |
|
||
| **T03** | 门店表单增强组件（省市区 + 主题 + 品牌） | `lib/widgets/region_picker.dart`、`lib/widgets/store_theme_grid.dart`、`lib/widgets/store_theme_preview.dart`、`lib/widgets/branding_editor.dart` | T01、T02 | P1 |
|
||
| **T04** | 门店表单接入 + 设备扫码模块 + 路由 | `lib/screens/store/store_list_page.dart`、`lib/screens/home/device_list_page.dart`、`lib/screens/home/device_detail_page.dart`、`lib/screens/device/device_scan_page.dart`、`lib/app/router.dart` | T03、T02 | P1 |
|
||
| **T05** | 构建验证与联调（编译/权限/占位跑通） | 复用上述全部文件 + `android/Info.plist/ohos` 权限配置 | T04 | P2 |
|
||
|
||
### 任务依赖图
|
||
```mermaid
|
||
graph TD
|
||
T01[T01 基础设施] --> T02[T02 模型+Service]
|
||
T01 --> T03[T03 组件]
|
||
T02 --> T03
|
||
T03 --> T04[T04 接入+扫码+路由]
|
||
T02 --> T04
|
||
T04 --> T05[T05 构建验证]
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 依赖包列表
|
||
|
||
```
|
||
- mobile_scanner@^5.2.0 : 跨平台相机/相册二维码扫码（替代华为 ScanKit）
|
||
- image_picker@^1.1.2 : 启动图/Logo 本地图片选择（相册/拍照）
|
||
# 以下为现有包（已存在，仅列示上下文）
|
||
- flutter / go_router@^14.2.0 / flutter_riverpod@^2.5.1 / dio@^5.4.3 / intl@^0.19.0
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 共享知识（跨文件约定）
|
||
|
||
- **province.json 加载**：统一由 `lib/data/region_data.dart` 的 `RegionData.load()` 懒加载并缓存为 `List<RegionNode>` 树；组件禁止直接 `rootBundle` 读取，避免重复解析（文件 284KB）。
|
||
- **主题枚举位置**：`lib/models/store_theme.dart` 定义 `StoreTheme` 枚举与 `StoreThemePresets`；所有主题相关 UI 仅引用枚举 id（`themeId`），不硬编码颜色。
|
||
- **预留接口 TODO 规范**：所有待对接后台的方法必须含 `// TODO(后端): POST /sys/...` 注释，写明预期路径与 body；前端占位实现只写 `StoreLocalCache`，并 `print`/debug 标注「占位未上报」。
|
||
- **本地持久化**：门店扩展字段统一经 `StoreLocalCache`（SharedPreferences，key 形如 `store_theme_$orgId`），不在内存态以外散落存储。
|
||
- **扫码 payload**：约定扫码内容优先解析为 `mac` 或 `deviceSn`；无法识别时原样透传，由 `DeviceService` 模糊匹配。
|
||
- **图片路径**：`image_picker` 返回的 `XFile.path` 直接存 `splashUrl/logoUrl`（占位）；真实上传走 `uploadAsset` 后再替换为 URL（TODO）。
|
||
- **路由参数**：`/device/scan?mode=query|bind&deviceId=xxx&storeId=xxx`，由 `device_scan_page` 解析。
|
||
|
||
---
|
||
|
||
## 8. 待明确事项
|
||
|
||
1. **主题占位资源形式**：内置纯色块 + 名称，还是需要 `assets/theme/*.png` 缩略图？当前设计按「纯色块 + 名称」实现，若需图片请在 T01 前提供 4–5 张占位图。
|
||
2. **扫码绑定语义**：「绑定到当前门店/分组」中「当前门店」取自设备详情页的 `storeName` 还是用户手动选？本设计默认取详情页所属门店，绑定弹窗可改分组。
|
||
3. **省市级联回显映射**：既有纯文本地址（如「北京市朝阳区xx路」）能否映射到 code 取决于关键词命中，映射不到仅回填 `addressDetail`，是否接受？
|
||
4. **鸿蒙权限**：`mobile_scanner` 在 ohos 平台的相机权限声明方式需工程师按鸿蒙规范确认（本设计不含具体 ohos 权限代码）。
|
||
5. **本地缓存生命周期**：`StoreLocalCache` 数据在重新登录/切换组织时是否清空？默认不清，如需隔离按 `orgId` 已做 key 隔离，可后续细化。
|
||
|
||
---
|
||
|
||
> 交付完毕：本设计为纯架构/任务分解，**不含实现代码**。工程师按 T01→T05 顺序落地即可。
|