# Story 007.001: 信息化项目全过程咨询服务页面完善

## Status
In Progress

## Story
**As a** 潜在客户（包括游客），
**I want** 查看详细的信息化项目全过程咨询服务介绍并能够提交我的项目需求和联系方式（无需登录），
**so that** 我能够了解公司提供的项目前期咨询、项目建议书编制、可行性研究、初步设计、深化审计、造价咨询和竣工资料等全流程服务能力，并能方便地获取专业咨询。

## Acceptance Criteria
1. 完善项目前期咨询服务介绍
2. 优化项目建议书编制展示
3. 添加项目可行性研究报告案例
4. 完善项目初步设计方案/实施方案说明
5. 优化项目深化审计服务展示
6. 添加项目造价咨询服务案例
7. 完善项目竣工资料编制说明
8. 添加客户需求提交表单功能（支持游客提交）
9. 实现客户需求数据存储和后台管理
10. 支持游客无需登录即可提交需求
11. 添加反垃圾邮件和机器人验证机制

## Tasks / Subtasks
- [x] 更新页面标题和描述 (AC: 1-7)
  - [x] 将"设计规划服务"改为"信息化项目全过程咨询服务"
  - [x] 更新页面副标题和描述文案
  - [x] 更新页面统计数据和指标
- [x] 重新设计服务范围部分 (AC: 1-7)
  - [x] 创建7个新的服务卡片，对应7个全过程咨询服务阶段
  - [x] 为每个服务阶段设计对应的图标和颜色主题
  - [x] 更新服务描述和功能特点列表
- [x] 更新设计流程部分 (AC: 1-7)
  - [x] 将设计流程改为信息化项目全过程咨询流程
  - [x] 更新流程步骤描述和持续时间
  - [x] 调整流程图标和视觉设计
- [x] 更新成功案例部分 (AC: 3)
  - [x] 替换为信息化项目咨询相关案例
  - [x] 更新案例行业分类和成果指标
  - [x] 确保案例与咨询服务内容相关
- [x] 更新设计原则部分 (AC: 1-7)
  - [x] 将设计原则改为咨询服务原则
  - [x] 更新原则图标和描述
  - [x] 确保原则与项目咨询业务相关
- [x] 创建客户需求实体和API (AC: 8-11)
  - [x] 创建客户需求实体类 (ConsultationRequest)
  - [x] 定义客户需求Zod Schema（支持游客提交）
  - [x] 创建客户需求服务类
  - [x] 实现公开的客户需求提交API路由（无需认证）
  - [x] 实现后台管理API路由（需要认证）
  - [x] 注册公开API路由到主应用
  - [x] 添加反垃圾邮件验证机制
- [x] 实现客户需求提交表单 (AC: 8, 10)
  - [x] 创建客户需求提交表单组件（支持游客提交）
  - [x] 实现表单验证和错误处理
  - [x] 集成表单到咨询服务页面CTA部分
  - [x] 添加表单提交成功反馈
  - [x] 实现机器人验证机制（如reCAPTCHA）
- [x] 更新CTA部分 (AC: 1-7, 8)
  - [x] 更新按钮文案为"咨询项目服务"
  - [x] 更新号召性用语
  - [x] 集成客户需求提交表单
  - [x] 确保整体页面风格一致
- [ ] 测试和验证 (AC: 1-9)
  - [ ] 进行响应式设计测试
  - [ ] 验证页面内容准确性
  - [ ] 测试客户需求表单提交功能
  - [ ] 验证数据存储和API调用
  - [ ] 检查页面加载性能

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md#前端技术栈]
- **前端框架**: React 19.1.0 + TypeScript
- **路由**: React Router v7
- **状态管理**: @tanstack/react-query (服务端状态) + Context (本地状态)
- **UI组件库**: shadcn/ui (基于Radix UI)
- **构建工具**: Vite 7.0.0
- **样式**: Tailwind CSS 4.1.11
- **表单处理**: React Hook Form 7 + Zod验证

### 后端技术栈信息 [Source: architecture/tech-stack.md#后端技术栈]
- **框架**: Hono 4.8.5 + TypeScript
- **数据库**: MySQL 8.0.36 + TypeORM 0.3.25
- **验证**: Zod schema验证
- **API文档**: @hono/zod-openapi + Swagger UI
- **通用CRUD**: 使用GenericCrudService和createCrudRoutes

### 项目结构信息 [Source: architecture/source-tree.md#实际项目结构]
- **页面位置**: `src/client/home/pages/DesignPlanningPage.tsx`
- **组件位置**: `src/client/components/ui/` (使用shadcn/ui组件)
- **路由配置**: `src/client/home/routes.tsx`
- **后端实体**: `src/server/modules/consultation/` (新建目录)
- **API路由**: `src/server/api/consultation-requests/` (新建目录)
- **样式文件**: 使用Tailwind CSS，无需额外CSS文件

### 现有页面分析 [Source: 当前DesignPlanningPage.tsx]
当前页面包含以下主要部分：
- Hero Section (标题和统计数据)
- Design Services (4个服务卡片)
- Design Process (5个流程步骤)
- Case Studies (3个案例展示)
- Design Principles (4个设计原则)
- CTA Section (行动号召)

### 客户需求实体设计 [Source: architecture/data-model-schema-changes.md#现有数据模型状态]
```typescript
// 客户需求实体字段设计（支持游客提交）
@Entity('consultation_requests')
export class ConsultationRequest {
  @PrimaryGeneratedColumn({ unsigned: true })
  id!: number;

  @Column({ name: 'customer_name', type: 'varchar', length: 255 })
  customerName!: string;

  @Column({ name: 'company_name', type: 'varchar', length: 255, nullable: true })
  companyName!: string | null;

  @Column({ name: 'phone', type: 'varchar', length: 20 })
  phone!: string;

  @Column({ name: 'email', type: 'varchar', length: 255, nullable: true })
  email!: string | null;

  @Column({ name: 'project_type', type: 'varchar', length: 100 })
  projectType!: string;

  @Column({ name: 'project_description', type: 'text' })
  projectDescription!: string;

  @Column({ name: 'budget_range', type: 'varchar', length: 100, nullable: true })
  budgetRange!: string | null;

  @Column({ name: 'timeline', type: 'varchar', length: 100, nullable: true })
  timeline!: string | null;

  @Column({ name: 'status', type: 'varchar', length: 20, default: 'pending' })
  status!: string;

  @Column({ name: 'is_guest', type: 'tinyint', default: 0, comment: '是否为游客提交' })
  isGuest!: number;

  @Column({ name: 'ip_address', type: 'varchar', length: 45, nullable: true, comment: '提交IP地址' })
  ipAddress!: string | null;

  @Column({ name: 'user_agent', type: 'text', nullable: true, comment: '用户代理信息' })
  userAgent!: string | null;

  @CreateDateColumn({ name: 'created_at' })
  createdAt!: Date;

  @UpdateDateColumn({ name: 'updated_at' })
  updatedAt!: Date;
}
```

### 表单验证Schema [Source: architecture/api-design-integration.md#OpenAPI规范]
```typescript
// 客户需求提交DTO Schema（支持游客提交）
export const CreateConsultationRequestDto = z.object({
  customerName: z.string().min(2, '姓名至少2个字符').max(255).openapi({
    description: '客户姓名',
    example: '张三'
  }),
  companyName: z.string().max(255).optional().openapi({
    description: '公司名称',
    example: 'ABC科技有限公司'
  }),
  phone: z.string().regex(/^1[3-9]\d{9}$/, '请输入正确的手机号').openapi({
    description: '手机号',
    example: '13800138000'
  }),
  email: z.string().email('请输入正确的邮箱地址').optional().openapi({
    description: '邮箱地址',
    example: 'zhangsan@example.com'
  }),
  projectType: z.string().min(1, '请选择项目类型').max(100).openapi({
    description: '项目类型',
    example: '企业ERP系统'
  }),
  projectDescription: z.string().min(10, '项目描述至少10个字符').max(2000).openapi({
    description: '项目描述',
    example: '我们需要开发一个企业ERP系统，包含财务、采购、销售等模块'
  }),
  budgetRange: z.string().max(100).optional().openapi({
    description: '预算范围',
    example: '10-50万'
  }),
  timeline: z.string().max(100).optional().openapi({
    description: '项目时间要求',
    example: '3-6个月'
  }),
  isGuest: z.boolean().default(true).openapi({
    description: '是否为游客提交',
    example: true
  }),
  captchaToken: z.string().optional().openapi({
    description: '机器人验证token',
    example: 'captcha_token_123'
  })
});
```

### 组件使用模式 [Source: architecture/component-architecture.md#前端组件架构]
- 使用Card、Button、Badge等shadcn/ui组件
- 采用响应式网格布局 (grid md:grid-cols-2, grid md:grid-cols-3)
- 使用Lucide React图标库
- 采用Tailwind CSS的渐变背景和阴影效果
- 表单使用React Hook Form + Zod验证

### 文件路径约定 [Source: architecture/source-tree.md#集成指南]
- 保持现有kebab-case命名约定
- 页面文件位于`src/client/home/pages/`目录
- 组件导入使用别名`@/client/components/ui/`
- 后端实体位于`src/server/modules/consultation/`目录
- API路由位于`src/server/api/consultation-requests/`目录

### 公开API路由设计 [Source: architecture/api-design-integration.md#OpenAPI规范]
```typescript
// 公开客户需求提交API路由（无需认证）
const routeDef = createRoute({
  method: 'post',
  path: '/api/v1/public/consultation-requests',
  // 注意：不使用authMiddleware，支持游客提交
  request: {
    body: {
      content: {
        'application/json': { schema: CreateConsultationRequestDto }
      }
    }
  },
  responses: {
    200: {
      description: '成功提交客户需求',
      content: { 'application/json': { schema: ConsultationRequestSchema } }
    },
    400: {
      description: '请求参数错误',
      content: { 'application/json': { schema: ErrorSchema } }
    },
    500: {
      description: '服务器错误',
      content: { 'application/json': { schema: ErrorSchema } }
    }
  }
});
```

### 反垃圾邮件和机器人验证机制 [Source: architecture/security-patterns.md#安全模式]
```typescript
// 反垃圾邮件验证服务
export class SpamProtectionService {
  async validateSubmission(requestData: CreateConsultationRequestDto, ipAddress: string): Promise<boolean> {
    // 1. IP频率限制：同一IP24小时内最多提交5次
    const recentSubmissions = await this.getRecentSubmissionsByIP(ipAddress);
    if (recentSubmissions >= 5) {
      throw new Error('提交频率过高，请稍后再试');
    }

    // 2. 内容重复检测：检查相似的项目描述
    const similarRequests = await this.findSimilarRequests(requestData.projectDescription);
    if (similarRequests.length > 0) {
      throw new Error('检测到重复提交，请修改项目描述');
    }

    // 3. 机器人验证：验证captcha token
    if (requestData.captchaToken) {
      const isValid = await this.validateCaptcha(requestData.captchaToken);
      if (!isValid) {
        throw new Error('机器人验证失败');
      }
    }

    return true;
  }

  // 支持多种验证方式：reCAPTCHA、hCaptcha、自定义验证等
  private async validateCaptcha(token: string): Promise<boolean> {
    // 实现具体的验证逻辑
    return true;
  }
}
```

### Testing
#### 测试标准 [Source: architecture/testing-strategy.md#测试金字塔策略]
- **单元测试位置**:
  - `src/client/home/pages/__tests__/DesignPlanningPage.test.tsx` (前端页面测试)
  - `src/server/modules/consultation/__tests__/consultation-request.service.test.ts` (后端服务测试)
  - `src/server/api/consultation-requests/__tests__/` (API路由测试)
- **测试框架**: Vitest + Testing Library
- **覆盖率目标**: ≥ 80%
- **测试类型**: 组件渲染测试、交互测试、表单验证测试、API集成测试

#### 测试要求 [Source: architecture/testing-strategy.md#测试执行流程]
- 验证页面正确渲染所有服务卡片
- 测试响应式布局在不同屏幕尺寸下的表现
- 验证页面内容与信息化项目咨询服务相关
- 检查所有链接和按钮功能正常
- 测试客户需求表单验证规则
- 验证表单提交功能正常工作
- 测试API端点的正确响应
- 验证数据存储和检索功能
- **游客提交场景测试**：
  - 测试游客无需登录即可提交需求
  - 验证游客提交时自动设置isGuest字段为true
  - 测试IP地址和用户代理信息的正确记录
  - 验证反垃圾邮件机制正常工作
  - 测试机器人验证集成
  - 验证频率限制和重复提交检测

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-09-25 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
| 2025-09-25 | 1.1 | 添加客户需求提交功能需求 | Bob (Scrum Master) |
| 2025-09-25 | 1.2 | 扩展支持游客提交需求功能 | Bob (Scrum Master) |

## Dev Agent Record
*此部分由开发代理在实施过程中填写*

### Agent Model Used
Claude Code (d8d-model)

### Debug Log References
- 成功将设计规划页面转换为信息化项目全过程咨询服务页面
- 更新了所有7个服务阶段的展示内容
- 修改了页面标题、描述、统计数据、服务范围、流程步骤、成功案例、服务原则和CTA部分
- 客户需求实体和API已完整实现，支持游客提交
- 客户需求表单组件已创建并集成到页面
- 反垃圾邮件和机器人验证机制已实现
- 类型错误已修复，系统可以正常编译

### Completion Notes List
1. ✅ 更新页面标题和描述：将"设计规划服务"改为"信息化项目全过程咨询服务"
2. ✅ 重新设计服务范围部分：创建7个新的服务卡片，对应7个全过程咨询服务阶段
3. ✅ 更新设计流程部分：将设计流程改为信息化项目全过程咨询流程，更新7个流程步骤
4. ✅ 更新成功案例部分：替换为信息化项目咨询相关案例（政务、制造、医疗行业）
5. ✅ 更新设计原则部分：将设计原则改为咨询服务原则，更新图标和描述
6. ✅ 创建客户需求实体和API：后端数据模型和CRUD接口已完整实现
7. ✅ 实现客户需求提交表单：前端表单组件与后端API集成已完成
8. ✅ 更新CTA部分：按钮文案已更新，表单集成已完成
9. ⚠️ 测试和验证：表单功能和API调用测试待进行
10. ✅ 扩展客户需求实体支持游客提交：isGuest、ipAddress、userAgent字段已实现
11. ✅ 更新表单验证Schema支持游客提交：isGuest和captchaToken字段已实现
12. ✅ 实现公开API路由设计：支持游客无需认证提交需求已实现
13. ✅ 添加反垃圾邮件和机器人验证机制：IP频率限制、内容重复检测、机器人验证已实现
14. ⚠️ 更新测试要求：游客提交场景的测试覆盖待实现

### File List
- `src/client/home/pages/DesignPlanningPage.tsx` - 主要修改文件（已实现UI更新）
- `src/client/components/ConsultationRequestForm.tsx` - 客户需求表单组件（已实现）
- `src/server/modules/consultation/consultation-request.entity.ts` - 客户需求实体（已实现）
- `src/server/modules/consultation/consultation-request.schema.ts` - 客户需求Schema（已实现）
- `src/server/modules/consultation/consultation-request.service.ts` - 客户需求服务（已实现）
- `src/server/modules/consultation/spam-protection.service.ts` - 反垃圾邮件验证服务（已实现）
- `src/server/api/consultation-requests/` - 客户需求API路由（已实现）
- `src/server/api/public/consultation-requests/` - 公开客户需求API路由（已实现）
- `src/client/api.ts` - 添加了客户需求客户端API（已更新）
- `src/server/api.ts` - 注册了客户需求API路由（已更新）
- `src/server/data-source.ts` - 注册了客户需求实体（已更新）

## QA Results
*此部分由QA代理在质量检查后填写*