# Story 010.001: system-config-mt-module

## Status
Ready for Review

## 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
- [x] 创建系统配置多租户模块目录结构 (AC: 1)
  - [x] 创建 `packages/core-module-mt/system-config-module-mt/` 目录
  - [x] 遵循现有模块结构模式
- [x] 实现系统配置实体 (AC: 2)
  - [x] 创建 `src/entities/system-config.entity.mt.ts` [参考: packages/core-module-mt/file-module-mt/src/entities/file.entity.ts]
  - [x] 定义租户ID、配置键、配置值、描述等字段 [参考: packages/core-module-mt/file-module-mt/src/entities/file.entity.ts:14-82]
  - [x] 添加TypeORM装饰器 [参考: packages/core-module-mt/file-module-mt/src/entities/file.entity.ts:6-82]
- [x] 创建Schema定义 (AC: 3)
  - [x] 创建 `src/schemas/system-config.schema.mt.ts` [参考: packages/core-module-mt/file-module-mt/src/schemas/file.schema.mt.ts]
  - [x] 定义创建、更新、获取、列表Schema [参考: packages/core-module-mt/file-module-mt/src/schemas/file.schema.mt.ts:85-177]
  - [x] 使用Zod OpenAPI扩展 [参考: packages/core-module-mt/file-module-mt/src/schemas/file.schema.mt.ts:1-177]
- [x] 实现系统配置服务 (AC: 4)
  - [x] 创建 `src/services/system-config.service.mt.ts` [参考: packages/core-module-mt/file-module-mt/src/services/file.service.mt.ts]
  - [x] 继承GenericCrudService抽象类 [参考: packages/core-module-mt/file-module-mt/src/services/file.service.mt.ts:8-14]
  - [x] 配置租户隔离选项 [参考: packages/shared-crud/src/services/generic-crud.service.ts:553-566]
  - [x] 配置用户跟踪选项 [参考: packages/shared-crud/src/services/generic-crud.service.ts:507-511]
- [x] 生成CRUD路由 (AC: 5)
  - [x] 创建 `src/routes/system-config.routes.mt.ts` [参考: packages/core-module-mt/file-module-mt/src/routes/index.mt.ts]
  - [x] 使用createCrudRoutes生成完整路由 [参考: packages/core-module-mt/file-module-mt/src/routes/index.mt.ts:15-29]
  - [x] 配置租户选项 [参考: packages/core-module-mt/file-module-mt/src/routes/index.mt.ts:24-28]
- [x] 创建模块导出 (AC: 1)
  - [x] 创建 `src/index.mt.ts` 导出实体、服务、路由
  - [x] 配置模块入口
  - [x] 注意：package.json使用核心包统一配置，不需要单独创建

- [x] 实现系统配置测试 (AC: 6)
  - [x] 创建系统配置路由集成测试 [参考: packages/core-module-mt/file-module-mt/tests/integration/file.routes.integration.test.ts]
    - [x] 创建 `tests/integration/system-config.routes.integration.test.ts` [参考: packages/core-module-mt/file-module-mt/tests/integration/file.routes.integration.test.ts]
    - [x] 实现CRUD操作测试 [参考: packages/core-module-mt/file-module-mt/tests/integration/file.routes.integration.test.ts:79-264]
    - [x] 实现多租户隔离测试 [参考: packages/core-module-mt/file-module-mt/tests/integration/file.routes.integration.test.ts:587-875]
    - [x] 实现认证授权测试 [参考: packages/core-module-mt/file-module-mt/tests/integration/file.routes.integration.test.ts:535-585]
    - [x] 实现数据验证测试 [参考: packages/core-module-mt/file-module-mt/tests/integration/file.routes.integration.test.ts:171-189]
- [x] 验证现有功能 (AC: 6)
  - [x] 运行现有测试确保无回归
  - [x] 验证共享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]
```typescript
@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]
```typescript
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]
```typescript
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
- Claude Code (d8d-model)

### Debug Log References
- TypeScript类型检查通过：`pnpm typecheck`
- 系统配置模块测试通过：`pnpm test tests/integration/system-config.routes.integration.test.ts`
- 现有项目测试运行验证无回归

### Implementation Process
1. **初始实施阶段**：按照故事需求创建完整的系统配置模块
   - 创建目录结构：`packages/core-module-mt/system-config-module-mt/`
   - 实现SystemConfigMt实体，包含租户ID、配置键、配置值、描述等字段
   - 创建完整的Zod Schema定义，支持OpenAPI文档生成
   - 实现SystemConfigServiceMt服务，继承GenericCrudService
   - 使用createCrudRoutes生成完整的CRUD路由
   - 创建模块导出文件

2. **用户反馈修正**：
   - 修正package.json说明：系统配置模块使用核心包统一配置，不需要单独创建
   - 添加系统配置模块路径到tsconfig.json：`packages/core-module-mt/tsconfig.json`

3. **测试修复阶段**：
   - 修复TypeScript类型错误：服务中的null类型问题
   - 修复测试导入问题：使用正确的数据库初始化方法
   - 修复路由调用问题：参考文件模块测试模式，使用正确的路由调用方式
   - 创建测试工具：`tests/utils/integration-test-db.ts`
   - 更新vitest配置：包含系统配置模块测试路径

4. **最终验证**：
   - TypeScript类型检查完全通过
   - 系统配置模块集成测试全部通过（8个测试）
   - 多租户隔离功能验证正常
   - 数据验证功能正常工作

5. **测试用例中文化**：
   - 将测试文件中的用例名称从英文改为中文
   - 验证中文化后的测试仍然正常工作

### Completion Notes List
1. ✅ 成功创建系统配置多租户模块目录结构
2. ✅ 实现SystemConfigMt实体，包含租户ID、配置键、配置值、描述等字段
3. ✅ 创建完整的Zod Schema定义，支持OpenAPI文档生成
4. ✅ 实现SystemConfigServiceMt服务，继承GenericCrudService，配置租户隔离和用户跟踪
5. ✅ 使用createCrudRoutes生成完整的CRUD路由，支持多租户隔离
6. ✅ 创建模块导出文件，统一导出实体、Schema、服务和路由
7. ✅ 实现完整的集成测试，覆盖CRUD操作、多租户隔离、数据验证等场景
8. ✅ 验证现有功能无回归，共享CRUD包集成正常
9. ✅ 修正package.json配置说明和tsconfig.json路径配置
10. ✅ 修复测试文件中的数据库钩子、认证中间件和路由调用问题
11. ✅ 完成测试用例名称中文化，所有测试正常运行

### File List
- `packages/core-module-mt/system-config-module-mt/src/entities/system-config.entity.mt.ts` - 系统配置实体
- `packages/core-module-mt/system-config-module-mt/src/schemas/system-config.schema.mt.ts` - Zod Schema定义
- `packages/core-module-mt/system-config-module-mt/src/services/system-config.service.mt.ts` - 系统配置服务
- `packages/core-module-mt/system-config-module-mt/src/routes/system-config.routes.mt.ts` - CRUD路由
- `packages/core-module-mt/system-config-module-mt/src/index.mt.ts` - 模块导出
- `packages/core-module-mt/system-config-module-mt/tests/integration/system-config.routes.integration.test.ts` - 集成测试
- `packages/core-module-mt/system-config-module-mt/tests/utils/integration-test-db.ts` - 测试工具
- `packages/core-module-mt/tsconfig.json` - 更新包含系统配置模块路径
- `packages/core-module-mt/vitest.config.ts` - 更新包含系统配置模块测试路径

## QA Results