danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
bc2d58753b8fe0b4f7150657bf40cfe756ce48de
kami_backend/openspec/project.md
danial bc2d58753b feat(jd_cookie):重构订单创建逻辑并优化相关模型 
- 新增 CreateOrderReq 结构体用于统一订单创建参数- 修改 CreateOrder 方法签名，使用结构体传参替代多个参数
- 更新 jd_cookie 相关枚举值，增加 JdCookieStatusUnknown 状态
- 调整 OrderInfo 和 JdOrderInfo 模型字段，增强数据一致性
-优化订单与京东订单关联逻辑，移除冗余的 CurrentOrderId 字段
- 移除 ShouldExtractCard 方法，改为内部私有方法 shouldExtractCard- 精简 Callback 方法参数，移除不必要的 userOrderId 和 amount 参数
- 修复订单历史记录中订单号关联问题，直接使用 orderId 字段查询
- 更新控制器层参数传递方式，适配新的服务层接口定义
- 调整卡密提取逻辑，去除对用户订单实体的依赖
- 完善订单状态检查机制，提高卡密提取安全性
- 优化数据库查询逻辑，减少不必要的关联查询操作
2025-10-18 14:13:40 +08:00

3.9 KiB
Raw Blame History

Project Context

Purpose

A comprehensive card redemption platform (卡密兑换平台) that manages various types of gift cards and payment processing, including Apple, T-Mall, JD, Walmart, and C-Trip cards. The platform handles order processing, merchant management, user authentication, and integration with multiple external payment providers.

Tech Stack

  • Framework: GoFrame v2 with heavy code generation usage
  • Language: Go 1.21+
  • Database: MySQL with dual database setup (kami_v2 primary, kami legacy)
  • Cache: Redis for caching, sessions, rate limiting
  • Authentication: JWT with TOTP support, multi-login capability
  • Authorization: Casbin RBAC
  • Tracing: OpenTelemetry with custom headers (x-service-token)
  • Task Scheduling: Cron jobs with graceful shutdown
  • Container: Docker with Kubernetes deployment
  • API: RESTful APIs with OpenTelemetry instrumentation

Project Conventions

Code Style

  • Go standard formatting (gofmt)
  • Verb-led naming for change IDs (add-, update-, remove-, refactor-)
  • Kebab-case for file and directory names
  • Domain separation with clear business boundaries

Architecture Patterns

  • DAO/DO/Entity pattern: GoFrame ORM with generated data access layers
  • API-First: Controllers generated from api/ definitions
  • Domain-Driven Design: Each business domain has its own logic folder
  • Dual Database: Separate connections for primary and legacy data
  • Graceful Shutdown: Implemented for cron jobs and connection pools
  • Code Generation Workflow: Database changes → make dao → make service → make ctrl

Testing Strategy

  • Focused test coverage in critical business logic areas
  • Unit tests for domain logic in internal/logic/*/
  • Integration tests for external platform integrations
  • Test command: go test ./... with verbose mode for specific packages
  • Critical areas: Apple account management, T-Mall order processing, rate limiting

Git Workflow

  • Main branch: develop (primary development branch)
  • Feature branches: Created from develop for new features
  • Commit format: Conventional commits with type(scope): description
  • Code generation: Automated through Makefile targets
  • Deployment: Docker-based with auto-generated git-based tags

Domain Context

Business Domains

  • Card Platform Management: Apple, T-Mall, JD, Walmart, C-Trip, and generic redemption cards
  • Order Processing: Complete lifecycle with callbacks, status tracking, summaries
  • Merchant Management: Configurations, deployments, hidden settings, steal rules
  • Channel & Road Management: Business routing with road pools and entrance management
  • User Management: Authentication, roles, authorization
  • Payment Processing: Payment methods, deductions, statistics
  • JDCookie Management: Cookie rotation, order processing, account management

Key Concepts

  • Steal Rules: Automated card acquisition logic
  • Road Pools: Business routing management
  • Cookie Rotation: JD account management strategy
  • Order Callbacks: Asynchronous payment status notifications
  • Rate Limiting: Redis-based access control

Important Constraints

  • Security: Built-in rate limiting, IP/device restrictions, authentication middleware
  • Performance: Optimized for high-volume card redemption operations
  • Scalability: Designed for multi-tenant architecture with merchant isolation
  • Compliance: Payment processing industry standards
  • Reliability: Graceful shutdown, error handling, monitoring integration

External Dependencies

  • T-Mall: OAuth gateway integration with eco.taobao.com
  • JD: JD API integration with cookie management
  • Walmart: Walmart API integration
  • C-Trip: Travel platform API integration
  • Agiso: App authentication service
  • Redis: Caching, sessions, rate limiting
  • MySQL: Primary and legacy data storage
  • OpenTelemetry: Distributed tracing and monitoring