# 文档索引

本目录只放**交付与契约类**文档，不放产品需求与项目计划（那些在项目文档库，不在代码主干）。

三个子目录按性质划分，判定标准是"这份文档过期时，谁能证明它是对的"。

## 一、handover／交付与安全清理

周工交付的 `SEC-Z-01 清理后` 材料，**原样保留，内容未改**。这是"这批源码从哪来、清理了什么、怎么证明"的凭据。

| 文件 | 内容 | 什么时候看 |
|---|---|---|
| `00_包内容与使用说明.md` | 包里有什么、没什么、怎么用 | 第一次接手 |
| `01_SEC-Z-01_最小安全清理差异清单.md` | 15 处明文逐处改成了什么 | 复核清理是否彻底 |
| `02_SEC-Z-01_敏感信息扫描报告.md` | 扫描范围、结果、复算方法、盲区、轮换结论 | 怀疑有凭据泄露时 |
| `03_Z-02_清理后哈希与构建说明.md` | 清理前后指纹、构建步骤、首提交顺序 | 核对版本标识、复现构建 |
| `04_155条证据适用边界.md` | 155 条重跑结果，**以及它不能证明什么** | 有人拿 155 条说"全过了"时 |
| `gitignore_建议.txt` | 交付方给的忽略清单建议 | 调整 `.gitignore` 时对照 |

> `00` 第二节称"没给演示前端"，但实际交付包含 8 个演示文件，已整理到 `demo/`。该说明为早于补包的旧稿，以实际文件为准。

## 二、contract／接口契约

**唯一的机读契约来源。** 本工程未引入 springdoc，没有运行时 OpenAPI 生成，所以这里的 md 与 yaml 是手工维护的——改了代码不改这里，就是契约漂移，且没有任何工具会报错。

| 文件 | 内容 |
|---|---|
| `6_J-00_接入接口规格_V1.8.md` | 接入接口规格正文（J-00 V1.8.1） |
| `6_J-00_接入接口规格_V1.8_OpenAPI.yaml` | 同上的机读形式 |
| `6_J-00_OpenAPI使用说明_V1.8.md` | yaml 怎么用、字段怎么读 |
| `内部五接口定义.md` | I-01／I-02／I-05／I-12／I-18 字段与语义 |
| `状态机.md` | 命令与告警的状态、动作、迁移条件 |
| `Mock样例.md` | 可直接喂给接入侧的请求样例 |

契约版本号升级时，文件名、正文、yaml 的 `info.version` 三处必须一致；旧版本文件保留不删。

## 三、reference／指纹与校验

| 文件 | 用途 |
|---|---|
| `原始交付包指纹.md` | 说明各清单的作用范围，并给出 12 条迁移脚本的哈希 |
| `SHA256SUMS_源码树.txt` | 84 个源码文件的逐文件哈希，**仓库根执行 `sha256sum -c` 可直接校验** |
| `SHA256SUMS_原始交付包.txt` | 原交付包的文件哈希清单（**只对原包有效**） |
| `SHA256SUMS_前端与设备端.txt` | 原包内演示前端子清单（**只对原包有效**） |

前两个清单在目录重排后**已不能直接校验**本仓库，保留是为了证明"交付时的文件与现在仓库里的是同一份"。怎么核对见 `原始交付包指纹.md`。

## 四、路径说明

`handover/` 里的文档写于交付当时，文中提到的目录名是**原交付包**的结构。对照本仓库：

| 文中写法 | 本仓库位置 |
|---|---|
| `aomin-gateway/` | `aomin-gateway/`（同名，未变） |
| `01_后端源码/` | `aomin-gateway/`（交付时的旧称） |
| `02_前端与设备端/` | `demo/` |
| `03_数据库与Flyway迁移/` | **未纳入**，见下 |
| `04_OpenAPI与内部IoT契约/` | `docs/contract/` |

### 迁移镜像为什么没纳入

原包的 `03_数据库与Flyway迁移/` 与 `aomin-gateway/src/main/resources/db/migration/` 是同一套 12 条 SQL 的两次出现，用途是"应用与镜像同源核对"。

同一套文件在仓库里出现两次，迟早会只改一处。所以仓库只保留工程内一套（Flyway 只认它），核对能力用哈希代替：12 条脚本的 SHA-256 记在 `reference/原始交付包指纹.md`，交付时已核为**逐字节一致**。

## 五、新增文档往哪放

| 新增内容 | 放这里 |
|---|---|
| 接口字段、状态机、协议变更 | `contract/` |
| 交付清单、安全清理、复验记录 | `handover/` |
| 哈希、版本指纹、校验脚本输出 | `reference/` |
| 都不属于（需求、计划、会议记录） | 不放本仓库 |

改版不覆盖旧件：同主题新建文件、版本号 +1，旧件保留。