mini-starter/docs/stories/007.005.geo-areas-module-multi-tenant-replication.md

Story 007.005: 地理区域模块多租户复制和租户支持

Status

Ready for Development

Story

As a 系统管理员， I want 复制地理区域模块为多租户版本并添加租户ID字段支持， so that 地理区域数据可以实现租户隔离，同时保持单租户版本完全可用。

Acceptance Criteria

1. 成功复制 @d8d/geo-areas 为 @d8d/geo-areas-mt
2. 在区域实体中添加租户ID字段，表名为 areas_mt
3. 所有区域CRUD操作支持租户过滤
4. 区域树形结构查询支持租户隔离
5. 租户数据隔离验证通过
6. 单租户版本功能完全保留且不受影响
7. API集成测试通过
8. 性能基准测试无明显下降

Tasks / Subtasks

• [ ] 复制地理区域模块为多租户版本 (AC: 1)

  • 复制 packages/geo-areas 为 packages/geo-areas-mt
  • 更新包配置为 @d8d/geo-areas-mt
  • 更新依赖：
  • 将 @d8d/user-module 替换为 @d8d/user-module-mt
  • 将 @d8d/auth-module 替换为 @d8d/auth-module-mt
  • 将 @d8d/file-module 替换为 @d8d/file-module-mt

• [ ] 更新多租户区域实体 (AC: 2)

  • 创建 AreaEntityMt 实体，表名为 areas_mt
  • 添加 tenantId 字段
  • 保持其他字段与单租户版本一致

• [ ] 更新多租户区域服务 (AC: 3, 4)

  • 创建 AreaServiceMt 服务
  • 所有查询操作自动添加租户过滤
  • 创建操作自动设置租户ID
  • 更新区域树形结构查询支持租户隔离
  • 更新层级查询方法支持租户过滤

• [ ] 更新多租户路由配置 (AC: 3)

  • 更新区域路由使用多租户实体和服务
  • 保持API接口与单租户版本一致
  • 更新认证中间件支持租户ID提取

• [ ] 更新Schema定义 (AC: 3)

  • 创建多租户区域Schema AreaSchemaMt
  • 添加租户ID字段定义

• [ ] 实现租户数据隔离API测试 (AC: 5)

  • 在 packages/geo-areas-mt/tests/integration/areas.integration.test.ts 中添加租户隔离测试用例
  • 在 packages/geo-areas-mt/tests/integration/admin-areas.integration.test.ts 中添加跨租户区域访问安全验证
  • 在现有功能测试中验证租户过滤功能正确性

• [ ] 验证单租户系统完整性 (AC: 6)

  • 运行单租户地理区域模块回归测试
  • 验证单租户API接口不受影响
  • 确认单租户数据库表结构不变

• [ ] 执行性能基准测试 (AC: 8)

  • 运行多租户地理区域模块性能测试
  • 比较单租户与多租户性能差异
  • 确保性能影响小于5%

Dev Notes

技术栈信息

[Source: architecture/tech-stack.md]

• 运行时: Node.js 20.18.3
• 框架: Hono 4.8.5 (Web框架和API路由)
• 数据库: PostgreSQL 17 + TypeORM 0.3.25
• 包管理: pnpm workspace

编码标准

[Source: architecture/coding-standards.md]

• 代码风格: TypeScript严格模式
• 测试框架: Vitest + hono/testing + shared-test-util
• 测试位置: packages/geo-areas-mt/tests/integration/
• 测试重点: API集成测试、租户数据隔离验证、区域树形结构功能

项目结构

• 包位置: packages/geo-areas-mt/
• 实体位置: packages/geo-areas-mt/src/modules/areas/
• 服务位置: packages/geo-areas-mt/src/modules/areas/
• 路由位置: packages/geo-areas-mt/src/api/
• Schema位置: packages/geo-areas-mt/src/modules/areas/

多租户架构要求

[Source: docs/prd/epic-007-multi-tenant-package-replication.md]

• 包命名: 使用 -mt 后缀区分多租户版本
• 表命名: 使用 _mt 后缀避免冲突
• 租户ID: 所有实体添加 tenantId 字段
• 数据隔离: 所有查询自动添加租户过滤
• 依赖关系: 多租户模块间正常依赖

地理区域模块特性

[Source: packages/geo-areas/src/modules/areas/area.entity.ts]

• 区域层级: 省/直辖市(1)、市(2)、区/县(3)、街道/乡镇(4)
• 树形结构: 自关联实体，支持完整的省市区树形查询
• 行政区划代码: 唯一的行政区划代码字段
• 状态管理: 启用/禁用状态和软删除支持

多租户区域存储策略

• 表名: areas_mt
• 租户ID: 所有区域记录关联租户ID
• 数据隔离: 通过租户ID过滤确保数据安全
• 树形查询: 树形结构查询自动添加租户过滤

测试要求

• 集成测试: packages/geo-areas-mt/tests/integration/**/*.test.ts
• 测试框架: Vitest + shared-test-util
• 测试重点: API功能验证、租户数据隔离、区域树形查询、跨租户安全
• 现有测试文件:
  • packages/geo-areas-mt/tests/integration/areas.integration.test.ts - 区域API集成测试
  • packages/geo-areas-mt/tests/integration/admin-areas.integration.test.ts - 管理区域API集成测试
  • packages/geo-areas-mt/tests/utils/integration-test-utils.ts - 测试断言工具
  • packages/geo-areas-mt/tests/utils/test-data-factory.ts - 测试数据工厂

依赖关系

• 必需依赖:
  • @d8d/user-module-mt (替换现有的 @d8d/user-module)
  • @d8d/auth-module-mt (替换现有的 @d8d/auth-module)
  • @d8d/file-module-mt (替换现有的 @d8d/file-module)
• 共享依赖:
  • @d8d/shared-crud (保持)
  • @d8d/shared-types (保持)
  • @d8d/shared-utils (保持)
• 测试依赖:
  • @d8d/shared-test-util (保持)
• 框架依赖:
  • hono, @hono/zod-openapi, typeorm, zod (保持)

共享CRUD包租户隔离支持

[Source: packages/shared-crud/src/routes/generic-crud.routes.ts]

• 当前状态: ✅ 已完成增强，支持完整的租户隔离功能
• 配置选项:
  • tenantOptions.enabled: 启用/禁用租户隔离
  • tenantOptions.tenantIdField: 租户ID字段名（默认 'tenantId'）
  • tenantOptions.autoExtractFromContext: 自动从上下文提取租户ID

数据库变更

• 新表: areas_mt
• 索引: 为 tenantId 字段创建索引
• 迁移: 使用独立迁移文件，不影响现有表

Change Log

Date	Version	Description	Author
2025-11-13	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

• James (全栈开发专家)

Completion Summary

⏳ 故事007.005待开发

待完成任务:

1. ⏳ 复制地理区域模块为多租户版本

   • 复制 packages/geo-areas 为 packages/geo-areas-mt
   • 更新包配置为 @d8d/geo-areas-mt
   • 添加多租户模块依赖：@d8d/user-module-mt

2. ⏳ 更新多租户区域实体

   • 创建 AreaEntityMt 实体，表名为 areas_mt
   • 添加 tenantId 字段

3. ⏳ 更新多租户区域服务

   • 创建 AreaServiceMt 服务
   • 所有查询操作自动添加租户过滤
   • 更新区域树形结构查询支持租户隔离

4. ⏳ 更新多租户路由配置

   • 更新区域路由使用多租户实体和服务
   • 配置CRUD路由支持租户隔离

5. ⏳ 更新Schema定义

   • 创建多租户区域Schema AreaSchemaMt
   • 添加租户ID字段定义

6. ⏳ 实现租户数据隔离API测试

   • 编写完整的租户隔离集成测试
   • 包含区域创建、查询、树形查询的租户隔离验证

7. ⏳ 验证单租户系统完整性

   • 确认单租户地理区域模块功能不受影响
   • 验证API接口兼容性

8. ⏳ 执行性能基准测试

   • 多租户地理区域模块测试全部通过
   • 性能影响在可接受范围内

预期技术实现要点:

• 使用 -mt 后缀区分多租户版本
• 使用 _mt 后缀避免表名冲突
• 所有查询自动添加租户过滤条件
• 区域树形结构查询支持租户隔离
• 保持API接口与单租户版本完全兼容

QA Results

⏳ 质量保证验证待执行