# cmall-app

**Repository Path**: netherworld/cmall-app

## Basic Information

- **Project Name**: cmall-app
- **Description**: 
CMall 是基于 Flutter 的 Android、iOS、H5 客户端。工程采用轻量Feature First + Repository 分层；

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CMall App

CMall 是基于 Flutter 的 Android、iOS、H5 客户端。工程采用轻量
Feature First + Repository 分层；当前已开始按
`api_doc/cmall-app-openapi.json` 对接服务端，尚未接入远端的数据域使用各功能
自己的 Mock Repository。页面结构、文案、交互和初始样例优先复用
`D:\workspace\mall-j`。

## 工程结构

```text
lib/
├── main.dart                         # 启动入口
├── app/                              # 应用组合根、壳层、导航和组件配置
│   ├── app.dart
│   ├── app_dependencies.dart
│   ├── component_config/
│   ├── navigation/
│   └── shell/
├── core/                             # 网络、返回栈等跨业务基础设施
├── shared/                           # 主题令牌和通用 Widget
└── features/
    └── <feature>/
        ├── domain/                   # 模型、Repository 契约、业务异常
        ├── data/                     # 远端/Mock 实现与 fixtures
        └── presentation/             # 页面、流程与展示组件

test/                                 # 按 lib 的 app/features 结构镜像组织
```

`AppDependencies` 是运行时唯一的功能依赖组合入口。页面通过 Repository 契约
读取和修改数据；静态样例、可变状态和 UI 已分离，不再共享跨业务的全局 Store。

## 环境要求

- Flutter SDK：3.41 或兼容版本
- Dart SDK：3.12 或兼容版本
- Chrome：运行 H5
- Android Studio / Android SDK：构建 Android
- macOS + Xcode：构建 iOS

本机未配置全局 `flutter` 时，可直接使用：

```powershell
D:\app\flutter\bin\flutter.bat pub get
```

## 启动

H5：

```powershell
# 生成用于本地联调的 Profile H5
D:\app\flutter\bin\flutter.bat build web --profile `
  --dart-define=CMALL_API_BASE_URL=http://localhost:8181

# 托管 build/web，并把 /api 转发到本机 App 服务
dart run tool/serve_web_dev_proxy.dart
```

浏览器访问 `http://localhost:8181`。H5 不能直接从 `8181` 跨域调用
`18087`；本地联调统一通过上述同源代理，避免服务端未配置 CORS 时组件配置
自动回退为全开启。

Android：

```powershell
D:\app\flutter\bin\flutter.bat devices
D:\app\flutter\bin\flutter.bat run -d <android-device-id> `
  --dart-define=CMALL_USE_REMOTE_API=true `
  --dart-define=CMALL_API_BASE_URL=http://10.0.2.2:18087
```

本机 HTTP 地址只允许 Debug/Profile 构建使用；Release 环境必须提供 HTTPS
接口地址。

iOS：

```bash
flutter devices
flutter run -d <ios-device-id> \
  --dart-define=CMALL_USE_REMOTE_API=true \
  --dart-define=CMALL_API_BASE_URL=http://localhost:18087
```

iOS 模拟器可使用 `localhost`；物理机必须改为开发机在局域网内可访问的地址。

H5 Release 构建：

```powershell
D:\app\flutter\bin\flutter.bat build web --release
```

## 演示账号

所有账号密码均为 `123456`：

| 手机号 | 姓名 | `mall-j` 身份 | CMall 服务端身份映射 |
| --- | --- | --- | --- |
| 13800001111 | 李明 | 普通消费者 | `CONSUMER`，无后台基线角色 |
| 13800002222 | 张伟 | 商城店主 | `SECONDHAND_SELLER` |
| 13800003333 | 王芳 | 美食餐饮店主 | `LOCAL_FOOD_SELLER` |
| 13800004444 | 刘洋 | 短视频创作者 | `SHORT_VIDEO_CREATOR` |
| 13800005555 | 陈静 | 物业员工 | `PROPERTY_MANAGER` |

普通消费者不会获得卖家身份。只有二手卖家账号能进入店铺经营页面。

当前联调仅接入密码登录与全局菜单获取。验证码登录尚无服务端接口。
其他业务域暂未进入远端模式，默认使用各自的 Mock Repository 回归；
联调时按上方命令显式设置 `CMALL_USE_REMOTE_API=true`。
远端联调页返回登录页时只清除内存 Token，不调用范围外的服务端退出接口。

组件功能开关独立于业务接口模式，默认会匿名请求
`GET /api/app/component-config`。启动和构建时必须通过
`CMALL_API_BASE_URL` 提供对应环境的服务地址；仅在离线回归时可显式设置
`--dart-define=CMALL_USE_REMOTE_COMPONENT_CONFIG=false`。App 会按平台、版本、
构建号和 Schema 精确查询，并使用同构建的最后有效缓存兜底。

App 组件发布源文件保存在 `app_component_releases/`。修改组件清单后先提升
`pubspec.yaml` 构建号，再运行：

```powershell
dart run tool/generate_app_component_releases.dart
```

## 数据说明

- 除密码登录与菜单获取外，各业务域目前由自己的 Mock Repository 提供数据。
- 登录会话由组合根共享；购物车、收藏、订单、报修、短视频关注和点赞在
  对应 Repository 实例内可观察地更新。
- 刷新 H5 或重启 App 后会重新创建依赖并恢复 `mall-j` 初始样例。
- fixtures 只保存在对应功能的 `data/` 目录，页面不直接读取静态样例。
- 图片地址属于 Mock 样例资源，与任何 CMall 服务端无关。
- 远端模式需要先在本机启动 `cmall-platform` 的 App 服务；纯 Mock 回归模式
  不需要服务端。

## 质量检查

```powershell
D:\app\flutter\bin\cache\dart-sdk\bin\dart.exe format --set-exit-if-changed lib test
D:\app\flutter\bin\flutter.bat analyze
D:\app\flutter\bin\flutter.bat test
D:\app\flutter\bin\flutter.bat build web --release
```

详细开发边界与编码规范见 [agent.md](agent.md)。