史诗007 - Allin System有实体模块移植到独立包

史诗目标

将allin_system-master/server/src目录下有对应数据库实体的模块移植到packages目录下，作为非多租户独立包，遵循项目现有的独立包结构和命名规范，实现模块的现代化重构和标准化管理。

史诗描述

现有系统上下文

当前相关功能：allin_system-master是一个基于NestJS的后端系统，根据allin_2025-11-25.sql分析，有以下有实体的模块：
1. channel_info模块 - 对应channel_info表
2. company模块 - 对应employer_company表
3. dict_management模块 - 对应sys_dict表
4. disability_person模块 - 对应disabled_person、disabled_bank_card、disabled_photo、disabled_remark、disabled_visit表
5. order模块 - 对应employment_order、order_person、order_person_asset表
6. platform模块 - 对应employer_platform表
7. salary模块 - 对应salary_level表
无实体模块（本次不移植）：admin、auth、users模块
技术栈：TypeScript、NestJS、PostgreSQL、Redis、MinIO
集成点：模块间通过NestJS模块系统集成，共享数据库连接和配置

增强详情

新增/变更内容：将7个有实体的现有模块从allin_system-master/server/src移植到packages目录下的独立包
集成方式：每个模块将重构为独立的npm包，遵循@d8d命名规范，通过workspace依赖管理
成功标准：
1. 7个有实体模块成功移植为独立包
2. 保持原有功能完整性
3. 遵循现有独立包结构模式
4. 通过类型检查和基本测试验证

模块分析结果

1. 模块依赖关系分析

根据对每个模块module.ts文件的分析，依赖关系如下：

channel_info模块 (channel.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm
- 实体：Channel (对应channel_info表)
- 无其他模块依赖
company模块 (company.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm, PlatformModule
- 实体：Company (对应employer_company表)
- 依赖模块：platform
dict_management模块 (dict.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm
- 实体：Dict (对应sys_dict表)
- 无其他模块依赖
disability_person模块 (disability_person.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm
- 实体：DisabledPerson, DisabledBankCard, DisabledPhoto, DisabledRemark, DisabledVisit
- 引用其他模块实体：EmploymentOrder, OrderPerson (order模块), Platform (platform模块), Company (company模块), Channel (channel_info模块)
- 复杂度：高（5个实体，多个控制器和服务）
order模块 (order.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm
- 实体：EmploymentOrder, OrderPerson, OrderPersonAsset
- 引用其他模块实体：DisabledPerson (disability_person模块), Platform (platform模块), Company (company模块), Channel (channel_info模块)
- 复杂度：中高（3个实体，跨模块依赖）
platform模块 (platform.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm
- 实体：Platform (对应employer_platform表)
- 无其他模块依赖
- 被依赖：company模块依赖此模块
salary模块 (salary.module.ts)
- 依赖：@nestjs/common, @nestjs/typeorm
- 实体：SalaryLevel (对应salary_level表)
- 无其他模块依赖

2. 依赖关系图

platform ───┐
            ↓
company ────┐
            ↓
channel_info ─┐
            ↓ ↓
order ───────┘
            ↑
disability_person
            ↑
dict_management (独立)
salary (独立)

关键发现：

platform模块是基础依赖，被company模块直接依赖
company、channel_info模块被order和disability_person模块引用
order和disability_person模块相互引用实体，形成循环依赖
dict_management和salary模块完全独立

3. 模块到独立包的映射方案

基于现有项目命名规范，并考虑这是Allin系统专属模块，制定以下映射方案：

原模块名	独立包名	目录名	说明
channel_info	`@d8d/allin-channel-module`	`channel-module`	渠道管理模块
company	`@d8d/allin-company-module`	`company-module`	公司管理模块，依赖platform-module
dict_management	`@d8d/allin-dict-module`	`dict-module`	字典管理模块
disability_person	`@d8d/allin-disability-module`	`disability-module`	残疾人管理模块（简化名称）
order	`@d8d/allin-order-module`	`order-module`	订单管理模块
platform	`@d8d/allin-platform-module`	`platform-module`	平台管理模块
salary	`@d8d/allin-salary-module`	`salary-module`	薪资管理模块

命名原则：

包名前缀：使用@d8d/allin-前缀，明确表明是Allin系统专属包
目录名：使用简洁的{模块名}-module格式，便于在allin-packages目录中管理
模块名：使用单数形式 + -module后缀
名称简洁：反映模块核心功能
非多租户：不使用-mt后缀（本次移植为非多租户版本）

4. 目录结构和包规范

目录结构决策

由于这些模块是allin_system-master项目独有的业务模块（非通用模块），将在项目根目录创建独立目录：

项目根目录/
├── allin-packages/          # Allin系统专属包目录
│   ├── channel-module/      # 渠道管理模块
│   ├── company-module/      # 公司管理模块
│   ├── dict-module/         # 字典管理模块
│   ├── disability-module/   # 残疾人管理模块
│   ├── order-module/        # 订单管理模块
│   ├── platform-module/     # 平台管理模块
│   └── salary-module/       # 薪资管理模块
├── packages/                # 现有通用包目录（保持不变）
└── allin_system-master/     # 原始代码目录（移植源）

目录命名说明：allin-packages清晰表明这是Allin系统专属的包目录，与allin_system-master源目录对应，区别于通用的packages目录。

包结构规范

参考现有auth-module结构，每个独立包应包含：

allin-packages/{module-name}/
├── package.json          # 包配置，workspace依赖管理
├── tsconfig.json        # TypeScript配置
├── vitest.config.ts     # 测试配置（如需要）
├── src/
│   ├── index.ts         # 主导出文件
│   ├── schemas/         # Zod模式定义（如需要）
│   │   └── index.ts
│   ├── entities/        # 数据库实体
│   ├── services/        # 业务服务
│   ├── controllers/     # API控制器
│   ├── dtos/           # 数据传输对象
│   └── types/          # TypeScript类型定义
└── dist/               # 构建输出

关键配置要求：

package.json中设置"type": "module"
主入口为src/index.ts
使用workspace依赖："@d8d/core-module": "workspace:*"
包名使用@d8d/allin-前缀，如@d8d/allin-channel-module
导出必要的服务和实体

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. 架构转换策略

NestJS控制器 → Hono路由：重写路由层
自定义Service → GenericCrudService继承：重构服务层
class-validator DTO → Zod Schema：转换验证逻辑
NestJS模块 → npm包：重新组织模块结构

B. 实体层转换示例

// 原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. 服务层转换示例

// 原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. 路由层转换示例

// 原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. 验证系统转换

// 原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），解决方案：

创建共享实体包：将相互引用的实体提取到共享包
接口抽象：使用接口而非具体实体引用
依赖注入调整：重构服务层减少直接实体依赖
移植顺序策略：按依赖顺序移植，先移植基础模块

建议移植顺序：

allin-platform-module（基础）
allin-channel-module、allin-dict-module、allin-salary-module（独立）
allin-company-module（依赖platform）
allin-order-module和allin-disability-module（最后处理，解决循环依赖）

兼容性保证

保持：数据库表结构、核心业务逻辑、数据关系
调整：API端点路径、请求/响应格式、错误处理
新增：OpenAPI文档、标准化CRUD操作、类型安全验证

故事分解（按模块拆分）

注：每个故事对应一个模块的完整移植，包括技术栈转换和API集成测试。

故事1：移植渠道管理模块（channel_info → @d8d/allin-channel-module）

目标：将channel_info模块移植为独立包，完成技术栈转换并验证功能完整性

验收标准：

✅ 创建allin-packages/channel-module目录结构
✅ 完成实体转换：Channel实体从下划线命名转换为驼峰命名
✅ 完成服务层转换：从NestJS自定义Service转换为GenericCrudService继承
✅ 完成路由层转换：从NestJS控制器转换为Hono路由
✅ 完成验证系统转换：从class-validator DTO转换为Zod Schema
✅ 配置package.json：使用@d8d/allin-channel-module包名，workspace依赖
✅ 编写API集成测试：覆盖所有路由端点，验证CRUD操作
✅ 通过类型检查和基本测试验证

API集成测试要求：

测试文件：tests/integration/channel.integration.test.ts
测试覆盖：GET/POST/PUT/DELETE所有端点
验证：认证、授权、数据验证、错误处理
遵循现有集成测试模式（参考advertisements-module）

故事2：移植公司管理模块（company → @d8d/allin-company-module）

目标：将company模块移植为独立包，处理对platform-module的依赖

验收标准：

✅ 创建allin-packages/company-module目录结构
✅ 完成实体转换：Company实体转换
✅ 处理模块依赖：正确配置对@d8d/allin-platform-module的依赖
✅ 完成服务层转换：处理跨模块业务逻辑
✅ 完成路由层转换：Hono路由实现
✅ 完成验证系统转换：Zod Schema定义
✅ 配置package.json：workspace依赖管理
✅ 编写API集成测试：验证模块间依赖正常工作
✅ 通过类型检查和基本测试验证

API集成测试要求：

测试文件：tests/integration/company.integration.test.ts
测试覆盖：公司管理的所有业务场景
验证：与platform-module的集成、数据关联查询
包含跨模块数据一致性测试

故事3：移植字典管理模块（dict_management → @d8d/allin-dict-module）

目标：将dict_management模块移植为独立包，验证独立模块移植模式

验收标准：

✅ 创建allin-packages/dict-module目录结构
✅ 完成实体转换：Dict实体转换
✅ 完成服务层转换：独立业务逻辑处理
✅ 完成路由层转换：Hono路由实现
✅ 完成验证系统转换：Zod Schema定义
✅ 配置package.json：独立包配置
✅ 编写API集成测试：验证字典CRUD操作
✅ 通过类型检查和基本测试验证
✅ 验证技术栈转换模板的适用性

API集成测试要求：

测试文件：tests/integration/dict.integration.test.ts
测试覆盖：字典分类、字典项管理
验证：树形结构处理、状态管理、排序功能
包含复杂查询场景测试

故事4：移植残疾人管理模块（disability_person → @d8d/allin-disability-module）

目标：移植最复杂的模块，处理5个实体和跨模块依赖

验收标准：

✅ 创建allin-packages/disability-module目录结构
✅ 完成实体转换：5个实体（DisabledPerson、DisabledBankCard等）转换
✅ 处理跨模块依赖：引用order、platform、company、channel模块实体
✅ 完成服务层转换：复杂业务逻辑处理
✅ 完成路由层转换：多个控制器转换为Hono路由
✅ 完成验证系统转换：复杂数据验证
✅ 配置package.json：处理多个依赖
✅ 编写API集成测试：覆盖所有5个实体的管理功能
✅ 通过类型检查和基本测试验证
✅ 解决与order-module的循环依赖问题

API集成测试要求：

测试文件：tests/integration/disability.integration.test.ts
测试覆盖：残疾人信息、银行卡、照片、备注、走访记录
验证：多实体关联、文件上传、复杂业务规则
包含性能测试：大数据量查询

故事5：移植订单管理模块（order → @d8d/allin-order-module）

目标：移植订单模块，处理与disability-module的循环依赖

验收标准：

✅ 创建allin-packages/order-module目录结构
✅ 完成实体转换：3个实体（EmploymentOrder、OrderPerson等）转换
✅ 解决循环依赖：与disability-module的相互引用处理
✅ 完成服务层转换：订单业务逻辑
✅ 完成路由层转换：Hono路由实现
✅ 完成验证系统转换：订单相关验证
✅ 配置package.json：依赖管理
✅ 编写API集成测试：覆盖订单全生命周期
✅ 通过类型检查和基本测试验证
✅ 验证循环依赖解决方案的有效性

API集成测试要求：

测试文件：tests/integration/order.integration.test.ts
测试覆盖：订单创建、人员分配、资产关联、状态流转
验证：与disability-module的集成、业务规则执行
包含工作流测试：订单状态机

故事6：移植平台管理模块（platform → @d8d/allin-platform-module）

目标：移植基础模块，作为其他模块的依赖

验收标准：

✅ 创建allin-packages/platform-module目录结构
✅ 完成实体转换：Platform实体转换
✅ 完成服务层转换：基础CRUD服务
✅ 完成路由层转换：Hono路由实现
✅ 完成验证系统转换：Zod Schema定义
✅ 配置package.json：作为基础依赖包
✅ 编写API集成测试：验证基础功能
✅ 通过类型检查和基本测试验证
✅ 验证作为依赖包被其他模块引用的能力

API集成测试要求：

测试文件：tests/integration/platform.integration.test.ts
测试覆盖：平台CRUD操作
验证：作为基础数据的完整性和一致性
包含被引用场景的模拟测试

故事7：移植薪资管理模块（salary → @d8d/allin-salary-module）

目标：移植独立模块，完成所有模块移植

验收标准：

✅ 创建allin-packages/salary-module目录结构
✅ 完成实体转换：SalaryLevel实体转换
✅ 完成服务层转换：薪资业务逻辑
✅ 完成路由层转换：Hono路由实现
✅ 完成验证系统转换：Zod Schema定义
✅ 配置package.json：独立包配置
✅ 编写API集成测试：验证薪资管理功能
✅ 通过类型检查和基本测试验证
✅ 整体验证：所有7个模块的集成测试

API集成测试要求：

测试文件：tests/integration/salary.integration.test.ts
测试覆盖：薪资等级管理、关联查询
验证：数值计算、等级规则
包含整体集成测试：验证所有模块协同工作

兼容性要求

现有API接口保持不变
数据库schema保持向后兼容
遵循现有TypeScript配置和构建模式
性能影响最小化

风险缓解

主要风险：模块间依赖关系复杂，移植过程中可能破坏现有功能
缓解措施：逐个模块移植，每个模块完成后进行功能验证
回滚计划：保留原始allin_system-master目录作为备份，可随时恢复

完成定义

所有4个故事完成，验收标准满足
现有功能通过测试验证
集成点正常工作
文档更新适当
现有功能无回归

验证清单

范围验证

史诗可在4个故事内完成
不需要架构文档变更
增强遵循现有模式
集成复杂度可管理

风险评估

对现有系统风险较低
回滚计划可行
测试方法覆盖现有功能
团队对集成点有足够了解

完整性检查

史诗目标清晰可实现
故事范围适当
成功标准可衡量
依赖关系已识别

故事经理交接说明

"模块分析和技术栈分析已完成，关键发现：

依赖关系分析完成：7个模块的依赖关系已明确，发现order和disability_person模块存在循环依赖
技术栈差异分析完成：源系统使用NestJS，目标系统使用Hono，存在重大架构差异
命名方案确定：使用@d8d/allin-前缀，-module后缀，非多租户版本
目录结构：在根目录创建allin-packages/目录存放专属包
移植顺序建议：platform → channel/dict/salary → company → order/disability
技术栈转换方案：已制定从NestJS到Hono的详细转换策略
故事拆分完成：按模块拆分为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）

每个故事的关键要求：

技术栈转换：必须完成实体、服务、路由、验证的完整转换
API集成测试：必须编写tests/integration/{module}.integration.test.ts文件
测试覆盖：必须覆盖所有路由端点，验证CRUD操作
遵循现有模式：参考advertisements-module的集成测试模式
验证要求：认证、授权、数据验证、错误处理

执行顺序建议：

先执行故事6（platform-module）：基础依赖模块
然后执行故事1、3、7（channel、dict、salary）：独立模块
接着执行故事2（company-module）：依赖platform
最后执行故事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集成测试验证。"

epic-007.md 22 KB Riwayat Mentahan

史诗007 - Allin System有实体模块移植到独立包

史诗目标

史诗描述

现有系统上下文

增强详情

模块分析结果

1. 模块依赖关系分析

2. 依赖关系图

3. 模块到独立包的映射方案

4. 目录结构和包规范

目录结构决策

包结构规范

5. 技术栈差异分析与移植方案

技术栈对比分析

关键依赖对比

移植调整方案

A. 架构转换策略

B. 实体层转换示例

C. 服务层转换示例

D. 路由层转换示例

E. 验证系统转换

依赖关系解决方案

兼容性保证

故事分解（按模块拆分）

故事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）

兼容性要求

风险缓解

完成定义

验证清单

范围验证

风险评估

完整性检查

故事经理交接说明

epic-007.md 22 KB

Riwayat Mentahan