Commit Graph

12 Commits

Author SHA1 Message Date
hailin bc0d1e0876 feat: 新增 deploy.sh 部署管理脚本体系 — 后端主控+12服务独立+区块链
参照 rwadurian 项目模式,为全栈系统创建统一的 deploy.sh 管理体系:

- backend/deploy.sh: 主控脚本 (up/down/restart/build/build-no-cache/health/infra-*/单服务操作)
- 12个服务独立 deploy.sh (build/rebuild/start/stop/restart/logs/health/shell/test)
- blockchain/deploy.sh: 节点+生态+合约+浏览器+监控全覆盖
- 更新 09-编译部署指南.md 新增第9章 deploy.sh 使用文档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-19 17:13:09 -08:00
hailin cc4d3d11f8 docs: 新增09-编译部署指南 — 全栈编译、运行与生产部署完整文档
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-18 16:54:03 -08:00
hailin 4c1d907df6 feat: ERC-1155 同质化券系统 + denom统一为agnx (18位EVM标准)
新增ERC-1155双模式券系统(Utility Track专用):
- ICouponBatch接口 + CouponBatch核心合约(FACTORY/BURNER角色)
- Redemption1155兑付合约(余额/过期/门店/黑名单验证)
- CouponFactory新增mintBatch1155路由(上限100,000张O(1)铸造)
- Deploy.s.sol部署CouponBatch+Redemption1155+角色授权
- 46个新测试(CouponBatch 16 + Redemption1155 9 + Factory 11 + Integration 5 + fuzz)

Denom统一: ugnx(6位)→agnx(18位EVM标准), 金额×10^12

全量测试143/143通过,编译零错误。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-15 22:34:30 -08:00
hailin 0ea869ac46 fix: 区块链生态审计修复 — SDK补全 + Enterprise API加固 + 删除无用wallet-service
基于08-区块链生态基础设施开发指南的全面审计,修复以下问题:

## SDK 补全(对齐指南 §7.2-7.4)

- **JS SDK**: 新增 SettlementModule (settlement.ts),实现 executeSwap() 合约交互
  和 onSwapExecuted() 事件监听,补齐指南 §7.2 要求的 settlement 模块
- **Go SDK**: 新增 ExecuteSwap() 函数 (settlement.go),完整实现 ABI 编码 → nonce
  获取 → gas 估算 → 签名 → 广播 → receipt 等链上交易全流程
- **Dart SDK**: 新增统一事件订阅接口 subscribeEvents(EventFilter),匹配指南 §7.4
  规范;新增 EventFilter 模型类,支持 newHeads/logs 两种订阅类型

## Enterprise API 加固(对齐指南 §3.2/§3.4)

- 新增 TierThrottlerGuard 分层限流守卫,按 API tier 区分速率限制:
  public 60/min, institutional 600/min, regulatory/internal unlimited
- WebSocket 网关增加完整认证:API Key 通过 query param 或 header 传递,
  最低要求 institutional 级别,未认证连接自动拒绝

## 删除无用的 wallet-service(架构纠正)

- 删除 blockchain/wallet-service/ 整个目录(13个文件,875行代码)
  该服务架构设计有误:钱包操作(用户钱包、机构操作、治理多签)已由现有
  后端微服务处理(user-service:3001、issuer-service:3002、trading-service:3003、
  clearing-service:3004),无需在 blockchain/ 目录下另建独立服务
- docker-compose.yml: 移除 wallet-service 服务定义和端口 3021 映射
- chain-ci.yml: 从 NestJS 生态服务 CI matrix 中移除 wallet-service
- 08-指南: 删除第4节(钱包体系 §4.1-4.3),移除部署清单中 MPC签名服务:3021,
  更新生态全景图,章节重新编号 (12→11章)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-15 22:05:52 -08:00
hailin 02a597c252 docs: 新增08-区块链生态基础设施开发指南 — 链生态完整工具链
独立于06-区块链开发指南(链内核),本文档覆盖Genex Chain量产运营所需的全部生态基础设施:

1. 区块浏览器(Blockscout)
   - EVM兼容配置、券NFT定制详情页、合规标签系统
   - 发行方档案页、验证节点面板、Gas补贴统计

2. 企业API服务(:3020)
   - 4层认证:公开API Key / 机构mTLS / 监管mTLS+证书 / 内部服务间mTLS
   - 公开端点(区块/交易/券查询)、机构端点(批量导出/WebSocket)、监管端点(地址图谱/Travel Rule/冻结)

3. 三层钱包体系
   - 用户抽象钱包:MPC 2-of-3门限签名,用户无感(手机号=身份)
   - 机构托管钱包:HSM/Fireblocks,多签审批,白名单+限额
   - 治理多签钱包:Gnosis Safe 3/5或4/5,合约升级/冻结/参数调整

4. Gas Relayer(Meta-TX中继器,:3022)
   - EIP-712签名验证、防重放nonce、Relayer热钱包自动补充

5. 链监控运维(Prometheus + Grafana)
   - 14项关键指标:共识/EVM/存储/网络/业务/Relayer/跨链桥
   - AlertManager → PagerDuty / Slack

6. 测试网水龙头(:3023)
7. 开发者SDK(JS/Go/Dart三语言)
8. 归档节点(pruning=nothing,全历史状态)
9. 跨链桥监控(Axelar资产对账,自动暂停)
10. 合约安全CI(Slither + Mythril + 第三方审计)
11. 完整端口分配(3020-3024 + 4000 + 9090)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-15 17:12:46 -08:00
hailin 0c70a030ea docs: 06-区块链开发指南 v3.0 量产版 — 去除全部MVP/阶段性限制
变更明细:
- 链设计参数:共识机制从"初期平台运营"改为"平台+合格机构验证节点"
- 节点运营:去掉"未来开放",直接定义多机构验证节点架构
- CouponFactory:移除Utility-only硬编码限制,开放Utility+Securities双轨制
  - Securities Track增加合格投资者验证+Broker-Dealer合规检查
- 新增第11节"多机构验证节点架构":
  - 4类节点(创世验证/机构验证/监管观察/全节点)准入条件
  - 生产验证节点CometBFT共识配置(出块≤1s)
  - 部署拓扑(Genex x3 + 机构 x4+ + 监管 x3)
- GNX代币:去掉"待法律意见书后开放"措辞,改为"需合规审批"
  - 代币分配去掉"预留设计"标签
- CBS资产证券化:从Phase 4接口预留升级为完整合约实现
  - createPool(券收益流打包)
  - purchaseShares(合格投资者份额认购)
  - setCreditRating(链下评级机构写入)
  - distributeYield(到期收益按份额分配)
- Gas策略保持不变(前期补贴+未来可通过Governance调整)
- 章节重新编号(11→21共21节)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-14 18:47:55 -08:00
hailin e20c321d12 refactor: 遥测与版本管理拆分为独立微服务 (telemetry-service + admin-service)
架构重构: 将遥测(Telemetry)和版本管理(App Version)从 user-service 拆分为两个独立微服务,
严格遵循 DDD + Clean Architecture 四层架构。

新增服务:
- telemetry-service (:3011) — 用户心跳检测、事件采集、DAU统计、Prometheus指标
  - domain: 3实体 + 3值对象(EventName/InstallId/TimeWindow) + 2领域事件
  - infrastructure: Redis(Sorted Set心跳) + Kafka(事件发布) + Prometheus(5指标)
  - 定时任务: 每分钟在线快照、每小时清理过期、凌晨DAU精确计算、滚动DAU更新
- admin-service (:3012) — APK/IPA版本管理、OTA更新、MinIO文件存储
  - domain: 1实体 + 4值对象(VersionCode/VersionName/FileSha256/DownloadUrl)
  - infrastructure: MinIO(文件上传/下载) + APK/IPA解析器
  - 移动端: 检查更新API(无认证) + 下载重定向(预签名URL)
  - 管理端: 版本CRUD + 上传解析 + 启禁用

user-service 清理:
- 删除24个已迁移文件(4实体+4服务+4基础设施+5控制器+6DTO+1gitkeep)
- 移除不再需要的依赖: @nestjs/schedule, minio, prom-client, kafkajs
- 精简 user.module.ts,仅保留用户核心功能(Profile/KYC/Wallet/Message/Admin)

基础设施更新:
- Kong: 遥测路由 → telemetry-service:3011, 版本路由 → admin-service:3012
- docker-compose: 新增2个服务容器 + MinIO app-releases bucket
- 07开发指南: 更新为独立服务架构描述

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 18:30:39 -08:00
hailin 0bf1df0f7a feat: 补全遥测/版本管理完整功能 + 清除全部开发指南中的MVP字样
## 功能补全 (12个新文件 + 6个修改)

DTO验证类 (6):
- batch-events.dto.ts — 批量事件上报验证(ArrayMaxSize 500, ValidateNested)
- heartbeat.dto.ts — 心跳上报验证(installId, appVersion)
- query-dau.dto.ts — DAU查询+事件查询验证(IsDateString, 分页)
- check-update.dto.ts — 检查更新验证(platform IsIn, version_code IsInt)
- create-version.dto.ts — 创建/更新版本验证(CreateVersionDto + UpdateVersionDto)
- upload-version.dto.ts — 上传版本验证(multipart/form-data字段)

基础设施 (3):
- package-parser.service.ts — APK解析(adbkit-apkreader) + IPA解析(unzipper+bplist-parser)
- telemetry-producer.service.ts — Kafka事件发布(telemetry.session.started + telemetry.heartbeat)
- telemetry-metrics.service.ts — Prometheus 5指标(online_users/dau/heartbeat_total/events_total/batch_duration)

控制器 (1):
- metrics.controller.ts — GET /metrics 端点(Prometheus格式)

功能增强:
- admin-version.controller.ts — 新增POST /parse解析预览端点 + upload自动解析填充元数据
- app-version.controller.ts — 新增GET /download/:id下载端点(302重定向MinIO)
- telemetry.service.ts — 集成Prometheus计数器+直方图 + Kafka事件发布
- telemetry-scheduler.service.ts — 快照/DAU时更新Prometheus指标
- user.module.ts — 注册MetricsController + TelemetryMetricsService + TelemetryProducerService + PackageParserService
- package.json — 新增prom-client依赖

## 开发指南MVP清除 (4个文件)

- 00-UI设计需求.md — "MVP阶段" → "当前阶段"
- 05-后端开发指南.md — "Phase 1 (MVP)" → "Phase 1 (基础平台)"
- 06-区块链开发指南.md — 清除所有MVP引用(合约注释/代币用途/Gas模型/预留接口)
- 07-遥测与版本管理开发指南.md — 清除MVP理由, 删除"可选"标记

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 18:09:10 -08:00
hailin 5a66b3071f feat: 新增用户遥测(Telemetry)与移动端OTA版本管理功能
## 遥测系统 (Telemetry)
- 心跳检测: 客户端60s上报心跳,Redis Sorted Set实时计算在线用户数(180s窗口)
- 事件采集: 批量上报客户端事件(会话/页面/操作),写入PostgreSQL telemetry_events表
- DAU统计: 基于app_session_start事件按userId/installId去重
  - 实时近似: Redis HyperLogLog (PFADD/PFCOUNT)
  - 精确计算: 每天凌晨1:00从事件表聚合,支持平台/地区维度
- 在线快照: 每分钟记录在线用户数快照,支持1m/5m/1h区间聚合查询
- 定时任务: @nestjs/schedule驱动 (每分钟快照/每小时清理/凌晨DAU/滚动DAU)

## 版本管理 (App Version / OTA Update)
- 版本CRUD: 管理员创建/编辑/删除/启禁用版本记录
- 文件上传: APK/IPA上传至MinIO(app-releases bucket),自动计算SHA256
- 强制更新: isForceUpdate标志,客户端据此决定是否阻断使用
- 检查更新API: GET /app/version/check?platform=android&current_version_code=200
- 预签名下载: MinIO presigned URL (24h有效)

## 新增文件清单 (18个新文件 + 3个修改)

数据库迁移 (4):
- 032_create_telemetry_events.sql — 事件日志表(append-only, BIGSERIAL)
- 033_create_daily_active_stats.sql — DAU日统计表(day PK, JSONB平台/地区)
- 034_create_online_snapshots.sql — 在线快照表(每分钟记录)
- 035_create_app_versions.sql — 应用版本表(platform CHECK, 唯一索引)

TypeORM实体 (4):
- telemetry-event.entity.ts — 遥测事件(userId, installId, eventName, properties)
- online-snapshot.entity.ts — 在线快照(ts, onlineCount, windowSeconds)
- daily-active-stats.entity.ts — DAU统计(day PK, dauByPlatform/Region JSONB)
- app-version.entity.ts — 应用版本(Platform enum, @VersionColumn乐观锁)

Redis基础设施 (1):
- presence-redis.service.ts — ZADD心跳 + ZCOUNT在线 + PFADD/PFCOUNT DAU

业务服务 (4):
- telemetry.service.ts — 批量事件入库 + 心跳记录 + 在线/DAU查询
- telemetry-scheduler.service.ts — 4个Cron定时任务
- app-version.service.ts — checkUpdate + CRUD + toggle + 重复检测
- file-storage.service.ts — MinIO上传(SHA256) + presigned下载URL

HTTP控制器 (4):
- telemetry.controller.ts — POST events(无需认证) + POST heartbeat + GET online
- admin-telemetry.controller.ts — GET /admin/telemetry/dau|events|realtime
- app-version.controller.ts — GET /app/version/check (移动端)
- admin-version.controller.ts — 完整CRUD + multipart上传 + toggle启禁用

修改文件 (3):
- user.module.ts — 注册4实体+4控制器+5服务+ScheduleModule
- package.json — 新增@nestjs/schedule, minio, @types/multer
- kong.yml — 新增4条Kong路由(telemetry, admin/telemetry, app/version, admin/versions)

文档 (1):
- docs/guides/07-遥测与版本管理开发指南.md — 完整开发指导(参考rwadurian适配)

注: admin遥测路径为/admin/telemetry,避免与issuer-service的/admin/analytics冲突

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 17:53:50 -08:00
hailin e450bef7cd feat: Complete all 4 frontend UI prototypes covering guides 00-04
Add 116 UI prototype files across 4 frontend applications, achieving
~95% coverage of all functional requirements from development guides.

## mobile/ (Flutter Consumer + Merchant App) — 48 files
- Auth: welcome, login, register, forgot-password
- Coupons: home, market, search, detail, my-coupons, my-coupon-detail,
  order-confirm, payment, payment-success, redeem-qr
- Trading: trading, sell-order (AI pricing), transfer
- Wallet: wallet, deposit, withdraw, transaction-records
- Profile: profile, kyc (L0-L3), settings, payment-management, pro-mode
  (WalletConnect, chain address, tx hash, track selection)
- AI Agent: agent-chat, ai-fab (floating button with unread count)
- Merchant: merchant-home (scanner, confirm, success, history, dashboard),
  merchant-ai-assistant (redeem assist, traffic prediction, anomaly alerts)
- Message: message-list, message-detail
- Issuer: issuer-main-page
- Shared widgets: coupon-card, price-tag, credit-badge, kyc-badge,
  status-tag, empty-state, skeleton-loader, confirm-sheet, genex-button,
  ai-confirm-dialog (3-level risk confirmation)
- Theme: app-colors, app-typography, app-spacing, app-theme
- i18n: zh-CN, en-US, ja-JP

## admin-app/ (Flutter Issuer Console) — 27 files
- Auth: issuer-login
- Onboarding: 5-step enterprise onboarding with AI compliance check
- Dashboard: issuer-dashboard (stats, AI insight, credit/quota),
  user-portrait (age/geo/preference/repurchase/AI insight)
- Coupon management: list, create (template-based, AI pricing),
  detail (recall/delist), batch-operations (issue/recall/price-adjust)
- Redemption: scan-to-redeem with offline mode
- Finance: overview, reconciliation (auto-reconcile, export PDF/Excel),
  financing-analysis (cost-benefit, liquidity, risk indicators, AI strategy)
- Credit: credit-scoring (4-factor, tier progress, AI suggestions),
  quota-management (usage gauge, type breakdown, tier upgrade, increase requests)
- AI Agent: full conversation UI with quick actions
- Settings: account, notification, support, tier display
- Store management: hierarchy (HQ/regional/store), employee roles
- Shared: ai-suggestion-card
- Theme: app-colors, app-theme, app-typography, app-spacing
- i18n: zh-CN, en-US, ja-JP

## admin-web/ (React + Next.js Platform Admin) — 26 files
- Layout: AdminLayout with collapsible sidebar, 10 nav sections
- Dashboard: key metrics, transaction feed, system health
- Users: user management with KYC filtering, risk tags
- Issuers: issuer review with AI pre-screening, credit rating display
- Trading: real-time monitor, order book, abnormal detection
- Risk: risk dashboard, AI warnings, suspicious transactions, OFAC logs
- Compliance: SAR/CTR management, audit logs, AI report generation
- SEC Filing: S-1/10-K/10-Q/8-K tracker, filing timeline, auto-disclosure
- License management: FinCEN MSB, BitLicense, MTL (48 states), renewal alerts
- SOX compliance: ICFR/ITGC/access/change-mgmt controls, deficiency tracking
- Tax compliance: Federal + 4 states, 8 IRS forms, tax calendar
- IPO readiness: 28-item checklist (legal/financial/SOX/governance/insurance),
  blocker tracking, milestone timeline, category progress, key contacts
- Finance: fee revenue, settlement queue, breakage tracking
- Disputes: case management with SLA countdown, chain evidence
- Analytics: user (DAU/MAU, cohort retention, geographic), coupon (category,
  breakage, secondary market), market-maker (TVL, spread, health, risk alerts),
  consumer-protection (complaints, CSAT, fund utilization, non-compliant issuers)
- Insurance: consumer protection fund, claims, IPO checklist overview
- Chain monitor: smart contract status, blockchain metrics
- Reports: platform-wide report center
- AI Agent panel: session stats, top questions, module accuracy
- Merchant redemption: stats, store ranking, real-time feed
- Design tokens: CSS custom properties (colors, typography, spacing, shadows)
- i18n: zh-CN, en-US, ja-JP

## miniapp/ (Taro Mini Program + H5) — 15 files
- Pages: home, detail, purchase, orders, my-coupons, login, redeem, profile
- H5 pages: h5-share, h5-activity (countdown, featured coupons),
  h5-register (benefits, phone/SMS form, WeChat login)
- Components: coupon-card, ai-guide (recommendation bar + purchase bubble),
  share-card (brand header, QR code, coupon info)
- i18n: zh-CN, en-US, ja-JP

## Design System
- Primary: #6C5CE7 (innovation purple), Material 3 style
- Consistent design tokens across all platforms
- Zero blockchain terminology — "我的券" not "NFT", "订单号" not "TX Hash"
- Utility Track MVP only; Securities Track reserved as "coming soon"

## Not included (by design)
- Data/Domain layers (API, state management, business logic) — UI prototypes only
- Securities Track full UI — MVP focuses on Utility Track
- P2 "求购" (want-to-buy) feature — marked as optional

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-11 01:16:44 -08:00
hailin 03e5f5b3e3 v2.0: Supplement all guides to achieve 100% SRS coverage
Comprehensive additions across all 7 guide files (+2,439 lines):

- 05-Backend: fee calculation (Maker-Taker), Breakage processing,
  refund mechanism, market maker system, three-factor pricing engine,
  AI/ML models (LightGBM/LSTM/IsolationForest), AML detection rules,
  OFAC sync service, Travel Rule (TRISA), tax compliance (1099/FATCA),
  CCPA/GDPR data deletion, security incident response (P0-P3),
  disaster recovery (RPO/RTO), mapping table security (MPC+audit+anchor),
  multi-currency, fiat hot-standby, chain reconciliation, capacity
  planning, SDK development plan, dispute handling, customer service

- 06-Blockchain: GNX token economics, non-transferable coupon revert,
  differentiated KYC checks, validator-level OFAC/structuring/TravelRule
  interception, batch transfer, Treasury guarantee fund locking,
  contract upgrade rollback, multi-stablecoin (USDC+USDT), Oracle
  integration, asset securitization contract reserve

- 01-Flutter Mobile: Pro mode (seed phrase, social recovery, AA wallet),
  MetaMask integration, external wallet extraction, transfer history,
  balance/deposit/withdraw, order history, phone number change,
  offline redemption limits/conflicts, dispute/complaint, notifications

- 02-Flutter Admin: guarantee fund/frozen sales, reconciliation reports,
  secondary market analysis, financing effect analysis, refund window
  config, batch operations, coupon recall, multi-store hierarchy,
  dedicated customer service channel

- 03-Web Admin: user behavior analytics, coupon category analysis,
  1099 tax reports, FATCA, false advertising monitoring, SOX audit
  module, fee/revenue dashboard, settlement management, dispute
  arbitration, web merchant redemption console, market maker monitoring

- 00-UI Design: Utility/Securities Track UI isolation design

- 04-Mini Program: multi-language i18n (zh-CN/en-US/ja-JP),
  multi-currency display

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-10 17:39:05 -08:00
hailin a0d2271cd5 Add comprehensive development guides for all platform components
- 00-UI设计需求 v1.1: AI Agent deep integration specs
- 01-Flutter移动端: Consumer + Merchant App (Riverpod + Clean Architecture)
- 02-Flutter管理后台: Issuer Console App (credit scoring, template-based issuance)
- 03-Web管理前端: Admin Dashboard (React + Next.js + Zustand + RTK)
- 04-小程序H5: Mini-program + H5 (Taro 3.x cross-platform)
- 05-后端: Backend services (NestJS + Go + DDD + Kong + PostgreSQL)
- 06-区块链: Genex Chain + 7-contract system (Cosmos SDK + cosmos/evm + Solidity)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 23:23:26 -08:00