diff --git a/IT服务平台/ICT服务平台/对MkDoc构建用户系统.md b/IT服务平台/ICT服务平台/对MkDoc构建用户系统.md
new file mode 100644
index 0000000..5bbb812
--- /dev/null
+++ b/IT服务平台/ICT服务平台/对MkDoc构建用户系统.md
@@ -0,0 +1,925 @@
+# MkDocs 用户阅读管理系统 — 规划设计及实施方案
+
+## 一、概述
+
+### 1.1 目标
+
+针对以 MkDocs 生成的静态文档站点（如 docs.writech.cn），构建一套**用户阅读管理系统**，实现用户登记与身份识别、文档分级权限控制、阅读次数与有效期管理、防爬虫保护和阅读行为统计分析。系统在保障文档安全可控的同时，为大部分公开文档提供**免登录流畅阅读**体验，仅在访问受控文档时才触发轻量认证。
+
+### 1.2 与现有平台的关系
+
+本系统基于 [ICT 服务平台](ICT服务平台概要.md) 已有基础设施构建，复用以下底座能力：
+
+| 已有组件 | 本系统中的角色 |
+|---------|-------------|
+| Keycloak（SSO） | 登录用户的 OIDC 认证中心，对接微信开放平台 Social IdP |
+| OpenLDAP（身份源） | 企业员工账户存储 |
+| DocForge（渲染引擎） | MkDocs 构建触发与权限元数据解析 |
+| Umami（统计分析） | 页面级阅读埋点与看板 |
+| PostgreSQL（数据库） | 用户注册信息、权限策略、阅读记录持久化 |
+| Nginx（反向代理） | 请求拦截、静态资源分发、SSL 终止 |
+
+### 1.3 设计原则
+
+1. **静态站点不改造**：MkDocs 仍按标准流程生成静态 HTML，用户系统以**反向代理网关层**注入，不侵入 MkDocs 构建产物
+2. **最小摩擦登录**：公开文档免登录访问；受控文档首次需认证后自动记住，不逐页弹登录框
+3. **双通道注册**：支持微信扫码和手机短信验证码两种轻量注册方式，适配 PC 和移动端
+4. **颗粒度可粗可细**：权限可设置到单篇文档，也可按目录/标签/仓库整体授权
+5. **全栈开源**：核心组件均采用开源方案，数据自托管
+
+---
+
+## 二、系统架构
+
+### 2.1 整体架构图
+
+```plantuml
+@startuml
+skinparam componentStyle rectangle
+skinparam nodesep 10
+skinparam ranksep 25
+title MkDocs 用户阅读管理系统 - 整体架构
+
+actor "PC 浏览器" as PCUser
+actor "手机浏览器" as MobileUser
+
+rectangle "互联网应用服务器" {
+
+  package "接入层" as P_Access {
+    [Nginx\n反向代理] as Nginx
+    [MkDocs Guard\n认证网关] as Guard
+  }
+
+  package "认证服务" as P_Auth {
+    [Keycloak SSO] as KC
+    [微信扫码服务] as WxAuth
+    [短信验证服务] as SMS
+  }
+
+  package "用户管理" as P_User {
+    [用户注册中心] as UC
+    [权限引擎] as Perm
+    [反爬虫模块] as AntiBot
+  }
+
+  package "文档服务" as P_Doc {
+    [MkDocs\n静态站点] as MkDocs
+    [DocForge\n渲染引擎] as Forge
+  }
+
+  package "数据与分析" as P_Data {
+    database "PostgreSQL" as DB
+    [Redis\n会话/限流] as Redis
+    [Umami 统计] as Umami
+  }
+}
+
+' === 分层布局控制 ===
+P_Access -[hidden]down-> P_Auth
+P_Access -[hidden]down-> P_User
+P_Auth -[hidden]right-> P_User
+P_Auth -[hidden]down-> P_Doc
+P_User -[hidden]down-> P_Data
+P_Doc -[hidden]right-> P_Data
+
+' === 用户入口 ===
+PCUser -down-> Nginx
+MobileUser -down-> Nginx
+Nginx -down-> Guard : 文档请求
+
+' === Guard 请求分发 ===
+Guard -down-> KC : OIDC 认证
+Guard -down-> Perm : 查询权限
+Guard -down-> AntiBot : 请求检测
+Guard -down-> MkDocs : 放行静态页面
+
+' === 注册中心 ===
+UC --> WxAuth : 微信登录
+UC --> SMS : 短信验证
+
+' === 数据持久化 ===
+UC -down-> DB : 用户数据
+Perm -down-> DB : 权限策略
+Perm -down-> Redis : 缓存
+Forge -down-> DB : 文档元数据
+Umami -down-> DB : 阅读埋点
+@enduml
+```
+
+### 2.2 核心组件清单
+
+| 组件 | 技术方案 | 用途 | 许可证 |
+|------|---------|------|--------|
+| 认证网关 | **MkDocs Guard**（自研，Go / Node.js） | Nginx 子请求认证，拦截文档请求并校验权限 | — |
+| 用户注册中心 | **UserCenter**（自研，Node.js + Express） | 微信扫码、短信验证码注册/登录，用户管理 | — |
+| 权限引擎 | **PermEngine**（自研，Node.js） | 文档 - 用户权限匹配、次数/期限校验 | — |
+| 反爬虫 | **AntiBot**（自研 + 开源中间件） | 频率限制、浏览器指纹、行为检测 | — |
+| 微信 OAuth | **微信开放平台** + Keycloak Social IdP | 微信扫码登录/注册 | — |
+| 短信网关 | **阿里云短信服务** / **腾讯云短信** | 验证码发送 | — |
+| 会话缓存 | **Redis** | 登录会话、验证码、频率计数器 | BSD |
+| 浏览器指纹 | **FingerprintJS**（开源版） | 匿名用户标识、反爬辅助 | MIT |
+| 静态站点 | **MkDocs** + **Material 主题** | Markdown 文档构建为静态 HTML | BSD |
+| 统计分析 | **Umami**（已有） | 页面访问量、阅读时长、用户来源 | MIT |
+| 数据库 | **PostgreSQL**（已有） | 用户、权限、阅读记录持久化 | PostgreSQL |
+
+### 2.3 请求处理流程
+
+```plantuml
+@startuml
+skinparam componentStyle rectangle
+title 文档请求处理流程
+
+start
+:用户请求 MkDocs 文档页面;
+
+:Nginx 转发至 MkDocs Guard;
+
+:AntiBot 检测;
+if (疑似爬虫 ?) then (是)
+  :返回 429 / 验证码挑战;
+  stop
+else (否)
+endif
+
+:Guard 查询文档权限级别;
+
+if (文档为 open 级别 ?) then (是)
+  :直接放行, 返回静态页面;
+  :Umami 记录匿名访问;
+  stop
+else (否)
+endif
+
+if (用户已持有有效会话 ?) then (是)
+  :从 Redis 读取用户身份;
+else (否)
+  :展示登录浮层;
+  note right
+    PC - 微信扫码 / 短信验证码
+    手机 - 微信授权 / 短信验证码
+  end note
+  :完成认证, 建立会话;
+endif
+
+:PermEngine 校验用户权限;
+if (用户有权访问 ?) then (是)
+  if (阅读次数/有效期已超限 ?) then (是)
+    :提示 "使用权已到期, 请联系管理员";
+    stop
+  else (否)
+    :放行, 返回静态页面;
+    :记录阅读日志;
+    :Umami 记录实名访问;
+    stop
+  endif
+else (否)
+  :返回 403 无权限页面;
+  stop
+endif
+
+@enduml
+```
+
+---
+
+## 三、用户注册与登录
+
+### 3.1 注册方式
+
+系统支持两种轻量注册方式，用户无需设置密码：
+
+#### 3.1.1 微信扫码注册/登录
+
+```plantuml
+@startuml
+skinparam componentStyle rectangle
+title 微信扫码注册/登录流程
+
+start
+:用户在 PC 浏览器访问受控文档;
+:Guard 弹出登录浮层;
+:浮层展示微信登录二维码;
+note right: 调用微信开放平台生成临时二维码
+
+:用户使用微信扫码;
+:微信弹出授权确认;
+:用户点击确认授权;
+
+:微信回调 Keycloak 携带 code;
+:Keycloak 换取微信 OpenID + 用户信息;
+
+if (OpenID 已绑定系统用户 ?) then (是)
+  :直接登录, 建立会话;
+else (否)
+  :自动创建用户;
+  note right
+    昵称 - 微信昵称
+    头像 - 微信头像
+    标识 - 微信 OpenID
+    角色 - 默认读者
+  end note
+  :登录并建立会话;
+endif
+
+:回到文档页面, 自动刷新;
+stop
+@enduml
+```
+
+**技术实现要点**：
+
+- Keycloak 配置微信开放平台作为 Social Identity Provider
+- 使用微信开放平台「网站应用」的扫码登录能力（非公众号）
+- PC 端展示二维码供手机扫描；手机端直接调起微信授权页面
+- 微信 OpenID 与系统用户 1:1 绑定，存储于 PostgreSQL
+
+#### 3.1.2 手机短信验证码注册/登录
+
+```plantuml
+@startuml
+skinparam componentStyle rectangle
+title 短信验证码注册/登录流程
+
+start
+:用户在浮层选择 "手机号登录";
+:输入手机号;
+
+:UserCenter 检查发送频率;
+if (60 秒内已发送 ?) then (是)
+  :提示 "请稍后重试";
+  stop
+else (否)
+endif
+
+:生成 6 位随机验证码;
+:验证码存入 Redis (有效期 5 分钟);
+:调用短信网关发送;
+
+:用户输入验证码;
+
+if (验证码正确 ?) then (是)
+  if (手机号已注册 ?) then (是)
+    :直接登录, 建立会话;
+  else (否)
+    :自动创建用户;
+    note right
+      标识 - 手机号
+      角色 - 默认读者
+    end note
+    :登录并建立会话;
+  endif
+else (否)
+  :提示 "验证码错误";
+  stop
+endif
+
+:回到文档页面;
+stop
+@enduml
+```
+
+**技术实现要点**：
+
+| 配置项 | 值 |
+|-------|-----|
+| 验证码长度 | 6 位纯数字 |
+| 有效期 | 5 分钟 |
+| 发送间隔 | 60 秒 |
+| 单手机号日上限 | 10 次 |
+| 短信模板 | 「您的 Writech 文档验证码为 {code}，5 分钟内有效。」 |
+| 频率计数器 | Redis INCR + TTL |
+
+### 3.2 PC 浏览器认证体验
+
+PC 端用户访问受控文档时，页面内弹出**半透明遮罩 + 居中登录浮层**（非跳转），浮层包含两个标签页：
+
+| 标签页 | 内容 |
+|-------|------|
+| 微信扫码 | 显示动态二维码，扫码后自动完成登录并关闭浮层 |
+| 短信验证 | 手机号输入框 + 发送按钮 + 验证码输入框 |
+
+浮层设计原则：
+- 背景半透明可窥见文档内容（制造阅读意愿）
+- 登录成功后浮层自动消失，无页面跳转
+- 会话有效期 7 天，有效期内不再弹出
+
+### 3.3 手机浏览器认证体验
+
+- **微信内打开**：直接调起微信授权（静默授权 + 头像/昵称），无需扫码
+- **其他浏览器**：展示短信验证码登录界面，微信扫码二维码作为备选
+
+### 3.4 会话管理
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 会话存储 | Redis | key = `session:{token}`，value = 用户信息 JSON |
+| 会话有效期 | 7 天 | 自最后一次请求起滑动续期 |
+| 会话 Token | HttpOnly Cookie | `mkdocs_session`，Secure + SameSite=Lax |
+| 并发会话 | 不限 | 同一用户可在多设备同时登录 |
+
+---
+
+## 四、用户管理
+
+### 4.1 用户数据模型
+
+```
+users
+├── id              UUID        主键
+├── phone           VARCHAR(20) 手机号（唯一，可为空）
+├── wechat_openid   VARCHAR(64) 微信 OpenID（唯一，可为空）
+├── wechat_unionid  VARCHAR(64) 微信 UnionID（可为空）
+├── nickname        VARCHAR(50) 昵称
+├── avatar_url      TEXT        头像 URL
+├── role            ENUM        角色：reader / reviewer / blocked
+├── list_type       ENUM        名单类型：normal / whitelist / blacklist
+├── group_id        UUID        所属用户组（外键）
+├── registered_at   TIMESTAMP   注册时间
+├── last_login_at   TIMESTAMP   最后登录时间
+└── status          ENUM        状态：active / suspended / deleted
+```
+
+### 4.2 用户角色
+
+| 角色 | 标识 | 权限说明 |
+|------|------|---------|
+| 读者 | reader | 默认角色，可阅读被授权的文档，可提交反馈 |
+| 审阅者 | reviewer | 受邀审阅指定文档，可阅读、评论并提交修改建议 |
+| 被封禁 | blocked | 黑名单用户，禁止访问所有受控文档 |
+| 管理员 | admin | 管理用户、权限策略、查看统计（复用 Keycloak 管理员角色） |
+
+> 说明：「作者」角色由 Gitea 仓库写权限定义，不在本系统管理范围内。
+
+### 4.3 白名单与黑名单
+
+#### 白名单机制
+
+- 白名单用户可访问**所有 `login` 级别文档**，无需逐文档授权
+- 适用场景：VIP 客户、长期合作伙伴、内部测试人员
+- 管理方式：管理员在后台设置 `list_type = whitelist`
+
+#### 黑名单机制
+
+- 黑名单用户访问任何受控文档均返回 403
+- 触发条件：
+  - 管理员手动加入
+  - AntiBot 检测到恶意爬取行为自动加入
+  - 用户连续提交违规反馈内容
+- 管理方式：管理员在后台设置 `list_type = blacklist`
+
+#### 名单优先级
+
+```
+黑名单 > 文档级 restricted > 白名单 > 文档级 login > 普通用户
+```
+
+### 4.4 用户分组
+
+用户可归入多个组，方便按组授权：
+
+```
+user_groups
+├── id          UUID        主键
+├── name        VARCHAR(50) 组名（如"经销商"、"教育局客户"）
+├── description TEXT        说明
+└── created_at  TIMESTAMP
+
+user_group_members
+├── user_id     UUID        外键 → users
+├── group_id    UUID        外键 → user_groups
+└── joined_at   TIMESTAMP
+```
+
+授权时可指定用户组，该组全部成员自动获得对应权限。
+
+---
+
+## 五、文档权限模型
+
+### 5.1 权限分级
+
+在现有 DocPortal 权限体系基础上，MkDocs 用户系统使用以下**五级访问控制**：
+
+| 级别 | 标识 | 说明 | 是否需要登录 |
+|------|------|------|-------------|
+| 完全公开 | `open` | 任何人可无限次阅读，不触发任何认证 | 否 |
+| 试读公开 | `open_once` | 匿名用户首次可阅读，再次访问需登录 | 首次否，再次是 |
+| 登录可读 | `login` | 登录用户（含白名单）可阅读 | 是 |
+| 指定可读 | `restricted` | 仅授权用户/用户组可阅读 | 是 |
+| 内部机密 | `confidential` | 仅管理员和显式授权用户，额外审计日志 | 是 + 审计 |
+
+### 5.2 文档操作权限
+
+每篇文档可独立配置以下操作权限：
+
+| 权限 | 标识 | 说明 |
+|------|------|------|
+| 只读 | `read` | 仅可在线阅读，不可复制/下载 |
+| 反馈 | `feedback` | 可提交反馈意见（文字/评分），不可修改文档 |
+| 评论 | `comment` | 可在文档段落级别发表评论 |
+| 下载 | `download` | 可下载 Markdown 原文或 PDF |
+| 修改建议 | `suggest` | 可提交修改建议（生成 Git PR），需作者审核 |
+
+### 5.3 权限配置方式
+
+#### 方式一：Front Matter 声明（文档级）
+
+在 Markdown 文件头部的 YAML Front Matter 中声明权限：
+
+```yaml
+---
+title: "智能笔 BLE 通信协议"
+access: restricted
+permissions:
+  read: true
+  feedback: true
+  comment: true
+  download: false
+  suggest: false
+allowed_users:
+  - "138****1234"
+  - "group:经销商"
+allowed_groups:
+  - "经销商"
+  - "教育局客户"
+usage:
+  max_views: 50
+  expires_at: "2027-03-31"
+---
+```
+
+#### 方式二：目录级继承（`.access.yml` 配置文件）
+
+在 MkDocs 目录下放置 `.access.yml` 文件，该目录及子目录下所有文档继承此权限配置：
+
+```yaml
+# docs/技术方案/.access.yml
+default_access: login
+default_permissions:
+  read: true
+  feedback: true
+  comment: false
+  download: false
+  suggest: false
+overrides:
+  - pattern: "公开简介.md"
+    access: open
+  - pattern: "机密/**"
+    access: confidential
+```
+
+#### 方式三：管理后台配置（全局策略）
+
+管理员在 Web 后台按**仓库、目录路径通配符、标签**维度设置批量策略：
+
+| 策略维度 | 示例 | 说明 |
+|---------|------|------|
+| 仓库 | `com-shware-doc` | 整个仓库默认 `login` |
+| 目录通配符 | `*/对外文档/**` | 所有仓库的「对外文档」目录 `open` |
+| 标签 | `tag:机密` | 含「机密」标签的文档 `confidential` |
+| 单文档 | `SmartPen/硬件设计/xxx.md` | 指定文档覆盖策略 |
+
+### 5.4 权限优先级（从高到低）
+
+```
+1. 黑名单 → 403 拒绝（最高优先）
+2. 单文档 Front Matter 声明
+3. 管理后台单文档策略
+4. 目录级 .access.yml
+5. 管理后台目录通配符策略
+6. 管理后台标签策略
+7. 管理后台仓库默认策略
+8. 系统默认（open）
+```
+
+### 5.5 避免登录繁杂的设计策略
+
+为满足"颗粒度到单文档但不逐页登录"的要求，采用以下策略：
+
+| 策略 | 机制 |
+|------|------|
+| 会话全站有效 | 登录一次后 7 天内访问同站点任何受控文档均免再次登录 |
+| 目录级继承 | 同目录下文档共享权限配置，无需逐文件设置 |
+| 公开文档零感知 | `open` 级文档不注入任何认证逻辑，加载速度等同纯静态页 |
+| 延迟认证 | 用户浏览目录/搜索时不触发登录，点击具体受控文档才弹浮层 |
+| 渐进式体验 | 受控文档先展示标题+摘要（前 3 段），余下内容模糊化并提示登录 |
+
+---
+
+## 六、文档使用控制
+
+### 6.1 阅读次数限制
+
+通过 Front Matter 或管理后台配置 `max_views` 参数：
+
+```yaml
+usage:
+  max_views: 50         # 该文档最多可被在线阅读 50 次
+  max_views_per_user: 5  # 每个用户最多阅读 5 次
+```
+
+**计数规则**：
+
+| 规则 | 说明 |
+|------|------|
+| 计数触发 | 用户打开文档页面并停留超过 5 秒才计为 1 次有效阅读 |
+| 去重窗口 | 同一用户 30 分钟内多次打开同一文档仅计 1 次 |
+| 存储位置 | PostgreSQL `doc_view_logs` 表 |
+| 缓存加速 | Redis 缓存当前计数，每 10 分钟同步至数据库 |
+
+### 6.2 有效期限制
+
+```yaml
+usage:
+  expires_at: "2027-03-31"    # 到期后文档不可访问
+  available_from: "2026-06-01" # 生效日期（可选）
+```
+
+**到期处理策略**：
+
+| 场景 | 行为 |
+|------|------|
+| 到期后匿名访问 | 返回"文档已过期"提示页 |
+| 到期后登录访问 | 返回"文档已过有效期，请联系管理员"提示页 |
+| 管理员访问 | 不受限制，可正常查看 |
+| 即将到期提醒 | 到期前 7 天向管理员发送 MsgHub 通知 |
+
+### 6.3 使用控制数据表
+
+```
+doc_usage_config
+├── doc_id          VARCHAR     文档唯一标识（仓库 + 路径）
+├── max_views       INT         总阅读次数上限（NULL = 不限）
+├── max_views_user  INT         单用户阅读次数上限（NULL = 不限）
+├── available_from  DATE        生效日期（NULL = 即时生效）
+├── expires_at      DATE        到期日期（NULL = 永不过期）
+└── updated_at      TIMESTAMP
+
+doc_view_logs
+├── id              UUID        主键
+├── doc_id          VARCHAR     文档标识
+├── user_id         UUID        用户 ID（匿名用户为 NULL）
+├── fingerprint     VARCHAR     浏览器指纹（匿名用户标识）
+├── ip_address      INET        访问 IP
+├── user_agent      TEXT        浏览器 UA
+├── duration_sec    INT         停留时长（秒）
+├── viewed_at       TIMESTAMP   访问时间
+└── is_counted      BOOLEAN     是否计入有效阅读
+```
+
+---
+
+## 七、防爬虫策略
+
+### 7.1 多层防护体系
+
+```plantuml
+@startuml
+title 防爬虫多层防护体系
+
+start
+:外部请求;
+
+partition "第一层 - Nginx 基础防护" {
+  :IP 频率限制;
+  :User-Agent 黑名单;
+  :robots.txt 声明;
+}
+
+if (命中拦截?) then (是)
+  :返回 429 / 403;
+  stop
+else (否)
+endif
+
+partition "第二层 - AntiBot 行为检测" {
+  :浏览器指纹验证;
+  :JS 执行检测;
+  :鼠标/滚动行为分析;
+}
+
+if (疑似爬虫?) then (是)
+  :验证码挑战;
+  stop
+else (否)
+endif
+
+partition "第三层 - 内容保护" {
+  :关键内容异步加载;
+  :文本防选择/防复制;
+  :动态水印注入;
+}
+
+:返回受保护的文档内容;
+
+partition "第四层 - 智能封禁（后台异步）" {
+  :分析访问行为模式;
+  if (触发封禁条件?) then (是)
+    :自动加入黑名单;
+  else (否)
+  endif
+}
+
+stop
+@enduml
+```
+
+### 7.2 各层策略详情
+
+#### 第一层：Nginx 基础防护
+
+| 策略 | 配置 | 说明 |
+|------|------|------|
+| IP 频率限制 | `limit_req_zone` 10 次/秒 | 单 IP 超限返回 429 |
+| 并发连接限制 | `limit_conn` 20 连接/IP | 超限返回 503 |
+| User-Agent 黑名单 | 拦截 curl/wget/scrapy/python-requests 等 | 返回 403 |
+| robots.txt | 仅允许搜索引擎索引 `open` 级文档路径 | 受控文档 Disallow |
+
+#### 第二层：AntiBot 行为检测
+
+| 策略 | 实现 | 说明 |
+|------|------|------|
+| JS 执行检测 | 页面注入一段 JS，执行后生成 Token 回传 | 无 JS 执行能力的爬虫无法通过 |
+| 浏览器指纹 | FingerprintJS 生成指纹，与 User-Agent 交叉验证 | 指纹缺失或矛盾判定为爬虫 |
+| 行为分析 | 监测鼠标移动、页面滚动、停留时长 | 零行为数据判定为爬虫 |
+
+#### 第三层：内容保护
+
+| 策略 | 实现 | 适用级别 |
+|------|------|---------|
+| 关键内容异步加载 | 受控文档正文通过 AJAX 请求获取，HTML 源码不含全文 | login / restricted / confidential |
+| CSS 防选择 | `user-select: none` + 右键菜单拦截 | restricted / confidential |
+| 动态水印 | 用户昵称 + 手机号后 4 位半透明水印 | confidential |
+
+#### 第四层：智能封禁
+
+| 触发条件 | 处置 |
+|---------|------|
+| 同一 IP 10 分钟内访问 > 100 个不同文档 | 自动加入 IP 黑名单 24 小时 |
+| 同一用户 1 小时内访问 > 50 个文档 | 账户临时冻结 + 管理员通知 |
+| 被 JS 检测拦截 > 3 次 | IP + 指纹 永久封禁 |
+
+---
+
+## 八、阅读统计
+
+### 8.1 统计维度
+
+基于 Umami 埋点和系统自有日志，提供以下统计维度：
+
+| 维度 | 数据来源 | 说明 |
+|------|---------|------|
+| 页面访问量 (PV) | Umami | 每篇文档的总访问次数 |
+| 独立访客数 (UV) | Umami + 指纹 | 去重后的独立用户数 |
+| 平均阅读时长 | Umami | 用户在文档页面的平均停留时间 |
+| 阅读完成率 | 前端 JS 埋点 | 滚动到文档底部的用户占比 |
+| 用户阅读清单 | doc_view_logs | 每个登录用户阅读过的文档列表 |
+| 文档热度排行 | 聚合计算 | 按 PV / UV 排序的文档热度榜 |
+| 时段分布 | Umami | 按小时/日/周分布的访问趋势 |
+| 来源渠道 | Umami (Referrer) | 文档从哪些渠道/页面被引流 |
+
+### 8.2 管理看板
+
+管理员可在 Web 后台查看以下看板：
+
+| 看板 | 内容 |
+|------|------|
+| 文档总览 | 各级别文档数量、总 PV/UV、活跃用户数 |
+| 文档详情 | 单篇文档的访问趋势、用户列表、阅读时长分布 |
+| 用户画像 | 单用户阅读历史、偏好标签、活跃时段 |
+| 权限使用 | 各文档的已用/剩余阅读次数、即将到期提醒 |
+| 安全日志 | 爬虫拦截记录、黑名单触发记录、异常访问报警 |
+
+### 8.3 自定义埋点
+
+在 MkDocs 主题模板中注入以下自定义事件：
+
+```javascript
+// 页面加载时
+umami.track('doc_view', {
+  doc_id: '{{ doc_id }}',
+  access_level: '{{ access_level }}',
+  user_type: '{{ user_type }}'  // anonymous / registered / whitelist
+});
+
+// 阅读完成时（滚动到底部）
+window.addEventListener('scroll', function() {
+  if (isScrolledToBottom()) {
+    umami.track('doc_complete', { doc_id: '{{ doc_id }}' });
+  }
+});
+
+// 反馈提交时
+function onFeedbackSubmit(rating, content) {
+  umami.track('doc_feedback', {
+    doc_id: '{{ doc_id }}',
+    rating: rating
+  });
+}
+```
+
+---
+
+## 九、MkDocs Guard 技术实现
+
+### 9.1 架构模式：Nginx auth_request
+
+MkDocs Guard 采用 **Nginx `auth_request` 子请求模式**，不修改 MkDocs 静态文件：
+
+```
+# Nginx 配置片段
+location /docs/ {
+    auth_request /auth/check;
+    auth_request_set $auth_user $upstream_http_x_auth_user;
+    auth_request_set $auth_role $upstream_http_x_auth_role;
+
+    # 认证通过后，代理到 MkDocs 静态文件
+    proxy_pass http://127.0.0.1:8001;
+
+    # 注入用户信息到响应头（供前端 JS 使用）
+    add_header X-Auth-User $auth_user;
+    add_header X-Auth-Role $auth_role;
+}
+
+location = /auth/check {
+    internal;
+    proxy_pass http://127.0.0.1:3100/guard/check;
+    proxy_set_header X-Original-URI $request_uri;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header Cookie $http_cookie;
+}
+```
+
+### 9.2 Guard 服务端逻辑
+
+```
+MkDocs Guard (Node.js, 端口 3100)
+├── GET /guard/check          — Nginx auth_request 回调
+│     ├─ 解析 X-Original-URI 获取文档路径
+│     ├─ 查询文档权限级别（Redis 缓存 → PostgreSQL）
+│     ├─ open 级别 → 200 放行
+│     ├─ 检查 Cookie 中的会话 Token
+│     ├─ 有效会话 → 调用 PermEngine 校验 → 200/403
+│     └─ 无会话 + 非 open → 401（触发前端弹登录浮层）
+├── POST /guard/login/wechat  — 微信扫码登录回调
+├── POST /guard/login/sms     — 短信验证码登录
+├── POST /guard/logout        — 登出
+└── GET  /guard/session       — 查询当前会话状态
+```
+
+### 9.3 PermEngine 权限引擎
+
+```
+PermEngine (Node.js 模块)
+├── checkAccess(userId, docPath)
+│     ├─ 检查用户黑名单 → blocked 则拒绝
+│     ├─ 加载文档权限配置（优先级链）
+│     ├─ open → 放行
+│     ├─ open_once → 查浏览器指纹记录
+│     ├─ login → 已登录即放行；白名单用户放行
+│     ├─ restricted → 检查 allowed_users / allowed_groups
+│     ├─ confidential → 检查显式授权 + 写审计日志
+│     └─ 检查 usage 限制（次数 + 日期）
+├── loadDocConfig(docPath)
+│     ├─ 查 Redis 缓存
+│     ├─ 缓存未命中 → 查 PostgreSQL
+│     ├─ 合并优先级链（Front Matter > 单文档 > 目录 > 仓库）
+│     └─ 写入 Redis 缓存（TTL 5 分钟）
+└── getPermissions(userId, docPath)
+      └─ 返回用户在该文档上的操作权限集合
+```
+
+### 9.4 数据库完整设计
+
+```plantuml
+@startuml
+skinparam componentStyle rectangle
+title 用户阅读管理系统 - 数据表关系
+
+rectangle "users\n用户表" as Users {
+  rectangle "id, phone, wechat_openid\nnickname, role, list_type\ngroup_id, status" as UF
+}
+
+rectangle "user_groups\n用户组表" as Groups {
+  rectangle "id, name, description" as GF
+}
+
+rectangle "user_group_members\n组成员表" as Members {
+  rectangle "user_id, group_id" as MF
+}
+
+rectangle "doc_access_policies\n文档权限策略表" as Policies {
+  rectangle "id, doc_pattern, access_level\npermissions, allowed_users\nallowed_groups, priority" as PF
+}
+
+rectangle "doc_usage_config\n使用控制表" as Usage {
+  rectangle "doc_id, max_views\nmax_views_user\navailable_from, expires_at" as UGF
+}
+
+rectangle "doc_view_logs\n阅读日志表" as Logs {
+  rectangle "id, doc_id, user_id\nfingerprint, ip, duration\nviewed_at" as LF
+}
+
+rectangle "antibot_blocklist\n封禁记录表" as Block {
+  rectangle "id, ip, fingerprint\nuser_id, reason\nblocked_until" as BF
+}
+
+Users -right-> Members
+Groups -down-> Members
+Users -down-> Logs
+Policies -down-> Usage
+@enduml
+```
+
+---
+
+## 十、管理后台
+
+### 10.1 功能模块
+
+管理后台作为 MkDocs Guard 的 Web 管理界面，提供以下功能：
+
+| 模块 | 功能 |
+|------|------|
+| 用户管理 | 查看用户列表、搜索、设置白名单/黑名单、编辑用户组 |
+| 权限管理 | 配置文档访问策略、目录级/标签级批量授权、授权用户/组 |
+| 使用控制 | 设置文档阅读次数上限、有效期、查看用量 |
+| 阅读统计 | 文档热度排行、用户阅读画像、渠道来源分析 |
+| 安全中心 | 爬虫拦截日志、封禁记录管理、异常告警配置 |
+| 系统配置 | 短信网关配置、微信开放平台参数、会话策略调整 |
+
+### 10.2 管理后台技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 前端框架 | React + Ant Design |
+| 后端 API | Node.js + Express（与 Guard 同进程） |
+| 认证 | Keycloak SSO（admin 角色） |
+| 部署 | 与 MkDocs Guard 同容器，路由 `/admin/` |
+
+---
+
+## 十一、部署方案
+
+### 11.1 服务清单
+
+| 服务 | 端口 | 部署位置 | 说明 |
+|------|------|---------|------|
+| Nginx | 443 | 互联网应用服务器 | SSL 终止 + auth_request |
+| MkDocs 静态站 | 8001 | 互联网应用服务器 | 由 DocForge 自动构建 |
+| MkDocs Guard | 3100 | 互联网应用服务器 | 认证网关 + 权限引擎 + 管理后台 |
+| Keycloak | 8080 | 互联网应用服务器（已有） | SSO 认证中心 |
+| Redis | 6379 | 互联网应用服务器 | 会话 + 缓存 + 限流 |
+| PostgreSQL | 5432 | 私有云（已有） | 用户数据 + 权限策略 + 日志 |
+| Umami | 3000 | 互联网应用服务器（已有） | 统计分析 |
+
+### 11.2 Docker Compose 部署
+
+```yaml
+services:
+  mkdocs-guard:
+    image: node:20-alpine
+    ports:
+      - "3100:3100"
+    environment:
+      - DATABASE_URL=postgresql://guard:***@db:5432/mkdocs_guard
+      - REDIS_URL=redis://redis:6379/2
+      - KEYCLOAK_URL=https://sso.writech.cn
+      - KEYCLOAK_REALM=writech
+      - WECHAT_APP_ID=${WECHAT_APP_ID}
+      - WECHAT_APP_SECRET=${WECHAT_APP_SECRET}
+      - SMS_ACCESS_KEY=${SMS_ACCESS_KEY}
+      - SMS_ACCESS_SECRET=${SMS_ACCESS_SECRET}
+    depends_on:
+      - redis
+
+  mkdocs-site:
+    image: nginx:alpine
+    ports:
+      - "8001:80"
+    volumes:
+      - ./site:/usr/share/nginx/html:ro
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+volumes:
+  redis_data:
+```
+
+---
+
+## 十二、实施路线图
+
+| 阶段 | 时间 | 任务 | 交付物 |
+|------|------|------|--------|
+| **一期：基础认证** | 第 1-3 周 | MkDocs Guard + Nginx auth_request 集成；微信扫码登录；短信验证码登录；会话管理 | 用户可通过微信/短信登录访问受控文档 |
+| **二期：权限引擎** | 第 4-6 周 | PermEngine 开发；Front Matter 权限解析；目录级 `.access.yml` 继承；白名单/黑名单管理 | 文档可按级别和用户/组授权 |
+| **三期：使用控制** | 第 7-8 周 | 阅读次数限制；有效期管理；渐进式体验（摘要预览 + 模糊化） | 文档使用可按次数和时间控制 |
+| **四期：防爬虫** | 第 9-10 周 | AntiBot 四层防护部署；智能封禁规则；内容异步加载 | 爬虫有效拦截 |
+| **五期：统计与后台** | 第 11-13 周 | Umami 自定义埋点；管理后台开发；阅读统计看板；安全日志 | 管理员可视化管理全部功能 |
+| **六期：优化上线** | 第 14-15 周 | 性能调优；安全审计；用户体验打磨；正式上线 | 系统全功能投入运营 |