aomin
a7605ef8b8
按周工交付的 SEC-Z-01 清理后源码建立 M-Z 主干，并按 Git 仓库惯例重排目录。 - aomin-gateway/ 后端工程 87 文件，原样保留，路径与构建命令未变 - demo/ 演示前端与设备模拟器 9 文件（原 02_前端与设备端），非正式三端 - docs/handover/ 交付与安全清理材料 6 份，内容未改 - docs/contract/ J-00 规格、OpenAPI、内部五接口、状态机、Mock 样例 - docs/reference/ 指纹与校验清单，含 84 个源码文件的 sha256 清单 目录重排只动位置不动内容：源码树 84 文件哈希与交付一致，逐文件自校验通过； 12 条 Flyway 迁移与交付包内镜像逐字节一致。 未纳入：迁移镜像目录（与工程内一套重复，改留指纹）、target/、证据 raw、 应急恢复脚本、评审用虚构台账数据。 安全：SEC-Z-01 15 处明文已清零，导入前重新扫描无新增命中，本仓库无历史污染。 行尾按交付字节原样保存（.gitattributes 设 * -text），不做归一化以免整树摘要失效。
文档索引
本目录只放交付与契约类文档，不放产品需求与项目计划（那些在项目文档库，不在代码主干）。
三个子目录按性质划分，判定标准是"这份文档过期时，谁能证明它是对的"。
一、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，旧件保留。