288 lines
9.5 KiB
Markdown
288 lines
9.5 KiB
Markdown
# Genex Flutter 管理后台 App 开发指南
|
||
|
||
> 发行方管理控制台（Issuer Console App）
|
||
|
||
---
|
||
|
||
## 1. 产品定位
|
||
|
||
发行方管理后台App为企业/政府/机构提供**Web2体验**的券发行与管理工具。发行方无需了解区块链技术，发券 = 创建优惠活动，链上铸造在后台自动完成。
|
||
|
||
**核心设计原则**：
|
||
- 发行方看到的是"创建优惠活动"，不是"链上铸造NFT"
|
||
- 消费数据隔离：发行方仅可见汇总数据（兑付率、销量），不可见消费者个人信息
|
||
- AI Agent深度融合：协助发券建议、定价优化、信用提升
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
|
||
| 技术 | 用途 |
|
||
|------|------|
|
||
| **Flutter 3.x** | 跨平台（iOS/Android），与Consumer App共享核心模块 |
|
||
| **Riverpod 2.x** | 状态管理 |
|
||
| **GoRouter** | 路由管理 |
|
||
| **Dio** | HTTP客户端 |
|
||
| **Freezed** | 不可变数据模型 |
|
||
| **fl_chart** | 数据可视化图表 |
|
||
| **qr_code_scanner** | 扫码核销 |
|
||
|
||
---
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
genex_issuer/
|
||
├── lib/
|
||
│ ├── main.dart
|
||
│ ├── app/
|
||
│ │ ├── router.dart # 发行方专用路由
|
||
│ │ └── theme/ # 企业端主题（区别于消费者端）
|
||
│ ├── core/ # 共享核心模块（可从mono-repo引用）
|
||
│ ├── features/
|
||
│ │ ├── auth/ # 企业注册/登录
|
||
│ │ ├── onboarding/ # 入驻审核流程
|
||
│ │ ├── coupon_management/ # 券管理（核心模块）
|
||
│ │ │ ├── create/ # 创建券（模板化发券）
|
||
│ │ │ ├── list/ # 券列表管理
|
||
│ │ │ ├── detail/ # 券详情/数据
|
||
│ │ │ └── recall/ # 券召回/下架
|
||
│ │ ├── redemption/ # 核销管理
|
||
│ │ ├── finance/ # 财务管理
|
||
│ │ ├── credit/ # 信用评级
|
||
│ │ ├── dashboard/ # 数据仪表盘
|
||
│ │ ├── ai_agent/ # AI Agent
|
||
│ │ └── settings/ # 设置
|
||
│ └── shared/ # 共享组件
|
||
├── test/
|
||
└── pubspec.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 核心功能模块
|
||
|
||
### 4.1 企业入驻审核
|
||
|
||
```dart
|
||
// 入驻流程状态机
|
||
enum OnboardingStep {
|
||
companyInfo, // 企业基本信息
|
||
documents, // 营业执照/资质文件上传
|
||
contactPerson, // 联系人信息
|
||
review, // 等待平台审核
|
||
approved, // 审核通过
|
||
rejected, // 审核拒绝（可重新提交）
|
||
}
|
||
|
||
// 零保证金入驻：审核通过后给予初始低额度
|
||
@freezed
|
||
class IssuerProfile with _$IssuerProfile {
|
||
const factory IssuerProfile({
|
||
required String id,
|
||
required String companyName,
|
||
required String businessLicense,
|
||
required CreditRating creditRating, // 信用等级
|
||
required double issuanceQuota, // 发行额度
|
||
required IssuerTier tier, // 白银/黄金/铂金/钻石
|
||
required OnboardingStep onboardingStep,
|
||
}) = _IssuerProfile;
|
||
}
|
||
|
||
enum CreditRating { AAA, AA, A, BBB, BB }
|
||
enum IssuerTier { silver, gold, platinum, diamond }
|
||
```
|
||
|
||
### 4.2 模板化发券
|
||
|
||
> 发行方通过Web2界面创建券，无需了解NFT/ERC标准。
|
||
|
||
```dart
|
||
// 券模板类型
|
||
enum CouponTemplate {
|
||
discount, // 折扣券
|
||
voucher, // 代金券
|
||
giftCard, // 礼品卡
|
||
storedValue, // 储值券
|
||
}
|
||
|
||
@freezed
|
||
class CreateCouponParams with _$CreateCouponParams {
|
||
const factory CreateCouponParams({
|
||
required CouponTemplate template,
|
||
required String name,
|
||
required double faceValue,
|
||
required DateTime expiryDate, // ≤12个月（Utility Track强制）
|
||
required int quantity, // 发行数量
|
||
double? issuePrice, // 发行价（通常折价）
|
||
bool? transferable, // 是否允许转让（默认可转让）
|
||
int? maxResaleCount, // 最大转售次数（默认2-3次）
|
||
bool? stackable, // 是否可叠加使用
|
||
double? minPurchaseAmount, // 最低消费金额
|
||
List<String>? allowedStoreIds, // 限定门店
|
||
String? description,
|
||
String? imageUrl,
|
||
}) = _CreateCouponParams;
|
||
}
|
||
```
|
||
|
||
```dart
|
||
// 发券流程
|
||
// 选择模板 → 填写信息 → 设定规则 → 预览 → 提交审核 → 审核通过 → 自动链上铸造+上架
|
||
class CreateCouponUseCase {
|
||
Future<Either<Failure, CouponDraft>> call(CreateCouponParams params) async {
|
||
// 前端校验
|
||
if (params.expiryDate.difference(DateTime.now()).inDays > 365) {
|
||
return Left(Failure.validation(
|
||
errors: {'expiryDate': 'Utility Track有效期不得超过12个月'},
|
||
));
|
||
}
|
||
return _repo.submitCouponDraft(params);
|
||
// 后端：审核通过 → 自动调用CouponFactory合约铸造（发行方无感知）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 数据仪表盘
|
||
|
||
```dart
|
||
// 发行方数据概览
|
||
@freezed
|
||
class IssuerDashboard with _$IssuerDashboard {
|
||
const factory IssuerDashboard({
|
||
required int totalIssued, // 总发行量
|
||
required int totalRedeemed, // 总核销量
|
||
required double redemptionRate, // 兑付率
|
||
required double breakageRate, // Breakage率
|
||
required double totalRevenue, // 总销售收入
|
||
required double availableBalance, // 可提现余额
|
||
required CreditRating creditRating, // 信用等级
|
||
required double quotaUsed, // 已用额度
|
||
required double quotaTotal, // 总额度
|
||
}) = _IssuerDashboard;
|
||
}
|
||
```
|
||
|
||
### 4.4 财务管理
|
||
|
||
```dart
|
||
// 财务视图：法币展示，不暴露链上稳定币细节
|
||
@freezed
|
||
class FinanceOverview with _$FinanceOverview {
|
||
const factory FinanceOverview({
|
||
required double salesRevenue, // 销售收入
|
||
required double pendingSettlement, // 待结算
|
||
required double withdrawable, // 可提现
|
||
required double totalWithdrawn, // 已提现
|
||
required List<Transaction> recentTransactions,
|
||
}) = _FinanceOverview;
|
||
}
|
||
```
|
||
|
||
### 4.5 信用评级展示
|
||
|
||
```dart
|
||
// 四因子信用评分：核销率35% + (1-Breakage率)25% + 市场存续20% + 用户满意度20%
|
||
class CreditScoreWidget extends StatelessWidget {
|
||
final CreditDetail credit;
|
||
|
||
@override
|
||
Widget build(BuildContext context) {
|
||
return Column(children: [
|
||
// 总分和等级
|
||
CreditScoreGauge(score: credit.totalScore, rating: credit.rating),
|
||
// 四因子明细
|
||
FactorBar(label: '核销率', value: credit.redemptionRate, weight: 0.35),
|
||
FactorBar(label: '沉淀控制', value: 1 - credit.breakageRate, weight: 0.25),
|
||
FactorBar(label: '市场存续', value: credit.tenureScore, weight: 0.20),
|
||
FactorBar(label: '用户满意度', value: credit.satisfaction, weight: 0.20),
|
||
]);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. AI Agent 集成
|
||
|
||
### 5.1 发行方AI Agent场景
|
||
|
||
| 场景 | AI能力 | UI实现 |
|
||
|------|--------|--------|
|
||
| 发券建议 | 分析市场趋势，建议发券时间/面值/折扣/数量 | 发券中心顶部AI建议卡片 |
|
||
| 定价优化 | 三因子模型+AI定价引擎，提供最优定价策略 | 创建券时AI推荐价格+对比分析 |
|
||
| 信用提升 | 分析信用评分各维度，给出改善建议 | 信用等级页面AI建议列表 |
|
||
| 销售分析 | 智能解读销售数据，发现异常和机会 | 数据中心AI洞察卡片 |
|
||
| 额度规划 | 预测额度消耗速度，建议补充计划 | 额度页面AI规划时间线 |
|
||
| 合规助手 | 提醒合规要求，辅助材料准备 | 入驻审核时AI检查清单 |
|
||
|
||
### 5.2 AI建议卡片组件
|
||
|
||
```dart
|
||
class AiSuggestionCard extends StatelessWidget {
|
||
final AiSuggestion suggestion;
|
||
final VoidCallback onAccept;
|
||
final VoidCallback onDismiss;
|
||
|
||
@override
|
||
Widget build(BuildContext context) {
|
||
return Card(
|
||
child: Column(children: [
|
||
Row(children: [
|
||
Icon(Icons.smart_toy, color: Colors.blue),
|
||
Text('AI建议', style: Theme.of(context).textTheme.titleSmall),
|
||
]),
|
||
Text(suggestion.content),
|
||
if (suggestion.actionable)
|
||
Row(children: [
|
||
TextButton(onPressed: onDismiss, child: Text('忽略')),
|
||
ElevatedButton(onPressed: onAccept, child: Text('采纳')),
|
||
]),
|
||
]),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 发行方分层激励展示
|
||
|
||
| 层级 | 月发行量 | 手续费率 | 增值服务 |
|
||
|------|---------|---------|---------|
|
||
| 白银 | < 100万 | 1.5% | 基础数据看板 |
|
||
| 黄金 | 100-500万 | 1.2% | 高级数据分析+推荐位 |
|
||
| 铂金 | 500-2000万 | 1.0% | 专属客服+定制报表 |
|
||
| 钻石 | > 2000万 | 0.8% | 定制开发+专属API+联合营销 |
|
||
|
||
> 新入驻发行方首月享黄金层级手续费（获客激励）。
|
||
|
||
---
|
||
|
||
## 7. 与Consumer App共享
|
||
|
||
| 共享模块 | 内容 |
|
||
|---------|------|
|
||
| `core/network/` | Dio配置、拦截器 |
|
||
| `core/storage/` | 本地存储封装 |
|
||
| `core/constants/` | 术语映射、API地址 |
|
||
| `shared/widgets/` | 通用UI组件 |
|
||
| `shared/models/` | Coupon、User等共享模型 |
|
||
|
||
通过Dart Package或Mono-repo方式实现代码共享。
|
||
|
||
---
|
||
|
||
## 8. 测试与发布
|
||
|
||
- 单元测试：发券参数校验、信用评分计算、额度校验
|
||
- Widget测试：发券表单、仪表盘图表
|
||
- 集成测试：完整发券流程、核销流程
|
||
- 发布通道：与Consumer App独立（不同App ID，不同签名）
|
||
|
||
---
|
||
|
||
*文档版本: v1.0*
|
||
*基于: Genex 券交易平台 - 软件需求规格说明书 v4.1*
|
||
*技术栈: Flutter 3.x + Riverpod + Clean Architecture*
|