# 星线社技术概览

星线社是面向实物商品的静态展示与咨询入口。当前商品数组为空，页面只保留品牌和联系内容；源码保留的搜索、详情和咨询清单组件，不代表当前已有商品可购买或已经形成电商订单系统。

## 入口与当前状态

公开入口为 [星线社](https://thestarline.shop/)。站点使用 HTML、CSS 和原生 ES modules，无运行时服务端或数据库依赖。产品数据来自 `catalog.mjs`，当前导出 `products = []`，分类为“全部”和“实物商品”。

页面初始化先判断商品数量。为空时隐藏商品区域、分类导航、搜索相关展示和咨询清单入口，并显示适用的品牌联系内容；不会自动生成占位商品、轮播或默认购物卡片。维护人员不能仅因组件存在就将站点描述为可下单商城。

| 层 | 实现 |
| --- | --- |
| 商品目录 | 静态 JavaScript 数组，当前为空 |
| 页面交互 | 筛选、商品详情、咨询清单与联系对话框 |
| 本机存储 | 已选咨询商品 ID数组 |
| 公开发布 | 白名单 HTML、CSS、模块与必要图片 |

## 商品模型与扩展方式

恢复商品展示时，应在目录中添加经过确认的真实商品，而不是只改页面隐藏开关。当前渲染器读取以下字段：

| 字段 | 用途 |
| --- | --- |
| `id` | 稳定唯一标识，用于详情和本机选择引用 |
| `name`、`description` | 商品名称及简要说明 |
| `category`、`keywords` | 分类与搜索匹配 |
| `image`、`imageAlt` | 公开图片与替代文字 |
| `priceLabel` | 展示用价格文案，不是结算金额 |
| `overview`、`includes`、`suitableFor`、`note` | 详情中的介绍、包含内容、适用场景及补充说明 |

搜索将查询去除首尾空白并转为小写，在名称、简介和关键词中执行包含匹配；分类与关键词条件同时生效。无结果显示重置筛选入口。字段进入页面时经过转义，避免将普通目录文本当作 HTML执行；这不能替代图片来源、价格和商品信息的人工确认。

## 咨询清单的数据流

咨询选择使用本机键 `starline.shop.inquiry.v1`，内容是 JSON 字符串数组。恢复时只接受数组、去重并保留当前目录已知的商品 ID；不存在或下架的商品不会继续进入咨询结果。损坏的 JSON、存储读取失败或非数组值回退为空清单。

加入和移除只对已知商品生效。存储写入失败时返回失败结果，不能据此宣称选择已跨页面持久保存。这里没有登录用户、服务端购物车或跨设备同步；同一浏览器的选择也不等于订单。

咨询文本由当前已选商品名称生成，附带来源链接；无有效选择时使用通用商品咨询文字。复制失败时使用可选择文本作为后备。站点不自动发送咨询，不会因此替用户向商家创建订单、锁定库存或扣款，用户仍需通过提供的联系渠道完成沟通。

## 对话框与访问性

详情和咨询对话框处理可见可聚焦控件、背景不可交互状态、关闭与焦点恢复，避免键盘停留在隐藏元素中。商品图片包含替代文字，按钮具备可识别名称。空商品目录下的联系入口使用通用分支，不会先要求用户勾选不存在的商品。

新增商品或更改弹窗结构后，仍需在窄屏、触屏和键盘操作中检查布局、文字换行、滚动与焦点；模型测试不能替代这些浏览器验收。

## 发布与能力边界

构建脚本先确认公开白名单文件存在，再重建输出目录，只复制站点运行文件及品牌、图标和公开联系图片。设计草稿、退役商品图、测试和其他内部资料不会因所在目录相邻而自动公开；新增公开资源需要显式纳入白名单。

当前没有支付、订单、库存、优惠、物流、退款或售后工单后端，也没有与 [星线 Pay](https://document.thestarline.cn/pay/) 的结算闭环。若未来接入交易能力，应另建服务端可信商品价格、订单状态、库存和履约契约，不能把 `priceLabel` 或本机清单用作可信收费依据。

资料依据 2026-10-23 源码整理。发布时仍需验证空目录行为、详情与咨询焦点、存储不可用、复制失败和触屏布局；咨询后续结果由实际联系流程确认。相关公开入口见 [官网](https://document.thestarline.cn/website/)，使用问题见 [支持中心](https://document.thestarline.cn/support/)。

## 源码依据

主要实现为 `shop/catalog.mjs`、`store.mjs`、`app.mjs`、`index.html`、`styles.css` 和 `build.mjs`。模型验证与浏览器实际操作需要分别检查。