Docs/engineering guides

README-zh_CN.md

@@ -2,11 +2,9 @@
 
 [English](README.md) | [繁體中文](README-zh_TW.md) | 简体中文
 
-**把产品数据变成正式、可搜索、可询价的官方网站，不必运维一整套应用系统。**
+Prods 是供制造商与经销商自托管的技术产品目录与 RFQ（询价请求）系统。管理员维护产品数据、分类专属规格与文档；买家发现已发布产品并提出询价。半导体与电子元器件目录不只是扁平产品列表：产品身份、适用规格、原始值、datasheet 与发布状态都有实际意义。
 
-Prods 是为制造商、经销商与其他 B2B 产品团队打造的自托管产品目录与 RFQ（询价请求）系统。小型团队可导入并维护技术产品数据，安全发布给访客、搜索引擎与机器使用，再从单个便携式 Go 可执行文件接收真实买家需求。
-
-运行时包含 Admin 后台、公开网站、SQLite 支持、搜索、发布、RFQ、备份、恢复与运维工具。Node.js 只在从源代码构建时需要；部署后不需要 Node.js、独立数据库服务器、Docker、队列或外部搜索服务。
+单个 Go 进程提供公开网站、内嵌 Admin 应用程序与生命周期工具，SQLite 为主数据库。Public 由 Go 生成 HTML，通过 React 增强交互；Admin 使用 React、headless Refine Core 与 Ant Design v6。Node.js 是构建依赖，不是部署后的运行要求。
 
 ## 为什么选择 Prods
 
@@ -17,25 +15,31 @@ Prods 是为制造商、经销商与其他 B2B 产品团队打造的自托管产
 - **运维方式清楚可掌握。** 单个进程负责 migration、写入节流、持久化任务、审计、备份、restore journal 与健康检查。Terminal 会显示当前状态、下一步、URL、Admin 路径、主机信息、资源路径与实时日志。
 - **掌握部署与数据。** Prods Community 采 AGPL 许可，以 SQLite 储存主要状态，将资产与备份放在明确的本机目录，可在 Windows 或 Linux 上执行并搭配自选的反向代理。
 
-## 适合的团队
+## 工程文档与当前状态
 
-Prods 适合需要官方产品目录与 RFQ 管道，但不想自行拼装并运维 CMS、定制数据库应用、搜索服务与独立后台的产品型企业。尤其适合元器件、工业、技术型与 B2B 产品目录，这些情境通常重视料号、分类、规格、文件、公开控制与询价脉络。
+| 文档 | 用途 |
+| --- | --- |
+| [架构概览](docs/zh-CN/architecture.md) | 组件、请求／数据流程、持久化、认证与系统边界 |
+| [工程案例研究](docs/zh-CN/engineering-case-study.md) | 六项决策及其证据、替代方案、取舍与演进触发条件 |
+| [运维与生产环境证据](docs/zh-CN/operations.md) | 安装、备份／恢复、部署控制与尚未验证的运维声明 |
 
-V1 刻意不包含结帐、定价、库存 Availability、CRM、通用页面编辑器、任意自定义 JavaScript，也不会由 RFQ 自动创建产品。这些边界让产品目录真实数据、公开内容与买家需求维持清楚可控。
+指南描述 2026-09-17 查看时的工作目录（`VERSION`：`v0.6.8`）。源代码、测试与发布 workflow 展示已实现的机制；本次核查未验证运行中的生产部署、客户负载或可用性目标。Release workflow 发布构建产物，不部署运行中的站点。历史需求与 ADR 保持内部文档属性；指南提供源代码链接与说明，不重新公开内部内容。
 
-## 主要能力
+## 已实现范围
 
-| 领域 | Prods 提供的能力 |
+| 领域 | 代码仓库中的实现 |
 | --- | --- |
-| 产品目录作业 | Current／Archived 产品、任意深度分类、规格与 Spec Set、字典、图片／文件、分页、排序、XLSX 导入／导出，以及批量 Publish／Hide／Archive／分类／生命周期操作 |
-| Website 与多语 | 版本化 Website 配置、预览／发布流程、Public Copy 覆写、导览与主题控制、独立 Admin UI 语言，以及十种内建公开语言 |
-| 公开探索 | 服务器端搜索与产品目录页、产品／分类／制造商／品牌／应用路由、Unicode folding 搜索、JSON-LD、JSON、Markdown、Sitemap、robots、manifest 与 `llms.txt` |
-| RFQ | 多产品询价、搜索无结果后的 Requested Part、high-entropy idempotency key、持久化回执、Admin 查看，以及由用户明确触发的可选 SMTP 发送 |
-| 权限与可追溯性 | 不透明 server-side session、CSRF 防护、能力型角色、Admin scope，以及必要管理操作记录 |
-| 运维 | Liveness／readiness、runtime log、排程与单次备份、验证式 restore、Recovery、Owner 救援、Maintenance、资产清理与手动版本检查 |
-| 发布 | 默认空白安装、可选且精确对应版本的 sample data、嵌入源代码 revision／版本、checksum，以及 Linux／Windows amd64 构建产物 |
+| 产品目录 | Current／Archived 产品、分类、Spec Set、原始规格值、字典、图片／文档、XLSX 导入／导出与逐产品批量结果 |
+| Website 与语言 | 工作中／预览／发布配置、Public Copy 覆盖、分类列表 profile、独立 Admin 语言与十种内置公开语言 |
+| 公开发现 | 语义 HTML、搜索／列表／分页、产品与分类字典路由、JSON-LD、JSON、Markdown、Sitemap、manifest 与 `llms.txt` |
+| RFQ | 目录产品及访客明确提出的目录外型号、canonical-payload idempotency、持久化回执、Admin 查看与可选且明确触发的 SMTP 发送 |
+| 访问 | 不透明 server-side session、服务器端 capability、CSRF 检查与审计记录 |
+| 运维 | Installer、health／readiness、runtime log、backup、journaled restore、Recovery、Maintenance 与可选 service 集成 |
+| 交付 | 内嵌 UI／sample payload、source／version metadata、checksum 与 Linux／Windows／macOS 构建目标；cross-build 不等于原生运行验收 |
+
+V1 排除结账、价格／库存承诺、CRM、通用页面编辑器、任意 JavaScript／template 与外部写入 token。RFQ 不创建 Product，也不自动发送邮件。机器可读输出不代表 AI／RAG 实现；语义相似不代表电气兼容。案例研究详细区分这些边界，以及已实现、延后与探索性工作。
 
-内建语言为 `en-US`、`zh-TW`、`zh-CN`、`ja-JP`、`ko-KR`、`de-DE`、`fr-FR`、`it-IT`、`es-ES`、`pt-BR`。内置默认文案已通过 key、placeholder、plural、格式与版面检查，但尚未经专业母语、法律或行销审核；正式发布前请审阅所有面向公网文案。
+内置语言为 `en-US`、`zh-TW`、`zh-CN`、`ja-JP`、`ko-KR`、`de-DE`、`fr-FR`、`it-IT`、`es-ES`、`pt-BR`。代码仓库包含资源契约检查，不声称已完成专业母语、法律或营销审核。工程指南与 README 同步提供英文、繁体中文与简体中文。
 
 ## 快速开始
 
@@ -48,7 +52,7 @@ V1 刻意不包含结帐、定价、库存 Availability、CRM、通用页面编
 执行前请先验证下载档。Linux：
 
 ```sh
-sha256sum --check SHA256SUMS
+sha256sum --check --ignore-missing SHA256SUMS
 chmod +x prods-linux-amd64
 ./prods-linux-amd64
 ```
@@ -137,7 +141,7 @@ RFQ 不会创建 Product、不会虚构价格或 availability，也不会自动
 
 ## 备份、恢复与 Maintenance
 
-可在 Admin 创建与监看备份，或执行单次备份：
+可在 Admin 创建与跟踪在线备份。命令行 backup、restore 或 Owner recovery 前，先停止运行中的 instance，并使用相同配置／data 路径；这些命令需要获取 instance ownership lock。单次备份：
 
 ```sh
 ./prods-linux-amd64 --backup-now
@@ -200,6 +204,7 @@ Browser / crawler
 
 - Go 1.27.1
 - Node.js 24
+- Python 3，用于许可政策验证
 - pnpm 10.28.1，由 `packageManager` 固定
 
 ```sh

README-zh_TW.md

@@ -2,11 +2,9 @@
 
 [English](README.md) | 繁體中文 | [简体中文](README-zh_CN.md)
 
-**把產品資料變成正式、可搜尋、可詢價的官方網站，不必維運一整套應用系統。**
+Prods 是供製造商與經銷商自架的技術產品型錄與 RFQ（詢價請求）系統。管理員維護產品資料、分類專屬規格與文件；買家探索已發布產品並提出詢價。半導體與電子零組件型錄不只是扁平產品清單：產品身分、適用規格、原始值、datasheet 與發布狀態都具有意義。
 
-Prods 是為製造商、經銷商與其他 B2B 產品團隊打造的自架產品型錄與 RFQ（詢價請求）系統。小型團隊可匯入並維護技術產品資料，安全發布給訪客、搜尋引擎與機器使用，再從同一個可攜式 Go 執行檔接收真實買家需求。
-
-執行環境內含 Admin 後台、公開網站、SQLite 支援、搜尋、發布、RFQ、備份、復原與維運工具。Node.js 只在從原始碼建置時需要；部署後不需要 Node.js、獨立資料庫伺服器、Docker、佇列或外部搜尋服務。
+單一 Go 行程提供公開網站、內嵌 Admin 應用程式與生命週期工具，SQLite 為主要資料庫。Public 由 Go 生成 HTML，以 React 增強互動；Admin 使用 React、headless Refine Core 與 Ant Design v6。Node.js 是建置相依工具，不是部署後的執行需求。
 
 ## 為什麼選擇 Prods
 
@@ -17,25 +15,31 @@ Prods 是為製造商、經銷商與其他 B2B 產品團隊打造的自架產品
 - **維運方式清楚可掌握。** 單一行程負責 migration、寫入節流、耐久工作、稽核、備份、restore journal 與健康檢查。Terminal 會顯示目前狀態、下一步、網址、Admin 路徑、主機資訊、資源路徑與即時 log。
 - **掌握部署與資料。** Prods Community 採 AGPL 授權，以 SQLite 儲存主要狀態，將資產與備份放在明確的本機目錄，可在 Windows 或 Linux 上執行並搭配自選的反向代理。
 
-## 適合的團隊
+## 工程文件與目前狀態
 
-Prods 適合需要官方產品型錄與 RFQ 管道，但不想自行拼裝並維運 CMS、客製資料庫應用、搜尋服務與獨立後台的產品型企業。尤其適合零組件、工業、技術型與 B2B 型錄，這些情境通常重視料號、分類、規格、文件、公開控制與詢價脈絡。
+| 文件 | 用途 |
+| --- | --- |
+| [架構概覽](docs/zh-TW/architecture.md) | 元件、請求／資料流程、持久化、認證與系統邊界 |
+| [工程案例研究](docs/zh-TW/engineering-case-study.md) | 六項決策及其證據、替代方案、取捨與演進觸發條件 |
+| [維運與正式環境證據](docs/zh-TW/operations.md) | 安裝、備份／復原、部署控制與尚未驗證的維運宣稱 |
 
-V1 刻意不包含結帳、定價、庫存 Availability、CRM、通用頁面編輯器、任意自訂 JavaScript，也不會由 RFQ 自動建立產品。這些邊界讓型錄真實資料、公開內容與買家需求維持清楚可控。
+指南描述 2026-09-17 檢視的工作目錄（`VERSION`：`v0.6.8`）。原始碼、測試與發布 workflow 呈現已實作機制；本次查核未驗證運行中的正式部署、客戶負載或可用性目標。Release workflow 發布成品，不部署運行中的站點。歷史需求與 ADR 保持內部文件身分；指南提供原始碼連結與說明，不重新公開內部內容。
 
-## 主要能力
+## 已實作範圍
 
-| 領域 | Prods 提供的能力 |
+| 領域 | 儲存庫中的實作 |
 | --- | --- |
-| 型錄作業 | Current／Archived 產品、任意深度分類、規格與 Spec Set、字典、圖片／文件、分頁、排序、XLSX 匯入／匯出，以及批次 Publish／Hide／Archive／分類／生命週期操作 |
-| Website 與多語 | 版本化 Website 設定、預覽／發布流程、Public Copy 覆寫、導覽與主題控制、獨立 Admin UI 語系，以及十種內建公開語系 |
-| 公開探索 | 伺服器端搜尋與型錄頁、產品／分類／製造商／品牌／應用路由、Unicode folding 搜尋、JSON-LD、JSON、Markdown、Sitemap、robots、manifest 與 `llms.txt` |
-| RFQ | 多產品詢價、搜尋無結果後的 Requested Part、high-entropy idempotency key、耐久收據、Admin 檢視，以及明確觸發的選用 SMTP 寄送 |
-| 權限與可追溯性 | 不透明 server-side session、CSRF 防護、能力型角色、Admin scope，以及必要管理操作記錄 |
-| 維運 | Liveness／readiness、runtime log、排程與單次備份、驗證式 restore、Recovery、Owner 救援、Maintenance、資產清理與手動版本檢查 |
-| 發布 | 預設空白安裝、選用且精確對應版本的 sample data、內嵌原始碼 revision／版本、checksum，以及 Linux／Windows amd64 成品 |
+| 型錄 | Current／Archived 產品、分類、Spec Set、原始規格值、字典、圖片／文件、XLSX 匯入／匯出與逐產品批次結果 |
+| Website 與語系 | 工作中／預覽／發布設定、Public Copy 覆寫、分類列表 profile、獨立 Admin 語系與十種內建公開語系 |
+| 公開探索 | 語意 HTML、搜尋／列表／分頁、產品與分類字典路由、JSON-LD、JSON、Markdown、Sitemap、manifest 與 `llms.txt` |
+| RFQ | 型錄產品及訪客明確提出的非型錄料號、canonical-payload idempotency、持久收據、Admin 檢視與選用且明確觸發的 SMTP 寄送 |
+| 存取 | 不透明 server-side session、伺服器端 capability、CSRF 檢查與稽核紀錄 |
+| 維運 | Installer、health／readiness、runtime log、backup、journaled restore、Recovery、Maintenance 與選用 service 整合 |
+| 交付 | 內嵌 UI／sample payload、source／version metadata、checksum 與 Linux／Windows／macOS 建置目標；cross-build 不等於原生執行驗收 |
+
+V1 排除結帳、價格／庫存承諾、CRM、通用頁面編輯器、任意 JavaScript／template 與外部寫入 token。RFQ 不建立 Product，也不自動寄信。機器可讀輸出不代表 AI／RAG 實作；語意相似不代表電氣相容。案例研究詳細區分這些邊界，以及已實作、延後與探索性工作。
 
-內建語系為 `en-US`、`zh-TW`、`zh-CN`、`ja-JP`、`ko-KR`、`de-DE`、`fr-FR`、`it-IT`、`es-ES`、`pt-BR`。預設文字已通過 key、placeholder、plural、格式與版面檢查，但尚未經專業母語、法律或行銷審校；正式上線前請審閱所有對外文案。
+內建語系為 `en-US`、`zh-TW`、`zh-CN`、`ja-JP`、`ko-KR`、`de-DE`、`fr-FR`、`it-IT`、`es-ES`、`pt-BR`。儲存庫包含資源契約檢查，不宣稱已經專業母語、法律或行銷審校。工程指南與 README 同步提供英文、繁體中文與簡體中文。
 
 ## 快速開始
 
@@ -48,7 +52,7 @@ V1 刻意不包含結帳、定價、庫存 Availability、CRM、通用頁面編
 執行前請先驗證下載檔。Linux：
 
 ```sh
-sha256sum --check SHA256SUMS
+sha256sum --check --ignore-missing SHA256SUMS
 chmod +x prods-linux-amd64
 ./prods-linux-amd64
 ```
@@ -137,7 +141,7 @@ RFQ 不會建立 Product、不會虛構價格或 availability，也不會自動
 
 ## 備份、復原與 Maintenance
 
-可在 Admin 建立與監看備份，或執行單次備份：
+可在 Admin 建立與追蹤線上備份。命令列 backup、restore 或 Owner recovery 前，先停止運行中的 instance，並使用相同設定／data 路徑；這些命令需要取得 instance ownership lock。單次備份：
 
 ```sh
 ./prods-linux-amd64 --backup-now
@@ -200,6 +204,7 @@ Browser / crawler
 
 - Go 1.27.1
 - Node.js 24
+- Python 3，用於授權政策驗證
 - pnpm 10.28.1，由 `packageManager` 固定
 
 ```sh