Skip to content

v0.3.1

Latest
Latest

Choose a tag to compare

View all tags
@ptonlix ptonlix released this 20 Oct 02:37
v0.3.1
0642afa
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v0.3.1

日期：2026-10-20

这是 v0.3.0 之后的店面说明。设备码、授权范围、买家注册、买入开关、支付成功条件、商家问答、商品描述的读写和长度、店面缓存、文本压缩范围、Caddy 匹配和安装回滚都没有改。没有新路由，没有新错误码，也没有新依赖。没有新的 SQL 文件。compose.yaml 与 v0.3.0 相同。install.sh 与 v0.3.0 相同。

v0.3.0 的店面渲染器已经会填 product.description。内置商品页和起始模板也已经声明这个槽位。/storefront/skill.md 的事实槽位清单当时停在名称、封面、字段、规格、库存、可售状态和价格。照着 Skill 改页面的人会把某一件商品的描述写进 HTML，或者一直不声明槽位，商品页正文就保持空白。这一版只把这个可选槽位写进店面 Skill，让说明和运行时一致。

生产应用镜像是 docker.io/<用户名>/merclink:0.3.1。正式版同时推送 0.3.1 和 latest。要换应用镜像，店面 Skill 才会变成这一版的正文。不需要换 compose.yaml。已经在 v0.3.0 上的机器没有新迁移要跑。

中文

这一版能做什么

  • /storefront/skill.md 的事实槽位清单增加空元素 <merclink-slot name="product.description"></merclink-slot>。
  • 这个槽位可以不声明。没有它的发布仍可激活。服务端不改写已发布模板，也不会自动补上描述。
  • 声明在商品页时，服务端填入当前商品自己的纯文本描述。内部换行予以保留。描述为空时槽位为空。不要把某一件商品当时的描述写进 HTML，也不要另起槽位名。
  • 首页和商品列表不必声明它。它不是商品页或商品列表的必填槽。必填商品槽仍是名称、封面、价格和可售状态，再加上列表的 products.next，以及商品页的字段和规格。
  • 常见错误用法补了两条：把某一件商品的描述直接写进 HTML；自创一个描述槽位名，或以为旧版 Skill 没写的 product.description 不能发布。
  • 买家 Skill 和商家 Skill 没有新增路径，也没有改描述字段的说明。

这一版不做

  • 不改商品描述的存储、写入、长度、搜索、Markdown 或 JSON-LD。
  • 不把 product.description 变成必填槽。缺少这个槽位时，发布校验仍然接受模板。
  • 不改写已经激活的自定义店面。页面不会因此多出一段描述。商家要在模板里声明这个槽位后再发布，自定义店面才会显示描述。
  • 不改内置商品页，也不改起始模板。这两处在 v0.3.0 里已经声明了 product.description。
  • 不改商家问答。全店和商品问答仍是 v0.3.0 的两份资源。GET /api/v1/store 在介绍未发布、全店问答已公开时，仍可以只返回 { faqs }。
  • 不改「如何使用 MercLink」。
  • 不改设备码流程、scope、买家注册或支付成功条件。只有订单状态 paid 表示支付成功。调用方仍不能传价格。
  • 不改店面 HTML 的 no-store，也不改 CSS、JS 的 10 分钟新鲜期和之后最多 24 小时的后台校验。
  • 不改公开图片按 id 缓存一年的规则。缺失图片仍是 404。
  • 不改 Caddy 的五行 Content-Type 匹配，也不改镜像标签。仍是 caddy:2.11.7-alpine。
  • 不改一键安装询问的字段，不安装系统包，也不默认打开买入。安装和升级未完成时的回滚与 v0.3.0 相同。
  • 不新增路由、错误码、依赖或迁移。不激活店面，不补写历史发布，也不把 Docker Hub 用户名、令牌、域名或证书写进仓库。

升级注意

这一版的变化在应用镜像里的店面 Skill。compose.yaml 和 install.sh 与 v0.3.0 相同。不要删 .env，也不要删 caddy_data。不要改已经应用过的迁移。这一版没有新的 SQL 文件。

从 v0.3.0 升上来时，数据库不再前进一步。从 v0.2.6 直接升到这一版时，进程启动仍会补上 v0.3.0 的 018_merchant_faqs.sql。那次迁移只建 merchant_faqs 和两个唯一索引，不回填。已经跑过 018 的库不会再执行一遍。

一键安装过的机器，等这个正式版发布后执行：

curl -fsSL -o /tmp/merclink-install.sh https://github.com/ptonlix/MercLink/releases/latest/download/install.sh && bash /tmp/merclink-install.sh upgrade

upgrade 会下载这个 tag 的 compose.yaml，保留已有密钥和后来手工打开的买入配置，然后 pull。它不打印已保存的密码。这次 compose.yaml 没有变化。升级如果没有完成，部署文件和版本号会回到升级前；已经换上的容器要再执行 docker compose up -d 才和文件一致。

手工部署的机器不要再跑一键安装。把 MERCLINK_IMAGE 改为 docker.io/<用户名>/merclink:0.3.1，然后执行：

docker compose pull && docker compose up -d

不要加 --build。拉取完成且进程起来之后，公开页与 v0.3.0 一致。/storefront/skill.md 会列出 product.description。已经激活的自定义店面不会因此改版。还没有接受发布时，起始店面仍是 v0.3.0 那一份，商品页里本来就有这个槽位。

回滚时把应用镜像改回 docker.io/<用户名>/merclink:0.3.0，再 pull。不要把 latest 当作回滚点。latest 会在这个正式版发布时移到 0.3.1。回到 0.3.0 只是让店面 Skill 重新不列出这个槽位。0.3.0 的渲染器在模板声明了 product.description 时仍然会填描述。没有新表需要保留或删除。v0.3.0 已经建成的 merchant_faqs 继续留着；删掉会丢掉那一版写入的问答。

English

Date: 2026-10-20

This is a storefront-skill correction after v0.3.0. The device-code flow, authorization scopes, buyer registration, purchase switch, the rule that only paid means payment success, merchant FAQs, how product descriptions are stored and how long they may be, storefront caching, the set of compressed types, the Caddy matchers, and install rollback are unchanged. There is no new route, no new error code, and no new dependency. There is no new SQL file. compose.yaml is the same file as v0.3.0. install.sh is the same file as v0.3.0.

The v0.3.0 storefront renderer already fills product.description. The built-in product page and the starter template already declare that slot. The fact-slot list in /storefront/skill.md stopped at the name, cover, fields, variants, stock, availability, and price. Someone following the Skill would hard-code one product's description into HTML, or never declare the slot, and the product page body would stay blank. This version only writes that optional slot into the storefront Skill, so the document matches the runtime.

The production image is docker.io/<namespace>/merclink:0.3.1. The stable release also publishes latest. The application image has to be replaced before the storefront Skill shows this text. compose.yaml does not need to change. A host already on v0.3.0 has no new migration to apply.

What this version does

  • The fact-slot list in /storefront/skill.md adds the empty element <merclink-slot name="product.description"></merclink-slot>.
  • The slot may be omitted. A release without it can still be activated. The server does not rewrite a published template, and it does not insert a description on its own.
  • When the product page declares the slot, the server fills the current product's own plain-text description. Line breaks inside that description are preserved. An empty description leaves the slot empty. Do not write one product's description into the HTML, and do not invent another slot name.
  • The home page and the product list do not need to declare it. It is not a required slot on the product page or the product list. The required product slots stay the name, cover, price, and availability, plus products.next on the list, and the fields and variants on the product page.
  • The common-mistakes list adds two cases: writing one product's description straight into HTML, and inventing a description slot name, or treating product.description as unpublishable because an older Skill omitted it.
  • The buyer Skill and the merchant Skill do not gain a path, and their description-field text is unchanged.

What this version does not do

  • It does not change how a product description is stored or written, its length rule, search, Markdown, or JSON-LD.
  • It does not make product.description required. Publish validation still accepts a template that omits the slot.
  • It does not rewrite an already active custom storefront. The page does not grow a description on its own. The merchant declares the slot and publishes again before a custom storefront shows the text.
  • It does not change the built-in product page or the starter template. Both already declared product.description in v0.3.0.
  • It does not change merchant FAQs. The store FAQ and the product FAQ stay the two resources from v0.3.0. When the profile is unpublished and the store FAQ is public, GET /api/v1/store can still return only { faqs }.
  • It does not change “如何使用 MercLink”.
  • It does not change the device-code flow, scopes, buyer registration, or the payment-success rule. Only order status paid means payment succeeded. The caller still cannot send a price.
  • It does not change no-store on storefront HTML, or the 10-minute freshness window and later 24-hour background revalidation for CSS and JS.
  • It does not change the one-year cache for a public image id. A missing image is still 404.
  • It does not change Caddy's five Content-Type lines or the image tag. It remains caddy:2.11.7-alpine.
  • It does not change what one-click install asks for, it does not install system packages, and it does not turn purchase on by default. Rollback of an unfinished install or upgrade stays as it was in v0.3.0.
  • It does not add a route, an error code, a dependency, or a migration. It does not activate a storefront, backfill old releases, or store a Docker Hub username, token, domain, or certificate in the repository.

Upgrade note

The change in this version is the storefront Skill inside the application image. compose.yaml and install.sh match v0.3.0. Do not delete .env or caddy_data. Do not edit a migration that has already been applied. This version adds no SQL file.

An upgrade from v0.3.0 does not move the database forward. An upgrade that jumps from v0.2.6 to this version still applies v0.3.0's 018_merchant_faqs.sql at process startup. That migration only creates merchant_faqs and two unique indexes. It does not backfill. A database that has already applied 018 does not run it again.

After this stable release is published, a host installed by the script should run:

curl -fsSL -o /tmp/merclink-install.sh https://github.com/ptonlix/MercLink/releases/latest/download/install.sh && bash /tmp/merclink-install.sh upgrade

upgrade downloads compose.yaml for this tag, keeps generated secrets and any later purchase settings, then pulls. It does not print stored passwords. This compose.yaml is unchanged. If this upgrade does not finish, the deploy files and version pin return to their previous values. Containers already recreated from the new image match those files only after another docker compose up -d.

Do not run a fresh one-click install over a deployment that was created by hand. Set MERCLINK_IMAGE to docker.io/<namespace>/merclink:0.3.1, then run:

docker compose pull && docker compose up -d

Do not add --build. After the pull, once the process is up, public pages stay as they were in v0.3.0. /storefront/skill.md lists product.description. An already active custom storefront is not republished by this upgrade. When no release has been accepted, the starter is still the v0.3.0 copy, and its product page already declares this slot.

To roll back, set the application image to docker.io/<namespace>/merclink:0.3.0 and pull again. Do not use latest as the rollback point. latest moves to 0.3.1 when this stable release is published. Returning to 0.3.0 only removes this slot from the storefront Skill. The v0.3.0 renderer still fills product.description when the template declares it. There is no new table to keep or to drop. Leave merchant_faqs in place if v0.3.0 created it. Dropping that table discards FAQs written by that version.

Assets 3
Loading