# 7. 参与维护

如何修正或扩展这个 Wiki。

## 快速修正（错别字、一句话）

1. 编辑 `docs/` 下对应的 `.md` 文件。
2. 运行 `../.venv/bin/mkdocs build` 重新生成 `../site/zh/` 下的静态站点，或运行 `../.venv/bin/mkdocs serve` 实时预览。
3. 确认满意后提交。

这个 Wiki 只存在于本机：没有远程仓库、没有 CI、没有 Pages。阅读者可以本地打开 `site/index.html`，也可以自己运行 `mkdocs serve`。

## 本地开发（编辑时预览）

```bash
cd xly-wiki/zh
../.venv/bin/mkdocs serve         # http://127.0.0.1:8000，支持实时刷新
```

## 重新生成自动目录

```bash
python scripts/gen_catalog.py     # 通过 ~/.my.cnf 查询实时 DB，写入 docs/auto-catalog/**
```

脚本直接使用 `~/.my.cnf` 的 `[client]` 配置连接实时 MySQL。需要时可用环境变量覆盖：

```bash
DB_DEFAULTS_FILE=/path/to/other.cnf python scripts/gen_catalog.py
DB_NAME=xlyweberp_some_other      python scripts/gen_catalog.py
```

生成器每次运行都会清空并重写 `docs/auto-catalog/{tables,views,procedures,functions}/` 下的全部文件。这些目录中的手工修改会丢失。

## Pre-commit 钩子（可选，建议本地编辑时使用）

安装一次：

```bash
ln -s ../../scripts/precommit.sh .git/hooks/pre-commit
chmod +x scripts/precommit.sh
```

钩子会在每次提交时运行 `mkdocs build --strict`，以便在提交前发现断开的交叉链接。

## 风格

- **Markdown 源文件是事实来源。** `site/` 中的静态 HTML 是生成物，不要手工编辑。
- **中文正文保留代码和业务术语的原始标识符。** 术语翻译集中在 [术语表](../glossary/index.md)。
- **切片是叙述的主要位置。** 概念页和参考页保持短小；如果概念页超过约 300 字，通常应改成一个切片。
- **自动目录页不手工编辑。** 从手写内容交叉链接到自动目录，不反向维护叙述。
- **多做交叉链接。** 切片中首次提到框架表时应链接到自动目录，首次提到概念时应链接到概念页。

## 添加新切片

1. 创建 `docs/slices/NN-<name>.md`。
2. 把它加入 `mkdocs.yml` 的导航。
3. 端到端记录该切片（一个 UI 动作，贯穿所有层）。
4. 将概念链接到 Concepts，将表 / 存储过程链接到 Auto-Catalog。
5. 更新 [切片索引](../slices/index.md) 表。

## 添加新概念

只有当至少一个切片引入该概念时才添加概念页。没有任何引用的概念页是负担。