维护受限文档与权限

本页面向站点维护者，说明正文怎样进入构建、怎样验证权限，以及怎样避免静态产物泄露

编辑文档源文件

文档正文统一放在项目的 content 目录，按一级主题、二级用途和三级工具组织。每页必须填写 title、description、section、group；需要更深层分类时使用 subgroup。

标题不使用冒号和表情符号。正文应包含准备材料、操作步骤、完成标志与错误处理。修改源文件后运行 npm run build，不直接编辑自动生成的 docs 页面。

划分公开预览和完整内容

受限路由由 shared/doc-access.js 决定，不能只改前端 frontmatter 解锁。tools 和 clients 下的具体教程使用余额保护，各自 introduction 公开。

在受限 Markdown 中插入且只插入一次 <!-- restricted -->。标记之前是公开预览，之后是完整正文。生成脚本会把前半部分交给 VitePress，把后半部分渲染、清理后写入 server/content/generated.json。

受限正文不会进入公开 HTML、页面 JavaScript 或搜索索引。搜索只能检索它的标题和公开说明。原项目的 CSS 遮罩方案已经移除。

理解运行时校验

浏览器请求同源的 /api/doc-auth/content?path=文档路径。云函数每次都核对来源、规范化路径、本地登录会话和普通教程权限范围；缺少有效阅读资格时才调用上游核对原始余额，通过后返回清理过的正文 HTML 并签发独立的 HttpOnly 阅读 Cookie。未登录返回 401，余额不满足返回明确的 403 错误码，未配置或上游暂不可用时不会伪装成余额不足。

门槛来自当前有效服务端配置，页面使用返回的 comparison 和 authorized 展示结果。例如门槛为 250 且比较器为 gt 时，250.00 不满足，严格大于才满足。已登录状态和权限状态是两层判断，前端不会仅凭本地数值或标记返回内容。

退出、跨标签页账号变更、路由切换或权限失效后，前端移除正文并取消旧请求。受限接口响应禁止缓存；密钥和上游 token 不进入 localStorage。

DOC_READING_GRANT_TTL_SECONDS 默认为 300，0 表示关闭短期资格、恢复每次正文请求都真实验证；正值只接受 30–900 秒整数。凭证绑定账号、登录会话、balance-preview 范围、当前门槛、gt 比较方式、策略版本和上游来源。到期时间在真实核验时固定，读取新文章和缓存命中都不续期；它也不会超过本地登录会话期限。

服务端返回真实核验、固定到期、建议刷新和响应生成时间，前端约在有效期 80% 处做后台强制刷新。页面隐藏时不做非必要刷新，恢复时按服务端绝对时间重新判断。后台失败不延长旧凭证，但在原到期前不拆除已加载正文；到期仍无法确认时停止新的受限读取。手动刷新会在前后端绕过阅读缓存。

本地会话期限与上游 Access Token 期限彼此独立。首次登录按 DOC_SESSION_MAX_AGE_SECONDS 建立本地到期时间；刷新上游令牌和更新 Cookie 内的下载计数都沿用这一时间，不会重新计算完整周期。期限到达后必须重新登录，上游刷新不能延长本地期限。

这是无状态凭证，不依赖单个云函数实例内的 Map，也没有为本功能引入 Redis 或数据库。相应地，已签发凭证在原到期前存在重放窗口；前端收到退出、换号或余额不足结果后会立即收起当前内容，但这不等于所有设备上的已签发凭证被强实时撤销。

所有普通认证请求共用一条服务端总预算，单次上游调用使用更短预算，浏览器等待时间再留出响应传输余量。取消和超时会中止响应体读取；刷新已经成功、但后续账户核验超时的请求仍保持锁定，同时回写轮换后的 Cookie。

受限正文挂载后会为当前导航补做一次 content- 章节定位。补定位只接受当前路径、hash、账号和请求代次；用户主动滚动或切换锚点后，旧请求不能把页面拉回原位置。

发布时包含服务端资源

构建前必须生成正文资源。EdgeOne 云函数通过 includeFiles 带上 server 与 shared，公开产物仅为 dist。不要把整个项目根目录当作静态目录上传，也不要把 server/content 复制到 docs/public。

本地开发与预览使用同一套 BFF 路由，生产环境从 Makers 服务端变量读取配置。真实 DOC_AUTH_SECRET 不进入 GitHub，也不使用 VITE_ 前缀。

验证修改

运行类型检查、单元测试、构建和浏览器流程。重点验证匿名、恰好门槛、超过门槛、会话过期、上游失败、退出后迟到响应，以及静态产物不含受限正文。

原设计中的未来独立内容 API 可以继续作为演进方向；当前实现已经通过同源云函数下发正文，不依赖那项未来迁移。