wiki/CLAUDE.md

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> 标签内），按分类分组，每个分类是一个对象：

{ dir: "分类名称", icon: "🔐", desc: "分类描述", color: "pink",
  items: [
    { path: "相对路径/文件.html", title: "文档标题", desc: "文档描述", date: "2026-05-08" }
  ]}

新增文档：在对应分类的 items 数组中添加条目。如果分类不存在，新建一个分类对象。

颜色映射（wikiData 中 color 字段的语义约定，颜色值直接写在各分类条目中）：

• pink — 深度分析、政策解读、政务行业
• blue — 工程指南、数据平台、医疗健康
• mint — 调研研究、商业分析、配送到家
• lavender — 参考资源、AI 工具、关于作者

新增分类时选择语义匹配的颜色，颜色样式通过 card-badge 类渲染。

页面特性

• 侧栏导航（桌面端）+ 抽屉导航（移动端 ≤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, #0078D4 0%, #2B88D8 100%)）
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 中的 Microsoft Fluent 2 / Windows 11 设计规范（2026-06 从 Ant Design v5 迁移）。关键约束：

• 配色方案：品牌色 #0078D4（Fluent 2 Communication Blue），功能色（成功 #107C10、警告 #FF8C00、错误 #FF4D4F）
• 字体规范：基准字号 14px，行高 20px，字体族 Segoe UI Variable Text → Segoe UI → PingFang SC / Microsoft YaHei 回退；等宽字体 Cascadia Code → Fira Code → SF Mono
• 圆角体系：2px / 4px / 6px / 8px 四级（Fluent 2 更方正）
• 间距体系：旧版 8px 基准保留向后兼容，新版推荐 4px 基准的 --fluent-spacing-* 系列
• 阴影与层级：Fluent 2 Elevation 体系（2/4/8/16/28/64 六级），对应 z-index 100–600
• 材质：Acrylic（亚克力半透明模糊，导航栏用）、Mica（云母，标题栏用）、Smoke（烟雾遮罩，Modal 用）
• 动效：标准缓动 cubic-bezier(0.8, 0.0, 0.2, 1.0)，时长 83ms–333ms 四级
• 主题：index.html 支持亮色/暗色切换（data-theme 属性 + localStorage 键 wiki-theme + prefers-color-scheme: dark 系统偏好）；报告页统一亮色主题

创建新 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 手动调用
ui-ux-pro-max	UI/UX 设计与前端实现辅助	按需调用

deep-research 技能包含参考资料（.claude/skills/deep-research/references/）和调研笔记（research-notes/），执行深度研究时会用到。