📝 docs(story): add advertisement module split story document

- 创建广告管理模块拆分故事文档，记录从server拆分到独立package的需求和计划
- 定义广告模块独立为@d8d/advertisements-module的验收标准和任务分解
- 详细记录技术栈信息、项目结构、实体设计和测试要求
- 提供完整的任务清单和依赖关系说明

docs/stories/005.006.advertisements-module.story.md

@@ -0,0 +1,158 @@
+# Story 005.006: Advertisements Module
+
+## Status
+Draft
+
+## Story
+
+**As a** 小程序开发者，
+**I want** 将广告管理模块从 packages/server/src 拆分到主项目的 packages 目录下作为独立 package，
+**so that** 项目可以按需引入广告管理功能，保持模块独立性和向后兼容性
+
+## Acceptance Criteria
+
+1. 创建 `@d8d/advertisements-module` package，包含完整的广告类型和广告管理功能
+2. 从 packages/server/src/modules/advertisements 迁移广告服务代码
+3. 实现广告类型和广告实体的完整CRUD功能
+4. 提供完整的 TypeScript 类型定义和 API 文档
+5. 集成到现有的文件管理系统（图片文件关联）
+6. 保持与现有认证系统的兼容性
+7. 提供单元测试和集成测试，覆盖率满足要求
+8. 更新 server package 依赖关系，支持按需引入
+
+## Tasks / Subtasks
+
+- [ ] Task 1: 创建 advertisements-module package 基础结构 (AC: 1, 2)
+  - [ ] 创建 packages/advertisements-module 目录结构
+  - [ ] 配置 package.json 和依赖关系
+  - [ ] 配置 TypeScript 编译配置
+  - [ ] 创建基础导出文件
+
+- [ ] Task 2: 迁移广告实体和服务代码 (AC: 2, 3)
+  - [ ] 迁移 Advertisement 实体和相关类型定义
+  - [ ] 迁移 AdvertisementType 实体和相关类型定义
+  - [ ] 迁移 AdvertisementService 和 AdvertisementTypeService
+  - [ ] 迁移广告相关的 Schema 定义
+
+- [ ] Task 3: 创建广告 API 路由 (AC: 3, 4)
+  - [ ] 创建广告管理路由 (/advertisements)
+  - [ ] 创建广告类型管理路由 (/advertisement-types)
+  - [ ] 实现完整的 OpenAPI 文档
+  - [ ] 配置认证中间件集成
+
+- [ ] Task 4: 集成文件管理系统 (AC: 5)
+  - [ ] 集成现有 file-module 依赖
+  - [ ] 配置图片文件关联关系
+  - [ ] 确保文件上传和关联功能正常
+  - [ ] 验证图片文件访问权限
+
+- [ ] Task 5: 迁移和实现测试套件 (AC: 7)
+  - [ ] 创建单元测试文件
+  - [ ] 创建集成测试文件
+  - [ ] 配置测试数据库和测试工具
+  - [ ] 验证测试覆盖率满足要求
+
+- [ ] Task 6: 更新 server package 依赖 (AC: 8)
+  - [ ] 更新 server package.json 添加 advertisements-module 依赖
+  - [ ] 集成广告路由到主应用
+  - [ ] 验证按需引入功能
+  - [ ] 更新文档说明
+
+## Dev Notes
+
+### 技术栈信息
+- **后端框架**: Hono 4.8.5 [Source: architecture/tech-stack.md#现有技术栈维护]
+- **数据库**: PostgreSQL 17 + TypeORM 0.3.25 [Source: architecture/tech-stack.md#现有技术栈维护]
+- **认证**: JWT Bearer Token [Source: architecture/api-design-integration.md#API集成策略]
+- **文件存储**: MinIO + file-module [Source: architecture/source-tree.md#实际项目结构]
+
+### 项目结构
+- **包位置**: `packages/advertisements-module/` [Source: architecture/source-tree.md#实际项目结构]
+- **代码结构**: 遵循现有模块化包模式 [Source: architecture/source-tree.md#包架构层次]
+- **依赖层次**: advertisements-module → file-module → auth-module → user-module → shared-crud → shared-utils → shared-types [Source: docs/prd/epic-005-mini-auth-modules-integration.md#依赖层次]
+
+### 广告功能详情
+- **广告实体**: Advertisement 实体包含标题、类型、调用别名、URL、图片文件、排序、状态等字段 [Source: packages/server/src/modules/advertisements/advertisement.entity.ts:1-125]
+- **广告类型实体**: AdvertisementType 实体包含类型名称、调用别名、备注、状态等字段 [Source: packages/server/src/modules/advertisements/advertisement-type.entity.ts:1-72]
+- **服务层**: 使用 GenericCrudService 提供标准CRUD操作 [Source: packages/server/src/modules/advertisements/advertisement.service.ts:1-9]
+- **API路由**: 使用通用CRUD路由生成器创建标准API [Source: packages/server/src/api/advertisements/index.ts:1-21]
+
+### 实体设计
+**Advertisement 实体字段**:
+- `id`: 主键ID
+- `title`: 广告标题 (varchar(30))
+- `typeId`: 广告类型ID
+- `code`: 调用别名 (varchar(20))
+- `url`: 跳转URL (varchar(255))
+- `imageFileId`: 图片文件ID
+- `sort`: 排序字段
+- `status`: 状态字段
+- `actionType`: 跳转类型 (0不跳转, 1webview, 2小程序页面)
+- `createdBy`, `updatedBy`: 用户跟踪字段
+
+**AdvertisementType 实体字段**:
+- `id`: 主键ID
+- `name`: 类型名称 (varchar(50))
+- `code`: 调用别名 (varchar(20))
+- `remark`: 备注 (varchar(100))
+- `status`: 状态 (0禁用, 1启用)
+- `createdBy`, `updatedBy`: 用户跟踪字段
+
+### 集成点
+- **认证集成**: 使用现有 auth.middleware [Source: packages/server/src/api/advertisements/index.ts:4]
+- **文件集成**: 依赖 file-module 获取图片文件信息 [Source: packages/server/src/modules/advertisements/advertisement.entity.ts:2]
+- **数据库**: 使用现有 TypeORM 数据源 [Source: architecture/source-tree.md:74]
+- **API 设计**: 遵循现有 RESTful API 模式 [Source: architecture/api-design-integration.md#API集成策略]
+
+### 环境配置要求
+- **数据库表**: 需要 ad 和 ad_type 表 [Source: packages/server/src/modules/advertisements/advertisement.entity.ts:5]
+- **文件存储**: 需要配置 MinIO 存储桶 [Source: architecture/source-tree.md:248]
+
+### Testing
+
+#### 测试标准
+- **测试框架**: Vitest 3.2.4 [Source: architecture/testing-strategy.md#工具版本]
+- **测试位置**: `packages/advertisements-module/tests/` [Source: architecture/testing-strategy.md#包测试架构]
+- **测试类型**: 单元测试 + 集成测试 [Source: architecture/testing-strategy.md#包测试架构]
+- **覆盖率要求**: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: architecture/testing-strategy.md#各层覆盖率要求]
+
+#### 测试模式
+- **集成测试**: 测试广告路由与认证集成 [Source: architecture/testing-strategy.md#集成测试]
+- **测试工具**: 使用 shared-test-util 基础设施 [Source: architecture/testing-strategy.md#包测试架构]
+
+#### 测试套件用法（参考 auth-module 模式）
+- **测试框架**: Vitest + Hono Testing Client [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:1-2]
+- **数据库钩子**: 使用 `setupIntegrationDatabaseHooksWithEntities` [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:31]
+- **测试客户端**: 使用 `testClient` 创建路由测试客户端 [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:41]
+- **数据源获取**: 使用 `IntegrationTestDatabase.getDataSource()` [Source: packages/auth-module/tests/integration/phone-decrypt.integration.test.ts:44]
+
+#### 关键测试场景
+- 广告创建和更新参数验证
+- 广告类型管理功能测试
+- 图片文件关联测试
+- 认证和权限验证测试
+- 错误处理和异常场景测试
+
+## Change Log
+
+| Date | Version | Description | Author |
+|------|---------|-------------|---------|
+| 2025-11-11 | 1.0 | 创建广告管理模块故事文档 | Bob (Scrum Master) |
+
+## Dev Agent Record
+
+### Agent Model Used
+- *This section will be populated by the development agent*
+
+### Debug Log References
+- *This section will be populated by the development agent*
+
+### Completion Notes List
+- *This section will be populated by the development agent*
+
+### File List
+- *This section will be populated by the development agent*
+
+## QA Results
+
+*Results from QA Agent QA review of the completed story implementation*