📝 docs(story-007.001): 添加渠道管理模块移植故事

创建故事007.001：将allin_system-master的channel_info模块移植为@d8d/allin-channel-module独立包

包含：
- 完整的技术栈转换指导（NestJS → Hono）
- 实体、服务、路由、验证系统的转换方案
- API集成测试要求
- 项目结构对齐说明

🤖 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.001.transplant-channel-management-module.story.md

@@ -0,0 +1,198 @@
+# Story 007.001: 移植渠道管理模块（channel_info → @d8d/allin-channel-module）
+
+## Status
+Draft
+
+## Story
+**As a** 开发者，
+**I want** 将channel_info模块从allin_system-master移植为独立包@d8d/allin-channel-module，完成技术栈转换并验证功能完整性，
+**so that** 我们可以将Allin系统的渠道管理功能集成到当前项目中，遵循现有的模块化架构和编码标准。
+
+## Acceptance Criteria
+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. ✅ 通过类型检查和基本测试验证
+
+## Tasks / Subtasks
+- [ ] 创建`allin-packages/channel-module`目录结构 (AC: 1)
+  - [ ] 创建`allin-packages/channel-module/`目录
+  - [ ] 创建`package.json`文件，配置包名`@d8d/allin-channel-module`和workspace依赖
+  - [ ] 创建`tsconfig.json`文件，配置TypeScript编译选项
+  - [ ] 创建`vitest.config.ts`文件，配置测试环境
+  - [ ] 创建`src/`目录结构：`entities/`, `services/`, `routes/`, `schemas/`, `types/`
+- [ ] 完成实体转换：`Channel`实体从下划线命名转换为驼峰命名 (AC: 2)
+  - [ ] 分析源实体`allin_system-master/server/src/channel_info/channel.entity.ts`
+  - [ ] 创建转换后的实体文件`src/entities/channel.entity.ts`
+  - [ ] 将下划线字段名转换为驼峰命名：`channel_id` → `channelId`, `channel_name` → `channelName`等
+  - [ ] 添加详细的TypeORM装饰器配置：`@Column({ name: 'channel_name', type: 'varchar', length: 100 })`
+  - [ ] 保持数据库表名不变：`@Entity('channel_info')`
+  - [ ] 添加必要的索引和约束配置
+- [ ] 完成服务层转换：从NestJS自定义Service转换为GenericCrudService继承 (AC: 3)
+  - [ ] 分析源服务`allin_system-master/server/src/channel_info/channel.service.ts`
+  - [ ] 创建转换后的服务文件`src/services/channel.service.ts`
+  - [ ] 继承`GenericCrudService<Channel>`，配置搜索字段
+  - [ ] 转换自定义业务方法：`createChannel`, `deleteChannel`, `updateChannel`, `searchByName`
+  - [ ] 保持原有业务逻辑，适配新的服务架构
+  - [ ] 添加错误处理和日志记录
+- [ ] 完成路由层转换：从NestJS控制器转换为Hono路由 (AC: 4)
+  - [ ] 分析源控制器`allin_system-master/server/src/channel_info/channel.controller.ts`
+  - [ ] 创建转换后的路由文件`src/routes/channel.routes.ts`
+  - [ ] 使用`OpenAPIHono`创建路由实例
+  - [ ] 转换所有端点：`createChannel`, `deleteChannel`, `updateChannel`, `getAllChannels`, `searchChannels`, `getChannel`
+  - [ ] 添加认证中间件集成
+  - [ ] 配置OpenAPI文档和参数验证
+- [ ] 完成验证系统转换：从class-validator DTO转换为Zod Schema (AC: 5)
+  - [ ] 分析源DTO`allin_system-master/server/src/channel_info/channel.dto.ts`
+  - [ ] 创建转换后的Schema文件`src/schemas/channel.schema.ts`
+  - [ ] 使用`z.object()`定义`CreateChannelSchema`, `UpdateChannelSchema`, `DeleteChannelSchema`
+  - [ ] 添加详细的验证规则：字符串长度、必填字段、可选字段
+  - [ ] 创建对应的TypeScript类型定义
+- [ ] 配置package.json：使用`@d8d/allin-channel-module`包名，workspace依赖 (AC: 6)
+  - [ ] 配置`package.json`中的`name`字段为`@d8d/allin-channel-module`
+  - [ ] 设置`type: "module"`和主入口`src/index.ts`
+  - [ ] 添加workspace依赖：`@d8d/core-module`, `@d8d/shared-crud`, `@d8d/shared-utils`
+  - [ ] 添加外部依赖：`@hono/zod-openapi`, `typeorm`, `zod`
+  - [ ] 配置导出路径：`services`, `schemas`, `routes`, `entities`
+- [ ] 编写API集成测试：覆盖所有路由端点，验证CRUD操作 (AC: 7)
+  - [ ] 创建测试文件`tests/integration/channel.integration.test.ts`
+  - [ ] 参考`advertisements-module`的集成测试模式
+  - [ ] 使用`testClient`创建测试客户端
+  - [ ] 使用`setupIntegrationDatabaseHooksWithEntities`设置测试数据库
+  - [ ] 编写测试用例覆盖所有端点：创建、查询、更新、删除、搜索
+  - [ ] 添加认证测试、数据验证测试、错误处理测试
+  - [ ] 包含边界条件和异常场景测试
+- [ ] 通过类型检查和基本测试验证 (AC: 8)
+  - [ ] 运行`pnpm typecheck`确保无类型错误
+  - [ ] 运行`pnpm test`确保所有测试通过
+  - [ ] 运行`pnpm test:integration`验证集成测试
+  - [ ] 检查测试覆盖率是否满足要求
+  - [ ] 验证模块可以正确导入和使用
+
+## Dev Notes
+
+### 先前故事洞察
+- **故事006.001**：创建了`core-module`作为聚合包，移除了多租户相关代码 [Source: docs/stories/006.001.create-core-module-and-update-config.story.md]
+- **技术栈转换经验**：从NestJS到Hono的转换需要完整的架构重构，包括实体、服务、路由和验证系统
+
+### 数据模型
+- **源实体结构**：`Channel`实体包含以下字段 [Source: allin_system-master/server/src/channel_info/channel.entity.ts]:
+  - `channel_id: number` (主键，自增)
+  - `channel_name: string` (渠道名称)
+  - `channel_type: string` (渠道类型)
+  - `contact_person: string` (联系人)
+  - `contact_phone: string` (联系电话)
+  - `description?: string` (描述，可选)
+  - `status: number` (状态，默认1)
+  - `create_time: Date` (创建时间)
+  - `update_time: Date` (更新时间)
+- **转换要求**：下划线命名 → 驼峰命名，添加详细TypeORM配置
+- **表名保持**：`channel_info`表名不变
+
+### API规范
+- **现有API端点** [Source: allin_system-master/server/src/channel_info/channel.controller.ts]:
+  - `POST /channel/createChannel` - 创建渠道
+  - `POST /channel/deleteChannel` - 删除渠道
+  - `POST /channel/updateChannel` - 更新渠道
+  - `GET /channel/getAllChannels` - 获取所有渠道（分页）
+  - `GET /channel/searchChannels` - 搜索渠道（按名称）
+  - `GET /channel/getChannel/:id` - 获取单个渠道详情
+- **认证要求**：所有端点需要JWT认证 (`@UseGuards(JwtAuthGuard)`)
+- **转换策略**：NestJS控制器 → Hono路由，保持相同的端点路径和功能
+
+### 服务规范
+- **源服务逻辑** [Source: allin_system-master/server/src/channel_info/channel.service.ts]:
+  - `createChannel`: 检查名称重复，设置默认值，插入数据
+  - `deleteChannel`: 根据ID删除
+  - `findAll`: 分页查询，按ID降序排序
+  - `searchByName`: 按名称模糊搜索，分页查询
+  - `findOne`: 根据ID查询单个
+  - `updateChannel`: 检查存在性，检查名称重复，更新数据
+- **转换策略**：继承`GenericCrudService`，复用现有CRUD模式，保持业务逻辑
+
+### 验证系统
+- **源DTO结构** [Source: allin_system-master/server/src/channel_info/channel.dto.ts]:
+  - `CreateChannelDto`: `channel_name`(必填), `channel_type`(可选), `contact_person`(可选), `contact_phone`(可选), `description`(可选)
+  - `UpdateChannelDto`: `channel_id`(必填), `channel_name`(可选), `channel_type`(可选), `contact_person`(可选), `contact_phone`(可选), `description`(可选)
+  - `DeleteChannelDto`: `channel_id`(必填)
+- **转换策略**：`class-validator` → `Zod Schema`，添加详细的验证规则
+
+### 文件位置
+- **包目录**：`allin-packages/channel-module/` (根据史诗007的目录结构决策)
+- **实体文件**：`src/entities/channel.entity.ts`
+- **服务文件**：`src/services/channel.service.ts`
+- **路由文件**：`src/routes/channel.routes.ts`
+- **Schema文件**：`src/schemas/channel.schema.ts`
+- **测试文件**：`tests/integration/channel.integration.test.ts`
+- **包配置**：`package.json`, `tsconfig.json`, `vitest.config.ts`
+
+### 测试要求
+- **测试框架**：Vitest [Source: architecture/testing-strategy.md#单元测试]
+- **测试位置**：`tests/integration/`目录 [Source: architecture/testing-strategy.md#测试金字塔策略]
+- **测试类型**：集成测试，验证API端点和数据库交互 [Source: architecture/testing-strategy.md#集成测试]
+- **覆盖率目标**：集成测试 ≥ 60% [Source: architecture/testing-strategy.md#测试覆盖率标准]
+- **测试模式**：参考`advertisements-module`的集成测试模式 [Source: packages/advertisements-module/tests/integration/advertisements.integration.test.ts]
+- **测试工具**：使用`@d8d/shared-test-util`中的测试基础设施 [Source: architecture/testing-strategy.md#包测试架构]
+
+### 技术约束
+- **技术栈**：Node.js 20.19.2, Hono 4.8.5, TypeORM 0.3.25, PostgreSQL 17 [Source: architecture/tech-stack.md]
+- **编码标准**：TypeScript严格模式，一致的缩进和命名 [Source: architecture/coding-standards.md]
+- **API设计**：RESTful API设计，使用Hono框架 [Source: architecture/api-design-integration.md]
+- **包管理**：使用pnpm workspace管理依赖 [Source: architecture/source-tree.md#集成指南]
+- **模块导出**：通过`src/index.ts`统一导出 [Source: architecture/source-tree.md#包结构规范]
+
+### 项目结构注意事项
+- **目录结构冲突**：根据史诗007决策，Allin系统专属包放在`allin-packages/`目录，而非通用的`packages/`目录
+- **命名规范**：使用`@d8d/allin-`前缀，`-module`后缀，非多租户版本
+- **依赖管理**：通过workspace依赖引用`@d8d/core-module`和其他共享包
+
+## Testing
+### 测试标准
+- **测试框架**：使用 Vitest [Source: architecture/testing-strategy.md#单元测试]
+- **测试位置**：`tests/integration/`目录 [Source: architecture/testing-strategy.md#集成测试]
+- **测试类型**：集成测试，验证API端点和数据库交互 [Source: architecture/testing-strategy.md#集成测试]
+- **覆盖率要求**：集成测试 ≥ 60% [Source: architecture/testing-strategy.md#测试覆盖率标准]
+
+### 本故事特定测试要求
+1. **API端点测试**：必须覆盖所有6个端点（创建、删除、更新、查询所有、搜索、查询单个）
+2. **认证测试**：验证所有端点需要有效的JWT令牌
+3. **数据验证测试**：测试输入验证规则（必填字段、字符串长度、数据类型）
+4. **业务逻辑测试**：测试渠道名称重复检查、分页查询、模糊搜索
+5. **错误处理测试**：测试各种错误场景（无效ID、重复名称、缺失字段）
+6. **数据库集成测试**：验证数据正确持久化和查询
+7. **测试数据管理**：使用测试数据工厂模式，每个测试后清理数据
+
+### 测试执行流程
+1. 设置测试数据库，包含必要的实体
+2. 创建测试用户和认证令牌
+3. 为每个端点编写成功场景测试
+4. 为每个端点编写失败场景测试
+5. 验证响应格式和数据正确性
+6. 检查数据库状态变化
+
+## Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-12-02 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
+
+## Dev Agent Record
+*此部分由开发代理在实现过程中填写*
+
+### Agent Model Used
+{{agent_model_name_version}}
+
+### Debug Log References
+Reference any debug logs or traces generated during development
+
+### Completion Notes List
+Notes about the completion of tasks and any issues encountered
+
+### File List
+List all files created, modified, or affected during story implementation
+
+## QA Results
+Results from QA Agent QA review of the completed story implementation