Rebuild guidance wiki as a unified SaaS workspace

docs/linked-guidance/acceptance.md

@@ -1,33 +1,38 @@
-# 交付验收清单
+# 交付验收记录
 
-这是要求与证据的对照表，不能用提交、PR 或测试意图代替实际验收。所有 PR 由用户手动合并。构建只使用 ces-control，网页只在指定服务器验收。
+所有 PR 由用户手动合并，只有 main 更新触发 ces-control CI/CD。用户后续明确允许在当前项目目录内本地开发和测试；本次 SaaS 重构使用独立工作区，结束后清理自建临时依赖、预览和构建产物。
 
-| 用户要求 | 应验证的行为 | 当前证据 / 待办 |
-| --- | --- | --- |
-| 研究 LLM Wiki | 能指出原始提案与本项目新增设计的边界 | protocol.md 引用 Karpathy 原始 gist；XML、条件链接和版本规则为本项目提案 |
-| SkillHub 逐页截图与设计分析 | 首页、目录、详情各标签、作者、登录、发布入口具备截图和观察记录 | 主 chat 已截取首页首屏与下半屏、目录、概述、文件、版本、评论、评测、登录、作者及发布限制；另补插件、SkillPay、大赛、使用指南、专家包列表/详情与企业专区首屏；截图目前在 chat 中，窄屏参考待补 |
-| 可独立使用的文档 | 单篇内容具有适用条件、正文和步骤，不要求安装包 | catalog.ts 与 /guide 原型；真实文档实现已随 PR #9 合入，待 CI 与运行时验证 |
-| 按链接寻找帮助 | 条件、关系、精确版本可读，缺失目标明确，背景不升级权限 | 协议及静态阅读页；真实文档预览与链接解析待 PR #9 验证 |
-| 新语法 | XML 可序列化、校验、往返，拒绝未知协议与非法实体 | 原型 XML 输出已合入；严格输入与往返测试已随 PR #9 合入，远程执行待确认 |
-| 基于现有 wiki 改造 | 沿用 Pages Router 与现有部署数据 | main 已包含新首页原型，实际服务仍在旧版本，等待 CI 部署 |
-| 保留旧小红书 UI | 旧首页和组件仍可在代码库找到，新入口不再使用 | src/legacy/WaterfallHome.tsx 以及原 ExploreFeed/Shell 保留；部署后需检查新首页 |
-| 邮箱与密码登录并验证邮箱 | 注册发信、验证一次消费、未验证不能登录、会话可注销 | #6/#8 已由用户合并；SMTP 配置、TLS 登录及诊断邮件实际投递已验证；实际注册、验证和登录待部署 |
-| 正常用户与管理员隔离 | 普通邮箱 cookie 无法授权旧管理写 API | auth.test.ts 与 account-integration.ts；最终 main CI 结果仍待确认 |
-| 真实发布与版本 | 已验证作者能发布和更新，其他人不能覆盖，旧版本不变 | PR #9 的 PostgreSQL 所有权/并发/撤下保留测试，待远程执行与网页验证 |
-| 独立开发与人工合并 | 每个方向独立分支和可评审 PR | #6/#7/#8/#9/#11/#12/#13/#14/#15/#16 已由用户合并；#10 待最终证据完善；所有 merge 由用户完成 |
+## 已部署功能的实际证据
 
-## SMTP 验收边界
+2026-10-29，main run 508 / job 556 成功：类型检查、51 项单元测试、生产构建、smoke、真实 PostgreSQL/S3/Chromium 集成、认证检查与生产部署全部通过。验收入口为 http://8.211.154.134:18131/ ，健康检查返回应用版本 `9a603cf87e9b726a566ae68f4f479030e0d02629`。随后 #18 仅修改工作流与说明，没有应用代码变更。
 
-配置已写入服务器 root 所有、0600 权限的 /etc/prompt.env。密码不在仓库、PR 或 CI 日志中。SMTP_SSL 证书验证、连接与认证已通过。2026-10-29 10:23 UTC 发送诊断邮件 LG-SMTP-20261029-01，SMTP 接受；随后通过 Gmail 定向检索确认该编号邮件位于指定测试收件箱的 INBOX、UNREAD、CATEGORY_PERSONAL，非垃圾邮件。诊断邮件不含验证链接；这不证明注册流程已经完成。生产服务尚未因配置而手动重启，等待正常 CI/CD 部署。
+| 用户要求                | 已有证据                                                                                                                                                        |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 研究 LLM Wiki 与新语法  | protocol.md 引用 Karpathy 原始 gist；独立 XML、条件链接、关系、预算与版本规则是本项目提出的实验协议，不声称 Agent 已原生支持                                    |
+| SkillHub 截图与设计分析 | chat 中已截取首页、目录、详情概述/文件/版本/评论/评测、登录、作者、发布限制；补充插件、SkillPay、大赛、使用指南、专家包与企业专区首屏。受限发布编辑器未完整验收 |
+| 单篇可独立采用          | 公开入口 GET/HEAD、Agent 索引、样例与持久文档读取均已验证；不要求安装整个集合                                                                                   |
+| 条件链接与固定版本      | 实际预览解析 source-trust 固定版本；缺失版本返回 404；XML 条件和标签往返已验证                                                                                  |
+| 邮箱、密码、邮箱验证    | 指定真实收件箱收到注册邮件并确认位于 INBOX；未验证登录 401，验证一次 200、重复消费 400，验证后登录 200                                                          |
+| 普通账户权限隔离        | 普通邮箱会话调用旧管理员写 API 返回 401；匿名预览 401，跨来源写入 403                                                                                           |
+| 真实发布与版本          | 实际发布 v1/v2，旧版本正文保持不变，旧版本号重复发布返回 409；目录返回最新版本                                                                                  |
+| 撤下与退出              | 验收文档已撤下，最新入口 404、固定历史版本 200、公开目录不再列出；注销后会话为空                                                                                |
+| 保留旧界面              | src/legacy/WaterfallHome.tsx 与旧 Shell/ExploreFeed 保留，新入口不再使用旧首页；旧内容路由仍在集成测试覆盖范围内                                                |
+| 独立分支、人工合并      | #6–#18 由用户合并；当前 SaaS 重构使用 codex/wiki-saas，交付 PR 等待用户手动合并                                                                                 |
 
-## 当前未完成工作
+## 邮件与敏感信息
 
-补齐窄屏参考及验收截图；完成当前 main 的远程 CI（仅 main 更新触发，PR/手动不触发）；其余 PR 由用户手动合并；等待正常部署；在服务器上测试邮箱注册验证与文档发布、编辑、精确版本及关联阅读；记录桌面与窄屏效果。只有运行时证据齐全后才认定完整交付。
+SMTP 运行时配置位于服务器 root 所有、0600 权限的 /etc/prompt.env。密码、注册验证令牌与测试账户密码不进入仓库、PR、截图或报告。早期 SMTP 诊断邮件只证明投递；上述后续真实注册验证才证明完整账户流程。验收文档已撤下；固定历史版本按产品约定保留。
 
-## Agent 发现入口
+## 本次 SaaS 视觉重构
 
-PR #12 将 llms.txt 与 /agent/index.md、/index.md 导向独立指导文档，索引同时包含持久化用户文档与示例，并只公开 GET/HEAD。测试覆盖发现入口、预算与固定版本链接；已由用户合并；远程 CI 和部署验收尚未完成。
+详细设计参考与页面规范见 ../wiki-saas/DESIGN.md。重构范围为公共外壳、目录、社区/我的文档、阅读、账户、编辑与协议页。
 
-## 最近的 main CI 证据
+本地独立预览中的 UI 回归使用明确的 API 测试夹具，覆盖 URL 筛选恢复、清除、键盘标签导航、阅读/XML/版本、账户模式与密码可见性、发布登录门槛、表单错误保留输入、校验预览、发布输入规范化、现有文档编辑、XML 往返、移动端导航关闭及无横向溢出。该测试不代替上述真实数据库、SMTP 和权限验证；已接入 main 集成测试流程。
 
-run 504（main 1925d15）类型检查、50 项单元测试与生产构建通过，随后 smoke 因缺管理员配置返回 503 而失败；不代表完整 CI 通过。PR #16 仅给绑定回环地址的 smoke 子进程设置显式测试模式，已由用户合并。main 254ac62 的后续检查仍待完成；未在本机编译，未手动触发构建。
+类型检查、51 项单元测试、生产构建与 standalone smoke 已通过。生产构建保留 preview.ts 动态文件跟踪的既有警告。
+
+实际检查了 1440px 桌面目录/阅读/账户/编辑器，以及 390px 手机目录/阅读/XML 编辑器/协议截图。原生桌面浏览器当时因 Mac 锁定不可操作，截图由项目隔离的无头 Chromium 回归测试生成，未将其表述为线上部署验收。
+
+## 剩余交付边界
+
+SaaS 改版尚未合并和部署。PR 就绪后等待用户手动合并，届时由正常 main CI/CD 运行真实存储集成与部署，再在指定服务器复核新页面。不得把旧版本的成功 CI 或本地夹具截图称为新版线上验证。

docs/wiki-saas/DESIGN.md

@@ -0,0 +1,46 @@
+# 织页 SaaS 界面重构
+
+用户明确要求以正式 SaaS 产品为标准，重做当前视觉；保留独立指导文档、条件链接、固定版本与邮箱账户的功能。本次本地开发测试获用户在“重构 Studio 设计与无限画布”chat 的直接授权，最终清理自建临时产物，不删除用户原有文件。所有 main 合并仍由用户完成。
+
+## 设计参考与取舍
+
+- https://github.com/bergside/awesome-design-skills ：阅读 professional、shadcn、clean 与 minimal 的说明，采用语义令牌、明确状态、统一间距和键盘可达性。professional 当前示例的商店品牌与黄色不适合知识工作台，不直接复制其品牌色。
+- https://ui.shadcn.com/docs/components/sidebar ：参考侧栏的导航分组、账户区与移动端抽屉结构，使用现有 React/CSS Modules 实现，不引入新的组件库依赖。
+- https://linear.app/features ：参考工作型产品的信息层级和克制的工具界面，而非复制营销首页。
+- 原 SkillHub、Hugging Face、GitHub 研究继续用于文档发现、单篇读取、来源与版本的组织。集合不会变成强制加载单位。
+
+## 视觉基础
+
+背景 #F8F9FC，面板 #FFFFFF，正文 #182230，次级文字 #667085，分隔线 #EAECF0，主色 #4F46E5。错误/成功颜色只表达真实反馈。间距 4/8/12/16/24/32，常规正文 14px，阅读正文 15–16px，页面标题 28px。按钮圆角 8px，面板圆角 12px；不使用装饰性渐变、低对比文字、虚假图表或无行为控件。
+
+## 页面与实现
+
+1. 应用外壳：左侧工作区、文档导航、资源和真实账户状态；顶部面包屑与创建入口；移动端可关闭、可键盘操作的导航。
+2. 目录：首页与社区/我的文档复用搜索、类型/来源筛选、排序、URL 恢复、按作者查询的我的文档（在数据库限制最近 100 篇前筛选作者）、加载/错误/空状态与文档行；数量来自实际内容。
+3. 阅读页：摘要、适用条件、正文、步骤、检查项、条件链接、固定版本和 XML；读取地址可复制，作者操作具有明确反馈。
+4. 发布页：按内容分组的表单，易读的条件链接编辑，结构化/XML 模式、真实校验预览与版本发布状态；普通用户不用手动拼接账户 UUID。
+5. 账户页：统一表单、注册/登录/重发验证、验证码链接状态、已验证会话和退出反馈；不展示不存在的重置密码、OAuth 或计费入口。
+6. 协议页：与产品一致的文档阅读布局，保留协议的实验状态与权限边界。
+
+## 验证
+
+在独立工作区本地运行类型、相关单测与构建，真实数据行为沿用现有隔离集成检查。通过可用的浏览器入口查看桌面与窄屏页面，检查导航、搜索/重置、表单、长 ID/链接、键盘焦点和错误反馈。最终提交完整改版 PR，等待用户手动合并后才触发 ces-control 部署；不以开发预览代替正式部署。
+
+## 本次检查结果
+
+- Node 24：类型检查、51 项单元测试、生产构建与 standalone smoke 通过。构建保留 preview.ts 动态文件跟踪的既有警告。
+- 项目 UI 回归使用隔离 API 夹具，覆盖作者筛选、筛选 URL 恢复、空状态、键盘标签、阅读/XML/版本、账户模式、密码显示、发布门槛、错误保留输入、预览、规范化发布和结构化/XML 往返。
+- 已检查 1440px 桌面与 390px 手机截图；新版真实 PostgreSQL/S3 集成尚待用户手动合并后的 main CI。此前已部署应用的真实邮件、账户、版本与权限证据见 ../linked-guidance/acceptance.md，不能替代新改版的部署验收。
+- 可在运行独立预览后执行：`WORKSPACE_TEST_URL=http://127.0.0.1:3217 CHROMIUM_PATH=<chromium可执行文件> node --import tsx --test tests/guidance-workspace.test.ts`。设置 WORKSPACE_SCREENSHOT_DIR 可生成截图。该用例也随原有集成测试在 CI 隔离栈运行，未添加 PR 或手动 CI 触发器。
+- 目录仅展示最近 100 篇社区文档；我的文档先在数据库筛选作者，再应用此上限。搜索与类型筛选作用于当前已加载目录，不声称全站无限搜索。
+
+## 可审阅截图
+
+以下为最终生产模式预览截图。社区条目、作者邮箱和编辑器内容均为明确的回归测试夹具，不是生产用户数据；它们只证明 UI 状态，不证明真实邮件投递或持久化发布。
+
+- [桌面目录](screenshots/directory.png)
+- [桌面阅读](screenshots/reader.png)
+- [账户注册](screenshots/account.png)
+- [结构化编辑器](screenshots/editor.png)
+- [手机目录](screenshots/mobile-directory.png)
+- [手机阅读](screenshots/mobile-reader.png)