Web 开发计划
本文档用于记录 Wiki Web 可视化系统的开发计划和进度。后续每完成一项并自测通过后，在对应任务前打勾。
1、开发目标
第一版目标是把 wiki/ 中的 Markdown、截图和图表可视化为一个好读、好搜、好导航的静态 Web Wiki。英文学习版加入后，站点同时展示 wiki/cn/ 中文源内容和 wiki/en/ 下的 en-US 学习内容。
第一版不做后台、不做数据库、不做在线编辑、不做用户权限。wiki/ 仍然是唯一知识库源头，web/ 只负责展示。
2、技术路线
| 项目 | 选择 |
|---|---|
| Web 框架 | VitePress |
| 中文知识库源目录 | wiki/cn/ |
| 英文学习版源目录 | wiki/en/ |
| Web 代码目录 | web/ |
| 项目级脚本目录 | scripts/ |
| 构建产物 | web/.vitepress/dist/ |
| 部署方式 | 静态文件部署，后续可用 Nginx 或服务器静态目录 |
3、目录边界
text
core-bank/
├── wiki/ # 知识库源内容，含 cn 与 en
├── web/ # Web 展示系统代码
├── scripts/ # 项目级/wiki 级自动化脚本
└── project-docs/ # 项目说明、规范、计划和部署文档原则：
wiki/cn/是中文知识库源头，不被 Web 构建流程改写。wiki/en/是英文学习版源头，使用 en-US 和美式银行/金融科技表达。web/可以生成临时内容副本，但不能成为业务知识源头。scripts/放服务整个项目或wiki/的脚本。- 每次开发后都要检查本地链接、图片引用和 Web 构建。
4、阶段计划
阶段 0：开发前确认
- [x] 确认当前
wiki/内容结构稳定。 - [x] 确认
web/当前没有历史代码或冲突文件。 - [x] 确认
scripts/当前没有历史脚本或冲突文件。 - [x] 确认本地 Markdown 链接检查通过。
自测标准：
- [x]
wiki/可独立阅读。 - [x]
project-docs/中目录规范和维护规范可正常打开。 - [x] 本地链接检查无失效链接。
阶段 1：搭建 VitePress 基础骨架
- [x] 在
web/初始化 VitePress 所需文件。 - [x] 创建
web/package.json。 - [x] 创建
web/.vitepress/config.ts。 - [x] 创建基础首页
web/index.md。 - [x] 配置基础导航。
- [x] 配置基础搜索。
- [x] 配置 Mermaid 支持方案。
自测标准：
- [x]
npm install成功。 - [x]
npm run dev能启动本地预览。 - [x]
npm run build能成功构建。 - [x] 首页可以正常访问。
阶段 2：建立 Wiki 内容同步机制
- [x] 设计
wiki/到web/的同步目标目录。 - [x] 编写同步脚本，复制 Markdown 内容。
- [x] 编写同步脚本，复制或映射图片资产。
- [x] 确保同步过程不修改
wiki/源文件。 - [x] 将生成目录加入 Web 侧忽略规则。
计划脚本：
text
scripts/sync-wiki-content.mjs自测标准：
- [x] 执行同步脚本后，Web 目录中出现可渲染的 Wiki 内容。
- [x]
wiki/源文件没有被修改。 - [x] 图片路径在 Web 预览中可访问。
- [x] 重复执行同步脚本结果稳定。
阶段 3：自动生成导航和侧边栏
- [x] 编写目录扫描逻辑。
- [x] 根据
wiki/目录自动生成侧边栏。 - [x] 支持中文目录和中文文件名。
- [x] 支持按目录顺序排序。
- [x] 将
wiki/00-总览、01-存款核心、03-通用核心能力等映射到导航。
计划脚本：
text
scripts/build-sidebar.mjs自测标准：
- [x] 左侧侧边栏能展示 Wiki 目录。
- [x] 点击侧边栏可以打开对应页面。
- [x] 中文路径链接正常。
- [x] 新增 Markdown 后重新生成侧边栏能自动出现。
阶段 4：Markdown 渲染体验优化
- [x] 确保表格样式适合阅读。
- [x] 确保图片正常显示。
- [x] 增加图片点击放大能力。
- [x] 确保 Mermaid 图正常渲染。
- [x] 增加 Mermaid 图点击放大、缩放和拖拽查看能力。
- [x] 优化代码块、引用块和目录锚点样式。
- [x] 确保页面右侧目录可用。
自测标准：
- [x] 页面截图能正常显示。
- [x] 至少抽查 5 个含图片页面。
- [x] 至少抽查 3 个含 Mermaid 的页面。
- [x] 表格在桌面端可读。
- [x] 页面目录锚点点击正常。
阶段 5：设计知识库首页
- [x] 创建 Web 首页内容结构。
- [x] 放置主要入口：学习路线、存款核心柜面、专题 Wiki、术语表、项目规范。
- [x] 首页突出学习路径和核心入口。
- [x] 避免营销式首页，直接作为学习入口。
自测标准：
- [x] 首页能快速进入核心柜面总览。
- [x] 首页能快速进入专题索引。
- [x] 首页能快速进入术语表。
- [x] 首页能快速进入项目规范。
阶段 6：项目级校验脚本
- [x] 编写 Markdown 本地链接检查脚本。
- [x] 检查图片引用是否存在。
- [x] 检查同步后的 Web 内容是否可构建。
- [x] 将校验命令写入
package.json或项目说明。
计划脚本：
text
scripts/check-wiki-links.mjs自测标准：
- [x] 能输出 Markdown 文件数量。
- [x] 能输出本地链接数量。
- [x] 能输出失效链接清单。
- [x] 当前项目检查结果为 0 个失效链接。
阶段 7：构建和部署准备
- [x] 确认
npm run build成功。 - [x] 确认构建产物目录为
web/.vitepress/dist/。 - [x] 编写部署说明。
- [x] 说明 Nginx 或静态文件部署方式。
- [x] 说明后续更新流程：更新
wiki/-> 同步 -> 构建 -> 部署。
新增文档：
text
project-docs/部署说明.md自测标准：
- [x] 构建产物可用静态服务器打开。
- [x] 刷新页面不出现明显路由问题。
- [x] 图片、搜索、侧边栏在构建产物中可用。
5、命令规划
后续计划形成这些命令：
text
npm run sync
npm run check
npm run dev
npm run build含义：
| 命令 | 作用 |
|---|---|
npm run sync | 从 wiki/ 同步内容到 Web 可渲染目录。 |
npm run check | 检查 Markdown 链接和图片引用。 |
npm run dev | 启动本地预览。 |
npm run build | 构建静态站点。 |
6、第一版验收清单
- [x]
wiki/内容不被破坏。 - [x]
web/可以本地启动。 - [x] 所有 Markdown 页面可以访问。
- [x] 现有截图可以正常展示。
- [x] Mermaid 图可以正常展示。
- [x] 左侧侧边栏可用。
- [x] 搜索可用。
- [x] 本地链接检查通过。
- [x]
npm run build成功。 - [x] 构建产物可以静态访问。
7、每次恢复开发时先检查
中断后重新开始开发时，先执行以下人工检查：
- 打开本文档，确认最后一个已完成任务。
- 查看
git diff或当前目录变更，确认是否有未完成文件。 - 运行链接检查。
- 如果 Web 骨架已建立，运行构建检查。
- 从下一个未打勾任务继续。
8、当前状态
当前第一版 Web 可视化系统已完成。
已完成：
- [x] 项目已拆分为
wiki/、web/、scripts/、project-docs/。 - [x]
wiki/已作为知识库源目录。 - [x]
web/已建立 VitePress 站点。 - [x]
scripts/已建立同步、侧边栏生成和链接检查脚本。 - [x]
wiki/en/已建立英文学习版骨架和首批样板页。 - [x] 项目目录说明和 Wiki 目录规范已建立。
- [x] 部署说明已建立。
- [x]
npm run check通过，当前 0 个失效本地链接。 - [x]
npm run build通过，构建产物位于web/.vitepress/dist/。
下一步：
- [x] 等待 review 本开发计划。
- [x] review 通过后，从阶段 0 开始执行。
- [x] 从阶段 1 开始搭建 VitePress 基础骨架。
- [ ] 根据实际试用反馈继续优化站点体验和知识库内容。