diff --git a/README.md b/README.md
index c1d8f9d..63b60c4 100644
--- a/README.md
+++ b/README.md
@@ -3,37 +3,48 @@
[](LICENSE)
[](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml)
-**A boutique ecommerce storefront with a complete, no-keys-required demo shopping journey.**
+**A boutique ecommerce storefront, from first browse to saved demo order.**
-FORMA is the sample brand inside **my-shop**, a portfolio project and reusable Next.js, React and TypeScript storefront template. Warm ivory, deep olive and an editorial layout give everyday clothing and lifestyle pieces room to breathe. Browse a shared catalog, choose variants, save a cart, place a simulated order and explore its delivery timeline.
+FORMA is the sample brand inside **my-shop**: a portfolio project and reusable **Next.js, React and TypeScript** template. Warm ivory, deep olive and an editorial layout frame a complete guest shopping journey—no API keys or database setup required.
-[中文说明](docs/README.zh-CN.md) · [Project showcase](docs/showcase.md) · [Architecture & extension guide](docs/architecture.md) · [Deployment](docs/deployment.md)
+[Run locally](#quick-start) · [Project case study](docs/showcase.md) · [v0.1.0 release](https://github.com/SakuraUltra/my-shop/releases/tag/v0.1.0) · [中文说明](docs/README.zh-CN.md)
> This is a **demo storefront**. It does not accept payments, register accounts, send emails or ship products. Cart and order data live in the visitor's browser. Use the fictional address provided at checkout.
## Preview
+[](https://github.com/SakuraUltra/my-shop/releases/tag/v0.1.0)
+
+[Watch the MP4 walkthrough](docs/media/storefront-walkthrough.mp4) · [Explore the design and engineering decisions](docs/showcase.md)
+
+The GIF and video are montages of captured screens from the working interface, not real-time screen recordings. Run the project locally to try the interactions.
+
+[Download the offline showcase kit](https://github.com/SakuraUltra/my-shop/releases/download/v0.1.0/forma-v0.1.0-showcase.zip): extract the ZIP and open `index.html` for a static presentation with images and video. Interactive shopping requires [running the project locally](#quick-start).
+
+
+View desktop, mobile and order screenshots
+
| Mobile storefront | Saved demo order |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| | |
-[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).
```bash
-git clone https://github.com/SakuraUltra/my-shop.git
+git clone --branch v0.1.0 https://github.com/SakuraUltra/my-shop.git
cd my-shop
npm ci
npm run dev
```
+This checks out the **v0.1.0** release. Omit `--branch v0.1.0` to work with the latest `main` branch.
+
Open [localhost:3000](http://localhost:3000). No `.env`, database, seed command, payment key or account is required. Internet access is needed for dependency installation, Google fonts at build time and remote product photographs.
## Try the complete journey
@@ -103,11 +114,9 @@ This is a frontend commerce demo, not a production transaction system. Browser s
`prisma/schema.prisma` preserves the original relational design **as a reference only**. Prisma, Stripe and authentication are not connected to the app. The unused SDK wrappers and outdated database seed were removed from the default installation; adding production commerce requires server-side ownership and validation. See the [extension guide](docs/architecture.md).
-## Deployment
-
-Run `npm run build` and deploy to a host supporting Next.js. Set `NEXT_PUBLIC_SITE_URL` to the actual public address before the production build. Full instructions and post-deployment checks are in [docs/deployment.md](docs/deployment.md).
+## Optional deployment
-The repository's previous Vercel address is not advertised as a working demo until a new deployment is verified.
+The project can be explored through this README, the release assets and a local installation. To host your own copy, run `npm run build` and deploy to a host supporting Next.js. Set `NEXT_PUBLIC_SITE_URL` to the actual public address before the production build. Full instructions and post-deployment checks are in [docs/deployment.md](docs/deployment.md).
## Images and licensing
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 6f51803..9421ba0 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -1,35 +1,48 @@
# FORMA · 可完整体验的电商作品集
-FORMA 是 **my-shop** 开源模板中的示例品牌，用 Next.js、React 和 TypeScript 构建。暖白、深橄榄色、商品大图与留白构成自然简约的精品店视觉。访客可以完整体验“浏览 → 选规格 → 购物车 → 模拟下单 → 查看订单 → 模拟配送”。
+**从浏览商品到保存模拟订单，一套可以完整体验的精品店购物流程。**
-**这是演示项目：不收款、不发货、不发送邮件，也不需要注册。** 订单只保存在当前浏览器，请使用结算页提供的虚构地址。
+FORMA 是 **my-shop** 中的示例品牌，也是一个可复用的 **Next.js、React 和 TypeScript** 开源模板。暖白、深橄榄色与编辑式排版构成自然简约的视觉；无需 API 密钥或数据库配置，就能体验“浏览 → 选规格 → 购物车 → 模拟下单 → 查看订单 → 模拟配送”。
-[English](../README.md) · [作品介绍与演示脚本](showcase.md) · [架构与扩展说明](architecture.md)
+[本地启动](#本地启动) · [项目案例](showcase.md) · [v0.1.0 Release](https://github.com/SakuraUltra/my-shop/releases/tag/v0.1.0) · [English](../README.md)
+
+> **这是演示项目：不收款、不发货、不发送邮件，也不需要注册。** 订单只保存在当前浏览器，请使用结算页提供的虚构地址。
## 效果预览
+[](https://github.com/SakuraUltra/my-shop/releases/tag/v0.1.0)
+
+[观看 MP4 演示](media/storefront-walkthrough.mp4) · [阅读设计与实现案例](showcase.md)
+
+动图和视频由实际运行界面的截图串联制作，并非实时录屏。启动本地项目后，可以亲自体验页面交互。
+
+[下载离线展示包](https://github.com/SakuraUltra/my-shop/releases/download/v0.1.0/forma-v0.1.0-showcase.zip)：解压 ZIP 后打开 `index.html`，即可浏览包含图片和视频的静态展示；购物交互需要[本地运行项目](#本地启动)。
+
+
+展开查看桌面、手机和订单截图
+
| 手机首页 | 模拟订单 |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| | |
-[观看简短演示](media/storefront-walkthrough.mp4)
-
-演示视频由实际界面截图串联制作，用于展示购物流程，并非实时录屏。从顶部的 **The collection** 进入商品列表即可亲自体验。
+
## 本地启动
使用 Node.js 22.22 或更新版本（推荐 Node 22 LTS）：
```bash
-git clone https://github.com/SakuraUltra/my-shop.git
+git clone --branch v0.1.0 https://github.com/SakuraUltra/my-shop.git
cd my-shop
npm ci
npm run dev
```
-打开 http://localhost:3000 。无需配置数据库、支付密钥或 `.env`。安装依赖、构建时加载 Google 字体，以及显示 Unsplash 图片需要联网。
+以上命令检出 **v0.1.0** 发布版本；去掉 `--branch v0.1.0` 即可获取最新的 `main` 分支。
+
+打开 [localhost:3000](http://localhost:3000)。无需配置数据库、支付密钥或 `.env`。安装依赖、构建时加载 Google 字体，以及显示 Unsplash 图片需要联网。
## 功能与设计
@@ -55,7 +68,7 @@ npm run dev
金额统一使用整数“分”。修改币种不会自动换算价格。订单不跨设备同步；每个购物车有数量限制，但多个演示订单不会共同扣减库存。税费未接入。
-## 检查与上线
+## 开发与检查
```bash
npm run lint
@@ -64,10 +77,16 @@ npm run build
npm run start
```
-参考[部署指南](deployment.md)和[架构与扩展说明](architecture.md)。数据库设计保留在 `prisma/schema.prisma` 供后续参考，目前应用不会连接数据库。
+数据库设计保留在 `prisma/schema.prisma` 供后续参考，目前应用不会连接数据库。更多实现细节见[架构与扩展说明](architecture.md)。
下一阶段可以完善产品内容编辑和自动化浏览器测试；真实登录、支付和共享库存应作为有明确后端边界的新阶段。
自动检查配置位于 [`.github/workflows/storefront-checks.yml`](../.github/workflows/storefront-checks.yml)，覆盖拉取请求和 `main` 分支更新，也支持手动运行。流程安装锁定依赖，然后执行代码检查、测试和生产构建；仓库令牌仅有读取权限。它不会自动部署网站，具体提交是否通过请以 [GitHub Actions 记录](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml)为准。
+## 可选部署
+
+通过 README、Release 素材和本地运行即可了解与体验这个项目。如果希望自行托管，可参考[部署指南](deployment.md)，在构建前将 `NEXT_PUBLIC_SITE_URL` 设置为实际域名。
+
+## 许可证与图片
+
应用代码采用 [MIT 许可证](../LICENSE)，方便保留署名后复用。示例照片来源与使用说明见英文 README。
diff --git a/docs/media/storefront-preview.gif b/docs/media/storefront-preview.gif
new file mode 100644
index 0000000..1880255
Binary files /dev/null and b/docs/media/storefront-preview.gif differ
diff --git a/docs/releases/v0.1.0.md b/docs/releases/v0.1.0.md
new file mode 100644
index 0000000..3eebd3d
--- /dev/null
+++ b/docs/releases/v0.1.0.md
@@ -0,0 +1,33 @@
+# FORMA v0.1.0
+
+The first portfolio release of **FORMA**, a boutique ecommerce storefront and reusable **Next.js / React / TypeScript** template. This release can be explored directly on GitHub or through the downloadable presentation; no website deployment is needed.
+
+## Start here
+
+- **Watch:** the README includes a 16-second animated overview. Download `forma-walkthrough.mp4` for the 32-second version.
+- **Present:** download `forma-v0.1.0-showcase.zip`, extract it and open `index.html`. The presentation bundles screenshots, video, an animated preview and a bilingual case study, so its media can be viewed offline. External source links require internet access.
+- **Interact:** use the source code archive below, or clone the `v0.1.0` tag. With Node.js 22.22+, run `npm ci` and `npm run dev`, then open `http://localhost:3000`. Dependencies, build-time Google fonts and product photography require internet access.
+- **Read:** [project case study](https://github.com/SakuraUltra/my-shop/blob/v0.1.0/docs/showcase.md) and [中文说明](https://github.com/SakuraUltra/my-shop/blob/v0.1.0/docs/README.zh-CN.md).
+
+## Included
+
+- FORMA's warm ivory and olive identity, responsive layouts and light/dark themes.
+- A shared catalog of 12 sample products, URL-based filters, sorting and keyboard search.
+- Variant selection, a persistent cart, catalog-based price and quantity checks, and guest demo checkout.
+- Saved order snapshots, order history, storage-error handling and an interactive delivery simulation.
+- 27 automated test cases and GitHub Actions checks for lint, tests and the production build.
+- MIT-licensed application code, bilingual setup documentation and source-linked engineering decisions.
+
+The animation and video are montages of captured working-interface screens, not real-time recordings. The presentation is a static showcase; interactive shopping runs in the local app.
+
+## Demo scope
+
+No real payments, accounts, emails or shipments are involved. Use the fictional address provided. Orders stay in the current browser; there is no shared inventory reservation or production transaction backend. Product photographs come from Unsplash and are separate from the code's MIT license.
+
+## 中文发布说明
+
+这是 FORMA 的首个作品展示版本。可以直接在 GitHub 看动图，或下载 **`forma-v0.1.0-showcase.zip`**，解压后打开 **`index.html`** 查看截图、视频和项目案例，无需部署、无需安装 Node.js。
+
+想亲自操作购物车和模拟订单时，请下载源码并按本地运行说明启动。此版本包含 12 件示例商品、27 个自动测试，以及完整的商品发现、规格选择、购物车、模拟结算、订单与配送演示流程。
+
+`SHA256SUMS.txt` lists checksums for the uploaded showcase ZIP, video and animated preview.
diff --git a/docs/showcase.html b/docs/showcase.html
new file mode 100644
index 0000000..c2b6438
--- /dev/null
+++ b/docs/showcase.html
@@ -0,0 +1,502 @@
+
+
+
+
+
+
+ FORMA — Project showcase
+
+
+
+
+
+
+
+
+
v0.1.0 / Project showcase
+
A considered storefront. A complete journey.
+
+ FORMA is a fictional everyday boutique and an open-source Next.js
+ storefront. Explore the design, the shopping flow and the decisions
+ behind it — all in this local presentation.
+
+
+
+
+ The working storefront, captured on desktop. This page is a visual
+ presentation; its screenshots are not interactive shopping controls.
+
+
+
Discover the collection and narrow it by category.
+
+ Choose a colour and size, then add the product to a persistent cart.
+
+
+ Use the fictional address for a demo checkout. No card details or
+ charges.
+
+
+ Return to the saved order and advance the simulated delivery
+ timeline.
+
+
+
+ Show the 16-second animated preview
+
+
+
+
+
Across the journey
+
Small screens. Lasting details.
+
+
+
+
+ Responsive mobile home and compact navigation.
+
+
+
+
+
+ An order snapshot that remains after a page refresh.
+
+
+
+
+
+
The project
+
Consistency is the foundation.
+
+
+
+ The goal is to make a frontend commerce demo feel complete and
+ easy to reuse. A single typed catalog connects discovery, search,
+ product details and checkout. The same data drives price and
+ quantity checks.
+
+
+ The focus is a coherent journey, not a production transaction
+ service. Cart and orders stay in the visitor's browser;
+ authentication, shared inventory, payments and live shipping would
+ require a server-backed system.
+
+
+
+
+ FORMA
+ 的目标是做出完整、易于复用的电商前端作品。浏览、搜索、商品详情与结算共用一份商品目录，让价格、规格和数量校验保持一致。
+
+ A shared source for 12 products keeps the storefront's shopping
+ surfaces consistent and makes template customization easier.
+
+
+
+
Recoverable state.
+
+ Saved carts are checked on restore. Orders are persisted before
+ the cart is cleared, so a storage failure does not erase the
+ visitor's selections.
+
+
+
+
Explicit tradeoffs.
+
+ No database or API keys are needed for the demo. Browser storage
+ is local and editable, so it is never treated as a trusted
+ transaction system.
+
+ This presentation uses bundled media and system fonts, so it can
+ be viewed without a server. To interact with the actual store,
+ download the source from
+ the v0.1.0 release
+ and follow its local setup instructions.
+
+
+ Requires Node.js 22.22+ for the app. Internet access is needed for
+ dependencies, Google fonts at build time and product photographs.
+ The source includes automated checks and MIT licensing.
+
+
+
+
+
+
diff --git a/docs/showcase.md b/docs/showcase.md
index 322ba48..be0aa92 100644
--- a/docs/showcase.md
+++ b/docs/showcase.md
@@ -1,71 +1,98 @@
-# FORMA storefront · Project showcase
+# FORMA storefront · Project case study
-[Repository](https://github.com/SakuraUltra/my-shop) · [Desktop preview](media/desktop-home.jpg) · [Mobile preview](media/mobile-home.jpg) · [Walkthrough](media/storefront-walkthrough.mp4)
+[中文案例](#中文项目案例) · [Animated preview](media/storefront-preview.gif) · [Desktop](media/desktop-home.jpg) · [Mobile](media/mobile-home.jpg) · [Walkthrough](media/storefront-walkthrough.mp4) · [v0.1.0 release](https://github.com/SakuraUltra/my-shop/releases/tag/v0.1.0)
-## Project summary
+**FORMA is a responsive ecommerce frontend and reusable Next.js template for a fictional everyday clothing and lifestyle brand.** The `my-shop` repository brings product discovery, variant selection, a persistent cart, guest demo checkout, saved orders and a delivery simulation into one coherent journey.
-**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.
+## Goal and audience
-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 goal was to turn a shop scaffold into a portfolio project that reviewers can understand quickly and developers can run without configuring a database, payment provider or account service. The intended audience is people reviewing frontend work and developers looking for a small storefront starter.
-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.
+FORMA's warm ivory, deep olive, serif headings and editorial photography are intended to create a calm boutique identity. That is a qualitative design direction, not a measured claim about conversion or usability. The [home page](../src/app/page.tsx), [hero](../src/components/home/HeroBanner.tsx) and [theme tokens](../src/app/globals.css) show how that direction is implemented.
-## Problem → implementation
+## Engineering decisions and tradeoffs
-| 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 |
+| Decision | Reason and tradeoff | Inspect the implementation |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One typed catalog supplies discovery and product pages | Keeps names, prices, variants and links consistent across 12 sample products. Catalog editing remains a code change; there is no content-management interface. | [Catalog](../src/lib/catalog.ts), [product routes](../src/app/products/%5Bslug%5D/page.tsx) |
+| Put filters and sorting in the URL | A filtered view survives refresh and can be linked directly. Unknown values fall back to supported defaults; filtering runs over the small local catalog rather than a search service. | [Filter rules](../src/lib/product-filters.ts), [listing](../src/components/product/ProductListingContent.tsx) |
+| Rebuild cart lines from catalog IDs and quantities | Restored data is checked, stale prices are replaced, duplicates are merged and quantities are capped by sample stock. This protects the demo's consistency; client validation is not a trusted transaction boundary. | [Cart rules](../src/lib/cart.ts), [Zustand persistence](../src/store/cart.ts) |
+| Save order snapshots before clearing the cart | A completed demo order preserves its own item and amount data. If order persistence fails, checkout keeps the cart and displays an error. Orders stay in browser storage, so clearing it removes the history. | [Order model](../src/lib/orders.ts), [checkout sequence](../src/components/checkout/CheckoutContent.tsx) |
+| Separate static catalog rendering from browser state | Product routes come from the catalog; cart and order screens wait until browser data is available. Order subscriptions refresh saved history across tabs. The cart currently needs a reload to reflect changes from another tab. | [Product routes](../src/app/products/%5Bslug%5D/page.tsx), [client readiness](../src/lib/use-client-ready.ts), [order subscription](../src/lib/use-orders.ts) |
-## Suggested CV entry
+Amounts use integer cents, with formatting and shipping rules in [store configuration](../src/lib/store-config.ts). Changing the currency changes display formatting; it does not convert catalog prices.
+
+## Evidence and validation
+
+The release baseline includes **12 catalog product pages and 27 automated test cases**. These are scope and test counts, not traffic or performance metrics.
+
+- [Commerce tests](../src/lib/commerce.test.ts) cover catalog consistency, combined filters, stock limits, invalid quantities, stale cart repair, reload persistence, shipping thresholds, order snapshots, malformed saved data and delivery progression.
+- [Checkout component tests](../src/components/checkout/CheckoutContent.test.tsx) exercise an empty cart, a completed guest checkout, order display after remount, failed storage with cart preservation and a missing-order state.
+- [GitHub Actions](../.github/workflows/storefront-checks.yml) runs locked dependency installation, lint, tests and a production build. The build also checks TypeScript. See [run history](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml) for evidence tied to a particular commit.
+
+These checks do not establish production security, cross-browser coverage, performance improvements or measured usability. The suite combines domain and component tests; it is not an automated end-to-end browser suite.
+
+## How the project is presented
+
+The repository's screenshots, animated preview and short video are the primary showcase. The animation and video are assembled from captured screens of the working interface, rather than a real-time recording; their timing is editorial and does not measure page-loading speed. The [saved order screenshot](media/demo-order.jpg) shows the end of the demo checkout journey.
+
+For an interactive review, follow the [local quick start](../README.md#quick-start) and use **The collection → choose a variant → Cart → Checkout → Place demo order → Explore demo delivery**. Use the supplied fictional address, refresh the order page to see persistence, then advance the delivery simulation. No website deployment is needed for this presentation.
+
+## Deliberate demo limits
+
+There are no real payments, accounts, emails, shipments, tax calculations or shared inventory reservations. Stock limits apply within each cart; placing multiple orders does not decrement shared stock. Browser storage can be edited or cleared, is local to the browser and is not an authorization boundary. Product photos are illustrative and do not change with colour selection.
+
+The retained Prisma schema is a design reference only. Production commerce would require server-side order ownership, trusted price calculation, atomic inventory reservation, a payment-provider integration and durable storage. These are separate engineering work described in the [extension guide](architecture.md), rather than a setting to switch on in this demo.
+
+## Portfolio summary
**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.
+- Built a responsive storefront covering discovery, variant selection, a persistent cart and guest demo checkout, using one typed catalog throughout 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.
+- Packaged an MIT-licensed template with centralized store configuration, bilingual documentation, 27 automated tests and CI checks 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 是一个自然简约风格的电商前端作品，也是 `my-shop` 仓库中的可复用 Next.js 模板。** 它将商品发现、规格选择、持久化购物车、游客模拟结算、订单查看和模拟配送串成完整体验。
-**FORMA 是一个以日常服饰和生活用品为主题的电商前端作品，同时也是可复用的 Next.js 开源模板。** 视觉采用暖白与深橄榄色，通过商品大图、排版和留白呈现自然简约的精品店风格。
+### 目标与设计方向
-项目打通了浏览、搜索筛选、选择规格、购物车、模拟结算、保存订单与模拟配送的完整体验。核心设计是让整个购物过程使用同一份商品数据，并在恢复购物车和结算时重新验证价格与数量。订单以独立快照保存在浏览器中，保存失败时不会清空购物车。
+目标是让作品评审者快速看懂项目，并让开发者无需配置数据库、支付服务或账号系统就能运行。暖白、深橄榄色、衬线标题和商品大图用于表达安静的精品店风格。这是设计意图，项目没有据此声称转化率提升或经过用户研究验证。
-无需数据库、支付密钥或注册账号即可运行，适合用于作品展示和继续开发。真实支付、登录权限、共享库存和物流不在当前演示范围内。
+### 关键决定与取舍
-### 中文简历条目
+- **统一商品来源。** [商品目录](../src/lib/catalog.ts)为 12 个商品详情页及搜索、筛选、首页提供数据，减少不同页面之间的信息偏差。取舍是商品编辑仍需改代码，目前没有管理后台。
+- **让筛选状态进入网址。** [筛选规则](../src/lib/product-filters.ts)支持直接分享和刷新恢复，并处理未知参数。当前在小规模本地目录上筛选，没有接入搜索服务。
+- **恢复购物车时重新校验。** [购物车规则](../src/lib/cart.ts)根据商品编号与数量恢复数据，替换旧价格、合并重复项、处理无效规格并限制数量。这保证演示一致性，不代表具备真实交易的服务端安全保障。
+- **先保存订单，再清空购物车。** [订单模型](../src/lib/orders.ts)保存独立快照；[结算组件](../src/components/checkout/CheckoutContent.tsx)在保存失败时保留购物车并提示错误。取舍是订单仅存在当前浏览器中，清除存储后会丢失。
+- **区分静态商品与浏览器状态。** 商品页面由目录生成，购物车与订单等浏览器数据在客户端就绪后展示。订单会响应跨标签页存储变化，购物车跨标签页更新目前需要刷新。
-**FORMA 电商前端与开源模板** · Next.js / React / TypeScript / Tailwind CSS / Zustand / Vitest
+### 已验证的范围
-- 构建响应式电商体验，覆盖商品搜索与筛选、规格选择、持久化购物车、游客模拟结算及订单查看，并统一商品数据来源。
-- 实现商品目录驱动的价格与数量校验、订单快照、浏览器存储错误处理和可交互的模拟配送流程。
-- 完善品牌视觉、集中配置、中英文文档与 MIT 开源许可，并配置 GitHub Actions 自动执行代码检查、测试和生产构建。
+发布基线包含 **12 个商品详情页、27 个自动测试用例**。[业务规则测试](../src/lib/commerce.test.ts)覆盖筛选、库存与数量、购物车恢复、运费边界、订单快照及异常存储；[结算组件测试](../src/components/checkout/CheckoutContent.test.tsx)覆盖下单、重新挂载后显示订单、保存失败保留购物车及未知订单状态。[CI 记录](https://github.com/SakuraUltra/my-shop/actions/workflows/storefront-checks.yml)可查看具体提交的代码检查、测试和生产构建结果。
+
+这些证据说明实现与验证范围，不代表真实用户量、商业效果、性能提升、跨浏览器完整覆盖或生产安全认证。目前没有自动化端到端浏览器测试，也没有用户研究结果。
-## 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 / 订单保存在当前浏览器，配送由用户手动演示 |
+GitHub 中的截图、动图和视频是主要展示材料。动图与视频由实际界面截图串联制作，并非实时录屏，也不能用于判断加载速度。想亲自操作时，按 [README 的本地启动步骤](../README.md#quick-start)运行即可；本阶段无需部署网站。
-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.
+项目不收款、不注册账号、不发送邮件、不发货、不计算税费，也不共享扣减库存。请使用结算页的虚构地址。订单只保存在当前浏览器中，既不跨设备同步，也不提供身份验证或权限保护。真实商用能力需要单独的后端设计与测试，具体见[架构与扩展说明](architecture.md)。
-仓库中的演示视频由实际界面截图串联制作，并非实时录屏。上表可用于现场演示，时间安排不代表页面加载性能。
+### 中文简历条目
+
+**FORMA 电商前端与开源模板** · Next.js / React / TypeScript / Tailwind CSS / Zustand / Vitest
+
+- 构建响应式电商体验，覆盖商品搜索筛选、规格选择、持久化购物车、游客模拟结算及订单查看，并统一商品数据来源。
+- 实现商品目录驱动的价格与数量校验、订单快照、浏览器存储错误处理和可交互的模拟配送流程。
+- 完善品牌视觉、集中配置、中英文文档与 MIT 开源许可，提供 27 个自动测试用例及代码检查、测试、生产构建的 CI 流程。
-## Review the engineering
+## One-minute presentation / 一分钟演示顺序
-- [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)
+1. **Identity / 视觉：** show desktop and mobile layouts, then explain the boutique design intent.
+2. **Discovery / 商品发现：** open **The collection**, select a category, then choose a product variant.
+3. **Checkout / 模拟结算：** open the cart and place a demo order using the fictional address.
+4. **Persistence / 保存与配送：** refresh the saved order and advance **Explore demo delivery**.
-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.
+Keep the demo labels visible. Present this as a frontend commerce project and describe only features, tests and outcomes supported by the repository.
| 
|
-[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.
+
+ 
+ 
+ 
+