mini-starter/docs/stories/010.001.system-config-mt-module.story.md

Story 010.001: system-config-mt-module

Status

Draft

Story

As a 系统管理员， I want 在多租户核心包中创建系统配置模块，实现系统配置实体、Schema定义，并复用共享CRUD包自动获得完整CRUD功能， so that 可以为小程序登录、支付等场景提供租户隔离的系统配置管理

Acceptance Criteria

1. 在多租户核心包中创建系统配置模块 (packages/core-module-mt/system-config-module-mt/)
2. 实现系统配置实体，包含租户ID、配置键、配置值、描述等字段
3. 创建对应的Zod Schema定义用于验证
4. 继承GenericCrudService抽象类，自动获得多租户隔离、用户跟踪、完整CRUD API
5. 使用createCrudRoutes生成完整的CRUD路由
6. 验证现有功能保持完整，无回归

Tasks / Subtasks

• 创建系统配置多租户模块目录结构 (AC: 1)
  • 创建 packages/core-module-mt/system-config-module-mt/ 目录
  • 遵循现有模块结构模式
• 实现系统配置实体 (AC: 2)
  • 创建 src/entities/system-config.entity.mt.ts
  • 定义租户ID、配置键、配置值、描述等字段
  • 添加TypeORM装饰器
• 创建Schema定义 (AC: 3)
  • 创建 src/schemas/system-config.schema.mt.ts
  • 定义创建、更新、获取、列表Schema
  • 使用Zod OpenAPI扩展
• 实现系统配置服务 (AC: 4)
  • 创建 src/services/system-config.service.mt.ts
  • 继承GenericCrudService抽象类
  • 配置租户隔离选项
  • 配置用户跟踪选项
• 生成CRUD路由 (AC: 5)
  • 创建 src/routes/system-config.routes.mt.ts
  • 使用createCrudRoutes生成完整路由
  • 配置租户选项
• 创建模块导出 (AC: 1)
  • 创建 src/index.mt.ts 导出实体、服务、路由
  • 配置模块入口
• 验证现有功能 (AC: 6)
  • 运行现有测试确保无回归
  • 验证共享CRUD包集成正常

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

• 运行时: Node.js 20.18.3
• 框架: Hono 4.8.5 (Web框架和API路由)
• 数据库: PostgreSQL 17 (通过TypeORM)
• ORM: TypeORM 0.3.25 (实体管理)
• 验证: Zod + @hono/zod-openapi

项目结构信息 [Source: architecture/source-tree.md]

• 包位置: packages/core-module-mt/system-config-module-mt/
• 包架构层次: 多租户核心包中的业务模块
• 文件组织:
  • src/entities/ - 实体定义 (使用 .mt.ts 后缀)
  • src/schemas/ - Zod Schema定义 (使用 .mt.ts 后缀)
  • src/services/ - 服务实现 (使用 .mt.ts 后缀)
  • src/routes/ - API路由 (使用 .mt.ts 后缀)
  • tests/ - 测试文件
• 现有模块参考:
  • auth-module-mt/ - 认证模块
  • user-module-mt/ - 用户模块
  • file-module-mt/ - 文件模块

共享CRUD集成模式 [Source: packages/shared-crud/src/services/generic-crud.service.ts]

• 继承模式: 继承 GenericCrudService<T> 抽象类
• 租户配置: 通过 tenantOptions 配置租户隔离
• 用户跟踪: 通过 userTracking 配置用户跟踪
• 核心方法: getList(), getById(), create(), update(), delete()

路由生成模式 [Source: packages/shared-crud/src/routes/generic-crud.routes.ts]

• 路由生成: 使用 createCrudRoutes() 函数
• 自动生成: 完整的CRUD路由 (GET, POST, PUT, DELETE)
• 验证集成: 自动集成Zod Schema验证
• 租户上下文: 自动处理租户ID提取和设置

实体设计模式 [Source: docs/epic-010-system-config-multi-tenant.md]

@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;
}

服务集成模式 [Source: docs/epic-010-system-config-multi-tenant.md]

export class SystemConfigService extends GenericCrudService<SystemConfig> {
  constructor(dataSource: DataSource) {
    super(dataSource, SystemConfig, {
      tenantOptions: {
        enabled: true,
        tenantIdField: 'tenantId',
        autoExtractFromContext: true
      },
      userTracking: {
        createdByField: 'createdBy',
        updatedByField: 'updatedBy'
      }
    });
  }
}

路由生成模式 [Source: docs/epic-010-system-config-multi-tenant.md]

const systemConfigRoutes = createCrudRoutes({
  entity: SystemConfig,
  createSchema: CreateSystemConfigSchema,
  updateSchema: UpdateSystemConfigSchema,
  getSchema: SystemConfigSchema,
  listSchema: SystemConfigSchema,
  tenantOptions: { enabled: true }
});

测试

测试标准 [Source: architecture/testing-strategy.md]

• 测试框架: Vitest + hono/testing
• 测试位置: packages/core-module-mt/system-config-module-mt/tests/
• 测试类型: 单元测试 + 集成测试
• 覆盖率目标: 单元测试 ≥ 80%，集成测试 ≥ 60%

测试文件结构

• tests/unit/ - 单元测试
  • system-config.service.test.ts - 服务单元测试
  • system-config.entity.test.ts - 实体单元测试
• tests/integration/ - 集成测试
  • system-config.routes.integration.test.ts - 路由集成测试

现有模块参考模式

• 认证模块: packages/core-module-mt/auth-module-mt/
• 用户模块: packages/core-module-mt/user-module-mt/
• 文件模块: packages/core-module-mt/file-module-mt/
• 命名约定: 所有文件使用 .mt.ts 后缀，遵循多租户包命名规范

测试要求

• 验证租户隔离功能
• 验证用户跟踪功能
• 验证完整的CRUD操作
• 验证Schema验证

Change Log

Date	Version	Description	Author
2025-11-19	1.0	初始故事创建	Bob (Scrum Master)
2025-11-19	1.1	调整模块位置到core-module-mt包内	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results