📝 docs(故事007.007): 将商户模块多租户复制故事翻译为中文

- 将故事标题、状态、用户故事描述翻译为中文
- 翻译任务/子任务部分为中文
- 翻译开发说明部分为中文
- 保持技术术语和引用格式不变
- 确保从前面的故事中学到的经验教训清晰传达

🤖 Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/stories/007.007.merchant-module-multi-tenant-replication.md

@@ -1,166 +1,166 @@
-# Story 007.007: Merchant Module Multi-Tenant Replication
-
-## Status
-
-Draft
-
-## Story
-
-**As a** system administrator,
-**I want** to replicate the merchant module with multi-tenant support,
-**so that** merchants can be managed in a tenant-isolated environment while maintaining full compatibility with the existing single-tenant system.
-
-## Acceptance Criteria
-
-1. **AC 1**: Successfully replicate `@d8d/merchant-module` as `@d8d/merchant-module-mt` with proper package configuration
-2. **AC 2**: Create multi-tenant merchant entity `MerchantMt` with tenant ID field and table name `merchants_mt`
-3. **AC 3**: Update all merchant CRUD operations to automatically include tenant filtering and set tenant ID on creation
-4. **AC 4**: Verify merchant data isolation works correctly across different tenants
-5. **AC 5**: Maintain full compatibility with existing single-tenant merchant module functionality
-6. **AC 6**: All existing single-tenant API interfaces remain unchanged and functional
-7. **AC 7**: Complete integration tests demonstrate tenant isolation and functionality
-8. **AC 8**: Performance impact is less than 5% compared to single-tenant version
-
-## Tasks / Subtasks
-
-- [ ] Replicate merchant module as multi-tenant version (AC: 1)
-  - [ ] Copy `packages/merchant-module` to `packages/merchant-module-mt`
-  - [ ] Update package configuration to `@d8d/merchant-module-mt`
-  - [ ] **Clean single-tenant files**: Remove all single-tenant related files from multi-tenant package to avoid naming conflicts
-  - [ ] Update dependencies:
-    - [ ] Replace `@d8d/user-module` with `@d8d/user-module-mt`
-    - [ ] Replace `@d8d/auth-module` with `@d8d/auth-module-mt`
-    - [ ] Replace `@d8d/file-module` with `@d8d/file-module-mt`
-
-- [ ] Update multi-tenant merchant entity (AC: 2)
-  - [ ] Create `MerchantMt` entity with table name `merchants_mt`
-  - [ ] Add `tenantId` field with proper TypeORM configuration
-  - [ ] Keep all other fields consistent with single-tenant version
-
-- [ ] Update multi-tenant merchant service (AC: 3, 4)
-  - [ ] Create `MerchantServiceMt` service extending GenericCrudService
-  - [ ] All query operations automatically add tenant filtering
-  - [ ] Create operations automatically set tenant ID
-  - [ ] Update login statistics methods to support tenant isolation
-  - [ ] Update username lookup methods to support tenant filtering
-
-- [ ] Update multi-tenant route configurations (AC: 3)
-  - [ ] Update user routes to use multi-tenant entity and service
-  - [ ] Update admin routes to use multi-tenant entity and service
-  - [ ] Maintain API interfaces consistent with single-tenant version
-  - [ ] Update authentication middleware to support tenant ID extraction
-
-- [ ] Update Schema definitions (AC: 3)
-  - [ ] Create multi-tenant merchant schema `MerchantSchemaMt`
-  - [ ] Create multi-tenant user merchant schema `UserMerchantSchemaMt`
-  - [ ] Create multi-tenant admin merchant schema `AdminMerchantSchemaMt`
-  - [ ] Add tenant ID field definitions
-
-- [ ] Implement tenant data isolation API tests (AC: 7)
-  - [ ] Add tenant isolation test cases in `packages/merchant-module-mt/tests/integration/user-routes.integration.test.ts`
-  - [ ] Add cross-tenant merchant access security validation in `packages/merchant-module-mt/tests/integration/admin-routes.integration.test.ts`
-  - [ ] Create dedicated tenant isolation test file `tenant-isolation.integration.test.ts`
-  - [ ] Verify tenant filtering functionality in existing feature tests
-
-- [ ] Validate single-tenant system integrity (AC: 5, 6)
-  - [ ] Run single-tenant merchant module regression tests
-  - [ ] Verify single-tenant API interfaces unaffected
-  - [ ] Confirm single-tenant database table structure unchanged
-
-- [ ] Execute performance benchmark tests (AC: 8)
-  - [ ] Run multi-tenant merchant module performance tests
-  - [ ] Compare single-tenant vs multi-tenant performance differences
-  - [ ] Ensure performance impact less than 5%
-
-## Dev Notes
-
-### Previous Story Insights
-
-**Critical lessons learned from Story 007.006 (Address Module):**
-- **Shared CRUD library execution order**: Must ensure tenant validation occurs BEFORE data permission validation in GenericCrudService.getById method [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
-- **Test data tenant ID management**: Test data factories must explicitly set tenantId field to avoid constraint errors [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
-- **Cross-tenant access status codes**: Should return 404 (Not Found) instead of 403 (Forbidden) for cross-tenant access [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
-- **File naming conventions**: Strictly use `.mt.ts` suffix for multi-tenant files [Source: epic-007-multi-tenant-package-replication.md#最佳实践]
-- **Database synchronization**: Use `fileParallelism: false` in vitest config to avoid database conflicts [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
-
-### Data Models
-
-**Merchant Entity Structure:**
-- Table name: `merchants_mt` (multi-tenant version)
-- Tenant ID field: `tenantId` (required, indexed)
-- Core fields: `name`, `username`, `password`, `phone`, `realname`, `loginNum`, `loginTime`, `loginIp`, `lastLoginTime`, `lastLoginIp`, `state`, `rsaPublicKey`, `aesKey` [Source: source-tree.md#商户管理模块]
-- User tracking fields: `createdBy`, `updatedBy` [Source: source-tree.md#商户管理模块]
-- Timestamp fields: `createdAt`, `updatedAt` [Source: source-tree.md#商户管理模块]
-
-### API Specifications
-
-**User Routes:**
-- Path: `/api/merchants` (user-specific)
-- Authentication: `authMiddleware` from `@d8d/auth-module-mt` [Source: source-tree.md#商户管理模块]
-- Data permission: Enabled with `userIdField: 'createdBy'` [Source: source-tree.md#商户管理模块]
-- Search fields: `['name', 'username', 'realname', 'phone']` [Source: source-tree.md#商户管理模块]
-
-**Admin Routes:**
-- Path: `/api/admin/merchants` (full access)
-- Authentication: `authMiddleware` from `@d8d/auth-module-mt` [Source: source-tree.md#商户管理模块]
-- Data permission: Disabled for admin routes [Source: source-tree.md#商户管理模块]
-
-### Component Specifications
-
-**Merchant Service Methods:**
-- `updateLoginStats(merchantId, loginTime, loginIp)`: Update merchant login statistics [Source: source-tree.md#商户管理模块]
-- `findByUsername(username)`: Find merchant by username with tenant filtering [Source: source-tree.md#商户管理模块]
-- `getByState(state)`: Get merchants by state with tenant filtering [Source: source-tree.md#商户管理模块]
-
-### File Locations
-
-**Source Files to Create:**
-- `packages/merchant-module-mt/src/entities/merchant.mt.entity.ts` (multi-tenant entity)
-- `packages/merchant-module-mt/src/services/merchant.mt.service.ts` (multi-tenant service)
-- `packages/merchant-module-mt/src/routes/user-routes.mt.ts` (multi-tenant user routes)
-- `packages/merchant-module-mt/src/routes/admin-routes.mt.ts` (multi-tenant admin routes)
-- `packages/merchant-module-mt/src/schemas/merchant.mt.schema.ts` (multi-tenant schemas)
-- `packages/merchant-module-mt/tests/integration/tenant-isolation.integration.test.ts` (tenant isolation tests)
-
-**Files to Remove (Single-tenant cleanup):**
-- All files without `.mt.ts` suffix in multi-tenant package
-- Any single-tenant specific configurations
-
-### Technical Constraints
-
-**Database Indexing:**
-- Must create index on `tenantId` field for performance [Source: epic-007-multi-tenant-package-replication.md#数据库迁移策略]
-- Composite indexes for common query patterns (tenantId + state, tenantId + username)
-
-**Authentication Integration:**
-- Use updated `authMiddleware` from `@d8d/auth-module-mt` that extracts tenant ID from user context [Source: epic-007-multi-tenant-package-replication.md#租户上下文管理]
-- Tenant ID should be automatically set from authenticated user context
-
-### Testing
-
-**Testing Standards:**
-- **Test file location**: `packages/merchant-module-mt/tests/integration/` [Source: testing-strategy.md#集成测试]
-- **Test framework**: Vitest + hono/testing + shared-test-util [Source: testing-strategy.md#集成测试]
-- **Test patterns**: Use test data factories with explicit tenantId setting [Source: testing-strategy.md#测试数据管理]
-- **Coverage target**: ≥ 60% integration test coverage [Source: testing-strategy.md#各层覆盖率要求]
-- **Database strategy**: Use test database with transaction rollback [Source: testing-strategy.md#数据库测试策略]
-
-**Specific Testing Requirements:**
-- Tenant isolation validation: Verify merchants from different tenants cannot access each other's data
-- Cross-tenant access: Should return 404 status code for cross-tenant access attempts
-- Login statistics: Verify login stats update correctly within tenant context
-- Username uniqueness: Ensure username uniqueness is enforced per tenant, not globally
+# 故事007.007: 商户模块多租户复制
+
+## 状态
+
+草稿
+
+## 故事
+
+**作为** 系统管理员，
+**我想要** 复制商户模块并添加多租户支持，
+**以便** 商户可以在租户隔离的环境中管理，同时保持与现有单租户系统的完全兼容性。
+
+## 验收标准
+
+1. **AC 1**: 成功复制 `@d8d/merchant-module` 为 `@d8d/merchant-module-mt`，包含正确的包配置
+2. **AC 2**: 创建多租户商户实体 `MerchantMt`，包含租户ID字段和表名 `merchants_mt`
+3. **AC 3**: 更新所有商户CRUD操作，自动包含租户过滤并在创建时设置租户ID
+4. **AC 4**: 验证商户数据隔离在不同租户间正常工作
+5. **AC 5**: 保持与现有单租户商户模块功能的完全兼容性
+6. **AC 6**: 所有现有单租户API接口保持不变且功能正常
+7. **AC 7**: 完整的集成测试证明租户隔离和功能正常
+8. **AC 8**: 性能影响相比单租户版本小于5%
+
+## 任务 / 子任务
+
+- [ ] 复制商户模块为多租户版本 (AC: 1)
+  - [ ] 复制 `packages/merchant-module` 为 `packages/merchant-module-mt`
+  - [ ] 更新包配置为 `@d8d/merchant-module-mt`
+  - [ ] **清理单租户文件**: 删除多租户包中所有单租户相关文件，避免命名冲突
+  - [ ] 更新依赖:
+    - [ ] 将 `@d8d/user-module` 替换为 `@d8d/user-module-mt`
+    - [ ] 将 `@d8d/auth-module` 替换为 `@d8d/auth-module-mt`
+    - [ ] 将 `@d8d/file-module` 替换为 `@d8d/file-module-mt`
+
+- [ ] 更新多租户商户实体 (AC: 2)
+  - [ ] 创建 `MerchantMt` 实体，表名为 `merchants_mt`
+  - [ ] 添加 `tenantId` 字段和正确的TypeORM配置
+  - [ ] 保持其他字段与单租户版本一致
+
+- [ ] 更新多租户商户服务 (AC: 3, 4)
+  - [ ] 创建 `MerchantServiceMt` 服务，继承GenericCrudService
+  - [ ] 所有查询操作自动添加租户过滤
+  - [ ] 创建操作自动设置租户ID
+  - [ ] 更新登录统计方法支持租户隔离
+  - [ ] 更新用户名查找方法支持租户过滤
+
+- [ ] 更新多租户路由配置 (AC: 3)
+  - [ ] 更新用户路由使用多租户实体和服务
+  - [ ] 更新管理员路由使用多租户实体和服务
+  - [ ] 保持API接口与单租户版本一致
+  - [ ] 更新认证中间件支持租户ID提取
+
+- [ ] 更新Schema定义 (AC: 3)
+  - [ ] 创建多租户商户Schema `MerchantSchemaMt`
+  - [ ] 创建多租户用户商户Schema `UserMerchantSchemaMt`
+  - [ ] 创建多租户管理员商户Schema `AdminMerchantSchemaMt`
+  - [ ] 添加租户ID字段定义
+
+- [ ] 实现租户数据隔离API测试 (AC: 7)
+  - [ ] 在 `packages/merchant-module-mt/tests/integration/user-routes.integration.test.ts` 中添加租户隔离测试用例
+  - [ ] 在 `packages/merchant-module-mt/tests/integration/admin-routes.integration.test.ts` 中添加跨租户商户访问安全验证
+  - [ ] 创建专门的租户隔离测试文件 `tenant-isolation.integration.test.ts`
+  - [ ] 在现有功能测试中验证租户过滤功能正确性
+
+- [ ] 验证单租户系统完整性 (AC: 5, 6)
+  - [ ] 运行单租户商户模块回归测试
+  - [ ] 验证单租户API接口不受影响
+  - [ ] 确认单租户数据库表结构不变
+
+- [ ] 执行性能基准测试 (AC: 8)
+  - [ ] 运行多租户商户模块性能测试
+  - [ ] 比较单租户与多租户性能差异
+  - [ ] 确保性能影响小于5%
+
+## 开发说明
+
+### 前面故事的经验教训
+
+**从故事007.006（地址模块）学到的关键经验：**
+- **共享CRUD库执行顺序**: 必须确保在GenericCrudService.getById方法中租户验证先于数据权限验证 [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
+- **测试数据租户ID管理**: 测试数据工厂必须显式设置tenantId字段以避免约束错误 [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
+- **跨租户访问状态码**: 跨租户访问应该返回404（未找到）而不是403（禁止访问） [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
+- **文件命名约定**: 严格使用 `.mt.ts` 后缀区分多租户文件 [Source: epic-007-multi-tenant-package-replication.md#最佳实践]
+- **数据库同步**: 在vitest配置中使用 `fileParallelism: false` 避免数据库冲突 [Source: epic-007-multi-tenant-package-replication.md#技术挑战和解决方案]
+
+### 数据模型
+
+**商户实体结构:**
+- 表名: `merchants_mt` (多租户版本)
+- 租户ID字段: `tenantId` (必需，已索引)
+- 核心字段: `name`, `username`, `password`, `phone`, `realname`, `loginNum`, `loginTime`, `loginIp`, `lastLoginTime`, `lastLoginIp`, `state`, `rsaPublicKey`, `aesKey` [Source: source-tree.md#商户管理模块]
+- 用户跟踪字段: `createdBy`, `updatedBy` [Source: source-tree.md#商户管理模块]
+- 时间戳字段: `createdAt`, `updatedAt` [Source: source-tree.md#商户管理模块]
+
+### API规范
+
+**用户路由:**
+- 路径: `/api/merchants` (用户专用)
+- 认证: `authMiddleware` 来自 `@d8d/auth-module-mt` [Source: source-tree.md#商户管理模块]
+- 数据权限: 启用，使用 `userIdField: 'createdBy'` [Source: source-tree.md#商户管理模块]
+- 搜索字段: `['name', 'username', 'realname', 'phone']` [Source: source-tree.md#商户管理模块]
+
+**管理员路由:**
+- 路径: `/api/admin/merchants` (完整权限)
+- 认证: `authMiddleware` 来自 `@d8d/auth-module-mt` [Source: source-tree.md#商户管理模块]
+- 数据权限: 管理员路由禁用数据权限控制 [Source: source-tree.md#商户管理模块]
+
+### 组件规范
+
+**商户服务方法:**
+- `updateLoginStats(merchantId, loginTime, loginIp)`: 更新商户登录统计信息 [Source: source-tree.md#商户管理模块]
+- `findByUsername(username)`: 根据用户名查找商户，包含租户过滤 [Source: source-tree.md#商户管理模块]
+- `getByState(state)`: 根据状态获取商户列表，包含租户过滤 [Source: source-tree.md#商户管理模块]
+
+### 文件位置
+
+**要创建的源文件:**
+- `packages/merchant-module-mt/src/entities/merchant.mt.entity.ts` (多租户实体)
+- `packages/merchant-module-mt/src/services/merchant.mt.service.ts` (多租户服务)
+- `packages/merchant-module-mt/src/routes/user-routes.mt.ts` (多租户用户路由)
+- `packages/merchant-module-mt/src/routes/admin-routes.mt.ts` (多租户管理员路由)
+- `packages/merchant-module-mt/src/schemas/merchant.mt.schema.ts` (多租户schemas)
+- `packages/merchant-module-mt/tests/integration/tenant-isolation.integration.test.ts` (租户隔离测试)
+
+**要删除的文件（单租户清理）:**
+- 多租户包中所有没有 `.mt.ts` 后缀的文件
+- 任何单租户特定的配置
+
+### 技术约束
+
+**数据库索引:**
+- 必须在 `tenantId` 字段上创建索引以提高性能 [Source: epic-007-multi-tenant-package-replication.md#数据库迁移策略]
+- 为常见查询模式创建复合索引 (tenantId + state, tenantId + username)
+
+**认证集成:**
+- 使用来自 `@d8d/auth-module-mt` 的更新版 `authMiddleware`，从用户上下文中提取租户ID [Source: epic-007-multi-tenant-package-replication.md#租户上下文管理]
+- 租户ID应该从认证用户上下文中自动设置
+
+### 测试
+
+**测试标准:**
+- **测试文件位置**: `packages/merchant-module-mt/tests/integration/` [Source: testing-strategy.md#集成测试]
+- **测试框架**: Vitest + hono/testing + shared-test-util [Source: testing-strategy.md#集成测试]
+- **测试模式**: 使用测试数据工厂并显式设置tenantId [Source: testing-strategy.md#测试数据管理]
+- **覆盖率目标**: ≥ 60% 集成测试覆盖率 [Source: testing-strategy.md#各层覆盖率要求]
+- **数据库策略**: 使用测试数据库和事务回滚 [Source: testing-strategy.md#数据库测试策略]
+
+**特定测试要求:**
+- 租户隔离验证: 验证不同租户的商户无法访问彼此的数据
+- 跨租户访问: 跨租户访问尝试应该返回404状态码
+- 登录统计: 验证登录统计在租户上下文中正确更新
+- 用户名唯一性: 确保用户名唯一性在租户级别强制执行，而不是全局
 
-## Change Log
+## 变更日志
 
-| Date | Version | Description | Author |
-|------|---------|-------------|---------|
-| 2025-11-14 | 1.0 | Initial story creation with comprehensive lessons learned from previous stories | Bob (Scrum Master) |
+| 日期 | 版本 | 描述 | 作者 |
+|------|------|------|------|
+| 2025-11-14 | 1.0 | 初始故事创建，包含从前面的故事中学到的全面经验教训 | Bob (Scrum Master) |
 
-## Dev Agent Record
+## 开发代理记录
 
-*This section will be populated by the development agent during implementation*
+*此部分将在实施过程中由开发代理填充*
 
-## QA Results
+## QA结果
 
-*This section will be populated by the QA agent during quality assurance review*
+*此部分将在质量保证审查过程中由QA代理填充*