📝 docs(epic-007): 更新技术栈差异分析与移植方案

- 新增【技术栈对比分析】章节，详细对比Hono与NestJS在Web框架、路由、验证等关键方面的差异
- 新增【关键依赖对比】表格，明确源系统与目标系统的依赖库差异
- 新增【移植调整方案】章节，包含架构转换策略、实体层、服务层、路由层及验证系统的具体转换示例
- 新增【兼容性保证】说明，明确需要保持、调整和新增的内容
- 更新【故事】部分，强调技术栈转换的验证工作，并调整故事描述以反映从NestJS到Hono的迁移
- 更新【故事经理交接说明】，补充技术栈差异分析结果和转换策略，明确架构迁移的关键考虑点

docs/epic-007.md

@@ -167,7 +167,117 @@ allin-packages/{module-name}/
 4. 包名使用`@d8d/allin-`前缀，如`@d8d/allin-channel-module`
 5. 导出必要的服务和实体
 
-### 5. 依赖关系解决方案
+### 5. 技术栈差异分析与移植方案
+
+#### 技术栈对比分析
+
+| 方面 | 当前项目（目标） | allin_system-master（源） | 差异程度 |
+|------|------------------|---------------------------|----------|
+| **Web框架** | Hono（轻量级） | NestJS（重量级） | **重大** |
+| **路由系统** | Hono路由 | NestJS装饰器路由 | **重大** |
+| **验证库** | Zod + @hono/zod-openapi | class-validator + class-transformer | **中等** |
+| **服务架构** | GenericCrudService继承 | 自定义Service类 | **中等** |
+| **实体配置** | 详细TypeORM装饰器 | 简单TypeORM装饰器 | **轻微** |
+| **命名规范** | 驼峰命名（channelId） | 下划线命名（channel_id） | **轻微** |
+| **模块系统** | npm包 + workspace | NestJS模块系统 | **重大** |
+| **API风格** | RESTful + OpenAPI | 自定义端点 | **中等** |
+
+#### 关键依赖对比
+- **当前项目**：`@d8d/core-module`、`@d8d/shared-crud`、`@d8d/shared-utils`、TypeORM、Hono、Zod
+- **allin_system**：`@nestjs/*`、TypeORM、class-validator、Passport/JWT
+
+#### 移植调整方案
+
+##### A. 架构转换策略
+1. **NestJS控制器 → Hono路由**：重写路由层
+2. **自定义Service → GenericCrudService继承**：重构服务层
+3. **class-validator DTO → Zod Schema**：转换验证逻辑
+4. **NestJS模块 → npm包**：重新组织模块结构
+
+##### B. 实体层转换示例
+```typescript
+// 原allin实体（下划线命名）
+@Entity('channel_info')
+export class Channel {
+  @PrimaryGeneratedColumn('increment')
+  channel_id: number;  // 下划线
+  @Column()
+  channel_name: string;
+}
+
+// 转换后实体（驼峰命名，详细配置）
+@Entity('channel_info')
+export class Channel {
+  @PrimaryGeneratedColumn({ name: 'channel_id', type: 'int' })
+  channelId!: number;  // 驼峰
+  @Column({ name: 'channel_name', type: 'varchar', length: 100 })
+  channelName!: string;
+}
+```
+
+##### C. 服务层转换示例
+```typescript
+// 原allin服务（NestJS风格）
+@Injectable()
+export class ChannelService {
+  constructor(@InjectRepository(Channel) private repo: Repository<Channel>) {}
+  async createChannel(data: CreateChannelDto): Promise<boolean> {
+    // 自定义逻辑
+  }
+}
+
+// 转换后服务（Hono + GenericCrudService）
+export class ChannelService extends GenericCrudService<Channel> {
+  constructor(dataSource: DataSource) {
+    super(dataSource, Channel, {
+      searchFields: ['channelName', 'contactPerson'],
+    });
+  }
+  // 保留特殊业务方法
+  async createChannel(data: CreateChannelDto): Promise<boolean> {
+    // 复用或重写逻辑
+  }
+}
+```
+
+##### D. 路由层转换示例
+```typescript
+// 原NestJS控制器
+@Controller('channel')
+@UseGuards(JwtAuthGuard)
+export class ChannelController {
+  @Post('createChannel')
+  createChannel(@Body() req: CreateChannelDto) {
+    return this.service.createChannel(req);
+  }
+}
+
+// 转换后Hono路由
+import { OpenAPIHono } from '@hono/zod-openapi';
+const channelRoutes = new OpenAPIHono()
+  .post('/createChannel', async (c) => {
+    const data = await c.req.json();
+    const result = await channelService.createChannel(data);
+    return c.json({ success: result });
+  });
+```
+
+##### E. 验证系统转换
+```typescript
+// 原class-validator DTO
+export class CreateChannelDto {
+  @IsString()
+  channel_name: string;
+}
+
+// 转换后Zod Schema
+export const CreateChannelSchema = z.object({
+  channelName: z.string().min(1).max(100),
+});
+export type CreateChannelDto = z.infer<typeof CreateChannelSchema>;
+```
+
+#### 依赖关系解决方案
 
 针对发现的循环依赖问题（order ↔ disability_person），解决方案：
 
@@ -182,37 +292,155 @@ allin-packages/{module-name}/
 3. `allin-company-module`（依赖platform）
 4. `allin-order-module`和`allin-disability-module`（最后处理，解决循环依赖）
 
-## 故事（更新后）
-
-**注**：故事1的分析工作已完成，结果见上方"模块分析结果"部分。
-
-1. **故事2：创建基础包模板和移植工具**
-   - 创建`allin-packages`目录结构
-   - 创建标准的独立包模板（参考auth-module结构）
-   - 开发自动化移植脚本
-   - 配置workspace依赖管理（使用`@d8d/allin-`前缀）
-   - 准备TypeScript配置和构建脚本
-   - 创建package.json模板
-
-2. **故事3：移植基础独立模块**
-   - 移植`allin-platform-module`（基础依赖）
-   - 移植`allin-channel-module`（独立模块）
-   - 移植`allin-dict-module`（独立模块）
-   - 移植`allin-salary-module`（独立模块）
-   - 验证基础模块功能
-
-3. **故事4：移植依赖模块和解决循环依赖**
-   - 移植`allin-company-module`（依赖platform-module）
-   - 处理`allin-order-module`和`allin-disability-module`的循环依赖
-   - 创建共享实体或接口抽象
-   - 移植两个复杂模块的核心功能
-
-4. **故事5：完成移植和集成验证**
-   - 完成所有7个模块的移植
-   - 解决剩余的依赖问题
-   - 进行整体功能验证
-   - 运行类型检查和基本测试
-   - 更新文档和配置
+#### 兼容性保证
+- **保持**：数据库表结构、核心业务逻辑、数据关系
+- **调整**：API端点路径、请求/响应格式、错误处理
+- **新增**：OpenAPI文档、标准化CRUD操作、类型安全验证
+
+## 故事分解（按模块拆分）
+
+**注**：每个故事对应一个模块的完整移植，包括技术栈转换和API集成测试。
+
+### 故事1：移植渠道管理模块（channel_info → @d8d/allin-channel-module）
+**目标**：将channel_info模块移植为独立包，完成技术栈转换并验证功能完整性
+
+**验收标准**：
+1. ✅ 创建`allin-packages/channel-module`目录结构
+2. ✅ 完成实体转换：`Channel`实体从下划线命名转换为驼峰命名
+3. ✅ 完成服务层转换：从NestJS自定义Service转换为GenericCrudService继承
+4. ✅ 完成路由层转换：从NestJS控制器转换为Hono路由
+5. ✅ 完成验证系统转换：从class-validator DTO转换为Zod Schema
+6. ✅ 配置package.json：使用`@d8d/allin-channel-module`包名，workspace依赖
+7. ✅ 编写API集成测试：覆盖所有路由端点，验证CRUD操作
+8. ✅ 通过类型检查和基本测试验证
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/channel.integration.test.ts`
+- 测试覆盖：GET/POST/PUT/DELETE所有端点
+- 验证：认证、授权、数据验证、错误处理
+- 遵循现有集成测试模式（参考advertisements-module）
+
+### 故事2：移植公司管理模块（company → @d8d/allin-company-module）
+**目标**：将company模块移植为独立包，处理对platform-module的依赖
+
+**验收标准**：
+1. ✅ 创建`allin-packages/company-module`目录结构
+2. ✅ 完成实体转换：`Company`实体转换
+3. ✅ 处理模块依赖：正确配置对`@d8d/allin-platform-module`的依赖
+4. ✅ 完成服务层转换：处理跨模块业务逻辑
+5. ✅ 完成路由层转换：Hono路由实现
+6. ✅ 完成验证系统转换：Zod Schema定义
+7. ✅ 配置package.json：workspace依赖管理
+8. ✅ 编写API集成测试：验证模块间依赖正常工作
+9. ✅ 通过类型检查和基本测试验证
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/company.integration.test.ts`
+- 测试覆盖：公司管理的所有业务场景
+- 验证：与platform-module的集成、数据关联查询
+- 包含跨模块数据一致性测试
+
+### 故事3：移植字典管理模块（dict_management → @d8d/allin-dict-module）
+**目标**：将dict_management模块移植为独立包，验证独立模块移植模式
+
+**验收标准**：
+1. ✅ 创建`allin-packages/dict-module`目录结构
+2. ✅ 完成实体转换：`Dict`实体转换
+3. ✅ 完成服务层转换：独立业务逻辑处理
+4. ✅ 完成路由层转换：Hono路由实现
+5. ✅ 完成验证系统转换：Zod Schema定义
+6. ✅ 配置package.json：独立包配置
+7. ✅ 编写API集成测试：验证字典CRUD操作
+8. ✅ 通过类型检查和基本测试验证
+9. ✅ 验证技术栈转换模板的适用性
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/dict.integration.test.ts`
+- 测试覆盖：字典分类、字典项管理
+- 验证：树形结构处理、状态管理、排序功能
+- 包含复杂查询场景测试
+
+### 故事4：移植残疾人管理模块（disability_person → @d8d/allin-disability-module）
+**目标**：移植最复杂的模块，处理5个实体和跨模块依赖
+
+**验收标准**：
+1. ✅ 创建`allin-packages/disability-module`目录结构
+2. ✅ 完成实体转换：5个实体（DisabledPerson、DisabledBankCard等）转换
+3. ✅ 处理跨模块依赖：引用order、platform、company、channel模块实体
+4. ✅ 完成服务层转换：复杂业务逻辑处理
+5. ✅ 完成路由层转换：多个控制器转换为Hono路由
+6. ✅ 完成验证系统转换：复杂数据验证
+7. ✅ 配置package.json：处理多个依赖
+8. ✅ 编写API集成测试：覆盖所有5个实体的管理功能
+9. ✅ 通过类型检查和基本测试验证
+10. ✅ 解决与order-module的循环依赖问题
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/disability.integration.test.ts`
+- 测试覆盖：残疾人信息、银行卡、照片、备注、走访记录
+- 验证：多实体关联、文件上传、复杂业务规则
+- 包含性能测试：大数据量查询
+
+### 故事5：移植订单管理模块（order → @d8d/allin-order-module）
+**目标**：移植订单模块，处理与disability-module的循环依赖
+
+**验收标准**：
+1. ✅ 创建`allin-packages/order-module`目录结构
+2. ✅ 完成实体转换：3个实体（EmploymentOrder、OrderPerson等）转换
+3. ✅ 解决循环依赖：与disability-module的相互引用处理
+4. ✅ 完成服务层转换：订单业务逻辑
+5. ✅ 完成路由层转换：Hono路由实现
+6. ✅ 完成验证系统转换：订单相关验证
+7. ✅ 配置package.json：依赖管理
+8. ✅ 编写API集成测试：覆盖订单全生命周期
+9. ✅ 通过类型检查和基本测试验证
+10. ✅ 验证循环依赖解决方案的有效性
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/order.integration.test.ts`
+- 测试覆盖：订单创建、人员分配、资产关联、状态流转
+- 验证：与disability-module的集成、业务规则执行
+- 包含工作流测试：订单状态机
+
+### 故事6：移植平台管理模块（platform → @d8d/allin-platform-module）
+**目标**：移植基础模块，作为其他模块的依赖
+
+**验收标准**：
+1. ✅ 创建`allin-packages/platform-module`目录结构
+2. ✅ 完成实体转换：`Platform`实体转换
+3. ✅ 完成服务层转换：基础CRUD服务
+4. ✅ 完成路由层转换：Hono路由实现
+5. ✅ 完成验证系统转换：Zod Schema定义
+6. ✅ 配置package.json：作为基础依赖包
+7. ✅ 编写API集成测试：验证基础功能
+8. ✅ 通过类型检查和基本测试验证
+9. ✅ 验证作为依赖包被其他模块引用的能力
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/platform.integration.test.ts`
+- 测试覆盖：平台CRUD操作
+- 验证：作为基础数据的完整性和一致性
+- 包含被引用场景的模拟测试
+
+### 故事7：移植薪资管理模块（salary → @d8d/allin-salary-module）
+**目标**：移植独立模块，完成所有模块移植
+
+**验收标准**：
+1. ✅ 创建`allin-packages/salary-module`目录结构
+2. ✅ 完成实体转换：`SalaryLevel`实体转换
+3. ✅ 完成服务层转换：薪资业务逻辑
+4. ✅ 完成路由层转换：Hono路由实现
+5. ✅ 完成验证系统转换：Zod Schema定义
+6. ✅ 配置package.json：独立包配置
+7. ✅ 编写API集成测试：验证薪资管理功能
+8. ✅ 通过类型检查和基本测试验证
+9. ✅ 整体验证：所有7个模块的集成测试
+
+**API集成测试要求**：
+- 测试文件：`tests/integration/salary.integration.test.ts`
+- 测试覆盖：薪资等级管理、关联查询
+- 验证：数值计算、等级规则
+- 包含整体集成测试：验证所有模块协同工作
 
 ## 兼容性要求
 
@@ -259,22 +487,50 @@ allin-packages/{module-name}/
 
 ## 故事经理交接说明
 
-"模块分析已完成，关键发现：
+"模块分析和技术栈分析已完成，关键发现：
 
 1. **依赖关系分析完成**：7个模块的依赖关系已明确，发现order和disability_person模块存在循环依赖
-2. **命名方案确定**：使用`@d8d/allin-`前缀，`-module`后缀，非多租户版本
-3. **目录结构**：在根目录创建`allin-packages/`目录存放专属包
-4. **移植顺序建议**：platform → channel/dict/salary → company → order/disability
-
-请基于以上分析开发详细的用户故事。关键考虑：
-
-- 这是对运行TypeScript、NestJS、PostgreSQL、Redis、MinIO的现有系统的增强
-- **只移植有实体的7个模块**，映射关系已确定（使用`@d8d/allin-`前缀）
-- **目录结构**：模块将放置在`allin-packages/`目录下
-- **循环依赖问题**：order和disability_person模块需要特殊处理
-- 集成点：模块间API调用、数据库访问、配置共享
-- 要遵循的现有模式：workspace依赖、模块化结构
-- 关键兼容性要求：API接口不变、数据库schema兼容、性能影响最小
-- 每个故事必须包含验证现有功能保持完整的检查
-
-史诗应在保持系统完整性的同时实现将有实体模块移植为标准化独立包的目标。"
+2. **技术栈差异分析完成**：源系统使用NestJS，目标系统使用Hono，存在重大架构差异
+3. **命名方案确定**：使用`@d8d/allin-`前缀，`-module`后缀，非多租户版本
+4. **目录结构**：在根目录创建`allin-packages/`目录存放专属包
+5. **移植顺序建议**：platform → channel/dict/salary → company → order/disability
+6. **技术栈转换方案**：已制定从NestJS到Hono的详细转换策略
+7. **故事拆分完成**：按模块拆分为7个故事，每个故事包含API集成测试要求
+
+**新的故事拆分方案**：
+- **故事1**：移植渠道管理模块（channel_info → @d8d/allin-channel-module）
+- **故事2**：移植公司管理模块（company → @d8d/allin-company-module）
+- **故事3**：移植字典管理模块（dict_management → @d8d/allin-dict-module）
+- **故事4**：移植残疾人管理模块（disability_person → @d8d/allin-disability-module）
+- **故事5**：移植订单管理模块（order → @d8d/allin-order-module）
+- **故事6**：移植平台管理模块（platform → @d8d/allin-platform-module）
+- **故事7**：移植薪资管理模块（salary → @d8d/allin-salary-module）
+
+**每个故事的关键要求**：
+1. **技术栈转换**：必须完成实体、服务、路由、验证的完整转换
+2. **API集成测试**：必须编写`tests/integration/{module}.integration.test.ts`文件
+3. **测试覆盖**：必须覆盖所有路由端点，验证CRUD操作
+4. **遵循现有模式**：参考advertisements-module的集成测试模式
+5. **验证要求**：认证、授权、数据验证、错误处理
+
+**执行顺序建议**：
+1. 先执行**故事6**（platform-module）：基础依赖模块
+2. 然后执行**故事1、3、7**（channel、dict、salary）：独立模块
+3. 接着执行**故事2**（company-module）：依赖platform
+4. 最后执行**故事4、5**（disability、order）：处理循环依赖
+
+**技术栈转换关键点**：
+- **NestJS控制器 → Hono路由**：使用OpenAPIHono
+- **class-validator DTO → Zod Schema**：使用z.object()定义
+- **自定义Service → GenericCrudService继承**：复用现有CRUD模式
+- **下划线命名 → 驼峰命名**：实体字段名转换
+- **模块间依赖**：通过workspace依赖管理
+
+**API集成测试模板参考**：
+参考`/packages/advertisements-module/tests/integration/advertisements.integration.test.ts`
+- 使用`testClient`创建测试客户端
+- 使用`setupIntegrationDatabaseHooksWithEntities`设置测试数据库
+- 包含认证测试、数据验证测试、错误处理测试
+- 每个端点都要有成功和失败场景测试
+
+史诗应在保持系统完整性的同时实现将有实体模块从NestJS架构移植到Hono架构的标准化独立包，每个模块都要有完整的API集成测试验证。"