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

Status

In Progress

Story

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

Acceptance Criteria

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

Tasks / Subtasks

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

// 客户需求实体字段设计（支持游客提交）
@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规范]

// 客户需求提交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规范]

// 公开客户需求提交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#安全模式]

// 反垃圾邮件验证服务
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

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

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代理在质量检查后填写

007.001.information-project-consulting.md 15 KB Riwayat Mentahan