Epic 010 - 系统配置多租户模块 - Brownfield Enhancement

Epic Goal

在多租户核心包中创建系统配置多租户模块，为小程序登录、支付等场景提供租户隔离的系统配置管理，支持在管理后台进行配置，并通过Redis缓存提高访问性能。

Epic Description

Existing System Context

Current relevant functionality:

共享CRUD包已提供完整的多租户支持，包括租户隔离、用户跟踪、数据权限
文件模块已实现完整的CRUD路由、实体和Schema模式
认证模块已实现小程序登录和手机号解密功能
支付模块已实现微信小程序支付功能
多租户认证模块已实现租户隔离的用户管理
Redis缓存已用于session_key存储

Technology stack:

TypeORM + PostgreSQL (数据库)
Hono + Zod OpenAPI (API框架)
Redis (缓存)
微信小程序SDK (认证和支付)
@d8d/shared-crud (共享CRUD工具包)

Integration points:

共享CRUD包的GenericCrudService和createCrudRoutes
认证模块的MiniAuthService (小程序登录)
支付模块的PaymentService (小程序支付)
Redis缓存工具 (配置缓存)

Enhancement Details

What's being added/changed:

创建系统配置多租户模块包，包含实体、Schema定义
复用共享CRUD包自动获得多租户隔离、用户跟踪、完整CRUD API
添加Redis缓存支持，提高配置访问性能
创建系统配置UI包，集成到web admin管理后台
修改认证和支付模块，使用系统配置获取租户相关参数

How it integrates:

直接复用共享CRUD包的GenericCrudService和createCrudRoutes
使用Redis缓存系统配置，减少数据库访问
在认证和支付服务中通过租户ID获取配置
在管理后台提供系统配置管理界面

Success criteria:

系统配置模块支持多租户隔离
配置访问通过Redis缓存优化
认证和支付模块正确使用系统配置
管理后台可以配置租户系统参数

Stories

✅ Story 1: 创建系统配置多租户模块包 - 实现系统配置实体、Schema定义，复用共享CRUD包自动获得完整CRUD功能
- 状态: 已完成 (提交哈希: 3217962)
- 详情: 已实现完整的系统配置多租户模块，包含实体、Schema、服务、路由和集成测试
- 验证: 8个集成测试全部通过，多租户隔离功能正常
✅ Story 2: 实现系统配置Redis缓存 - 添加Redis缓存支持，优化配置访问性能
- 状态: 已完成 (提交哈希: 1385392)
- 详情: 已实现完整的Redis缓存功能，包括单键查询、批量查询、缓存失效、缓存穿透保护、多租户缓存隔离和缓存预热
- 验证: 8个Redis缓存集成测试全部通过，16个系统配置模块测试全部通过，无回归
- 实施经验:
  - 修复了多租户隔离概念，移除了错误的"全局配置"概念，强制要求tenantId参数
  - 修复了TypeORM In操作符使用问题，确保批量查询正确工作
  - 实现了完整的缓存穿透保护机制，使用5分钟TTL的空值缓存
  - 验证了多租户缓存隔离，确保不同租户的配置完全隔离
✅ Story 3: 集成系统配置到认证和支付模块 - 修改小程序登录和支付功能使用系统配置
- 状态: 已完成 (提交哈希: 02b448f)
- 详情: 已成功集成系统配置模块到认证和支付模块，支持租户特定的微信小程序登录和支付配置
- 验证: 认证和支付模块正确使用系统配置，支持租户隔离，保持环境变量回退兼容性
- 实施经验:
  - 修复了包导出配置问题，确保system-config-module-mt正确导出
  - 实现了配置键常量定义，支持认证和支付模块的配置需求
  - 保持了向后兼容性，支持环境变量回退机制
  - 验证了多租户配置隔离，确保不同租户使用独立配置
Story 4: 创建系统配置UI包并集成到管理后台 - 开发系统配置管理界面

Compatibility Requirements

现有API保持不变
数据库schema变化向后兼容
UI变化遵循现有模式
性能影响最小化

Risk Mitigation

Primary Risk: 系统配置模块可能影响现有认证和支付功能的稳定性

Mitigation: 分阶段实施，先创建独立模块，再逐步集成到现有功能

Rollback Plan: 如果出现问题，可以回退到使用环境变量的方式，系统配置模块作为可选功能

Definition of Done

所有故事完成且验收标准满足
现有功能通过测试验证
集成点正常工作
文档适当更新
现有功能无回归

Technical Implementation Details

系统配置实体设计

@Entity('system_config')
export class SystemConfig {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column()
  tenantId!: number;  // 自动通过共享CRUD的tenantOptions设置

  @Column()
  configKey!: string;

  @Column('text')
  configValue!: string;

  @Column()
  description?: string;

  // 自动通过共享CRUD的userTracking设置
  @Column()
  createdBy?: number;

  @Column()
  updatedBy?: number;

  @Column()
  createdAt!: Date;

  @Column()
  updatedAt!: Date;
}

共享CRUD集成（核心简化）

// 服务实现 - 继承GenericCrudService（参考文件模块模式）
export class SystemConfigService extends GenericCrudService<SystemConfig> {
  constructor(dataSource: DataSource) {
    super(dataSource, SystemConfig, {
      tenantOptions: {
        enabled: true,
        tenantIdField: 'tenantId',
        autoExtractFromContext: true
      },
      userTracking: {
        createdByField: 'createdBy',
        updatedByField: 'updatedBy'
      }
    });
  }

  // 可添加自定义方法，如Redis缓存相关方法
  async getConfigByKey(tenantId: number, key: string): Promise<string | null> {
    // Redis缓存逻辑
  }
}

// 路由生成 - 一行代码获得完整CRUD API
const systemConfigRoutes = createCrudRoutes({
  entity: SystemConfig,
  createSchema: CreateSystemConfigSchema,
  updateSchema: UpdateSystemConfigSchema,
  getSchema: SystemConfigSchema,
  listSchema: SystemConfigSchema,
  tenantOptions: { enabled: true }
});

Redis缓存策略

缓存键格式: system_config:{tenantId}:{configKey}
默认TTL: 1小时
配置更新时自动清除缓存

集成点修改

MiniAuthService: 从系统配置获取微信小程序AppID和Secret
PaymentService: 从系统配置获取微信支付商户配置
PhoneDecrypt: 使用租户特定的配置参数

管理后台界面

基于现有UI模式创建系统配置管理页面
支持按租户筛选和配置管理
提供配置项的增删改查功能

Validation Checklist

Scope Validation

Epic可以在4个故事内完成
不需要架构文档
增强遵循现有模式
集成复杂度可控

Risk Assessment

对现有系统风险较低
回滚计划可行
测试方法覆盖现有功能
团队对集成点有足够了解

Completeness Check

Epic目标清晰可实现
故事范围适当
成功标准可衡量
依赖项已识别

Story Manager Handoff:

"请为这个棕地史诗开发详细的用户故事。关键考虑因素：

这是对运行TypeORM + PostgreSQL + Hono + Redis + @d8d/shared-crud的现有系统的增强
核心简化: 继承GenericCrudService抽象类，自动获得多租户隔离、用户跟踪、完整CRUD API
集成点：共享CRUD包的GenericCrudService和createCrudRoutes、认证模块的MiniAuthService、支付模块的PaymentService、Redis缓存
要遵循的现有模式：共享CRUD包的通用模式、文件模块的CRUD模式、多租户实体模式
关键兼容性要求：现有API保持不变，数据库schema向后兼容
每个故事必须包括验证现有功能保持完整的验证

该史诗应在保持系统完整性的同时交付多租户系统配置管理功能。"

epic-010-system-config-multi-tenant.md 7.9 KB Histórico Raw