# D8D Starter + 命理咨询平台 产品需求文档 (PRD)

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 1.0 | 2024-09-14 | 初始PRD版本 | John (PM) |
| 1.1 | 2025-09-17 | 更新Epic结构和指标，与实际epic对齐 | Sarah (PO) |
| 1.2 | 2025-09-19 | 在Epic 001中集成数据库备份功能 | Winston |
| 2.0 | 2025-09-29 | 集成命理咨询平台功能需求 | John (PM) |

## 1. 项目介绍和分析

### 1.1 现有项目概览

**分析来源**: 基于现有架构文档 `docs/brownfield-architecture.md`

**当前项目状态**: D8D Starter 是一个现代化的全栈Web应用启动模板，提供：
- 🚀 **快速开发基础**: Node.js + React 技术栈
- 🔐 **身份认证系统**: JWT-based 用户认证
- 👥 **用户管理**: 完整的用户和角色管理功能
- 📊 **数据库集成**: TypeORM + PostgreSQL 数据持久化
- 🎨 **现代化UI**: React 19 + Tailwind CSS 界面

### 1.2 可用文档分析

✅ **技术文档完整**:
- 技术栈和版本信息
- 源码结构和模块组织
- 数据模型和API规范
- 技术债务和已知问题
- 开发和部署指南

⚠️ **需要补充的业务文档**:
- 产品愿景和目标
- 用户需求和场景
- 功能优先级
- 业务指标

### 1.3 增强范围定义

**项目类型**: 现有项目功能完善和业务需求文档化

**主要目标**:
1. 将现有技术实现与业务需求对齐
2. 定义清晰的产品方向和成功标准
3. 为未来功能扩展建立需求基线

### 1.4 目标和背景

#### 业务目标
- 📈 **确立产品市场定位**: 明确D8D Starter的目标用户和使用场景
- 🎯 **定义成功指标**: 建立可衡量的产品成功标准
- 🔄 **建立迭代流程**: 为持续改进提供需求框架
- 🤝 **促进团队对齐**: 确保技术实现与业务目标一致
- 🔮 **扩展业务领域**: 基于D8D Starter技术基础构建命理咨询平台

#### 技术背景
D8D Starter已经具备优秀的技术基础：
- 现代化的全栈技术架构
- 模块化的代码组织
- 完整的认证和用户管理系统
- 生产就绪的部署配置

#### 业务扩展背景
基于现有技术基础，扩展命理咨询平台功能：
- 提供手机号码分析、八字详批、风水调整等专业服务
- 支持在线咨询、预约、支付等电商功能
- 集成内容管理和案例分享系统

现在需要将技术能力转化为明确的业务价值主张，并扩展至命理咨询领域。

## 2. 需求定义

### 2.1 功能需求

基于现有技术实现，我定义了以下功能需求。请仔细审核这些需求是否准确反映了项目的业务目标：

**FR1: 用户认证和管理系统**
- 必须提供完整的用户注册、登录、密码重置功能
- 支持基于JWT的安全认证机制
- 用户信息需要持久化存储到PostgreSQL数据库
- 提供用户角色和权限管理基础框架

**FR2: 现代化前端界面**
- 使用React 19构建响应式用户界面
- 采用Tailwind CSS确保一致的视觉设计
- 提供管理后台和用户主页两种界面模式
- 支持组件化开发和代码复用

**FR3: 类型安全的API架构**
- 使用Hono RPC (hc) 提供前后端统一的类型安全
- 集成@hono/zod-openapi自动生成OpenAPI文档
- 使用@hono/swagger-ui提供交互式API文档界面
- 实现通用的CRUD路由和服务，避免每个实体重复编写
- **支持关联查询和复杂数据关系处理**
- 前后端共享Zod schema，确保表单验证一致性

**FR4: 数据库集成和ORM**
- 使用TypeORM进行数据库操作抽象
- 支持PostgreSQL数据库连接和连接池管理
- 提供数据模型定义和迁移能力
- 实现基础的数据验证和约束

**FR5: 开发和生产环境支持**
- 提供Vite开发服务器支持热重载
- 支持生产环境构建和优化
- 集成Docker Compose用于本地开发环境
- 提供环境变量配置管理

**FR6: 命理咨询核心功能**
- **手机号码分析系统**: 提供手机号码吉凶分析、改号建议
- **八字详批系统**: 基于出生年月日时进行八字分析和命运解读
- **起名改名服务**: 提供个人和公司起名、改名服务
- **风水调整系统**: 平面家宅/公司风水分析和化解方案
- **职业规划咨询**: 适合行业分析、职场沟通建议
- **起卦占卜功能**: 在线起卦和占卜解读

**FR7: 咨询预约和支付系统**
- **在线预约系统**: 支持用户预约命理咨询服务
- **支付集成**: 集成第三方支付平台完成服务费用支付
- **咨询记录管理**: 存储和管理用户咨询历史记录
- **服务评价系统**: 用户对咨询服务进行评价和反馈

**FR8: 内容管理系统**
- **案例分享系统**: 展示成功案例和用户反馈
- **行业资讯发布**: 发布命理行业相关资讯和文章
- **道德经学习**: 提供道德经学习和悟道内容
- **收费标准展示**: 清晰展示各项服务的收费标准

**FR9: 客户关系管理**
- **客户信息管理**: 管理客户基本信息和咨询历史
- **跟进提醒系统**: 提醒咨询师进行客户跟进
- **营销推广功能**: 支持营销活动和优惠推广
- **数据统计分析**: 分析业务数据和客户行为

**FR10: 定价和订单管理系统**
- **服务定价配置**: 支持不同服务的动态定价和规则设置
- **订单生命周期管理**: 从预约、支付、服务执行到完成的完整流程
- **大师时间管理**: 管理大师的工作时间、接单限制和预约安排
- **支付集成管理**: 支持多种支付方式的安全集成
- **售后管理**: 支持八字详批终生售后和其他售后服务跟踪

### 详细 rationale (决策依据):

这些需求基于对现有代码的深入分析：
- **技术选择权衡**: 选择了Hono而不是Express，主要因为Hono RPC提供前后端类型安全
- **架构决策**: 采用shadcn管理后台模板，专注于提供高质量的管理界面组件
- **API设计**: 使用@hono/zod-openapi实现自动API文档生成和类型安全
- **开发效率**: 通用CRUD路由和服务大幅减少重复代码编写
- **数据验证**: 前后端共享Zod schema确保验证逻辑一致性

**命理咨询功能扩展决策**:
- **业务模式**: 基于现有技术基础快速构建垂直领域应用
- **数据模型**: 需要扩展用户模型支持咨询师角色和咨询记录
- **支付集成**: 必须集成第三方支付平台支持在线交易
- **内容管理**: 需要CMS功能支持案例分享和资讯发布
- **移动适配**: 响应式设计确保在手机端良好体验

**关键假设**:
- 目标用户是需要快速构建管理后台的全栈开发者
- 主要使用场景是创建企业级管理界面和CRUD操作
- 开发体验和类型安全是核心价值主张
- 需要提供生产就绪的认证和权限管理
- 命理咨询功能作为业务扩展，目标用户是命理咨询师和寻求咨询服务的用户

**需要验证的领域**:
- 这些功能需求是否覆盖了所有重要的业务场景？
- 是否有遗漏的关键功能？
- 优先级排序是否合理？
- 命理咨询功能的合规性和市场接受度？



### 2.2 非功能性需求

**NFR1: 类型安全和开发体验**
- 必须提供端到端的类型安全，减少运行时错误
- 开发环境需要支持热重载和快速迭代
- 代码提示和自动完成需要完整支持
- 构建过程应该快速且可靠

**NFR2: 代码质量和可维护性**
- 遵循一致的代码风格和架构模式
- 提供清晰的模块边界和接口定义
- 支持代码复用和组件化开发
- 文档需要保持与代码同步
- 通用CRUD路由和服务必须支持自定义路由和服务的扩展
- **关联查询功能需要保持性能和可维护性**

**NFR3: 安全性和认证**
- 实现基于JWT的安全认证机制
- 提供角色基础的权限控制(RBAC)
- 输入验证必须使用Zod schema
- 防止常见Web安全漏洞(XSS, CSRF等)

**NFR4: 性能和可扩展性**
- API响应时间应该在100ms以内
- 支持数据库连接池和性能优化
- 前端打包需要优化加载性能
- 架构应该支持水平扩展

**NFR5: 文档和开发者体验**
- 自动生成完整的API文档
- 提供清晰的使用示例和教程
- 错误信息应该具有指导性
- 配置过程应该简单直观

**NFR6: 命理咨询平台特殊需求**
- **数据隐私保护**: 用户个人信息和咨询记录需要严格加密保护
- **支付安全**: 支付系统必须符合PCI DSS安全标准
- **移动端优化**: 确保在手机端有良好的用户体验和响应速度
- **多语言支持**: 支持中英文界面，便于国际用户使用
- **合规性**: 确保命理咨询服务符合当地法律法规要求
- **高可用性**: 咨询预约和支付系统需要保证99.9%的可用性

### 详细 rationale (决策依据):

这些非功能性需求反映了项目的核心价值主张：
- **类型安全优先**: 选择Hono RPC和Zod是为了最大化开发效率和减少错误
- **开发者体验**: shadcn模板和通用CRUD服务专注于提升开发速度
- **扩展性设计**: 通用CRUD服务支持自定义路由和服务扩展，平衡便利性和灵活性
- **生产就绪**: 包含认证、权限、安全等企业级功能
- **文档自动化**: @hono/zod-openapi确保文档与代码同步

**技术约束**:
- 必须保持与现有shadcn设计系统的兼容性
- 需要支持PostgreSQL关系型数据库
- 前端构建基于Vite，后端基于Hono
- 部署环境支持Docker容器化

### 3.2 集成策略

**数据库集成策略**:
- 使用TypeORM实体定义数据模型
- **支持复杂的关联查询和关系映射**
- 支持数据库迁移和版本控制
- 实现连接池管理优化性能
- 提供事务支持和数据一致性保证

**API集成策略**:
- RESTful API设计遵循OpenAPI规范
- Hono RPC确保前后端类型安全
- 统一的错误处理和响应格式
- 支持API版本管理(v1前缀)
- **通用CRUD服务支持关联查询参数**

**前端集成策略**:
- shadcn UI组件库提供一致的设计语言
- React Query管理服务端状态
- 基于Zod的表单验证和类型安全
- 响应式设计支持多种设备
- **关联数据的高效渲染和处理**

**一级页面核心服务展示方案**:

### 首页核心服务布局设计

**横向三栏布局（推荐）**:
```
┌─────────────┬─────────────┬─────────────┐
│   手机改运   │   八字详批   │   风水调整   │
│   📱        │   📅        │   🏠        │
│ 号码能量分析 │ 命运精准预测 │ 环境优化方案 │
│  立即分析 →  │  立即详批 →  │  立即调整 →  │
└─────────────┴─────────────┴─────────────┘
```

**纵向瀑布流布局（备选）**:
```
手机改运
[详细内容...]

八字详批
[详细内容...]

风水调整
[详细内容...]
```

### 各核心服务展示要素

**手机改运模块**:
- **展示位置**: 页面顶部/左侧主推区域
- **核心卖点**: 手机号码吉凶分析、改号转运建议、号码能量解读
- **视觉元素**: 手机图标 + 能量流动动画
- **行动按钮**: "立即分析"

**八字详批模块**:
- **展示位置**: 页面中央/核心区域
- **核心卖点**: 基于出生年月日时的精准分析、命运走势预测、人生规划指导
- **视觉元素**: 八字命盘图表 + 时间轴展示
- **行动按钮**: "立即详批"

**风水调整模块**:
- **展示位置**: 页面右侧/底部重要区域
- **核心卖点**: 家宅/公司风水分析、专业化解方案、上门勘察服务
- **视觉元素**: 风水罗盘 + 环境布局图
- **行动按钮**: "立即调整"

### 用户体验要求
- **加载性能**: 首页核心区域加载时间 < 2秒
- **移动适配**: 在手机端保持良好可操作性和视觉体验
- **转化引导**: 每个服务模块都有明确的行动召唤按钮
- **视觉层次**: 通过颜色、大小、位置突出核心服务



## 5. Epic和故事结构

### 5.1 Epic方法

**Epic结构决策**: 多Epic并行结构 - 针对不同关注点分别优化

**决策依据**:
- 项目已经具备完整的技术基础架构
- 不同功能领域有明确的优化目标和优先级
- 独立Epic便于并行开发和专门团队负责
- 每个Epic有明确的成功标准和验收指标

### 5.2 Epic详情

**Epic 001: 测试基础设施搭建**
**Epic目标**: 为现有项目建立完整的测试基础设施，包括单元测试、集成测试和端到端测试，确保代码质量和可维护性。
**成功标准**: 测试覆盖率达标（单元测试 > 70%, 集成测试 > 50%），CI/CD流水线集成测试执行正常，数据库备份恢复机制完善

**Epic 002: 用户管理界面现代化增强**
**Epic目标**: 优化现有用户管理界面的用户体验和功能完整性，使其更符合现代Web应用标准。
**成功标准**: 用户管理操作效率提升30%，界面响应时间保持在200ms以内

**Epic 003: Lint配置集成**
**Epic目标**: 集成完整的ESLint代码质量检查配置，确保代码风格一致性和质量规范。
**成功标准**: ESLint配置能够正确检查所有.ts和.tsx文件，修复现有代码中的lint错误

**Epic 004: API实际请求测试增强**
**Epic目标**: 为现有API系统添加实际HTTP请求测试，验证系统在真实数据库环境下的行为。
**成功标准**: 所有核心API端点都有实际请求测试，测试通过率100%

**Epic 005: 命理咨询核心功能开发**
**Epic目标**: 开发命理咨询平台的核心功能，包括手机号码分析、八字详批、起名改名、风水调整等专业服务。
**成功标准**: 所有核心命理咨询功能可用，用户体验流畅，数据计算准确率>95%

**Epic 006: 咨询预约和支付系统**
**Epic目标**: 实现完整的在线咨询预约和支付系统，支持用户预约服务和完成支付。
**成功标准**: 预约系统可用性99.9%，支付成功率>98%，用户满意度>4/5

**Epic 007: 内容管理和客户关系系统**
**Epic目标**: 构建内容管理系统和客户关系管理功能，支持案例分享、资讯发布和客户跟进。
**成功标准**: 内容发布流程自动化程度>90%，客户跟进效率提升40%

**Epic 008: 定价和订单管理系统**
**Epic目标**: 建立灵活定价配置和完整订单生命周期管理，支持复杂服务定价规则。
**成功标准**: 定价配置灵活度100%，订单处理效率提升50%，支付集成成功率>99%

### 5.3 各Epic用户故事概览

**Epic 001 - 测试基础设施**:
- 基础单元测试框架搭建
- 集成测试环境配置
- 端到端测试流水线
- 数据库备份和恢复工具集成

**Epic 002 - 用户管理增强**:
- 用户搜索和过滤功能
- 批量操作支持
- 用户详情页优化

**Epic 003 - Lint配置**:
- ESLint基础框架配置
- Prettier和代码格式化集成
- 开发工作流集成和问题修复

**Epic 004 - API实际测试**:
- 实际请求测试基础设施
- 用户API实际请求测试实现
- CI/CD流水线集成

**Epic 005 - 命理咨询核心功能**:
- 手机号码吉凶分析系统
- 八字详批算法实现
- 起名改名服务功能
- 风水调整方案生成
- 职业规划咨询模块
- 起卦占卜功能实现

**Epic 006 - 咨询预约和支付**:
- 在线预约系统开发
- 第三方支付集成
- 咨询记录管理
- 服务评价系统
- 咨询师管理后台

**Epic 007 - 内容管理和CRM**:
- 案例分享系统
- 行业资讯发布
- 道德经学习内容
- 客户信息管理
- 跟进提醒系统
- 数据统计分析

**Epic 008 - 定价和订单管理**:
- 服务定价配置系统
- 订单生命周期管理
- 大师时间管理
- 支付集成管理
- 售后管理系统

## 6. 成功指标和验收标准

### 6.1 关键绩效指标(KPI)

**Epic 001 - 测试基础设施指标**:
- ✅ 单元测试覆盖率 > 70%
- ✅ 集成测试覆盖率 > 50%
- ✅ CI/CD测试流水线执行成功率 100%
- ⏱️ 测试执行时间优化在可接受范围内
- 💾 数据库备份恢复测试通过率 100%

**Epic 002 - 用户管理增强指标**:
- ⚡ 用户管理操作效率提升 30%
- ⏱️ 界面响应时间 < 200ms (p95)
- 📊 用户搜索和过滤功能使用率 > 80%
- 👍 用户满意度评分 > 4/5

**Epic 003 - Lint配置指标**:
- ✅ ESLint错误修复率 100%
- 🔧 代码风格一致性达到 95%
- 📝 开发工作流集成完成度 100%
- 🚀 开发效率提升（减少代码审查时间）

**Epic 004 - API实际测试指标**:
- ✅ 核心API端点测试覆盖率 100%
- ✅ 实际请求测试通过率 100%
- 🐛 生产环境缺陷减少 50%
- 🔄 测试数据管理自动化程度 100%

**Epic 005 - 命理咨询核心功能指标**:
- 🔮 命理算法准确率 > 95%
- ⚡ 咨询功能响应时间 < 500ms
- 📱 移动端用户体验评分 > 4.5/5
- 🔒 用户数据加密率 100%

**Epic 006 - 咨询预约和支付指标**:
- 💰 支付成功率 > 98%
- 📅 预约系统可用性 99.9%
- ⭐ 用户满意度评分 > 4/5
- 🔄 咨询记录完整性 100%

**Epic 007 - 内容管理和CRM指标**:
- 📊 内容发布效率提升 50%
- 👥 客户跟进及时率 > 90%
- 📈 业务数据分析准确率 > 95%
- 🎯 营销活动转化率 > 5%

**Epic 008 - 定价和订单管理指标**:
- 💰 定价配置灵活度 100%
- ⚡ 订单处理效率提升 50%
- 🔄 支付集成成功率 > 99%
- 📊 售后处理及时率 > 95%

**首页展示性能指标**:
- ⚡ 首页核心区域加载时间 < 2秒
- 📱 移动端首页用户体验评分 > 4.5/5
- 🎯 核心服务模块点击转化率 > 15%
- 🔄 首页跳出率 < 40%

**总体项目指标**:
- 📚 文档完整性：API文档覆盖率达到100%
- 🚀 项目使用率：内部项目采用率>60%
- 📈 功能完成度：PRD需求实现率100%
- 💼 业务收入：命理咨询平台月收入目标达成率>80%

### 6.2 验收标准

**项目级验收**:
- 所有功能需求和非功能需求实现
- 文档完整且与代码同步
- 测试覆盖率达到目标
- 性能指标满足要求
- 安全审计通过

**阶段性验收**:
- 每个用户故事完成后进行代码审查
- 每周演示进度和获取反馈
- 每月进行整体质量评估

## 7. 服务定价和业务流程

### 7.1 核心服务定价体系

#### 手机改运服务
**手机判号**
- **服务内容**: 解析感情、财运、健康、事业
- **限制条件**: 号码使用不满半年的不看，不常用的号不看（磁场未磨合，看不准）
- **价格**: 待定

**手机改号**
- **服务内容**: 根据八字喜用神选适合的号码
- **价格**: 首个选号 680元/个，叠加二次选号 980元/个

#### 八字详批服务
**八字详批**
- **服务范围**: 除了寿命什么都可以问，问出来的问题都可以化解
- **限制**: 不回答寿命问题（因为大师不能延寿）
- **售后**: 凭八字底单终生售后问询都免费，遇到问题需要化解才收费
- **价格**: 待定

**问题化解**
- **服务内容**: 根据难易程度及化解摆件数量报价
- **包含**: 摆件开光和布局方位标注
- **不包含**: 风水摆件本身
- **价格**: 根据具体问题报价

#### 起卦占卜服务
**起卦占卜**
- **收费方式**: 单人单次收费，一卦占一事
- **可问内容**: 吉凶、事态发展、相应对策及建议
- **限制**:
  - 同一事情不能起卦两次
  - 大师每日最多起三卦
  - 晚上不起卦，只可白天起卦
  - 遇事可以晚上留言
- **价格**: 待定

#### 取名改名服务
**个人取名改名**
- **新生儿取名**: 费用包含八字详批
- **已有名字改名**: 需要叠加批算八字费用
- **要求**: 提前说明要求，汇总不能用的长辈名与讨厌忌讳的字
- **限制**: 取名后不重改！！！
- **价格**: 待定

**公司或店铺取名**
- **方式1**: 提供喜欢的主体名称，由大师选择或组合不同的字
- **方式2**: 无喜欢的名字或提供的名字不适用的，则全权由大师起名
- **包含**: 主体名与公司或店铺全称
- **限制**: 除非工商注册显示已被注册，否则不重改
- **价格**: 待定

#### 风水调整服务
**家宅平面图/公司平面图**
- **单层家宅图户型图**: 勘察化解费用 2万
  - 包含：一家三口八字详批
  - 增加一名家庭成员：叠加 3千
- **个人独资、单一股东公司**: 单层平面图勘察化解费用 2万
  - 每增加一位股东或合伙人：费用叠加 3千
- **多层建筑**: 按每层勘察化解费用叠加 3千
- **包含服务**: 任何时候遇到任何问题，只需要花钱买摆件就可以，没有其他费用
- **限制**:
  - 需要客人自己画详细图纸，测准方位
  - 不看视频代画图
  - 不包上门勘察
  - 不包风水摆件

**上门勘察调整服务**
- **单层住宅或独栋别墅**: 勘察费用 8万
- **个人独资公司多栋建筑**: 增加 2万/栋的费用
- **多位股东合伙公司**:
  - 公司独栋建筑：每位股东增加 5千（包含八字详批与方位吉凶）
  - 多栋建筑且多位股东：按前述标准叠加费用

### 7.2 业务流程规范

#### 预约流程
1. **服务选择**: 用户选择具体服务类型
2. **信息提交**: 提供必要信息（八字、手机号、平面图等）
3. **费用确认**: 系统显示服务价格和支付方式
4. **预约确认**: 大师确认可接单时间
5. **支付完成**: 用户完成支付
6. **服务执行**: 大师在规定时间内完成服务
7. **结果交付**: 通过系统交付服务结果

#### 售后政策
- **八字详批**: 凭八字底单终生免费问询
- **风水调整**: 后续问题只需购买摆件，无额外服务费
- **取名服务**: 除工商注册冲突外，不重改
- **占卜服务**: 同一事情不能重复起卦

### 7.3 系统功能需求

基于以上业务流程，系统需要支持：
- **服务类型管理**: 支持不同服务的定价和规则配置
- **预约时间管理**: 大师工作时间和接单限制
- **支付集成**: 支持多种支付方式
- **文件上传**: 支持平面图、八字信息等文件上传
- **消息系统**: 支持用户与大师的沟通
- **订单管理**: 完整的订单生命周期管理

## 8. 附录

### 8.1 参考资料
- 现有架构文档: `docs/brownfield-architecture.md`
- Hono框架文档: https://hono.dev
- Zod验证库: https://zod.dev
- shadcn/ui组件库: https://ui.shadcn.com

### 8.2 相关文档
- API文档: 通过 `/ui` 端点访问
- 开发指南: `docs/development.md`
- 部署指南: `docs/deployment.md`
- 贡献指南: `docs/contributing.md`

### 8.3 联系方式
- 产品负责人: [待指定]
- 技术负责人: [待指定]
- 开发团队: [待指定]

---

**文档状态**: 已更新（集成命理咨询平台功能）
**最后更新**: 2025-09-29
**下次评审**: 2025-10-06