gcx/docs/guides/02-Flutter管理后台App开发指南.md

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 企业入驻审核

// 入驻流程状态机
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标准。

// 券模板类型
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;
}

// 发券流程
// 选择模板 → 填写信息 → 设定规则 → 预览 → 提交审核 → 审核通过 → 自动链上铸造+上架
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 数据仪表盘

// 发行方数据概览
@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 财务管理

// 财务视图：法币展示，不暴露链上稳定币细节
@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 信用评级展示

// 四因子信用评分：核销率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建议卡片组件

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，不同签名）

---

9. 财务管理增强

9.1 保证金与冻结销售款

// 发行方可选：缴纳保证金以快速提升额度
@freezed
class GuaranteeFund with _$GuaranteeFund {
  const factory GuaranteeFund({
    required double deposited,         // 已缴纳保证金
    required double frozenSales,       // 冻结的销售款（自愿开启）
    required bool autoFreezeEnabled,   // 是否开启销售款自动冻结
    required double freezePercent,     // 冻结比例（如20%销售额）
  }) = _GuaranteeFund;
}

// 财务管理增强视图
@freezed
class FinanceDetailView with _$FinanceDetailView {
  const factory FinanceDetailView({
    required double salesRevenue,       // 销售收入
    required double breakageIncome,     // Breakage收入（过期券）
    required double platformFees,       // 平台手续费支出
    required double pendingSettlement,  // 待结算
    required double withdrawable,       // 可提现
    required double totalWithdrawn,     // 已提现
    required double guaranteeDeposit,   // 保证金
    required double frozenSales,        // 冻结销售款
  }) = _FinanceDetailView;
}

9.2 对账报表

// 日/月对账单
class ReconciliationReport {
  final DateTime periodStart;
  final DateTime periodEnd;
  final List<TransactionEntry> entries;
  final double totalIncome;
  final double totalExpense;
  final double netBalance;

  // 导出为CSV/PDF
  Future<File> exportAsCsv() async { /* ... */ }
  Future<File> exportAsPdf() async { /* ... */ }
}

---

10. 发行方数据分析增强

10.1 二级市场分析

@freezed
class SecondaryMarketAnalysis with _$SecondaryMarketAnalysis {
  const factory SecondaryMarketAnalysis({
    required int listedCount,          // 二级市场挂单数
    required double avgResalePrice,    // 平均转售价
    required double avgDiscount,       // 平均折扣率
    required int resaleVolume,         // 转售成交量
    required double resaleRevenue,     // 转售成交额
    required List<PricePoint> priceHistory, // 价格历史（K线数据）
  }) = _SecondaryMarketAnalysis;
}

10.2 融资效果分析

@freezed
class FinancingEffectReport with _$FinancingEffectReport {
  const factory FinancingEffectReport({
    required double cashAdvanced,       // 现金提前回笼总额
    required double avgAdvanceDays,     // 平均提前回笼天数
    required double financingCost,      // 融资成本（平台手续费+折扣损失）
    required double effectiveRate,      // 等效年利率
    required List<CashFlowPoint> cashFlowTimeline, // 现金流时序图
  }) = _FinancingEffectReport;
}

---

11. 退款窗口配置

// 发行方可配置退款期限
@freezed
class RefundPolicy with _$RefundPolicy {
  const factory RefundPolicy({
    required int refundWindowDays,      // 退款窗口（天，默认7天）
    required bool autoRefundEnabled,    // 是否自动退款
    required String refundConditions,   // 退款条件说明
  }) = _RefundPolicy;
}

// 创建券时配置退款策略
class CreateCouponWithRefundPolicy {
  Widget buildRefundSection() {
    return Column(children: [
      Text('退款策略'),
      NumberPicker(
        label: '退款窗口（天）',
        min: 0, max: 30, initial: 7,
        onChanged: (days) => _refundDays = days,
      ),
      SwitchListTile(
        title: Text('允许自动退款'),
        subtitle: Text('窗口期内用户可直接退款无需审核'),
        value: _autoRefund,
        onChanged: (v) => setState(() => _autoRefund = v),
      ),
    ]);
  }
}

---

12. 批量操作

// 批量发行、批量核销、批量导出
class BatchOperationsService {
  // 批量发行（一次创建多种券模板）
  Future<Either<Failure, List<CouponDraft>>> batchCreate(
    List<CreateCouponParams> paramsList
  ) async {
    return _repo.batchSubmitDrafts(paramsList);
  }

  // 批量核销
  Future<Either<Failure, BatchRedeemResult>> batchRedeem(
    List<String> couponCodes
  ) async {
    return _repo.batchRedeem(couponCodes);
  }

  // 批量数据导出
  Future<File> exportData({
    required ExportType type,  // coupons / transactions / reconciliation
    required DateRange range,
    required ExportFormat format, // csv / xlsx / pdf
  }) async {
    return _repo.exportBatchData(type, range, format);
  }
}

---

13. 券召回与下架

// 券召回流程
class CouponRecallService {
  /// 召回未售出的券（链上销毁）
  Future<Either<Failure, RecallResult>> recallUnsold(String couponBatchId) async {
    return _repo.recallUnsoldCoupons(couponBatchId);
  }

  /// 问题券紧急下架
  Future<Either<Failure, void>> emergencyDelist(String couponId, String reason) async {
    return _repo.delistCoupon(couponId, reason);
  }

  /// 已售出券的退款处理
  Future<Either<Failure, void>> initiateRefundForSold(
    String couponBatchId, String refundReason
  ) async {
    return _repo.initiateRefundForSoldCoupons(couponBatchId, refundReason);
  }
}

---

14. 多门店管理增强

// 门店层级管理
@freezed
class StoreHierarchy with _$StoreHierarchy {
  const factory StoreHierarchy({
    required String id,
    required String name,
    required StoreLevel level,         // headquarters / regional / store
    String? parentId,                  // 上级ID
    required List<StoreHierarchy> children,
    required StorePermissions permissions,
  }) = _StoreHierarchy;
}

enum StoreLevel { headquarters, regional, store }

// 门店员工管理
@freezed
class StoreEmployee with _$StoreEmployee {
  const factory StoreEmployee({
    required String id,
    required String name,
    required String phone,
    required StoreRole role,            // cashier / manager / admin
    required List<String> storeIds,     // 可操作的门店
  }) = _StoreEmployee;
}

enum StoreRole {
  cashier,  // 收银员：仅核销权限
  manager,  // 店长：核销 + 数据查看
  admin,    // 管理员：全部权限
}

---

15. 专属客服通道

// 铂金/钻石层级发行方专属客服
class DedicatedSupportWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final issuer = ref.watch(issuerProfileProvider);

    if (['platinum', 'diamond'].contains(issuer.tier.name)) {
      return Card(
        child: ListTile(
          leading: Icon(Icons.headset_mic, color: Colors.amber),
          title: Text('专属客服'),
          subtitle: Text('1小时内响应 | 您的客户经理：${issuer.accountManager}'),
          onTap: () => _openDedicatedChat(context),
        ),
      );
    }

    return Card(
      child: ListTile(
        leading: Icon(Icons.support_agent),
        title: Text('在线客服'),
        subtitle: Text('24小时内响应'),
        onTap: () => _openSupportTicket(context),
      ),
    );
  }
}

---

文档版本: v2.0 基于: Genex 券交易平台 - 软件需求规格说明书 v4.1 技术栈: Flutter 3.x + Riverpod + Clean Architecture 更新: 补充保证金/冻结销售款/对账报表/二级市场分析/融资效果/退款窗口/批量操作/券召回/多门店增强/专属客服