📝 feat(故事007.008): 创建供应商模块多租户复制故事

- 创建故事007.008文档，吸取之前故事的经验教训
- 整合从故事007.007和007.012学到的关键经验
- 包含完整的技术细节和测试要求
- 确保开发代理能够清晰理解实施要求

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.008.supplier-module-multi-tenant-replication.md

@@ -0,0 +1,205 @@
+# 故事007.008: 供应商模块多租户复制
+
+## 状态
+
+Draft
+
+## 故事
+
+**作为** 系统管理员，
+**我想要** 复制供应商管理模块并添加多租户支持，
+**以便** 供应商可以在租户隔离的环境中管理，同时保持与现有单租户系统的完全兼容性。
+
+## 验收标准
+
+1. **AC 1**: 成功复制 `@d8d/supplier-module` 为 `@d8d/supplier-module-mt`，包含正确的包配置
+2. **AC 2**: 创建多租户供应商实体 `SupplierMt`，包含租户ID字段和表名 `suppliers_mt`
+3. **AC 3**: 更新所有供应商CRUD操作，自动包含租户过滤并在创建时设置租户ID
+4. **AC 4**: 验证供应商数据隔离在不同租户间正常工作
+5. **AC 5**: 保持与现有单租户供应商管理模块功能的完全兼容性
+6. **AC 6**: 所有现有单租户API接口保持不变且功能正常
+7. **AC 7**: 完整的集成测试证明租户隔离和功能正常
+8. **AC 8**: 性能影响相比单租户版本小于5%
+9. **AC 9**: 完成所有多租户模块的回归测试验证，确保系统稳定性
+
+## 任务 / 子任务
+
+- [ ] 复制供应商管理模块为多租户版本 (AC: 1)
+  - [ ] 复制 `packages/supplier-module` 为 `packages/supplier-module-mt`
+  - [ ] 更新包配置为 `@d8d/supplier-module-mt`
+  - [ ] **清理单租户文件**: 删除多租户包中所有单租户相关文件，避免命名冲突
+  - [ ] 更新依赖:
+    - [ ] 将 `@d8d/user-module` 替换为 `@d8d/user-module-mt`
+    - [ ] 将 `@d8d/auth-module` 替换为 `@d8d/auth-module-mt`
+
+- [ ] 更新多租户供应商实体 (AC: 2)
+  - [ ] 创建 `Supplier` 实体，表名为 `suppliers_mt`
+  - [ ] 为实体添加 `tenantId` 字段和正确的TypeORM配置
+  - [ ] 保持其他字段与单租户版本一致
+
+- [ ] 更新多租户供应商服务 (AC: 3, 4)
+  - [ ] 使用共享CRUD库的GenericCrudService
+  - [ ] 所有查询操作自动添加租户过滤
+  - [ ] 创建操作自动设置租户ID
+  - [ ] 更新关联查询支持租户隔离
+
+- [ ] 更新多租户路由配置 (AC: 3)
+  - [ ] 更新用户路由使用多租户实体和服务
+  - [ ] 更新管理员路由使用多租户实体和服务
+  - [ ] 保持API接口与单租户版本一致
+  - [ ] 启用租户选项：`tenantOptions: { enabled: true, tenantIdField: 'tenantId' }`
+
+- [ ] 更新Schema定义 (AC: 3)
+  - [ ] 使用多租户供应商Schema `SupplierSchema`
+  - [ ] 使用多租户用户专用Schema `UserSupplierSchema`
+  - [ ] 使用多租户管理员专用Schema `AdminSupplierSchema`
+  - [ ] 添加租户ID字段定义
+
+- [ ] 实现租户数据隔离API测试 (AC: 7)
+  - [ ] 在 `packages/supplier-module-mt/tests/integration/user-routes.integration.test.ts` 中添加租户隔离测试用例
+  - [ ] 在 `packages/supplier-module-mt/tests/integration/admin-routes.integration.test.ts` 中添加跨租户供应商访问安全验证
+  - [ ] 在现有功能测试中验证租户过滤功能正确性
+
+- [ ] 验证单租户系统完整性 (AC: 5, 6)
+  - [ ] 运行单租户供应商管理模块回归测试
+  - [ ] 验证单租户API接口不受影响
+  - [ ] 确认单租户数据库表结构不变
+
+- [ ] 在创建复制的代码修改完后先运行安装
+  - [ ] 在复制模块后运行 `pnpm install` 安装依赖
+  - [ ] 验证新包已正确添加到工作区
+  - [ ] 确认所有依赖解析正确
+
+- [ ] 执行性能基准测试 (AC: 8)
+  - [ ] 运行多租户供应商管理模块性能测试
+  - [ ] 比较单租户与多租户性能差异
+  - [ ] 确保性能影响小于5%
+
+- [ ] 执行回归测试验证 (AC: 9)
+  - [ ] 运行所有多租户模块的回归测试
+  - [ ] 验证权限模块多租户测试 (38个测试)
+  - [ ] 验证文件模块多租户测试 (40个测试)
+  - [ ] 验证区域模块多租户测试 (29个测试)
+  - [ ] 验证用户模块多租户测试 (41个测试)
+  - [ ] 验证配送地址模块多租户测试 (36个测试)
+  - [ ] 验证商户模块多租户测试 (37个测试)
+  - [ ] 验证租户模块多租户测试 (16个测试)
+  - [ ] 验证广告模块多租户测试 (22个测试)
+  - [ ] 确认所有239个测试全部通过
+
+## 开发说明
+
+### 前面故事的经验教训
+
+**从故事007.007（商户模块）学到的关键经验：**
+- **共享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#技术挑战和解决方案]
+- **实体循环依赖**: UserEntityMt和FileMt必须使用字符串形式的关系定义 [Source: story-007.007.merchant-module-multi-tenant-replication.md#技术挑战解决]
+- **Zod验证问题**: 需要完全解决所有数据库返回数据的Schema验证问题 [Source: story-007.007.merchant-module-multi-tenant-replication.md#技术挑战解决]
+- **共享CRUD错误处理**: 恢复`update`和`delete`方法中的权限验证抛出错误逻辑，确保路由层能正确捕获并返回相应状态码 [Source: story-007.007.merchant-module-multi-tenant-replication.md#技术挑战解决]
+
+**从故事007.012（广告模块）学到的关键经验：**
+- **关联关系问题**: 实体中的关联需要指向正确的多租户实体，例如将 `@ManyToOne('File')` 改为 `@ManyToOne('FileMt')` [Source: story-007.012.advertisements-module-multi-tenant-replication.md#技术挑战解决]
+- **租户ID缺失**: 测试中创建实体时必须显式设置 `tenantId` 字段 [Source: story-007.012.advertisements-module-multi-tenant-replication.md#技术挑战解决]
+- **租户过滤启用**: 必须显式启用路由的租户选项才能实现数据隔离 [Source: story-007.012.advertisements-module-multi-tenant-replication.md#技术挑战解决]
+
+### 数据模型
+
+**供应商实体结构:**
+- 表名: `suppliers_mt` (多租户版本)
+- 租户ID字段: `tenantId` (必需，已索引)
+- 核心字段: `name`, `username`, `password`, `phone`, `realname`, `loginNum`, `loginTime`, `loginIp`, `lastLoginTime`, `lastLoginIp`, `state` [Source: source-tree.md#供应商管理模块]
+- 用户跟踪字段: `createdBy`, `updatedBy` [Source: source-tree.md#供应商管理模块]
+- 时间戳字段: `createdAt`, `updatedAt` [Source: source-tree.md#供应商管理模块]
+
+### API规范
+
+**用户路由:**
+- 路径: `/api/suppliers`
+- 认证: `authMiddleware` 来自 `@d8d/auth-module-mt` [Source: source-tree.md#供应商管理模块]
+- 数据权限: `dataPermission: { enabled: true, userIdField: 'createdBy' }` [Source: story-005.015.supplier-module.story.md#L152-L157]
+- 用户跟踪: `createdByField: 'createdBy'`, `updatedByField: 'updatedBy'` [Source: source-tree.md#供应商管理模块]
+
+**管理员路由:**
+- 路径: `/api/admin/suppliers`
+- 认证: `authMiddleware` 来自 `@d8d/auth-module-mt` [Source: source-tree.md#供应商管理模块]
+- 数据权限: `dataPermission: { enabled: false }` [Source: story-005.015.supplier-module.story.md#L152-L157]
+- 用户跟踪: `createdByField: 'createdBy'`, `updatedByField: 'updatedBy'` [Source: source-tree.md#供应商管理模块]
+
+### 组件规范
+
+**供应商服务方法:**
+- 继承GenericCrudService的所有标准CRUD方法
+- 所有查询操作自动添加租户过滤
+- 创建操作自动设置租户ID
+
+### 文件位置
+
+**要创建的源文件:**
+- `packages/supplier-module-mt/src/entities/supplier.mt.entity.ts` (多租户供应商实体)
+- `packages/supplier-module-mt/src/services/supplier.mt.service.ts` (多租户供应商服务)
+- `packages/supplier-module-mt/src/routes/user-routes.mt.ts` (多租户用户路由)
+- `packages/supplier-module-mt/src/routes/admin-routes.mt.ts` (多租户管理员路由)
+- `packages/supplier-module-mt/src/schemas/supplier.mt.schema.ts` (多租户供应商schemas)
+- `packages/supplier-module-mt/src/schemas/user-supplier.mt.schema.ts` (多租户用户专用schemas)
+- `packages/supplier-module-mt/src/schemas/admin-supplier.mt.schema.ts` (多租户管理员专用schemas)
+
+**要删除的文件（单租户清理）:**
+- 多租户包中所有没有 `.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应该从认证用户上下文中自动设置
+
+**关联关系处理:**
+- 供应商实体关联UserMt，需要使用字符串形式的关系定义避免循环依赖
+- 确保所有关联实体都正确注册到TypeORM
+
+## 测试
+
+### 测试标准
+
+**测试文件位置**: `packages/supplier-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状态码
+- 数据权限测试: 验证用户路由和管理员路由在租户上下文中的权限控制
+- 供应商登录统计功能: 确保登录统计功能在租户隔离环境中正常工作
+
+## 变更日志
+
+| 日期 | 版本 | 描述 | 作者 |
+|------|------|------|------|
+| 2025-11-14 | 1.0 | 初始故事创建，包含从前面的故事中学到的全面经验教训 | Bob (Scrum Master) |
+
+## 开发代理记录
+
+*此部分由开发代理在实现过程中填写*
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List
+
+## QA结果
+
+*此部分将在质量保证审查过程中由QA代理填充*