# Story 010.004: system-config-ui-package

## Status
Ready for Review

## Story
**As a** 系统管理员，
**I want** 在管理后台中查看和管理租户的系统配置，
**so that** 可以为不同租户配置小程序登录和支付参数

## Acceptance Criteria
1. 创建系统配置UI包，提供系统配置管理界面
2. 在管理后台中集成系统配置管理页面
3. 支持按租户筛选和查看系统配置
4. 提供配置项的增删改查功能
5. 验证现有功能保持完整，无回归

## 任务 / 子任务

- [x] 任务 1 (AC: 1): 创建多租户系统配置界面包结构
  - [x] 创建包目录：`packages/system-config-management-ui-mt/`
  - [x] 复制广告管理包结构作为参考：`cp -r packages/advertisement-management-ui-mt/* packages/system-config-management-ui-mt/`
  - [x] **重要：复制后立即重命名文件为系统配置包名**
  - [x] 更新包名为 `@d8d/system-config-management-ui-mt`

- [x] 任务 2 (AC: 1, 3): 配置包依赖和构建
  - [x] 复制并修改 `packages/system-config-management-ui-mt/package.json`：
    - [x] 更新包名：`"name": "@d8d/system-config-management-ui-mt"`
    - [x] 更新依赖：`"@d8d/core-module-mt/system-config-module-mt": "workspace:*"`
    - [x] 删除广告管理相关依赖：`@d8d/advertisements-module-mt`、`@d8d/advertisement-type-management-ui-mt`
  - [x] 复制并修改 `packages/system-config-management-ui-mt/tsconfig.json`：
    - [x] 更新路径映射：`"@d8d/core-module-mt/system-config-module-mt/*"`
  - [x] 复制并修改 `packages/system-config-management-ui-mt/vitest.config.ts`：
    - [x] 更新测试环境配置
  - [x] 复制并修改 `packages/system-config-management-ui-mt/tests/setup.ts`：
    - [x] 更新测试设置的系统配置相关配置
  - [x] 复制并修改 `packages/system-config-management-ui-mt/eslint.config.js`：
    - [x] 更新ESLint配置
  - [x] 安装依赖：`cd packages/system-config-management-ui-mt && pnpm install`

- [x] 任务 3 (AC: 4, 5): 实现RPC客户端架构和类型定义
  - [x] 复制并修改 `packages/system-config-management-ui-mt/src/api/systemConfigClient.ts`：
    - [x] 更新导入路径：`import { systemConfigRoutesMt } from '@d8d/core-module-mt/system-config-module-mt'`
    - [x] 更新客户端实例：`systemConfigClient = systemConfigRoutesMt`
    - [x] 保持单例模式和延迟初始化逻辑 [参照: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts]
  - [x] 复制并修改 `packages/system-config-management-ui-mt/src/types/systemConfig.ts`：
    - [x] 从多租户系统配置模块包导入类型定义
    - [x] 确保类型定义与系统配置架构对齐
  - [x] 验证RPC客户端在主应用中的正确集成 [参考: web/src/client/api_init.ts]
  - [x] 实现类型安全的API调用模式 [参考: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx:100-112]

- [x] 任务 4 (AC: 1, 5): 复制并调整系统配置管理界面组件
  - [x] 复制并修改 `packages/system-config-management-ui-mt/src/components/SystemConfigManagement.tsx`：
    - [x] 更新导入路径：
      - [x] `import { systemConfigClientManager } from '../api/systemConfigClient'`
      - [x] `import { CreateSystemConfigDto, UpdateSystemConfigDto } from '@d8d/core-module-mt/system-config-module-mt/schemas'`
    - [x] **规范**：共享UI包组件导入必须使用具体组件路径，如 `@d8d/shared-ui-components/components/ui/button`，避免从根导入
    - [x] 使用系统配置客户端管理实例.get()来获取系统配置RPC客户端
    - [x] **骨架屏优化**：确保骨架屏只在表格数据区域显示，不影响搜索框、筛选器等其他UI元素
    - [x] 调整表单字段为系统配置相关字段：configKey, configValue, description等
  - [x] 复制并修改组件导出文件：
    - [x] `packages/system-config-management-ui-mt/src/components/index.ts`

- [x] 任务 5 (AC: 3, 4): 实现完整的系统配置管理功能
  - [x] 复制并修改 `packages/system-config-management-ui-mt/src/hooks/useSystemConfigs.ts`：
    - [x] 更新导入路径，使用多租户系统配置客户端
    - [x] 确保查询和突变操作使用正确的多租户API
  - [x] 复制并修改hooks导出文件：
    - [x] `packages/system-config-management-ui-mt/src/hooks/index.ts`
  - [x] 实现搜索和过滤功能，支持按configKey和description搜索
  - [x] 实现配置值的表单验证和错误处理
  - [x] 确保所有组件支持多租户上下文

- [x] 任务 6 (AC: 2): 集成系统配置UI包到管理后台
  - [x] 在管理后台路由中添加系统配置页面路由 [参照: web/src/client/admin/routes.tsx]
  - [x] 在管理后台菜单中添加系统配置菜单项 [参照: web/src/client/admin/menu.tsx]
  - [x] 配置系统配置页面的权限控制 [参照: web/src/client/admin/routes.tsx]
  - [x] 验证系统配置页面在管理后台中正确显示和功能正常

- [x] 任务 7 (AC: 5, 6): 创建测试套件
  - [x] 复制并修改 `packages/system-config-management-ui-mt/tests/integration/system-config-management.integration.test.tsx`：
    - [x] 更新导入路径，使用系统配置包
    - [x] 添加系统配置管理功能测试
  - [x] 复制并修改 `packages/system-config-management-ui-mt/tests/setup.ts`：
    - [x] 配置系统配置测试环境
  - [x] **系统配置测试重点**：
    - [x] 测试系统配置列表页面渲染
    - [x] 验证配置项的增删改查功能
    - [x] 测试租户筛选功能
    - [x] 确保API调用包含正确的租户标识

- [x] 任务 8 (AC: 1, 7): 配置包导出接口
  - [x] 复制并修改 `packages/system-config-management-ui-mt/src/index.ts`：
    - [x] 更新导出组件和hook的路径
    - [x] 确保所有导出组件、hook和类型定义正确
  - [x] 验证导出脚本正常工作

- [x] 任务 9 (AC: 6, 8): 验证功能无回归
  - [x] 运行包构建：`cd packages/system-config-management-ui-mt && pnpm build`
  - [x] 运行所有测试：`cd packages/system-config-management-ui-mt && pnpm test`
  - [x] 验证系统配置管理功能正常
  - [x] 验证与多租户系统兼容性
  - [x] 验证现有管理后台功能无回归

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md]
- **前端框架**: React 19.1.0 + TypeScript
- **路由**: React Router v7
- **状态管理**: @tanstack/react-query (服务端状态) + Context (本地状态)
- **UI组件库**: shadcn/ui (基于Radix UI)
- **构建工具**: Vite 7.0.0
- **样式**: Tailwind CSS 4.1.11
- **HTTP客户端**: 基于Hono Client的封装 + axios适配器

### 项目结构信息 [Source: architecture/source-tree.md]
- **管理后台位置**: `web/src/client/admin/`
- **页面组件位置**: `web/src/client/admin/pages/`
- **共享组件位置**: `web/src/client/components/ui/`
- **系统配置模块位置**: `packages/core-module-mt/system-config-module-mt/`
- **API客户端位置**: `web/src/client/api.ts`

### 现有管理后台结构 [Source: web/src/client/admin/pages/Users.tsx]
- **页面组件模式**: 使用React函数组件 + TypeScript
- **状态管理**: 使用React Query管理服务端状态，useState管理本地状态
- **表单处理**: 使用react-hook-form + zod验证
- **UI组件**: 使用shadcn/ui组件库
- **API调用**: 使用Hono RPC客户端，类型安全
- **分页模式**: 使用DataTablePagination组件
- **搜索过滤**: 支持关键词搜索和高级筛选

### 系统配置模块现有结构 [Source: packages/core-module-mt/system-config-module-mt/src/services/system-config.service.mt.ts]
- **SystemConfigServiceMt**: 继承GenericCrudService，支持多租户和Redis缓存
- **实体字段**: id, tenantId, configKey, configValue, description, createdBy, updatedBy, createdAt, updatedAt
- **API端点**: 完整的CRUD API，支持租户隔离
- **缓存策略**: Redis缓存，正常值1小时TTL，空值5分钟TTL

### API规范
- 使用RPC客户端架构进行API调用 [Source: architecture/tech-stack.md#前端技术栈]
- 租户上下文由后端认证包处理，前端使用标准RPC客户端 [Source: architecture/component-architecture.md#认证授权]
- 系统配置API端点：`/api/system-configs` [Source: packages/core-module-mt/system-config-module-mt/src/routes/system-config.routes.mt.ts]
- 系统配置路由导出：`systemConfigRoutesMt` [Source: packages/core-module-mt/system-config-module-mt/src/index.mt.ts]
- 使用单例模式和延迟初始化确保类型安全和性能 [参照: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts]

### 配置键定义 [Source: packages/core-module-mt/system-config-module-mt/src/constants/config-keys.constants.mt.ts]
- **认证配置键**:
  - `wx.mini.app.id` - 微信小程序AppID
  - `wx.mini.app.secret` - 微信小程序AppSecret
- **支付配置键**:
  - `wx.payment.merchant.id` - 微信支付商户ID
  - `wx.payment.v3.key` - 微信支付V3密钥
  - `wx.payment.cert.serial.no` - 商户证书序列号
  - `wx.payment.public.key` - 商户公钥
  - `wx.payment.private.key` - 商户私钥
  - `wx.payment.notify.url` - 支付回调URL

### 组件规范
- React 19.1.0 + TypeScript [Source: architecture/tech-stack.md#前端技术栈]
- TanStack Query v5用于状态管理 [Source: architecture/tech-stack.md#前端技术栈]
- React Hook Form v7用于表单处理 [Source: architecture/tech-stack.md#前端技术栈]
- 组件采用函数式组件和Hooks模式 [Source: architecture/component-architecture.md#组件设计原则]
- 使用shadcn/ui组件库构建界面 [Source: architecture/tech-stack.md#前端技术栈]

### 文件位置
- 新包位置：`packages/system-config-management-ui-mt/` [Source: architecture/source-tree.md#包结构]
- 组件文件：`packages/system-config-management-ui-mt/src/components/` [Source: architecture/source-tree.md#前端包结构]
- API客户端：`packages/system-config-management-ui-mt/src/api/` [Source: architecture/source-tree.md#前端包结构]
- 测试文件：`packages/system-config-management-ui-mt/tests/` [Source: 广告管理包实际结构]

### UI包创建策略
- **包命名**: `system-config-management-ui-mt`
- **包位置**: 在packages目录下创建
- **组件结构**: 遵循现有管理后台组件模式 [参照: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx]
- **API集成**: 使用Hono RPC客户端，类型安全 [参照: packages/advertisement-management-ui-mt/src/api/advertisementClient.ts]
- **租户支持**: 支持多租户筛选和管理 [参照: packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx]

### 测试要求
- 使用Vitest进行集成测试 [Source: architecture/testing-strategy.md#测试框架]
- 使用Testing Library进行组件集成测试 [Source: architecture/testing-strategy.md#测试框架]
- 测试文件组织：集成测试在 `tests/integration/`，单元测试在 `tests/unit/` [Source: 广告管理包实际结构]
- 重点验证系统配置管理和功能完整性
- **系统配置测试重点**：
  - 测试系统配置列表页面渲染
  - 验证配置项的增删改查功能
  - 测试租户筛选功能
  - 确保API调用包含正确的租户标识
  - 验证认证和授权的多租户感知

### 技术约束
- Node.js 20.19.2 [Source: architecture/tech-stack.md#开发环境]
- TypeScript严格模式启用 [Source: architecture/component-architecture.md#typescript配置]
- 租户上下文由后端处理，前端使用标准RPC客户端 [Source: architecture/component-architecture.md#多租户支持]

### 实施注意事项
- **依赖管理**: 所有包配置更新完成后，必须执行 `pnpm install` 命令以确保依赖正确安装
- **包命名规范**: 多租户包使用 `-mt` 后缀标识（Multi-Tenant）
- **API客户端集成**: 必须使用系统配置模块包导出的路由 `systemConfigRoutesMt`
- **类型安全**: 确保从系统配置模块包正确导入类型定义

### 关键参考文件路径
- **广告管理主组件**: `packages/advertisement-management-ui-mt/src/components/AdvertisementManagement.tsx` - 完整的CRUD管理组件参考
- **广告管理API客户端**: `packages/advertisement-management-ui-mt/src/api/advertisementClient.ts` - Hono RPC客户端实现参考
- **广告管理类型定义**: `packages/advertisement-management-ui-mt/src/types/advertisement.ts` - TypeScript类型定义参考
- **广告管理包配置**: `packages/advertisement-management-ui-mt/package.json` - 包依赖和配置参考
- **广告管理集成测试**: `packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx` - 完整集成测试参考
- **广告管理包导出**: `packages/advertisement-management-ui-mt/src/index.ts` - 包导出结构参考
- **系统配置路由**: `packages/core-module-mt/system-config-module-mt/src/routes/system-config.routes.mt.ts` - API路由定义参考
- **系统配置包导出**: `packages/core-module-mt/system-config-module-mt/src/index.mt.ts` - 模块导出结构参考

### 系统配置相关参考文件路径
- **用户管理页面参考**: `web/src/client/admin/pages/Users.tsx`
- **系统配置服务**: `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`
- **系统配置实体**: `packages/core-module-mt/system-config-module-mt/src/entities/system-config.entity.mt.ts`
- **系统配置Schema**: `packages/core-module-mt/system-config-module-mt/src/schemas/system-config.schema.mt.ts`

### Testing

#### 测试标准 [Source: architecture/testing-strategy.md]
- **测试框架**: Vitest + hono/testing
- **测试位置**: 各模块的`tests/integration/`目录
- **测试类型**: 集成测试
- **覆盖率目标**: 集成测试 ≥ 60%

#### 测试文件结构
- `packages/system-config-management-ui-mt/tests/unit/` - UI组件单元测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
- `web/tests/integration/system-config.integration.test.ts` - 系统配置页面集成测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]

#### 测试场景
- 系统配置列表页面渲染测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
- 系统配置创建功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
- 系统配置编辑功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
- 系统配置删除功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
- 租户筛选功能测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]
- 现有管理后台功能回归测试 [参照: packages/advertisement-management-ui-mt/tests/integration/advertisement-management.integration.test.tsx]

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-11-20 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record

### Agent Model Used
- **Agent**: James (Dev Agent)
- **Environment**: Multi-tenant development environment
- **Session Date**: 2025-11-20

### Debug Log References

### Completion Notes List
1. ✅ 系统配置管理UI包已成功创建并配置
2. ✅ RPC客户端架构已实现，支持单例模式和延迟初始化
3. ✅ 系统配置管理组件已实现完整的CRUD功能
4. ✅ 管理后台集成已完成，包含路由和菜单配置
5. ✅ 集成测试套件已创建，覆盖完整的CRUD流程
6. ✅ 包构建和测试验证通过
7. ⚠️ 构建警告：hooks目录缺少package.json文件，但不影响功能

### File List
**创建/修改的文件：**
- `packages/system-config-management-ui-mt/` - 完整的系统配置管理UI包
- `packages/system-config-management-ui-mt/src/components/SystemConfigManagement.tsx` - 主管理组件
- `packages/system-config-management-ui-mt/src/api/systemConfigClient.ts` - RPC客户端
- `packages/system-config-management-ui-mt/src/types/systemConfig.ts` - 类型定义
- `packages/system-config-management-ui-mt/tests/integration/system-config-management.integration.test.tsx` - 集成测试
- `web/src/client/admin/routes.tsx` - 添加系统配置路由
- `web/src/client/admin/menu.tsx` - 添加系统配置菜单项
- `web/package.json` - 添加系统配置UI包依赖

### File List
**已删除的文件：**
- `packages/system-config-management-ui-mt/tests/integration/system-config-management.integration.test.tsx` (重新创建)

## QA Results