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），不做归一化以免整树摘要失效。
76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
# 文档索引
|
||
|
||
本目录只放**交付与契约类**文档，不放产品需求与项目计划（那些在项目文档库，不在代码主干）。
|
||
|
||
三个子目录按性质划分，判定标准是"这份文档过期时，谁能证明它是对的"。
|
||
|
||
## 一、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，旧件保留。
|