zdh
a2eea31c9b
- index.html: section.items空值检查(5处)、移除dead badgeStyle - 物流网报告×3 + AI转型方案×3: 添加background-clip:text兼容Firefox - ai-dev-workflow/v2: 移动端汉堡导航+抽屉覆盖层+返回顶部 - crmeb-deploy-plan: Markdown→HTML+新增NPM私服(Verdaccio)章节 - 需求对比分析报告: 谷歌蓝→品牌蓝, CSS变量化 - ai-dev-workflow-v2: npm私服统一指向npm.ycbat.com(上游阿里云镜像) - CLAUDE.md/design-tokens.md: 修正UI规范与目录文档
140 lines
7.8 KiB
Markdown
140 lines
7.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概览
|
||
|
||
"一人公司开发团队知识库" — 独立开发者的技术沉淀与参考资源站。
|
||
|
||
所有文档以单页 HTML 形式发布，通过根目录 `index.html` 作为导航入口统一展示。
|
||
|
||
## 版本控制
|
||
|
||
`招标投标AI推广应用政策解读/` 子目录有独立的 `.git/`。部署通过 `/remote-sync`（rsync）完成，不走 git push 流程。
|
||
|
||
`.gitignore` 排除了 `.superpowers/`、`qModel/.git/` 以及嵌套子目录的独立 `.git/`。
|
||
|
||
## 目录约定
|
||
|
||
每个子目录遵循 `{主题}/{类型}/` 的层级结构，类型包括 `报告/`、`代码/`、`笔记/` 等。新增主题目录时保持此约定。
|
||
|
||
**例外情况**：
|
||
- `crmeb-mer-graph-report.html` — 位于根目录的单文件报告，不走子目录结构
|
||
- `mcp-services-guide/` — 有独立的 `index.html`，自成一体的子站，不遵循 `报告/` 子目录模式
|
||
- `交互式演示/` — 存放交互式前端 demo（如正四面体 3D 动画），非报告页
|
||
- `中医馆内部管理系统/报告/` 下有 `.md` 需求文档，是唯一在 `报告/` 目录下出现非 HTML 文件的情况（其他 `.md` 文件如 `研发型企业AI转型方案/section-*.md`、`政府审批流解决方案/*.md`、`YqBoot系统说明书/*.md` 位于主题根目录，属规划/源文件，不走报告页模板）
|
||
- `研发型企业AI转型方案/` — `.md` 分段规划文件 + `.pptx`/`.xlsx` 源材料位于主题根目录，HTML 报告在 `报告/` 子目录
|
||
- `政府审批流解决方案/` — `.md` 与 `.html` 并存于主题根目录（非 `报告/` 下）
|
||
- `YqBoot系统说明书/` — `.md` 与 `.html` 并存于主题根目录，另有 `screenshots/` 子目录
|
||
|
||
## 构建与开发
|
||
|
||
本项目是**纯静态 HTML/CSS/JS 文档站**，无构建步骤、无依赖管理、无测试框架。
|
||
|
||
- **查看页面**：直接在浏览器中打开 `index.html` 或任意 HTML 文件
|
||
- **新增文档**：创建 HTML 文件 → 更新 `index.html` 的 `wikiData` 数组（见下文）
|
||
- **部署到远端**：调用 `/remote-sync` 将指定目录增量同步到服务器
|
||
- **更新图谱**：修改代码后运行 `graphify-rs build --path . --output graphify-out --no-llm --update`
|
||
|
||
## 索引页（index.html）
|
||
|
||
`index.html` 是纯 HTML/CSS/JS 单文件 SPA，包含侧栏导航、搜索、暗色模式切换、移动端抽屉菜单。
|
||
|
||
### wikiData 数据结构
|
||
|
||
文档条目通过 `wikiData` 数组管理（在 `<script>` 标签内），按分类分组，每个分类是一个对象：
|
||
|
||
```js
|
||
{ dir: "分类名称", icon: "🔐", desc: "分类描述", color: "pink",
|
||
items: [
|
||
{ path: "相对路径/文件.html", title: "文档标题", desc: "文档描述", date: "2026-05-08" }
|
||
]}
|
||
```
|
||
|
||
**新增文档**：在对应分类的 `items` 数组中添加条目。如果分类不存在，新建一个分类对象。
|
||
|
||
**颜色映射**（`wikiData` 中 `color` 字段与 `badgeStyle` 对象的语义约定）：
|
||
- `pink` — 深度分析、政策解读
|
||
- `blue` — 工程指南、数据平台
|
||
- `mint` — 调研研究、商业分析
|
||
- `lavender` — 参考资源、AI 工具
|
||
|
||
`badgeStyle` 对象已定义对应 CSS 样式（约 `index.html:391`），当前渲染函数未直接渲染 badge，但保留供未来扩展。新增分类时仍需选择语义匹配的颜色并确保 `badgeStyle` 中有对应键。
|
||
|
||
### 页面特性
|
||
|
||
- 侧栏导航（桌面端）+ 抽屉导航（移动端 ≤768px）
|
||
- 实时搜索（按标题、描述、分类名匹配）
|
||
- 暗色/亮色模式切换（localStorage 持久化）
|
||
- 响应式布局：≤768px 隐藏侧栏，显示移动端 chip 筛选栏
|
||
|
||
### JS 运行时架构
|
||
|
||
`<script>` 块中的数据流与状态管理：
|
||
|
||
```
|
||
wikiData (声明式) → allItems (展开数组, 附加 section/icon) → 视图渲染
|
||
```
|
||
|
||
| 变量/函数 | 作用 |
|
||
|-----------|------|
|
||
| `wikiData` | 源数据：按分类分组的文档条目数组 |
|
||
| `allItems` | `wikiData` 展开后的扁平数组，每个条目附加 `section`（分类名）和 `icon` 属性 |
|
||
| `currentView` | 当前视图状态：`'all'` 或某个分类的 `dir` 值 |
|
||
| `searchQuery` | 搜索框绑定值，实时过滤 |
|
||
| `render()` | 分发函数：`currentView === 'all'` 时调用 `renderAllView(main)`，否则 `renderSectionView(main)` |
|
||
| `buildNav(targetEl)` | 构建侧栏/抽屉导航 HTML，绑定点击事件切换视图 |
|
||
| `buildChips()` | 构建移动端 chip 筛选栏 |
|
||
| `setTheme(t)` | 主题切换：设置 `data-theme` 属性 + localStorage 键 `wiki-theme`，同时尊重 `prefers-color-scheme: dark` 系统偏好 |
|
||
|
||
## 报告页模板
|
||
|
||
所有报告页（`{主题}/报告/*.html`）遵循统一的 HTML 模板结构：
|
||
1. `:root` 块复制 CSS 设计 Token（含品牌色、功能色、中性色、圆角、阴影等变量）
|
||
2. 固定 header-bar（sticky top，品牌标题渐变 `linear-gradient(135deg, #1677FF, #722ED1)`）
|
||
3. 单列容器布局，`max-width: 1200px` 居中
|
||
4. Markdown 内容通过内联 HTML 渲染（表格、代码块、列表）
|
||
5. 语言属性 `lang="zh-CN"`
|
||
|
||
创建新报告页时，复制任意现有报告页的 `:root` 和 header 结构作为模板。
|
||
|
||
**报告页有两种变体**：
|
||
1. **基础版**（大多数报告）：固定 header-bar + 单列内容区，结构最简单
|
||
2. **侧栏导航版**（物流网系列报告）：左侧 260px 粘性导航菜单 + 右侧内容区，适合多章节长报告。标题带 `[章节名]` 便于搜索跳转
|
||
|
||
移动端（≤768px）侧栏导航版自动隐藏菜单，显示汉堡按钮触发抽屉导航。
|
||
|
||
**手机适配版**：部分报告有 `_mobile.html` 后缀的独立手机版（卡片式折叠布局 + 底部标签导航），如 `中医馆内部管理系统_需求分析对比报告_mobile.html`。
|
||
|
||
## UI 设计规范
|
||
|
||
所有页面遵循 `.claude/design-tokens.md` 中的 Ant Design 阿里云风格设计规范。关键约束：
|
||
|
||
- **配色方案**：品牌色 `#1677FF`，功能色（成功 `#52C41A`、警告 `#FAAD14`、错误 `#FF4D4F`）
|
||
- **字体规范**：基准字号 14px，行高 22px，字体族使用系统默认 + 中文字体回退
|
||
- **圆角体系**：`2px / 6px / 8px / 12px` 四级
|
||
- **间距基准**：8px 单位
|
||
- **主题**：仅 `index.html` 支持亮色/暗色切换（通过 `data-theme` 属性 + localStorage 持久化）；报告页统一使用亮色主题，不定义暗色变量。注意 `design-tokens.md` §8 声称"全部页面统一使用亮色主题"与实际不符——索引页的暗色模式是刻意设计，`design-tokens.md` 此处有误
|
||
|
||
创建新 HTML 页面时应直接复用 `:root` CSS 变量块，不要重新定义颜色值。完整规范详见 `.claude/design-tokens.md`。
|
||
|
||
## Graphify 知识图谱
|
||
|
||
本项目已集成 graphify-rs 知识图谱。图谱输出位于 `graphify-out/` 目录（按需生成，默认不存在，需手动构建）。
|
||
|
||
- 架构/代码库问题：如果 `graphify-out/` 存在，先读取 `graphify-out/GRAPH_REPORT.md` 了解核心节点和社区结构
|
||
- 如果 `graphify-out/wiki/index.md` 存在，优先导航该索引而非直接读取原始文件
|
||
- 修改代码文件后，运行 `graphify-rs build --path . --output graphify-out --no-llm --update` 保持图谱更新（AST-only，约 2-5s）
|
||
- graphify-rs 使用手册参考 `graphify-rs使用手册/` 目录
|
||
|
||
## 项目级 Skills
|
||
|
||
`.claude/skills/` 下挂载了项目级技能：
|
||
|
||
| 技能 | 说明 | 触发方式 |
|
||
|------|------|---------|
|
||
| `remote-sync` | rsync 增量同步到远端服务器，自动排除 `node_modules`/`.git` 等 | `/remote-sync` 手动调用 |
|
||
| `deep-research` | 生成格式控制的研究报告，含证据追踪、引用治理和多轮综合 | `/deep-research` 手动调用 |
|
||
|
||
`deep-research` 技能包含参考资料（`.claude/skills/deep-research/references/`）和调研笔记（`research-notes/`），执行深度研究时会用到。
|