# UmayShop 技术文档平台界面原型

以 PRD v0.5 创建并按后续确认需求增补的 6 页可点击原型；主 PRD 已修订为 v0.6，新增产品验收条款不等于原型已实现生产能力。由 Gemini 生成页面主体，主代理统一样式、修正内容、接入本地交互并验证。仅用于产品评审，非生产系统。现已增加 `umay/website0813` 一次真实只读采集验证，真实快照与其余演示内容分开展示。

## 打开

解压交付包后，用桌面浏览器打开根目录 `index.html`（原型总目录）或 `admin/docs.html`。点击“Web 真实验证”查看已采集快照；也可用 `admin/docs.html#web-validation` 直接定位。页面、样例和真实验证报告均在包内，阅读不依赖外网。验证报告中的 GitLab 证据链接需要网络和项目访问权限。交付包现在包含私有项目的接口路径、文件路径和提交标识，仅供获授权人员内部使用。也可在本目录运行 `python3 -m http.server 4173 --bind 127.0.0.1`，访问 `http://127.0.0.1:4173/` 进入原型总目录，或访问 `http://127.0.0.1:4173/admin/docs.html`。本地服务不是公网部署。

## 6 页范围

| 页面 | 文件 | 可评审内容 |
|---|---|---|
| 文档工作区 | `admin/docs.html` | 14 类完整中英双语模板示例、章节导航、图表及下载；旧 Mobile 与历史示例仅保留链接兼容，不显示侧栏或顶部入口 |
| 搜索结果 | `admin/search.html` | 关键词、模块及语言筛选；空输入、无结果、索引失败；定位章节 |
| 更新审阅 | `admin/review.html` | 修订差异、译文对照、人工补充、证据缺口阻断、退回原因 |
| 同步任务 | `admin/sync-runs.html` | 成功、失败与部分完成；任务详情、重试排队；原失败记录保留 |
| 文档覆盖与缺口 | `admin/coverage.html` | 5 个候选项目、缺口筛选、负责人及资料缺失 |
| 接入与模板配置 | `admin/settings.html` | 来源、模板、语言及访问策略；空模板校验和模拟连接 |

根目录 `index.html` 作为原型交付包的全局总目录与导览入口，集中呈现 6 大核心业务页面、14 大类技术文档标准规范全景（中英双语 28 篇全文本地直达）、离线矢量图表清单、website0813 真实只读采集验证报告以及同期需求资料索引。管理控制台内部严格保持 6 页边界，搜索、审阅通过上下文进入，不扩展一级菜单。主要输入、按钮、链接及浮层均有稳定的 `data-prototype-anchor`，便于后续批注。

## 建议评审顺序

1. 在左侧 14 类目录阅读模板示例，用“正文语言”中文/English 切换同篇文档；顶部界面语言只模拟选择。
2. 模板示例可下载当前正文 Markdown 或对应语言的含图 ZIP。旧 `#overview` 链接中，中文/英文 r12、俄文 r11 与历史确认属于独立旧演示，不与模板下载混用。
3. 打开图表、来源与历史抽屉。
4. 输入“订单”或“orders”，筛选模块并定位文档章节。
5. 创建修改稿，查看差异及来源缺口；提交不能绕过缺口。退回必须填写原因。
6. 在同步任务中筛选失败、重试；只显示排队演示，不把失败记录改成成功。
7. 查看候选范围与模板配置。所有保存、接入及访问操作都是本地演示。

## 已锁定的边界

- App 当前源码采集分支为 `dev`，不等于生产或应用商店版本。
- `umay/cis-mep` 及所有下级项目排除，不计入采集和验收分母。
- 5 个根项目只是候选范围。Backend/WMS 主体来源、在用状态及各模块负责人仍需确认。
- Mobile 页面及原有表格仍为演示。Web 真实验证区读取的是指定仓库的固定版本证据，不将演示数据计入真实结果；未保存源码正文、令牌或敏感 IP。
- 14 类目录均有完整中文和英文模板示例正文，默认进入第 01 类；全部为虚构示例，不表示真实技术文档已生成或核验。原 Mobile 多语言样例保留旧链接兼容；侧栏及顶部入口已移除。
- 新增模板正文支持下载本篇 Markdown、空白模板和全套含图 ZIP；14 篇英文已提供，俄文及 PDF 未生成。原 Mobile 区继续支持预置中英俄 ZIP/PDF 示例。下载与当前视图隔离，不是实时导出服务。
- 14 类模板英文为完整机器译稿，7 张矢量图及图源的可见标签已翻译；尚无人工语言签认。旧 Mobile 示例中的俄文故意使用历史修订，旧图表保留中文标签。没有新增截图文字识别或图片重制服务。
- 已完成 website0813 单项目的一次只读采集、文件树核对、空差异补读和技术事实摘要生成。没有常驻在线连接、自动轮询、真实业务资料自动翻译、正式发布、权限配置或部署动作；虚构模板的英文机器翻译已离线完成。
- 未确认规则保留在 `page-inventory.md` 的 D-01 至 D-10，不由原型自行定案。

## 生成与修改

- 页面结构与静态文案权威源：`_gen_pages.py`，其中包含已整合的 Gemini 页面数据。
- 共享样式与交互：`shared/common.css`、`shared/common.js`。
- 修改生成源后运行 `python3 _gen_pages.py`，不要直接改生成后的 HTML。
- 可见文字、正文、表格、译文和异常状态全部预写在 HTML；JavaScript 只控制切换、筛选、校验和反馈。
- 下载样例生成器：`tests/build_download_samples.py`。重建需要 Python 的 BeautifulSoup、ReportLab 及指定 Unicode 字体；交付包已经包含成品，阅读不需要这些依赖。
- `tests/validate_static.py` 检查链接、组件目标、范围约束、源文件重复生成一致性及 ZIP/PDF 内容。使用 BeautifulSoup 和 pypdf。
- `tests/browser-checks.cjs` 是供已授权 Playwright 浏览器工具执行的测试函数；不是生产脚本。

验证结果见 `tests/validation-report.md`，页面清单见 `page-inventory.md`，Gemini 调用记录摘要见 `generation-provenance.json`。

## 真实只读验证

- 入口：`admin/docs.html#web-validation`；设置、同步任务页也有入口。仍为六个业务页面。
- 固定比较：`staging-2.0.289` 至 `staging-2.0.290`，不是生产发布认定。
- 采集工具：`verification/tools/gitlab_readonly.py`；仅通过 HTTPS GET 访问指定项目，拒绝跨项目和跳转，不保存令牌。运行时用隐藏输入提示输入只读令牌。
- 产物：`verification/baseline.md`、`verification/current.md`、`verification/website0813-report.md`、对应 PDF 和去掉源码正文的证据 JSON。
- 报告渲染源：`verification/render_snapshot.py`。重新采集后运行它，再生成页面；PDF 使用 `verification/tools/build_report_pdf.py`。
- 快照不会随点击同步按钮改变。重新采集须主动运行工具；不把凭据放入浏览器或原型 JavaScript。
- 基础验证使用 GitLab 自身的多个接口交叉核对，并非两个独立外部证据来源。

详情见 `verification/README.md`。

## 同期需求与文档参考

Web 真实验证内新增“同期需求资料”入口：`admin/docs.html#issue-references`。已纳入 `umay/doc-and-issues` 的 23 条同期资料及 52 条非系统评论，并提供 Markdown/PDF 索引和分项摘录。

来源时间、代码关联候选、需求分歧与未读取附件分别标注。3 个原文件下载受认证跳转限制，尚未读取；原附件中的图片/视频未复核，不视为已完成全内容采集。Tezber API 与 Admin 手册已有可读取正文，作为带来源的参考而非已验证实现。

离线包包含私有需求内容与源链接，只供授权人员内部使用。生产权限、周期采集、真实资料翻译与正式发布仍未启用。

## 2026-10-02：模板正文接入

- `admin/docs.html` 默认打开 01 项目概述；`#template-01` 至 `#template-14` 分别定位 14 类正文。原 `#web-validation`、`#issue-references` 和 `#overview` 链接保持有效。
- 在同一页切换模板示例与 Web 真实验证；Mobile 旧示例保留链接兼容，不再提供侧栏及顶部切换入口。模板正文内的相关文档、上一篇/下一篇、章节导航可点击并支持刷新与浏览器返回。
- 原文来自 `umay-tech-docs-kit` 的 14 份虚构示例。`template-library/source-manifest.json` 保存复制来源的文件哈希；正文在 Python 生成阶段转为静态 HTML，不在浏览器拼接内容。
- 搜索范围为 14 篇中文 + 14 篇英文模板全文及 6 条旧多语言片段，共 34 个预置结果。其结果全部为演示，不把真实核验候选当作模板事实。
- 模板正文的“下载本篇 Markdown”只下载 `.md`；保留全部图片、图源及交叉引用请使用“全套含图 ZIP”。空白模板保留待填写项。模板视图不显示旧 Mobile PDF/历史/修改稿操作。
- 模板统一要求：明确最终决策、确认权限、完整代码 SHA、实现位置、核验人和范围后，才可作为正式参考。集成示例没有改变实际核验状态。

### 维护入口

```bash
# 仅当模板包更新后重新复制；阅读和普通页面重生成不依赖包外路径
python3 tools/sync_template_library.py --source ../umay-tech-docs-kit
# 中文源变化后须先补齐 translations/en.json 中对应片段；缺项会停止构建
python3 tools/build_english_examples.py
python3 _gen_pages.py
python3 -m unittest discover -s tests -p 'test_*.py' -v
python3 tests/validate_static.py
```

新增源码：`template_content.py`（Markdown 编译与静态目录/搜索）；`shared/template-reader.css`（仅阅读区样式）；`tools/sync_template_library.py`（复制和本地图文打包）。生成额外依赖 Python-Markdown 与 BeautifulSoup，当前环境已有；交付 HTML 阅读仍无运行时依赖或外网请求。

本轮 Gemini 样式子任务遇到子代理吞吐限流，未取得可用输出，最终采用现有风格由主代理完成；并非 Gemini 成功生成本轮新阅读区。验证记录见 `tests/template-integration/validation-report.md`。


## 2026-10-02：英文接入与最终验证

- 同一六页原型内提供 14 篇中文和 14 篇英文示例。英文深链为 `admin/docs.html#template-01-en` 至 `#template-14-en`；目录、章节、相关文档、前后篇、搜索与下载保持所选正文语言。
- 965 条翻译片段已齐全。保留标题层级、表格、代码和链接目标；7 张 SVG 与 7 份 Mermaid 图源有英文版。图表扩大连线间距并换行标签，避免英文被节点遮挡。
- 可下载英文单篇 Markdown 或 `template-library/examples-en-with-images.zip`。单个 Markdown 不内嵌图片，离线含图阅读请解压 ZIP 并保持目录结构。译文附说明：正文内语言/发布检查表忠实保留原示例快照，不代表当前原型可用性。
- 顶部语言菜单仅模拟中文/English/Русский，刷新恢复中文；不改变正文、URL 或下载语种。菜单为不透明白底，仅当前项勾选。
- 原模板包、真实 Web 验证和 Issue 资料区保持独立；没有新增第七个页面。所有模板示例为虚构资料，不计入已核实参考。

**边界**：英文已完成结构、技术标识和浏览器验证，仍是未经人工语言签认的机器稿；14 篇示例的俄文全文与 PDF 未生成，生产采集/权限/发布/自动更新服务未实现。本轮目标是示例正文与英文接入，不代表主 PRD 全部产品能力已交付。

维护英文翻译使用 `tools/build_english_examples.py` 和 `translations/en.json`，重建无需再次调用模型。`translation-manifest.json` 记录原文及译文哈希、修订关系和核验边界。中文原文更新后必须重新核对翻译，不可沿用旧映射冒充最新译文。

最终验证记录：[英文与语言菜单验证](tests/english-integration/validation-report.md)。原型包由 `python3 tools/package_prototype.py` 更新；`manifest.json` 逐文件记录哈希。包内含私有需求资料及源链接，仅供获授权人员内部使用。


## 2026-10-02：移除旧多语言示例入口

按页面批注意见，移除侧栏“多语言交互示例”及顶部“Mobile 多语言示例”两个入口。文档工作区只保留“模板示例正文”和“Web 真实验证”切换；14 类正文、正文中英切换及顶部界面语言模拟不变。旧 `#overview` 和既有章节链接仍可打开，避免现存引用失效；本次没有删除旧示例内容或下载资源。

针对性验证见 `tests/demo-entry-removal/validation-report.md`。