211 lines
10 KiB
Markdown
211 lines
10 KiB
Markdown
# 智绘微刻小程序 R1 前后端任务报告
|
||
|
||
> 报告日期：2026-09-14
|
||
> 关联前端：`wechat_wc`（Gitee）
|
||
> 关联后端：`wxmp_backend`（GitHub）
|
||
> 本报告用于说明当前小程序的整体功能、R1 商品目录工作、前后端联调结果以及可交付状态。
|
||
|
||
## 一、项目概况
|
||
|
||
“智绘微刻”是一个微信小程序定制商城。用户可以浏览激光微雕商品，查看商品详情，制作个性化设计，保存设计清单，填写收货地址并提交订单。后端负责统一保存商品、用户、地址、设计、订单和支付等业务数据，前端负责小程序页面展示和交互。
|
||
|
||
简单来说，整个项目是一条完整的定制购物链路：
|
||
|
||
**浏览商品 → 查看详情 → 进入定制 → 保存设计 → 选择地址 → 提交订单 → 查看订单状态。**
|
||
|
||
前端采用 Taro + React + TypeScript，可编译为微信小程序；后端采用 NestJS + Prisma，使用 PostgreSQL 保存业务数据，Redis 用于缓存或队列能力。开发环境通过 Docker Compose 统一运行，减少 Windows 与 Linux 部署环境之间的差异。
|
||
|
||
## 二、当前小程序已经具备的功能
|
||
|
||
### 1. 首页
|
||
|
||
- 小程序品牌标题和搜索入口。
|
||
- 定制成品展示区。
|
||
- 热门品类图片入口。
|
||
- 为你推荐商品区。
|
||
- 搜索商品时只显示搜索结果，自动隐藏成品展示、热门品类和推荐区，避免内容混杂。
|
||
- 商品价格、名称和图片优先来自后端接口，接口暂时不可用时保留本地缓存展示。
|
||
|
||
### 2. 商品目录与详情
|
||
|
||
- 商品列表页展示在售商品。
|
||
- 支持商品图片、名称、描述和价格展示。
|
||
- 商品详情页展示主图、名称、价格、原价、商品介绍、设计理念、使用场景、标签和规格参数。
|
||
- 商品详情页保留原有的沉浸式主图收束动画和滚动过渡。
|
||
- 顶部返回按钮和底部返回按钮均可返回商品列表。
|
||
- 商品列表和商品详情均已接入后端，而不是只依赖前端写死数据。
|
||
|
||
### 3. 个性化定制
|
||
|
||
- 定制页面支持词云、底图和贴纸等设计元素。
|
||
- 支持贴纸编辑、位置调整、缩放和旋转。
|
||
- 设计数据按统一结构保存，可供后续生产投递使用。
|
||
- 支持从设计清单继续编辑。
|
||
|
||
### 4. 设计清单
|
||
|
||
- 查看个人设计清单。
|
||
- 按“未设计、设计中、生产中、已下单”等状态查看。
|
||
- 进入设计、继续设计和批量删除。
|
||
- 设计数据支持本地暂存与后端同步。
|
||
|
||
### 5. 地址与订单
|
||
|
||
- 收货地址新增、修改、删除和设置默认地址。
|
||
- 结算页展示设计预览、商品数量、价格和收货地址。
|
||
- 下单时由后端根据真实商品价格重新计算金额，避免只相信前端传来的价格。
|
||
- 订单列表、订单详情、订单状态和支付入口已经接入项目流程。
|
||
|
||
### 6. 用户与其他页面
|
||
|
||
- 微信登录、用户资料和个人中心。
|
||
- 订单、设计清单、地址、设置、协议和客服页面。
|
||
- 词云生成任务、任务状态查询和结果获取接口。
|
||
- OSS 图片资源和上传凭证接口。
|
||
|
||
## 三、R1 商品目录工作内容
|
||
|
||
R1 的核心不是单独做一个静态目录页面，而是建立“商品目录数据通路”：后端提供统一商品数据，前端通过接口读取并展示，其他成员的设计、订单和生产功能都使用同一份商品信息。
|
||
|
||
### 后端已完成
|
||
|
||
- 商品分类数据模型和分类列表接口。
|
||
- 商品数据模型、在售状态和排序字段。
|
||
- 商品列表接口，支持分页、分类筛选和关键词搜索。
|
||
- 商品详情接口，只返回在售商品。
|
||
- 创建商品接口，供管理后台或初始化数据使用。
|
||
- DTO 参数校验、分页上限和统一金额输出。
|
||
- Prisma 数据库迁移和种子数据。
|
||
- Swagger 接口说明和 `api-contract-v1.md` 契约同步。
|
||
|
||
### 前端已完成
|
||
|
||
- 首页、商品列表页调用 `fetchProducts`。
|
||
- 商品详情页调用 `fetchProduct`。
|
||
- 增加后端字段到前端商品模型的适配处理。
|
||
- 服务端字段不完整时，使用本地商品资料补齐介绍、规格、标签和图片。
|
||
- 商品价格、名称和图片不再由页面单独维护，减少前后端数据不一致。
|
||
|
||
### R1 对外接口
|
||
|
||
| 接口 | 用途 | 状态 |
|
||
|---|---|---|
|
||
| `GET /api/categories` | 获取商品分类 | 已完成 |
|
||
| `GET /api/products` | 获取在售商品列表，支持分页、分类和关键词 | 已完成 |
|
||
| `GET /api/products/:id` | 获取商品详情 | 已完成 |
|
||
| `POST /api/products` | 创建商品，管理端使用 | 已完成 |
|
||
|
||
接口契约中的基础路径、鉴权规则、分页格式、金额格式和错误码保持统一，后续成员可直接按契约消费，不需要各自猜测字段。
|
||
|
||
## 四、前后端联调与验证结果
|
||
|
||
本项目已经进行过本机容器化联调和前端编译验证。
|
||
|
||
### 已验证内容
|
||
|
||
1. Docker Compose 可以启动后端、PostgreSQL 和 Redis 容器。
|
||
2. 后端健康检查可用，Swagger 文档可以打开。
|
||
3. 商品列表接口和商品详情接口可以返回商品数据。
|
||
4. 前端商品列表和详情页能够读取后端数据。
|
||
5. 修改后端数据库中的商品价格后，重新编译并刷新前端，页面价格同步变化。
|
||
6. 该价格变化证明前端不是只显示写死数据，前后端数据通路已经打通。
|
||
7. 商品详情页的介绍文本、主图、价格和滚动过渡已恢复并编译通过。
|
||
8. 自定义底部栏增加了独立点击入口，降低不同微信基础库下点击失效的概率。
|
||
|
||
### 当前验证结论
|
||
|
||
商品目录接口已经经过实际联调，可以作为其他成员开发设计清单、订单和生产流程时的共同数据来源。前端和后端的目录字段能够对齐，商品信息修改能够传递到页面，R1 商品目录部分达到可交付状态。
|
||
|
||
## 五、工作量概览
|
||
|
||
工作量不仅包括写几个接口，还包括数据模型、接口契约、种子数据、容器化环境、前端适配和联调验证。
|
||
|
||
### 后端工作量
|
||
|
||
- 商品分类和商品数据结构设计。
|
||
- Prisma schema 与迁移脚本。
|
||
- 商品列表、详情和创建接口。
|
||
- 分页、关键词、分类筛选和在售状态过滤。
|
||
- DTO 校验和金额类型转换。
|
||
- 商品种子数据维护。
|
||
- Docker 开发镜像和 Compose 联调配置。
|
||
- 接口契约、对接说明和验证说明文档。
|
||
|
||
R1 商品目录实现涉及约 15 个后端文件，包含接口、服务、DTO、数据库迁移、种子数据、Docker 配置和文档。
|
||
|
||
### 前端工作量
|
||
|
||
- 首页商品数据接入。
|
||
- 商品列表页和详情页数据接入。
|
||
- 前后端商品字段适配及本地兜底。
|
||
- 商品搜索结果布局优化。
|
||
- 热门品类改为图片入口，降低图标入口的识别成本。
|
||
- 商品详情页介绍文本和规格信息补齐。
|
||
- 沉浸式详情页滚动过渡恢复和节流优化。
|
||
- 详情页返回逻辑兼容处理。
|
||
- 自定义底部栏点击逻辑增强。
|
||
- 微信小程序构建产物更新。
|
||
|
||
前端 R1 相关改动覆盖首页、商品列表、商品详情、商品接口适配、自定义底部栏及对应编译产物。
|
||
|
||
## 六、项目的独特性和提升点
|
||
|
||
### 1. 商品数据真正统一
|
||
|
||
商品价格、图片、描述和规格由后端统一维护，首页、商品目录、详情、定制和订单可以使用同一商品记录。后续调整价格或下架商品时，不需要逐个修改前端页面。
|
||
|
||
### 2. 面向定制生产，而不是普通电商展示
|
||
|
||
商品信息不仅用于展示，还与设计数据、词云结果、贴纸和后续生产投递关联。设计清单中的数据结构为后续生成生产文件保留了统一入口。
|
||
|
||
### 3. 前端具备离线兜底能力
|
||
|
||
当开发环境接口暂时不可用时，页面仍可以使用本地商品配置展示，方便开发调试；接口恢复后再以服务端数据为准。
|
||
|
||
### 4. 详情页具有沉浸式交互
|
||
|
||
商品详情页不是简单的静态表格，而是通过主图收束、标题接替、内容渐入和滚动节流，形成更接近实物定制展示的浏览体验。
|
||
|
||
### 5. 开发环境可迁移
|
||
|
||
Docker Compose 将 Node、PostgreSQL 和 Redis 组合在一起，本机 Windows 环境可以模拟 Linux 容器运行方式，后续迁移到服务器时主要调整环境变量和反向代理配置。
|
||
|
||
### 6. 契约优先的多人协作
|
||
|
||
前后端以 `api-contract-v1.md` 为共同依据，接口字段、金额、分页、鉴权和错误码都有明确约定。R2、R3、R4 成员可以在不复制整套项目的情况下，直接消费 R1 商品接口。
|
||
|
||
## 七、代码交付情况
|
||
|
||
### 前端
|
||
|
||
- 远程仓库：Gitee `lhmin0604/wechat_wc`
|
||
- 分支：`feat/r1-catalog`
|
||
- 最新提交：`99bcf4a fix(ui): restore tab bar and detail navigation`
|
||
- 状态：已推送，工作区干净
|
||
|
||
### 后端
|
||
|
||
- 远程仓库：GitHub `obroccolio/wxmp_backend`
|
||
- 分支：`feat/r1-catalog`
|
||
- 最新提交：`d27753f chore: snapshot handoff documents before home search redesign`
|
||
- 状态：已推送，工作区干净
|
||
|
||
两个仓库均保留独立分支，其他成员可以先拉取分支检查，再合并到各自主干，不会覆盖主干历史。
|
||
|
||
## 八、仍需在上线前确认的事项
|
||
|
||
以下内容不影响 R1 商品目录已经完成，但在真机和正式上线前仍需确认：
|
||
|
||
- 微信公众平台 AppID、AppSecret 与后端环境变量必须属于同一个小程序。
|
||
- 真机不能访问本机 `127.0.0.1`，需要使用 HTTPS 域名、FRP 或服务器反向代理。
|
||
- 微信公众平台需要配置后端接口合法域名和 OSS 图片合法域名。
|
||
- 生产环境需要使用正式数据库、Redis、OSS 和 JWT 密钥，不能沿用本机测试值。
|
||
- 真机测试时应再次检查首页、商品列表、商品详情、设计清单、地址和订单请求是否返回 200。
|
||
|
||
## 九、最终结论
|
||
|
||
当前项目已经形成一个可运行的定制商城小程序雏形，前端页面、后端业务接口、数据库、Docker 开发环境和多人协作契约已经连接起来。
|
||
|
||
R1 商品目录的核心目标已经完成：后端提供可复用的商品分类、商品列表和商品详情接口，前端已经完成真实接口对接，并通过修改后端商品价格后前端同步变化的方式验证了数据通路。该接口可以交给其他成员继续用于设计清单、订单和生产流程开发。
|
||
|