✨ feat(multi-tenant): 创建史诗007 - 多租户复制包方案

## 新增内容
- 创建史诗007文档，详细规划多租户复制包方案
- 基于复制包策略，形成单租户和多租户两套业务包体系
- 保持共享包不变，业务包添加-mt后缀标识多租户版本

## 核心设计
- 租户包从商户包复制修改
- 认证中间件名字保持不变，内部集成租户上下文
- 按依赖关系分阶段实施：基础架构→核心业务→系统集成
- 14个独立故事，每个模块单独复制

## 优势
- 风险可控：两套系统完全独立
- 实施简单：基于现有代码复制
- 维护明确：责任清晰分离
- 回滚简单：多租户包可随时移除

🤖 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/prd/epic-007-multi-tenant-package-replication.md

@@ -0,0 +1,611 @@
+# Epic-007: 多租户复制包方案 - Brownfield Enhancement
+
+## Epic Goal
+
+基于用户的多租户复制包方案，通过复制现有业务包并添加租户标记和租户ID支持，形成两套业务包：单租户版本和多租户版本，在server中按需进行依赖拼装，实现多租户支持。
+
+## Epic Description
+
+### Existing System Context
+
+**Current relevant functionality:**
+- **共享包** (保持不变):
+  - `@d8d/shared-crud`: 通用CRUD操作和用户跟踪字段
+  - `@d8d/shared-types`: 共享类型定义
+  - `@d8d/shared-utils`: 共享工具函数
+  - `@d8d/shared-test-util`: 共享测试工具
+
+- **业务包** (需要复制):
+  - `@d8d/user-module`: 用户管理、认证、角色权限
+  - `@d8d/orders-module`: 订单创建、支付、物流管理
+  - `@d8d/goods-module`: 商品管理、分类、库存
+  - `@d8d/merchant-module`: 商户管理
+  - `@d8d/supplier-module`: 供应商管理
+  - `@d8d/delivery-address-module`: 配送地址管理
+  - `@d8d/file-module`: 文件上传管理
+  - `@d8d/geo-areas`: 地理区域管理
+  - `@d8d/auth-module`: 认证模块
+  - `@d8d/mini-payment`: 小程序支付
+  - `@d8d/advertisements-module`: 广告模块
+
+**Current limitations:**
+- 现有系统为单租户架构，所有数据共享同一数据库
+- 缺乏租户隔离机制，无法支持多租户场景
+- 业务逻辑与租户概念耦合度低
+- 无法在同一系统中部署多个独立租户
+
+**Technology stack:**
+- Backend: Node.js, TypeScript, Hono, TypeORM, PostgreSQL
+- Authentication: JWT, Redis session management
+- Database: PostgreSQL with user tracking fields
+- Package Management: pnpm workspace
+- Architecture: Monorepo with modular packages
+
+**Integration points:**
+- 各业务模块通过TypeORM实体关联
+- 共享类型定义在shared-types中
+- CRUD操作通过shared-crud统一处理
+- 认证通过auth-module统一管理
+- 模块间通过workspace依赖管理
+
+### Enhancement Details
+
+**What's being added/changed:**
+- 复制所有业务包，创建带租户标记的版本
+- 在新复制的包中添加租户ID字段支持
+- 形成两套业务包体系：单租户版本和多租户版本
+- 在server中按需进行依赖拼装
+- 保持共享包不变，避免重复维护
+
+**Enhanced architecture:**
+```
+packages/
+├── shared-crud/ (保持不变)
+├── shared-types/ (保持不变)
+├── shared-utils/ (保持不变)
+├── shared-test-util/ (保持不变)
+├──
+├── 单租户业务包 (现有包):
+│   ├── user-module/
+│   ├── orders-module/
+│   ├── goods-module/
+│   └── ...
+├──
+└── 多租户业务包 (新复制包):
+    ├── user-module-mt/ (多租户版本)
+    ├── orders-module-mt/ (多租户版本)
+    ├── goods-module-mt/ (多租户版本)
+    └── ...
+```
+
+**How it integrates:**
+- 保持现有单租户系统完全可用
+- 新增多租户包通过命名约定区分（-mt后缀）
+- server根据配置选择加载单租户或多租户包
+- 共享包在两套系统中复用
+- 数据库schema通过租户ID字段实现数据隔离
+
+**Success criteria:**
+- 现有单租户系统功能完全保留，无任何影响
+- 多租户系统能够独立运行，租户间数据完全隔离
+- 两套系统可以同时部署，互不干扰
+- 共享包在两套系统中正常工作
+- 性能影响小于5%
+- 完整的测试覆盖和文档
+
+## Stories
+
+### 阶段 1: 基础架构和主数据包
+
+1. **Story 1:** 租户基础包创建和租户管理
+   - 复制 `@d8d/merchant-module` 为 `@d8d/tenant-module-mt` 租户管理模块
+   - 修改商户实体为租户实体，调整字段和业务逻辑
+   - 实现租户管理API
+   - 创建租户上下文管理
+   - 验证租户管理功能
+
+2. **Story 2:** 用户模块多租户复制和租户支持
+   - 复制 `@d8d/user-module` 为 `@d8d/user-module-mt`
+   - 在用户实体中添加租户ID字段
+   - 更新用户CRUD操作支持租户过滤
+   - 验证用户数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+3. **Story 3:** 文件模块多租户复制和租户支持
+   - 复制 `@d8d/file-module` 为 `@d8d/file-module-mt`
+   - 在文件实体中添加租户ID字段
+   - 更新文件CRUD操作支持租户过滤
+   - 验证文件数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+4. **Story 4:** 认证模块多租户复制和租户支持
+   - 复制 `@d8d/auth-module` 为 `@d8d/auth-module-mt`
+   - 修改认证中间件逻辑，集成租户上下文管理（中间件名字保持不变）
+   - 在认证逻辑中添加租户支持
+   - 验证多租户认证功能
+   - 保持单租户版本完全可用
+
+### 阶段 2: 核心业务包多租户化
+
+5. **Story 5:** 地理区域模块多租户复制和租户支持
+   - 复制 `@d8d/geo-areas` 为 `@d8d/geo-areas-mt`
+   - 在区域实体中添加租户ID字段
+   - 更新区域CRUD操作支持租户过滤
+   - 验证区域数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+6. **Story 6:** 地址模块多租户复制和租户支持
+   - 复制 `@d8d/delivery-address-module` 为 `@d8d/delivery-address-module-mt`
+   - 在地址实体中添加租户ID字段
+   - 更新地址CRUD操作支持租户过滤
+   - 验证地址数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+7. **Story 7:** 商户模块多租户复制和租户支持
+   - 复制 `@d8d/merchant-module` 为 `@d8d/merchant-module-mt`
+   - 在商户实体中添加租户ID字段
+   - 更新商户CRUD操作支持租户过滤
+   - 验证商户数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+8. **Story 8:** 供应商模块多租户复制和租户支持
+   - 复制 `@d8d/supplier-module` 为 `@d8d/supplier-module-mt`
+   - 在供应商实体中添加租户ID字段
+   - 更新供应商CRUD操作支持租户过滤
+   - 验证供应商数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+9. **Story 9:** 商品模块多租户复制和租户支持
+   - 复制 `@d8d/goods-module` 为 `@d8d/goods-module-mt`
+   - 在商品和分类实体中添加租户ID字段
+   - 更新商品CRUD操作支持租户过滤
+   - 验证商品数据租户隔离正确性
+   - 保持单租户版本完全可用
+
+### 阶段 3: 业务包多租户化和系统集成
+
+10. **Story 10:** 订单模块多租户复制和租户支持
+    - 复制 `@d8d/orders-module` 为 `@d8d/orders-module-mt`
+    - 在订单、订单商品、退款实体中添加租户ID字段
+    - 更新订单CRUD操作支持租户过滤
+    - 验证订单数据租户隔离正确性
+    - 保持单租户版本完全可用
+
+11. **Story 11:** 小程序支付模块多租户复制和租户支持
+    - 复制 `@d8d/mini-payment` 为 `@d8d/mini-payment-mt`
+    - 在支付实体中添加租户ID字段
+    - 更新支付CRUD操作支持租户过滤
+    - 验证支付数据租户隔离正确性
+    - 保持单租户版本完全可用
+
+12. **Story 12:** 广告模块多租户复制和租户支持
+    - 复制 `@d8d/advertisements-module` 为 `@d8d/advertisements-module-mt`
+    - 在广告实体中添加租户ID字段
+    - 更新广告CRUD操作支持租户过滤
+    - 验证广告数据租户隔离正确性
+    - 保持单租户版本完全可用
+
+### 阶段 4: 系统集成和租户管理
+
+13. **Story 13:** 多租户系统server集成
+    - 创建多租户server配置
+    - 实现租户感知的依赖注入
+    - 实现动态包加载机制
+    - 验证多租户系统完整功能
+
+14. **Story 14:** 租户管理和配置界面
+    - 创建租户管理API
+    - 实现租户配置界面
+    - 添加租户切换功能
+    - 完整的多租户系统测试
+    - 性能基准测试和优化
+
+## Compatibility Requirements
+
+- [x] 现有单租户系统API保持完全兼容
+- [x] 现有数据库schema变更向后兼容
+- [x] 共享包在两套系统中正常工作
+- [x] 单租户系统性能不受影响
+- [x] 多租户系统可独立部署
+- [x] 配置向后兼容，现有配置继续有效
+
+## Risk Mitigation
+
+**Primary Risk:** 代码重复度高，维护成本增加
+**Mitigation:** 共享包保持不变，业务逻辑变化控制在最小范围
+**Rollback Plan:** 多租户包为新增，可随时移除，不影响单租户系统
+
+**Primary Risk:** 包依赖关系复杂化
+**Mitigation:** 清晰的命名约定和文档，server依赖管理简化
+**Rollback Plan:** 保持单租户包不变，多租户包可独立移除
+
+**Primary Risk:** 数据库schema变更影响现有数据
+**Mitigation:** 多租户包使用新的数据库表或字段，不修改现有表
+**Rollback Plan:** 多租户数据可独立清理，不影响单租户数据
+
+**Primary Risk:** 性能影响
+**Mitigation:** 租户过滤使用数据库索引，性能基准测试
+**Rollback Plan:** 多租户系统可独立关闭，不影响单租户性能
+
+## Definition of Done
+
+- [ ] 所有故事完成且验收标准满足
+- [ ] 现有单租户功能通过回归测试验证
+- [ ] 多租户系统功能完整且稳定
+- [ ] 租户间数据隔离验证通过
+- [ ] 性能基准测试通过，无明显性能下降
+- [ ] 完整的单元测试和集成测试覆盖
+- [ ] 使用文档和示例代码完整
+- [ ] 向后兼容性验证通过
+
+## 架构设计详情
+
+### 包命名约定
+
+```typescript
+// 单租户包 (现有)
+@d8d/user-module
+@d8d/orders-module
+@d8d/goods-module
+@d8d/merchant-module
+@d8d/supplier-module
+@d8d/delivery-address-module
+@d8d/file-module
+@d8d/geo-areas
+@d8d/auth-module
+@d8d/mini-payment
+@d8d/advertisements-module
+
+// 多租户包 (新增，-mt后缀)
+@d8d/tenant-module-mt (从商户包复制修改)
+@d8d/user-module-mt
+@d8d/orders-module-mt
+@d8d/goods-module-mt
+@d8d/merchant-module-mt
+@d8d/supplier-module-mt
+@d8d/delivery-address-module-mt
+@d8d/file-module-mt
+@d8d/geo-areas-mt
+@d8d/auth-module-mt
+@d8d/mini-payment-mt
+@d8d/advertisements-module-mt
+```
+
+### 租户包从商户包复制修改
+
+```typescript
+// 从商户包复制后修改为租户包
+// 商户实体 -> 租户实体
+@Entity('tenants_mt')
+export class TenantEntityMt {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column({ name: 'name', type: 'varchar', length: 100 })
+  name: string; // 租户名称
+
+  @Column({ name: 'code', type: 'varchar', length: 50, unique: true })
+  code: string; // 租户代码
+
+  @Column({ name: 'status', type: 'varchar', length: 20, default: 'active' })
+  status: string; // 租户状态
+
+  @Column({ name: 'config', type: 'jsonb', nullable: true })
+  config: Record<string, any>; // 租户配置
+
+  // ... 其他字段根据租户需求调整
+}
+```
+
+### 实体设计 - 多租户版本
+
+```typescript
+// 多租户用户实体示例
+@Entity('users_mt') // 使用不同的表名避免冲突
+@TenantAware()
+export class UserEntityMt {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @TenantId()
+  @Column({ name: 'tenant_id', type: 'int', unsigned: true })
+  tenantId: number;
+
+  @Column({ name: 'username', type: 'varchar', length: 50 })
+  username: string;
+
+  // ... 其他字段保持不变
+}
+```
+
+### 服务层设计 - 多租户版本
+
+```typescript
+// 多租户用户服务
+@Service()
+export class UserServiceMt {
+  constructor(
+    @InjectRepository(UserEntityMt)
+    private userRepository: Repository<UserEntityMt>,
+    private tenantContext: TenantContext
+  ) {}
+
+  async getUsers(page: number = 1, pageSize: number = 10): Promise<[UserEntityMt[], number]> {
+    const tenantId = this.tenantContext.getCurrentTenantId();
+
+    return this.userRepository.findAndCount({
+      where: { tenantId },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+      order: { id: 'DESC' }
+    });
+  }
+
+  async createUser(data: CreateUserDto): Promise<UserEntityMt> {
+    const tenantId = this.tenantContext.getCurrentTenantId();
+
+    const user = this.userRepository.create({
+      ...data,
+      tenantId
+    });
+
+    return this.userRepository.save(user);
+  }
+}
+```
+
+### 路由设计 - 多租户版本
+
+```typescript
+// 多租户用户路由（使用原有的认证中间件名字）
+const userRoutesMt = new Hono()
+  .use('*', authMiddleware) // 保持原有中间件名字
+  .get('/', async (c) => {
+    const userService = c.get('userServiceMt') as UserServiceMt;
+    const [users, total] = await userService.getUsers();
+    return c.json({ code: 200, data: { users, total } });
+  })
+  .post('/', async (c) => {
+    const userService = c.get('userServiceMt') as UserServiceMt;
+    const data = await c.req.json();
+    const user = await userService.createUser(data);
+    return c.json({ code: 201, data: user });
+  });
+
+export { userRoutesMt };
+```
+
+### Server依赖管理
+
+```typescript
+// 单租户server配置
+export function createSingleTenantServer(): Hono {
+  const app = new Hono();
+
+  // 加载单租户包
+  app.route('/api/users', userRoutes);
+  app.route('/api/orders', ordersRoutes);
+  app.route('/api/goods', goodsRoutes);
+  // ... 其他单租户路由
+
+  return app;
+}
+
+// 多租户server配置
+export function createMultiTenantServer(): Hono {
+  const app = new Hono();
+
+  // 加载多租户包
+  app.route('/api/users', userRoutesMt);
+  app.route('/api/orders', ordersRoutesMt);
+  app.route('/api/goods', goodsRoutesMt);
+  // ... 其他多租户路由
+
+  return app;
+}
+
+// 根据配置选择server
+export function createServer(): Hono {
+  const isMultiTenant = process.env.MULTI_TENANT_ENABLED === 'true';
+
+  if (isMultiTenant) {
+    return createMultiTenantServer();
+  } else {
+    return createSingleTenantServer();
+  }
+}
+```
+
+### 租户上下文管理
+
+```typescript
+// 租户上下文
+export class TenantContext {
+  private static readonly tenantIdStorage = new AsyncLocalStorage<number>();
+
+  static getCurrentTenantId(): number | undefined {
+    return this.tenantIdStorage.getStore();
+  }
+
+  static runWithTenant<T>(tenantId: number, fn: () => Promise<T>): Promise<T> {
+    return this.tenantIdStorage.run(tenantId, fn);
+  }
+}
+
+// 多租户认证中间件（保持原有中间件名字）
+export const authMiddleware: MiddlewareHandler = async (c, next) => {
+  // 1. 执行原有认证逻辑
+  const token = c.req.header('Authorization')?.replace('Bearer ', '');
+  if (!token) {
+    return c.json({ code: 401, message: '未授权访问' }, 401);
+  }
+
+  // 2. 验证token并获取用户信息
+  const user = await verifyToken(token);
+  if (!user) {
+    return c.json({ code: 401, message: '无效token' }, 401);
+  }
+
+  // 3. 设置用户上下文
+  c.set('user', user);
+
+  // 4. 设置租户上下文（从用户信息中提取租户ID）
+  const tenantId = user.tenantId;
+  if (tenantId) {
+    await TenantContext.runWithTenant(tenantId, async () => {
+      await next();
+    });
+  } else {
+    await next();
+  }
+};
+```
+
+### 数据库迁移策略
+
+```sql
+-- 多租户表使用不同的表名或schema
+-- 方案1: 使用不同表名
+CREATE TABLE users_mt (
+  id SERIAL PRIMARY KEY,
+  tenant_id INTEGER NOT NULL,
+  username VARCHAR(50) NOT NULL,
+  -- ... 其他字段
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 方案2: 使用不同schema
+CREATE SCHEMA IF NOT EXISTS tenant_1;
+CREATE TABLE tenant_1.users (
+  id SERIAL PRIMARY KEY,
+  username VARCHAR(50) NOT NULL,
+  -- ... 其他字段
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 创建索引优化租户查询
+CREATE INDEX idx_users_mt_tenant_id ON users_mt(tenant_id);
+CREATE INDEX idx_orders_mt_tenant_id ON orders_mt(tenant_id);
+CREATE INDEX idx_goods_mt_tenant_id ON goods_mt(tenant_id);
+```
+
+### 包依赖配置
+
+```json
+// 多租户包的package.json
+{
+  "name": "@d8d/user-module-mt",
+  "version": "1.0.0",
+  "dependencies": {
+    "@d8d/shared-crud": "workspace:*",
+    "@d8d/shared-types": "workspace:*",
+    "@d8d/shared-utils": "workspace:*"
+    // 不依赖其他业务包，避免循环依赖
+  }
+}
+```
+
+## 实施策略
+
+### 阶段化实施
+1. **第一阶段**: 基础架构和主数据包（租户、用户、文件、认证）
+2. **第二阶段**: 核心业务包多租户化（地理区域、地址、商户、供应商、商品）
+3. **第三阶段**: 业务包多租户化和系统集成（订单、小程序支付、广告）
+4. **第四阶段**: 系统集成和租户管理
+
+### 并行开发支持
+- 单租户系统继续正常开发和维护
+- 多租户系统独立开发，不影响现有功能
+- 新功能在两套系统中分别实现或通过配置共享
+
+### 数据迁移策略
+- 多租户系统使用全新数据库表，不迁移现有数据
+- 提供数据导出导入工具，支持从单租户迁移到多租户
+- 保持两套系统数据独立
+
+## 优势分析
+
+### 复制包方案的优势
+1. **风险可控**: 两套系统完全独立，互不影响
+2. **实现简单**: 基于现有代码复制，技术复杂度低
+3. **维护明确**: 单租户和多租户维护责任清晰分离
+4. **部署灵活**: 可以独立部署单租户或多租户系统
+5. **回滚简单**: 多租户系统可随时移除，不影响单租户
+
+### 相比可配置方案的权衡
+- **代码重复**: 业务逻辑需要维护两套
+- **维护成本**: 长期维护成本较高
+- **功能同步**: 新功能需要在两套系统中分别实现
+- **技术债务**: 存在一定的技术债务积累
+
+## 技术实现要点
+
+### 向后兼容性保证
+1. **配置可选**: 通过环境变量控制多租户启用
+2. **API 不变**: 现有单租户API接口和行为保持不变
+3. **数据独立**: 多租户使用独立的数据表，不修改现有数据
+4. **性能隔离**: 两套系统性能互不影响
+
+### 安全性考虑
+1. **租户隔离**: 严格的租户数据隔离机制
+2. **权限控制**: 租户间数据访问权限控制
+3. **输入验证**: 所有用户输入进行严格的验证和转义
+4. **审计日志**: 租户操作审计日志记录
+
+### 性能优化
+1. **数据库索引**: 确保租户ID字段有合适的索引
+2. **查询优化**: 租户过滤条件与现有查询条件合并
+3. **连接池**: 优化数据库连接池配置
+4. **缓存策略**: 租户级缓存策略
+
+## 测试策略
+
+### 单元测试
+- 单租户包功能回归测试
+- 多租户包功能完整测试
+- 租户数据隔离测试
+- 权限控制测试
+
+### 集成测试
+- 单租户系统完整功能测试
+- 多租户系统完整功能测试
+- 租户切换测试
+- 性能基准测试
+
+### 回归测试
+- 现有单租户功能回归测试
+- 向后兼容性验证测试
+- 配置迁移测试
+
+---
+
+## Story Manager Handoff
+
+"请为此brownfield epic开发详细的用户故事。关键考虑因素：
+
+- 这是基于现有TypeScript + Node.js + TypeORM + Hono系统的多租户复制包方案
+- 集成点：现有业务包、共享包、数据库schema、server配置
+- 要遵循的现有模式：模块化架构、CRUD操作、认证中间件
+- 关键兼容性要求：现有单租户系统完全不变、多租户系统独立部署、共享包复用
+- 每个故事必须包含验证现有功能保持完整的检查
+
+该epic应在提供多租户支持的同时，通过复制包方案保持系统完整性和风险可控性。"
+
+## 总结
+
+多租户复制包方案为用户提供了明确的实施路径：
+
+1. **风险可控**: 两套系统完全独立，互不影响
+2. **实施简单**: 基于现有代码复制，技术复杂度低
+3. **维护明确**: 单租户和多租户维护责任清晰分离
+4. **部署灵活**: 可以独立部署单租户或多租户系统
+
+虽然存在代码重复和维护成本增加的权衡，但该方案在风险控制、实施简单性和团队接受度方面具有明显优势，特别适合需要快速实现多租户支持且对现有系统稳定性要求极高的场景。
+
+---
+
+**🤖 Generated with [Claude Code](https://claude.com/claude-code)**
+
+**Co-Authored-By: Claude <noreply@anthropic.com>**