上次发了篇不写代码的软件开发时代已经到来，有朋友问文档是什么样的，这里发一下。
这份文档，是跟AI聊出来的，而不是自己动手一个字一个字敲出来的。
工具是 Trae ，模型是系统自带的Kimi 2.5/GLM5.0/MiniMax2.5等。
这里顺便提一句，即便不写程序的朋友，也可以安装Trae、CodeBuddy等VSCode类的IDE（集成开发环境）工具。
这类工具比传统办公软件，对AI的支持程度要高得多。
至于传统办公软件，只把它们当成排版工具就可以了。
1. 项目概述
1.1 项目背景
旅游年卡在线销售平台，销售产品为各类旅游年卡（电子卡），一次性销售，不涉及线下核销。
1.2 项目目标
1.3 项目类型
B2C 电商平台（旅游年卡垂直领域）- 虚拟商品销售，Web 应用
2. 技术架构
2.1 技术栈选型
2.2 系统架构图
┌─────────────────────────────────────────────────────────┐│ Web 客户端 (React) ││ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ││ │ 首页 │ │ 详情页 │ │ 购物车 │ │ 用户中心 │ ││ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │└───────┼───────────┼───────────┼───────────┼───────────┘ │ │ │ │ └───────────┴─────┬─────┴───────────┘ │ ┌─────▼─────┐ │ Nginx │ │ (负载均衡) │ └─────┬─────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ │API Server │ │API Server │ │API Server │ │ (Node.js)│ │ (Node.js)│ │ (Node.js)│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │ │ └─────────────────┼─────────────────┘ │ ┌───────────┼───────────┐ │ │ │ ┌─────▼─────┐ ┌───▼───┐ ┌─────▼─────┐ │ PostgreSQL│ │Redis │ │ 腾讯云COS │ │(主数据库) │ │(缓存) │ │ (文件存储) │ └───────────┘ └───────┘ └───────────┘
2.3 目录结构
ct-yearcard/├── client/ # Web 前端（React）│ ├── src/│ │ ├── components/ # 公共组件│ │ │ ├── Button/ # 按钮组件│ │ │ ├── Header/ # 头部导航│ │ │ ├── ProductCard/ # 商品卡片│ │ │ ├── Toast/ # 提示组件│ │ │ └── ErrorBoundary/ # 错误边界│ │ ├── pages/ # 页面│ │ │ ├── Home/ # 首页│ │ │ ├── ProductDetail/ # 商品详情│ │ │ ├── Cart/ # 购物车│ │ │ ├── Checkout/ # 结算页│ │ │ ├── OrderList/ # 订单列表│ │ │ ├── OrderDetail/ # 订单详情│ │ │ ├── UserCenter/ # 用户中心│ │ │ ├── Login/ # 登录页│ │ │ ├── Coupons/ # 优惠券页│ │ │ ├── Points/ # 积分明细页│ │ │ └── Feedback/ # 意见反馈页│ │ ├── services/ # API 请求封装│ │ ├── store/ # Zustand 状态管理│ │ ├── styles/ # 全局样式│ │ ├── App.tsx # 应用入口│ │ └── main.tsx # 渲染入口│ ├── index.html│ ├── vite.config.ts # Vite 配置│ └── package.json│├── server/ # 后端项目│ ├── src/│ │ ├── common/ # 公共模块│ │ │ ├── decorators/ # 装饰器│ │ │ ├── filters/ # 异常过滤器│ │ │ ├── guards/ # 守卫│ │ │ └── utils/ # 工具函数│ │ ├── config/ # 配置文件│ │ ├── modules/ # 业务模块│ │ │ ├── auth/ # 认证模块│ │ │ ├── user/ # 用户模块│ │ │ ├── product/ # 商品模块│ │ │ ├── cart/ # 购物车模块│ │ │ ├── order/ # 订单模块│ │ │ ├── payment/ # 支付模块│ │ │ ├── coupon/ # 优惠券模块│ │ │ └── feedback/ # 反馈模块│ │ ├── app.module.ts│ │ └── main.ts│ ├── prisma/│ │ ├── schema.prisma # 数据库模型│ │ └── seed.ts # 种子数据│ ├── package.json│ └── tsconfig.json│├── docs/│ ├── DESIGN.md # 本设计文档│ └── BUG_FIXES.md # Bug 修复记录│├── docker-compose.yml # Docker 编排└── package.json # 根目录脚本
3. 数据库设计
3.1 ER 图（实体关系）
┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ users │ │ products │ │ coupons │├─────────────┤ ├─────────────┤ ├─────────────┤│ id (PK) │ │ id (PK) │ │ id (PK) ││ username │ │ name │ │ code ││ email │ │ type │ │ name ││ phone │ │ price │ │ value ││ password_ │ │ stock │ │ min_amount ││ hash │ │ status │ │ total_count ││ nickname │ └──────┬──────┘ │ used_count ││ role │ │ └──────┬──────┘│ status │ │ ││ points │ │ │└──────┬──────┘ │ │ │ │ │ │ 1:N │ N:N │ ▼ │ │┌─────────────┐ ┌──────▼──────┐ ┌──────▼──────┐│ cart_items │ │ order_items│ │ user_coupons│├─────────────┤ ├─────────────┤ ├─────────────┤│ id (PK) │ │ id (PK) │ │ id (PK) ││ user_id (FK)│◄──────│ order_id(FK)│ │ user_id(FK) ││ product_id │ │ product_id │ │ coupon_id ││ (FK) │ │ (FK) │ │ (FK) ││ quantity │ │ product_name│ │ status │└──────┬──────┘ │ price │ │ order_id │ │ │ quantity │ └──────┬──────┘ │ │ subtotal │ │ │ └──────┬──────┘ │ │ │ │ │ 1:N │ 1:N │ ▼ ▼ ▼┌─────────────┐ ┌─────────────┐│ orders │ │ card_codes │├─────────────┤ ├─────────────┤│ id (PK) │ │ id (PK) ││ order_no │ │ product_id ││ user_id(FK) │◄──────│ order_item_ ││ total_amount│ │ id (FK) ││ discount_ │ │ code ││ amount │ │ password ││ pay_amount │ │ status ││ status │ │ expired_at ││ pay_method │ └─────────────┘│ pay_time ││ expired_at │└─────────────┘
3.2 数据模型
3.1.1 用户表 (users)
3.1.2 年卡商品表 (products)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
provincial/hefei/huangshan/chizhou/other
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.1.3 订单表 (orders)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PENDING/PAID/CANCELLED/REFUNDED
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.1.4 订单商品表 (order_items)
3.1.5 积分记录表 (points_records)
3.1.6 购物车表 (cart_items)
3.1.7 优惠券表 (coupons)
3.1.8 用户优惠券表 (user_coupons)
3.1.9 年卡卡密表 (card_codes)
3.3 索引与约束
3.4 级联关系
4. API 接口设计
4.1 接口规范
-
-
-
-
响应格式：
{ code: number, message: string, data: any }
4.2 接口列表
4.2.1 认证模块
4.2.2 商品模块
4.2.3 购物车模块
4.2.4 订单模块
4.2.5 支付模块
4.2.6 优惠券模块
4.2.7 用户模块
4.3 详细接口规范
4.3.1 认证模块
POST /auth/login – 微信小程序登录
GET /auth/info – 获取当前用户信息
4.3.2 商品模块
GET /products – 商品列表
GET /products/:id – 商品详情
4.3.3 购物车模块
GET /cart – 获取购物车列表
POST /cart – 添加到购物车
4.3.4 订单模块
POST /orders – 创建订单
items 数组项结构：
GET /orders – 订单列表
|
|
|
|
|
|
|
|
|
状态筛选（pending/paid/cancelled）
|
|
|
|
|
|
|
|
|
|
|
GET /orders/:id – 订单详情
4.3.5 支付模块
POST /payment/create – 创建支付
|
|
|
|
|
|
|
|
|
|
|
微信支付参数（appId, timeStamp, nonceStr, package, signType, paySign）
|
4.3.6 优惠券模块
GET /coupons – 可领取优惠券列表
GET /my-coupons/available – 可用优惠券
4.4 错误码规范
4.5 响应示例
成功响应：
{"code": 0,"message": "success","data": {"id": "xxx","name": "测试" }}
失败响应：
{"code": 1001,"message": "缺少必要参数","data": null}
5. 前端页面设计
5.1 页面结构
├── 首页 (Home) ✅ 已实现│ ├── 顶部导航（Logo、搜索、购物车、用户入口）│ ├── 分类筛选区│ ├── 年卡列表（卡片式展示）│ └── 商品推荐│├── 登录页 (Login) ✅ 已实现│ ├── 账号密码登录│ ├── 注册表单│ └── 协议勾选│├── 商品详情页 (ProductDetail) ✅ 已实现│ ├── 商品图片展示│ ├── 价格区域（原价/促销价）│ ├── 商品信息（名称、城市、适用景区）│ ├── 数量选择│ ├── 加入购物车 / 立即购买│ ├── 商品详情介绍│ └── 产品特点│├── 购物车页 (Cart) ✅ 已实现│ ├── 商品列表（勾选、数量修改）│ ├── 全选操作│ ├── 价格汇总│ └── 去结算│├── 结算页 (Checkout) ✅ 已实现│ ├── 订单商品预览│ ├── 优惠券选择│ ├── 积分抵扣│ ├── 支付方式选择│ └── 提交订单│├── 订单列表页 (OrderList) ✅ 已实现│ ├── 订单筛选（全部/待支付/已支付/已取消）│ ├── 订单卡片│ └── 订单详情入口│├── 订单详情页 (OrderDetail) ✅ 已实现│ ├── 订单状态│ ├── 商品信息│ ├── 支付信息│ └── 操作按钮（支付/取消）│├── 用户中心 (UserCenter) ✅ 已实现│ ├── 用户头像/昵称│ ├── 订单快捷入口│ ├── 优惠券入口│ ├── 积分入口│ └── 退出登录│├── 优惠券页 (Coupons) ✅ 已实现│ ├── 可用优惠券列表│ ├── 已使用优惠券│ ├── 已过期优惠券│ ├── 票券式卡片设计│ └── 使用说明│├── 积分明细页 (Points) ✅ 已实现│ ├── 积分余额展示│ ├── 积分明细列表│ └── 积分规则说明│└── 意见反馈页 (Feedback) ✅ 已实现 ├── 反馈表单 └── 提交反馈
5.2 公共组件
|
|
|
|
|
|
components/Header |
|
|
|
components/Button |
|
|
|
components/ProductCard |
|
|
|
components/Toast |
|
|
|
components/ErrorBoundary |
|
5.2 核心交互流程
5.2.1 购买流程
1. 用户浏览年卡列表 ↓2. 点击进入年卡详情页 ↓3. 选择年卡类型、数量 ↓4. 点击"加入购物车"或"立即购买" ↓5a. 加入购物车 → 继续浏览/去购物车结算5b. 立即购买 → 进入结算页 ↓6. 结算页：选择优惠券、积分抵扣 ↓7. 提交订单 → 选择支付方式 ↓8. 调用支付接口 → 跳转支付网关 ↓9. 支付成功 → 获取卡密/兑换码 → 订单详情
6. 安全设计
6.1 认证与授权
-
-
JWT Token 有效期：access_token 2小时，refresh_token 7天
-
-
6.2 数据安全
-
SQL 注入：使用 Prisma ORM 参数化查询
-
-
-
6.3 支付安全
7. 部署方案
7.1 环境准备
7.2 开发环境搭建（本地 Docker）
7.2.1 环境要求
7.2.2 docker-compose.yml
在项目根目录创建 docker-compose.yml：
version:'3.8'services:# PostgreSQL 数据库postgres:image:postgres:15-alpinecontainer_name:yearcard-postgresenvironment:POSTGRES_USER:yearcardPOSTGRES_PASSWORD:yearcard123POSTGRES_DB:yearcardports:-"5432:5432"volumes:-postgres_data:/var/lib/postgresql/datahealthcheck:test:["CMD-SHELL","pg_isready -U yearcard"]interval:10stimeout:5sretries:5# Redis 缓存redis:image:redis:7-alpinecontainer_name:yearcard-redisports:-"6379:6379"volumes:-redis_data:/datacommand:redis-server--appendonlyyeshealthcheck:test:["CMD","redis-cli","ping"]interval:10stimeout:5sretries:5volumes:postgres_data:redis_data:
7.2.3 启动步骤
# 1. 启动服务docker-compose up -d# 2. 查看服务状态docker-compose ps# 3. 查看日志docker-compose logs -f# 4. 停止服务docker-compose down
7.2.4 连接配置
服务启动后，本地连接信息：
7.2.5 后端 .env 配置
DATABASE_URL="postgresql://yearcard:yearcard123@localhost:5432/yearcard"REDIS_URL="redis://localhost:6379"JWT_SECRET="dev-secret-key-change-in-production"JWT_EXPIRES_IN="2h"
7.2.6 初始化数据库
cd server# 安装依赖npm install# 执行数据库迁移npx prisma migrate dev# 生成 Prisma Clientnpx prisma generate
7.3 部署流程
1. 构建前端：npm run build2. 构建后端：npm run build3. 配置 Nginx 静态文件托管4. 配置 PM2 进程管理5. 配置 HTTPS 证书6. 配置域名解析
8. 开发计划
Phase 1：基础框架 ✅ 已完成
Phase 2：核心功能 ✅ 已完成
Phase 3：支付与完善 ✅ 已完成
Phase 4：优化与上线 🚧 进行中
当前实现状态
夜雨聆风
