| 
|
+
+[Watch the short storefront walkthrough](docs/media/storefront-walkthrough.mp4) · [Read the project story and demo script](docs/showcase.md)
+
+The walkthrough is assembled from captured screens of the working interface; it is not a real-time screen recording.
+
## Quick start
Use Node.js **22.22+** (Node 22 LTS recommended).
@@ -25,7 +38,7 @@ Open [localhost:3000](http://localhost:3000). No `.env`, database, seed command,
## Try the complete journey
-1. Open **Products**, filter by category/colour/price, or search with **⌘K / Ctrl+K**.
+1. Open **The collection**, filter by category/colour/price, or search with **⌘K / Ctrl+K**.
2. Choose a product colour and size. Unavailable variants cannot be added.
3. Open the cart, adjust quantities and continue to checkout.
4. Keep the example shipping address and select **Place demo order**. There is no card form.
@@ -35,13 +48,14 @@ Open [localhost:3000](http://localhost:3000). No `.env`, database, seed command,
## Features
- **One catalog, everywhere:** home, search, filtered listings, sale items, all 12 product pages and sitemap share one data source.
-- **Shareable discovery:** category, colour, price and sorting are reflected in the URL; “New arrivals” works on direct visits.
+- **Shareable discovery:** category, colour, price and sorting are reflected in the URL; direct links such as `/products?sort=newest` preserve the **Newest** sort order.
- **Persistent cart:** variant quantities survive reloads; integer validation, unavailable-product handling and per-variant stock limits.
- **Guest checkout:** catalog-based price recalculation, consistent shipping thresholds, empty-cart protection and useful storage-error feedback.
- **Saved demo orders:** unique IDs, item and price snapshots, order history, missing-order states and interactive simulated delivery.
-- **Responsive interface:** mobile navigation and filters, image gallery, dark/light themes, labelled controls and a skip link.
+- **Boutique visual identity:** an editorial home page, warm neutral surfaces, olive accents and a responsive layout with dark/light themes.
+- **Accessible interactions:** labelled controls, keyboard search, a skip link, mobile navigation and filters.
- **Configurable branding:** store name, description, currency, shipping and canonical URL in one file.
-- **Validation:** domain and component tests plus lint, TypeScript and production build checks, with a ready-to-enable CI workflow.
+- **Validation:** domain and component tests plus lint, TypeScript and production build checks; GitHub Actions configuration lives alongside the code.
## Make it your own
@@ -65,7 +79,7 @@ npm run build
npm run start
```
-`npm run test` starts watch mode. `npm run typecheck` performs a separate type check (the production build also checks types). A ready-to-enable GitHub Actions workflow is provided in `docs/storefront-checks.yml`. To activate it, copy it to `.github/workflows/ci.yml` using a GitHub connection with workflow-write permission. It will then check pull requests and pushes to `main`.
+`npm run test` starts watch mode. `npm run typecheck` performs a separate type check (the production build also checks types). The [Storefront checks workflow](.github/workflows/storefront-checks.yml) installs locked dependencies, lints, tests and builds on pull requests and pushes to `main`. It can also be run manually from GitHub Actions. It uses a read-only repository token and does not deploy the site. Check the [Actions page](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml) for the status of a particular commit.
Tests cover stock and quantity limits, duplicate and stale cart data, price recalculation, shipping boundaries, unique order IDs, persistence, malformed saved orders, failed storage, missing orders and the guest checkout UI.
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 17f76b5..6f51803 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -1,9 +1,23 @@
-# My Shop · 可完整体验的电商作品集
+# FORMA · 可完整体验的电商作品集
-这是一个用 Next.js、React 和 TypeScript 构建的简洁商店，也是可继续扩展的店铺模板。重点是让访客完整体验“浏览 → 选规格 → 购物车 → 模拟下单 → 查看订单 → 模拟配送”。
+FORMA 是 **my-shop** 开源模板中的示例品牌，用 Next.js、React 和 TypeScript 构建。暖白、深橄榄色、商品大图与留白构成自然简约的精品店视觉。访客可以完整体验“浏览 → 选规格 → 购物车 → 模拟下单 → 查看订单 → 模拟配送”。
**这是演示项目：不收款、不发货、不发送邮件，也不需要注册。** 订单只保存在当前浏览器，请使用结算页提供的虚构地址。
+[English](../README.md) · [作品介绍与演示脚本](showcase.md) · [架构与扩展说明](architecture.md)
+
+## 效果预览
+
+
+
+| 手机首页 | 模拟订单 |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 
| 
|
+
+[观看简短演示](media/storefront-walkthrough.mp4)
+
+演示视频由实际界面截图串联制作，用于展示购物流程，并非实时录屏。从顶部的 **The collection** 进入商品列表即可亲自体验。
+
## 本地启动
使用 Node.js 22.22 或更新版本（推荐 Node 22 LTS）：
@@ -17,7 +31,7 @@ npm run dev
打开 http://localhost:3000 。无需配置数据库、支付密钥或 `.env`。安装依赖、构建时加载 Google 字体，以及显示 Unsplash 图片需要联网。
-## 本次完善的内容
+## 功能与设计
- 首页、搜索、列表、促销和详情统一使用 12 件示例商品，价格与链接保持一致。
- 分类、颜色、价格和排序保存在网址中，直接打开“新品”链接也会正确排序。
@@ -26,7 +40,8 @@ npm run dev
- 订单拥有独立编号和商品快照，可刷新查看；未知订单不会显示虚构的固定记录。
- 配送页面可以手动推进演示状态，不会冒充真实物流查询。
- 手机布局、主题切换、键盘搜索、空状态和错误提示。
-- 自动测试与待启用的 GitHub Actions 配置，帮助后续迭代。
+- 自然简约的 FORMA 品牌视觉，以及桌面、手机和订单展示素材。
+- 自动测试与 GitHub Actions 配置，帮助后续迭代。
## 自定义入口
@@ -51,6 +66,8 @@ npm run start
参考[部署指南](deployment.md)和[架构与扩展说明](architecture.md)。数据库设计保留在 `prisma/schema.prisma` 供后续参考，目前应用不会连接数据库。
-下一阶段可以完善独立品牌视觉、产品内容编辑和自动化浏览器测试；真实登录、支付和共享库存应作为有明确后端边界的新阶段。
+下一阶段可以完善产品内容编辑和自动化浏览器测试；真实登录、支付和共享库存应作为有明确后端边界的新阶段。
+
+自动检查配置位于 [`.github/workflows/storefront-checks.yml`](../.github/workflows/storefront-checks.yml)，覆盖拉取请求和 `main` 分支更新，也支持手动运行。流程安装锁定依赖，然后执行代码检查、测试和生产构建；仓库令牌仅有读取权限。它不会自动部署网站，具体提交是否通过请以 [GitHub Actions 记录](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml)为准。
-自动检查配置位于 `docs/storefront-checks.yml`。当前 GitHub 连接没有 `workflow` 权限，尚未启用；之后用具备该权限的连接将它放到 `.github/workflows/ci.yml` 即可。
+应用代码采用 [MIT 许可证](../LICENSE)，方便保留署名后复用。示例照片来源与使用说明见英文 README。
diff --git a/docs/deployment.md b/docs/deployment.md
index 922680c..d8ef597 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -29,7 +29,7 @@ This app also runs with `npm run build` followed by `npm run start`. Set the env
## Verify the deployed site
- Home, product listing, all product details and sale pages load.
-- `Products → choose variant → cart → checkout → Place demo order` produces the selected items and calculated total.
+- `The collection → choose variant → cart → Checkout → Place demo order` produces the selected items and calculated total.
- Refreshing the order URL restores the order in the same browser.
- An order URL opened in a different browser shows the missing-order message.
- A cart below the shipping threshold has the configured demo shipping charge; one at or above it ships free.
diff --git a/docs/media/demo-order.jpg b/docs/media/demo-order.jpg
new file mode 100644
index 0000000..0abdc05
Binary files /dev/null and b/docs/media/demo-order.jpg differ
diff --git a/docs/media/desktop-home.jpg b/docs/media/desktop-home.jpg
new file mode 100644
index 0000000..8109566
Binary files /dev/null and b/docs/media/desktop-home.jpg differ
diff --git a/docs/media/mobile-home.jpg b/docs/media/mobile-home.jpg
new file mode 100644
index 0000000..c805274
Binary files /dev/null and b/docs/media/mobile-home.jpg differ
diff --git a/docs/media/storefront-walkthrough.mp4 b/docs/media/storefront-walkthrough.mp4
new file mode 100644
index 0000000..c0b27cf
Binary files /dev/null and b/docs/media/storefront-walkthrough.mp4 differ
diff --git a/docs/showcase.md b/docs/showcase.md
new file mode 100644
index 0000000..322ba48
--- /dev/null
+++ b/docs/showcase.md
@@ -0,0 +1,71 @@
+# FORMA storefront · Project showcase
+
+[Repository](https://github.com/SakuraUltra/my-shop) · [Desktop preview](media/desktop-home.jpg) · [Mobile preview](media/mobile-home.jpg) · [Walkthrough](media/storefront-walkthrough.mp4)
+
+## Project summary
+
+**FORMA is a responsive ecommerce storefront and reusable Next.js template for a fictional everyday clothing and lifestyle brand.** Its warm ivory and deep olive visual identity sits around a complete guest shopping journey: discovery, variant selection, a persistent cart, simulated checkout, saved orders and an interactive delivery timeline.
+
+The project focuses on making the experience consistent. A shared catalog supplies every shopping surface; catalog prices and variant availability are checked again at checkout. Orders preserve their own item and amount snapshots, so later catalog changes do not rewrite saved history. Failed browser storage leaves the cart intact and gives the visitor a recoverable error.
+
+The default installation needs no database, payment keys or user account. That makes it easy to run as a portfolio demo or adapt as a storefront starter. Production authentication, payment processing, shared inventory and fulfillment are future server integrations, not features of this demo.
+
+## Problem → implementation
+
+| Problem | Implementation |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| A generic shop layout does not communicate a clear brand | A restrained FORMA identity, editorial home page, warm neutral palette and responsive product presentation |
+| Separate product data makes search, listings and details disagree | One typed catalog across home, search, filters, sale pages and product details |
+| A cart can contain stale prices, invalid quantities or unavailable variants | Restore-time repair, per-variant limits and catalog-based checkout validation |
+| A checkout demo can end at a disconnected confirmation screen | Unique local order snapshots, history and a manually advanced delivery simulation |
+| Browser persistence can fail or contain malformed data | Validated reads, explicit error states and saving the order before clearing the cart |
+| A reusable template needs a clear starting point | No-key setup, centralized store configuration, MIT licensing and bilingual documentation |
+
+## Suggested CV entry
+
+**FORMA — Next.js ecommerce storefront** · React, TypeScript, Tailwind CSS, Zustand, Vitest
+
+- Built a responsive storefront spanning product discovery, variant selection, a persistent cart and guest demo checkout, with a shared typed catalog across the shopping journey.
+- Implemented catalog-based price and quantity validation, persistent order snapshots, storage-failure handling and an interactive simulated delivery timeline.
+- Created a reusable MIT-licensed template with centralized branding, bilingual documentation and a GitHub Actions workflow for lint, tests and production builds.
+
+Describe this as a **frontend commerce demo**. Do not describe it as a live payment platform or claim customer, revenue, conversion or performance results without measurements.
+
+## 演示与作品集介绍
+
+**FORMA 是一个以日常服饰和生活用品为主题的电商前端作品，同时也是可复用的 Next.js 开源模板。** 视觉采用暖白与深橄榄色，通过商品大图、排版和留白呈现自然简约的精品店风格。
+
+项目打通了浏览、搜索筛选、选择规格、购物车、模拟结算、保存订单与模拟配送的完整体验。核心设计是让整个购物过程使用同一份商品数据，并在恢复购物车和结算时重新验证价格与数量。订单以独立快照保存在浏览器中，保存失败时不会清空购物车。
+
+无需数据库、支付密钥或注册账号即可运行，适合用于作品展示和继续开发。真实支付、登录权限、共享库存和物流不在当前演示范围内。
+
+### 中文简历条目
+
+**FORMA 电商前端与开源模板** · Next.js / React / TypeScript / Tailwind CSS / Zustand / Vitest
+
+- 构建响应式电商体验，覆盖商品搜索与筛选、规格选择、持久化购物车、游客模拟结算及订单查看，并统一商品数据来源。
+- 实现商品目录驱动的价格与数量校验、订单快照、浏览器存储错误处理和可交互的模拟配送流程。
+- 完善品牌视觉、集中配置、中英文文档与 MIT 开源许可，并配置 GitHub Actions 自动执行代码检查、测试和生产构建。
+
+## One-minute demo script / 一分钟演示脚本
+
+| Time | Show | Explain |
+| ------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| 0–10 s | Desktop home page, then mobile layout | FORMA's visual identity and responsive shopping experience / 品牌视觉与手机布局 |
+| 10–20 s | The collection, a category filter and one product | The shared catalog keeps discovery and product detail consistent / 商品数据统一，列表和详情一致 |
+| 20–30 s | Select an available variant and open the cart | Quantities persist across reloads and respect sample stock / 购物车刷新恢复与规格数量限制 |
+| 30–45 s | Checkout using the provided fictional address | Simulated checkout recalculates prices; no payment details / 重新核算金额，无需输入付款信息 |
+| 45–60 s | Saved order and delivery simulation | Order snapshots persist locally; delivery advances only on interaction / 订单保存在当前浏览器，配送由用户手动演示 |
+
+Keep the demo label visible and use only fictional customer details. The bundled walkthrough is assembled from captured screens of the working interface, not a real-time screen recording. The table above is a script for a live presentation, not a performance benchmark.
+
+仓库中的演示视频由实际界面截图串联制作，并非实时录屏。上表可用于现场演示，时间安排不代表页面加载性能。
+
+## Review the engineering
+
+- [Architecture and data lifecycle](architecture.md)
+- [Tests and local validation](../README.md#development)
+- [GitHub Actions runs](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml)
+- [Deployment instructions and current hosting boundary](deployment.md)
+
+See [`src/lib/store-config.ts`](../src/lib/store-config.ts) to change the sample brand, currency and shipping configuration. The repository remains named `my-shop`; FORMA is its example storefront identity.
diff --git a/docs/storefront-checks.yml b/docs/storefront-checks.yml
deleted file mode 100644
index 31c5c26..0000000
--- a/docs/storefront-checks.yml
+++ /dev/null
@@ -1,20 +0,0 @@
-name: Storefront checks
-on:
- push:
- branches: [main]
- pull_request:
-permissions:
- contents: read
-jobs:
- validate:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: actions/setup-node@v4
- with:
- node-version: 22
- cache: npm
- - run: npm ci
- - run: npm run lint
- - run: npm run test:run
- - run: npm run build
diff --git a/src/app/about/page.tsx b/src/app/about/page.tsx
index 925d14d..464d5e8 100644
--- a/src/app/about/page.tsx
+++ b/src/app/about/page.tsx
@@ -4,19 +4,19 @@ import { storeConfig } from "@/lib/store-config";
export const metadata = { title: "About the demo" };
export default function AboutPage() {
return (
-
+
An interactive storefront
+
{storeConfig.name} is a portfolio project and a starting point for
building your own storefront. Explore the collection, choose a variant,
fill a cart and follow a demo order through delivery.
+
Cart contents, demo orders and theme preferences are saved in browser
storage. Use the fictional address provided; please do not enter real
personal information. Orders do not sync across devices. You can clear
demo order history from the orders page and remove cart items using the
cart controls.
+
Product photographs load from Unsplash through the image service.
Hosting providers may receive normal web request information. This
application does not include analytics, account registration, payment
@@ -55,13 +55,13 @@ export default function AboutPage() {
- Your cart is empty
- Your cart is empty
{item.productName}
+
{item.color} / {item.size}
+ Demo checkout. No payment is taken.
+
Find something you like before checking out.
+
Try the full experience. No payment, emails or shipments.
+
Small details. A complete journey.
- How to try it
-
+
How to try it
+
-
+
Your data stays in this browser
-
+
{items.map((item) => (
-
Your cart is empty
+
+ Your cart is empty
+
Demo checkout
-
+ Demo checkout
+
+