文档与决策

Web 界面提供文档列表和决策记录的浏览功能，支持按子文件夹分组查看，方便在浏览器中阅读项目知识库内容。

进入文档页面

启动 Web 界面后，点击顶部导航栏的「文档」标签，进入文档列表页面。页面以分组形式展示 backlog/docs/ 目录下的全部 Markdown 文档。

浏览文档列表

文档列表按子文件夹自动分组展示。例如：

• guides — 存放指南类文档
• api — 存放接口文档
• (根目录) — 直接存放在 docs/ 下的文档

点击分组标题可展开或折叠该文件夹下的文档条目。每个文档条目显示标题、最后更新时间摘要和标签（如有）。

侧边栏排序开关

侧边栏的文档区标题栏提供名称 / ID 两个排序开关，点击切换排序列与升降序（列名旁显示 ↑ / ↓）：

• 名称：按文档标题排序（无标题时回退文件名），数字感知（doc-4 排在 doc-10 前）
• ID：按文档 ID 排序，名称作为平局决胜
• 每个文件夹层级独立排序，文件夹始终排在文件之前

决策区同样提供标题 / ID 排序开关，决策为平铺列表、不涉及文件夹。三个侧边栏分区（文档、Wiki、决策）共用同一控件样式。

查看文档内容

在列表中点击目标文档标题，页面跳转至文档详情页。文档内容以渲染后的 Markdown 格式展示，包括：

• 标题与正文
• 代码块与高亮
• 表格与列表
• 图片与链接

点击页面顶部的「返回」按钮或浏览器后退键，可回到文档列表页面。

文档内锚点跳转

文档正文中的标题链接（[链接](#章节名) 形式）会在当前文档上下文内平滑滚动跳转，并同步更新地址栏锚点，而不会跳到应用根页面。标题 ID 由统一的 slug 算法生成，人类可读的 TOC 锚点（如 #A1、#A1: Section Title）仍能被正确解析定位。对于超链接到本地短链接的文档，还支持附加 :行号 或 :起始-结束 行区间后缀，点击后按指定行范围在预览框中展示内容。

带锚点的链接（如 /documentation/5#A2）在首次加载时也会自动滚动到目标标题：内容异步渲染完成后由观察器定位标题，地址栏中的锚点在 URL 规范化（裸 ID 补齐标题 slug）过程中不会丢失。

文档同样支持按 ID 直接定位：无论是根目录还是子目录下的文档，输入裸 ID（如 doc-20）或纯数字（20）都能精确打开对应文档；ID 存在歧义时仍按 fail-closed 抛出冲突提示并给出候选列表。

页面目录（TOC）

文档、决策与 Wiki 详情页的头部提供目录按钮：点击展开当前页面的标题大纲，条目层级来自实际渲染的标题（含重复标题与 CJK 标题）：

• 点击条目即平滑滚动到对应章节；滚动页面时当前章节在目录中高亮（scrollspy）
• 含子树的条目可折叠；条目较多时深层级默认折叠，当前所在分支自动展开
• 面板头部提供「全部折叠 / 全部展开」总开关
• 页面没有标题（或处于编辑模式）时目录按钮不出现

任务详情、Wiki 预览与文件预览弹窗内也有同款大纲，以书签式抽屉从弹窗左边缘探出（不改动弹窗宽度），详见任务列表的「大纲抽屉」小节。

内容变更静默重载

文档在磁盘上被外部修改时，已打开的文档页会按内容指纹比对后静默重载：只有内容确实变化才更新正文，且保持滚动位置与锚点不丢失；编辑模式下不会重载，未保存的输入不受影响。

Mermaid 图表

文档、决策与 Wiki 正文中的 ```mermaid 代码块会渲染为图表：围栏语言标识不区分大小写；图表主题跟随界面亮 / 暗模式自动切换；Markdown 编辑器的预览窗格同样渲染 Mermaid。

进入决策记录页面

在顶部导航栏中点击「决策」标签，进入决策记录（ADR）列表页面。页面展示 backlog/decisions/ 目录下的全部决策文件。

每条决策记录显示：

• 决策标题
• 当前状态（Proposed、Accepted、Rejected、Deprecated、Superseded）
• 创建日期

查看决策详情

点击决策列表中的任意条目，进入决策详情页。页面渲染展示完整的 ADR 内容，包括决策背景、考量因素、最终决定和后续影响等章节。

决策的状态标签以颜色区分，且状态名称随界面语言本地化（如中文界面显示「已接受」）；非标准状态原样显示。每个状态还带独立图标，颜色不是唯一辨识信号。

新建决策

侧边栏决策区的「+」按钮打开新建决策页：输入标题与正文（可粘贴图片，保存时自动提升到 assets/paste/），保存后跳转到新决策页面；正文留空时使用默认的「背景 / 决策 / 后果」模板。

编辑决策

决策详情页右上角提供 Edit 按钮：点击进入编辑模式，出现 Cancel / Save 按钮对；编辑过程中列表刷新不会打断或覆盖你的输入；?edit=true 深链接可直接以编辑模式打开。

编辑模式下可在头部直接修改状态：下拉框列出 proposed / accepted / rejected / superseded 等标准状态（本地化显示，存储值保持原始英文），也可保留数据中已有的自由状态。只改状态不重写正文。