# 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/`），执行深度研究时会用到。