📝 docs(story): add goods module split story documentation

- create story document for goods module split task
- define acceptance criteria for independent package creation
- outline detailed tasks for package migration and integration
- specify technical requirements and dependencies
- document testing standards and key test scenarios

docs/stories/005.010.goods-module.story.md

@@ -0,0 +1,230 @@
+# Story 005.010: Goods Module
+
+## Status
+Draft
+
+## Story
+
+**As a** 小程序开发者，
+**I want** 将商品管理模块从 packages/server/src 拆分到主项目的 packages 目录下作为独立 package，
+**so that** 项目可以按需引入商品分类和商品管理功能，保持模块独立性和向后兼容性
+
+## Acceptance Criteria
+
+1. 创建 `@d8d/goods-module` package，包含完整的商品分类和商品管理功能
+2. 从 packages/server/src/modules/goods 迁移商品服务代码
+3. 实现商品和商品分类的完整CRUD功能
+4. 提供完整的 TypeScript 类型定义和 API 文档
+5. 集成到现有的文件管理系统（商品图片关联）
+6. 保持与现有认证系统的兼容性
+7. 提供单元测试和集成测试，覆盖率满足要求
+8. 更新 server package 依赖关系，支持按需引入
+
+## Tasks / Subtasks
+
+- [ ] Task 1: 创建 goods-module package 基础结构 (AC: 1, 2)
+  - [ ] 创建 packages/goods-module 目录结构
+  - [ ] 配置 package.json 和依赖关系
+  - [ ] 配置 TypeScript 编译配置
+  - [ ] 配置 vitest.config.ts 测试配置
+  - [ ] 创建基础导出文件
+
+- [ ] Task 2: 迁移商品实体和类型定义 (AC: 2, 4)
+  - [ ] 迁移 Goods 实体到 packages/goods-module/src/entities/
+  - [ ] 迁移 GoodsCategory 实体到 packages/goods-module/src/entities/
+  - [ ] 迁移 GoodsSchema、CreateGoodsDto、UpdateGoodsDto 到 packages/goods-module/src/schemas/
+  - [ ] 迁移 GoodsCategorySchema、CreateGoodsCategoryDto、UpdateGoodsCategoryDto 到 packages/goods-module/src/schemas/
+  - [ ] 迁移 RandomGoodsQuerySchema、RandomGoodsResponseSchema 到 packages/goods-module/src/schemas/
+  - [ ] 创建类型定义文件 packages/goods-module/src/types/goods.types.ts
+  - [ ] 更新实体导入路径，使用 workspace:* 依赖
+
+- [ ] Task 3: 迁移商品服务 (AC: 2, 3)
+  - [ ] 迁移 GoodsService 到 packages/goods-module/src/services/
+  - [ ] 迁移 GoodsCategoryService 到 packages/goods-module/src/services/
+  - [ ] 重构服务使用 shared-crud 基础设施
+  - [ ] 更新服务依赖注入配置
+
+- [ ] Task 4: 创建商品路由 (AC: 3, 4)
+  - [ ] 创建商品管理路由 packages/goods-module/src/routes/goods.ts
+  - [ ] 创建商品分类管理路由 packages/goods-module/src/routes/goods-categories.ts
+  - [ ] 集成认证中间件
+  - [ ] 配置用户追踪字段
+  - [ ] 配置关联关系（分类、供应商、商户、文件）
+
+- [ ] Task 4.1: 创建随机商品功能 (AC: 3, 4)
+  - [ ] 迁移随机商品查询Schema packages/goods-module/src/schemas/random.schema.ts
+  - [ ] 创建随机商品路由 packages/goods-module/src/routes/random.ts
+  - [ ] 实现随机商品查询逻辑（支持分类过滤和图片包含选项）
+  - [ ] 配置随机排序和状态过滤
+  - [ ] 验证关联数据加载（图片、分类、供应商等）
+
+- [ ] Task 5: 创建用户权限API路由文件 (AC: 3, 4)
+  - [ ] 创建用户专用schema packages/goods-module/src/schemas/user-goods.schema.ts
+  - [ ] 创建管理员专用schema packages/goods-module/src/schemas/admin-goods.schema.ts
+  - [ ] 创建用户路由 packages/goods-module/src/routes/user-routes.ts
+  - [ ] 创建管理员路由 packages/goods-module/src/routes/admin-routes.ts
+  - [ ] 配置数据权限控制，使用 shared-crud 的 dataPermission 配置
+  - [ ] 验证用户路由只能访问和操作授权的数据
+  - [ ] 验证管理员路由可以访问所有数据
+
+- [ ] Task 7: 创建测试套件 (AC: 7)
+  - [ ] 创建商品路由集成测试 packages/goods-module/tests/integration/goods.integration.test.ts
+  - [ ] 创建商品分类路由集成测试 packages/goods-module/tests/integration/goods-categories.integration.test.ts
+  - [ ] 创建随机商品路由集成测试 packages/goods-module/tests/integration/random.integration.test.ts
+  - [ ] 创建用户路由集成测试 packages/goods-module/tests/integration/user-routes.integration.test.ts
+  - [ ] 创建管理员路由集成测试 packages/goods-module/tests/integration/admin-routes.integration.test.ts
+  - [ ] 配置测试数据库连接，使用 shared-test-util
+  - [ ] 添加关联关系测试场景
+  - [ ] 测试商品状态管理逻辑
+  - [ ] 测试随机商品查询功能
+  - [ ] 确保测试覆盖率满足要求
+
+- [ ] Task 8: 集成到现有系统 (AC: 5, 6, 8)
+  - [ ] 更新 server package 依赖，添加 @d8d/goods-module
+  - [ ] 在 server 中注册商品路由
+  - [ ] 验证与文件模块的集成
+  - [ ] 验证与认证系统的集成
+  - [ ] 确保商品图片关联正常工作
+  - [ ] 验证商品分类树形结构
+
+- [ ] Task 9: 验证和文档 (AC: 4, 6)
+  - [ ] 运行所有测试验证功能
+  - [ ] 更新 docs/architecture/source-tree.md 文档
+  - [ ] 验证向后兼容性
+
+## 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/goods-module/` [Source: architecture/source-tree.md#实际项目结构]
+- **代码结构**: 遵循现有模块化包模式 [Source: architecture/source-tree.md#包架构层次]
+- **依赖层次**: goods-module → file-module → auth-module → user-module → shared-crud → shared-utils → shared-types [Source: docs/prd/epic-005-mini-auth-modules-integration.md#依赖层次]
+
+### 商品功能详情
+- **商品实体**: Goods 实体包含名称、价格、成本价、销售数量、点击次数、三级分类ID、商品类型、供应商ID、商户ID、图片文件ID、轮播图、详情、简介、排序、状态、库存、SPU信息、最小起购量等字段 [Source: packages/server/src/modules/goods/goods.entity.ts:1-115]
+- **商品分类实体**: GoodsCategory 实体包含名称、上级ID、图片文件ID、层级、状态等字段 [Source: packages/server/src/modules/goods/goods-category.entity.ts:1-39]
+- **服务层**: 使用 GenericCrudService 提供标准CRUD操作 [Source: packages/server/src/modules/goods/goods.service.ts:1-9]
+- **随机商品功能**: 提供随机商品列表查询，支持分类过滤和图片包含选项 [Source: packages/server/src/api/goods/random.ts:49-111]
+
+### 实体设计
+**Goods 实体关键字段**:
+- `name`: 商品名称 (varchar(255))
+- `price`: 售卖价 (decimal(10,2))
+- `costPrice`: 成本价 (decimal(10,2))
+- `categoryId1`, `categoryId2`, `categoryId3`: 三级分类ID
+- `goodsType`: 商品类型 (1实物产品, 2虚拟产品)
+- `supplierId`: 供应商ID
+- `merchantId`: 商户ID
+- `imageFileId`: 商品主图文件ID
+- `slideImages`: 商品轮播图文件列表 (多对多关联)
+- `state`: 状态 (1可用, 2不可用)
+- `stock`: 库存
+- `lowestBuy`: 最小起购量
+
+**GoodsCategory 实体关键字段**:
+- `name`: 类别名称 (varchar(255))
+- `parentId`: 上级分类ID
+- `imageFileId`: 分类图片文件ID
+- `level`: 分类层级
+- `state`: 状态 (1可用, 2不可用)
+
+### 集成点
+- **认证集成**: 使用 auth-module 的认证中间件 [Source: packages/auth-module/src/middleware/auth.middleware.ts:1]
+- **文件集成**: 依赖 file-module 获取图片文件信息 [Source: packages/server/src/modules/goods/goods.entity.ts:4]
+- **数据库**: 使用现有 TypeORM 数据源 [Source: architecture/source-tree.md:74]
+- **API 设计**: 遵循现有 RESTful API 模式 [Source: architecture/api-design-integration.md#API集成策略]
+
+### 环境配置要求
+- **数据库表**: 需要 goods 和 goods_category 表 [Source: packages/server/src/modules/goods/goods.entity.ts:7]
+- **文件存储**: 需要配置 MinIO 存储桶 [Source: architecture/source-tree.md:248]
+
+### 依赖关系
+- **基础设施依赖**:
+  - `@d8d/shared-types` - 基础类型定义 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L269-L276]
+  - `@d8d/shared-utils` - 工具函数 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L280-L291]
+  - `@d8d/shared-crud` - CRUD基础设施 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L266-L278]
+- **业务模块依赖**:
+  - `@d8d/user-module` - 用户管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L321-L334]
+  - `@d8d/auth-module` - 认证管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L337-L350]
+  - `@d8d/file-module` - 文件管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L353-L366]
+- **测试依赖**: `@d8d/shared-test-util` [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L294-L306]
+
+### 配置参考
+- **package.json**: 参考广告模块配置，统一依赖版本 [Source: packages/advertisements-module/package.json#L47-L66]
+- **tsconfig.json**: 参考广告模块配置 [Source: packages/advertisements-module/tsconfig.json#L1-L16]
+- **vitest.config.ts**: 参考广告模块配置 [Source: packages/advertisements-module/vitest.config.ts#L1-L21]
+- **shared-test-util**: 测试基础设施包，提供统一的测试工具 [Source: packages/shared-test-util/package.json#L1-L16]
+
+### 当前用户权限API路由设计
+- **用户路由**: `packages/goods-module/src/routes/user-routes.ts` - 仅限当前用户使用 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
+- **管理员路由**: `packages/goods-module/src/routes/admin-routes.ts` - 管理员使用的完整权限路由 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
+- **用户专用Schema**: `packages/goods-module/src/schemas/user-goods.schema.ts` - 移除用户权限相关字段，自动使用当前登录用户权限
+- **管理员专用Schema**: `packages/goods-module/src/schemas/admin-goods.schema.ts` - 保留完整权限字段，允许管理员指定权限
+- **数据权限配置**: 使用 shared-crud 的 `dataPermission` 配置 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L22-L25]
+- **权限验证**: 查询、创建、更新、删除操作都会验证用户权限 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L26-L41]
+
+### 向后兼容性
+- **API 兼容**: 现有商品API保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L101]
+- **数据库兼容**: 数据库schema保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L102]
+- **认证兼容**: 认证流程保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L103]
+
+## Testing
+
+### 测试标准
+- **测试文件位置**: `packages/goods-module/tests/` [Source: architecture/testing-strategy.md#L39-L42]
+- **单元测试**: `tests/unit/**/*.test.ts` [Source: architecture/testing-strategy.md#L39-L42]
+- **集成测试**: `tests/integration/**/*.test.ts` [Source: architecture/testing-strategy.md#L47-L56]
+- **测试框架**: Vitest 3.2.4 [Source: architecture/testing-strategy.md#L43]
+
+### 测试要求
+- **覆盖率目标**: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: architecture/testing-strategy.md#L166-L171]
+- **测试数据库**: 使用专用测试数据库，事务回滚 [Source: architecture/testing-strategy.md#L200-L202]
+- **测试模式**: 遵循测试金字塔策略 [Source: architecture/testing-strategy.md#L33-L64]
+
+### 关键测试场景
+- 商品CRUD操作
+- 商品分类CRUD操作
+- 随机商品列表查询
+- 商品状态管理
+- 商品库存管理
+- 商品分类树形结构
+- 认证和权限验证
+- 图片文件关联验证
+- **用户路由权限测试**:
+  - 验证用户只能访问和操作授权的数据
+  - 验证用户创建商品时自动使用当前用户权限
+  - 验证用户无法访问其他权限的数据
+- **管理员路由权限测试**:
+  - 验证管理员可以访问所有数据
+  - 验证管理员可以为其他权限创建商品
+  - 验证管理员可以更新任何商品
+  - 验证管理员可以删除任何商品
+- **数据权限配置测试**: 验证 dataPermission 配置正确工作
+
+## Change Log
+
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-11-11 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
+
+## Dev Agent Record
+
+*此部分由开发代理在实现过程中填写*
+
+### Agent Model Used
+- James (Developer Agent)
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List
+
+## QA Results
+
+*此部分由QA代理在质量审查后填写*