aomin
983191628e
.gitignore 的 `.env.*` 会把 `.env.example` 一起排除，等于把变量清单挡在仓库外， 接手的人只能翻 application.yml 逐个猜要配什么。加 `!.env.example`（含 `.sample`、`.template`）例外，规则顺序放在忽略之后。 同时补 .env.example：从 application.yml 与代码里实际提取 20 个变量，分组注明 默认值与是否必须替换。三个必改项（DB_PASS 无默认、GATEWAY_TOKEN 占位、 BIZ_TOKEN_SECRET 与 BIZ_PII_KEY 为 dev-only）单独标出。 本文件只放占位值；真实的 .env 仍不入库。另注明工程不自动读 .env （未引入 dotenv），必须由启动脚本加载或 docker compose --env-file 注入—— 这一条不说清，会有人建了 .env 直接启动然后发现 DB_PASS 还是缺。
69 lines
4.7 KiB
Markdown
69 lines
4.7 KiB
Markdown
# 变更记录
|
||
|
||
本文件记录仓库层面的变更（目录结构、契约版本、迁移序列、安全处置）。
|
||
代码内部改动以提交历史为准，不在此重复登记。
|
||
|
||
版本号与 `docs/handover/03_Z-02_清理后哈希与构建说明.md` 第五节的「版本标识一致性」保持一致。
|
||
|
||
---
|
||
|
||
## [Unreleased]
|
||
|
||
### Added
|
||
|
||
- `.env.example`：20 个环境变量的清单模板（数据库、Redis、日志、内部接口鉴权、业务密钥、短信、演示数据、告警、分区维护、设备模拟器），每项注明默认值与是否必须替换。真实 `.env` 不入库。
|
||
|
||
### Fixed
|
||
|
||
- `.gitignore` 的 `.env.*` 会把 `.env.example` 一并排除，导致变量清单无法入库。已加 `!.env.example`（以及 `.sample`、`.template`）例外。
|
||
|
||
---
|
||
|
||
## [V1.9-baseline] - 2026-11-13
|
||
|
||
首次入库，对应周工交付的 `SEC-Z-01 清理后` 源码包。
|
||
|
||
### Added
|
||
|
||
- `aomin-gateway/`：M-Z 业务层完整 Maven 工程 87 文件，含 84 个 `src/main` 文件、`pom.xml`、`README.md`、`start-gateway.bat`。
|
||
- `demo/`：演示前端与设备模拟器 9 文件（`web/` 静态页 7 个、`sim/sim_device.py`、`README.md`）。**不是正式三端。**
|
||
- `docs/handover/`：交付与安全清理材料 6 份（`00` 包说明、`01` 差异清单、`02` 扫描报告、`03` 哈希与构建、`04` 证据边界、`gitignore_建议`）。
|
||
- `docs/contract/`：接口契约 6 份，含 J-00 接入接口规格（md + OpenAPI yaml）、OpenAPI 使用说明、内部五接口定义、状态机、Mock 样例。
|
||
- `docs/reference/`：原始交付包指纹说明，以及两个原始 `SHA256SUMS` 清单、12 条迁移脚本哈希。
|
||
- `docs/reference/SHA256SUMS_源码树.txt`：84 个源码文件的逐文件哈希，`sha256sum -c` 可直接校验（导入时自校验 84/84 通过）。交付方给的整树摘要 `5E9F894B…` 算法描述不足复现，此清单纯为替代物。
|
||
- 仓库级规范文件：`README.md`、`LICENSE`、`CHANGELOG.md`、`CONTRIBUTING.md`、`SECURITY.md`、`.gitignore`、`.gitattributes`、`.editorconfig`。
|
||
|
||
### Changed
|
||
|
||
- 目录重排，便于跨平台工具与外部读取：
|
||
- `02_前端与设备端/` → `demo/`（`web/`、`sim/` 子路径不变，`demo/README.md` 原文未改）
|
||
- `04_OpenAPI与内部IoT契约/` → `docs/contract/`
|
||
- `00`～`04` 五份交接件与 `gitignore_建议.txt` → `docs/handover/`
|
||
- 两个 `SHA256SUMS_包内.txt` → `docs/reference/`，重命名以区分作用域
|
||
- 原包根目录的 `README.md`（本为后端工程说明）保留为 `aomin-gateway/README.md`，仓库根改为项目总览。**文件内容未改。**
|
||
|
||
### Excluded
|
||
|
||
- `03_数据库与Flyway迁移/`：与 `aomin-gateway/src/main/resources/db/migration/` 是同一套 12 条的两次出现。仓库只保留工程内一套，避免两处漂移；镜像与工程内副本已核为**逐字节一致**，指纹见 `docs/reference/原始交付包指纹.md`。
|
||
- `target/`、`*.jar`：构建产物。
|
||
- 证据原始数据（`raw/`、日志、截图）：按受控目录单独交付。
|
||
- `99_应急恢复（非正式路径）`：应急手段，非主干迁移序列。
|
||
- 评审用虚构台账数据：演示数据。
|
||
|
||
### Security
|
||
|
||
- 按 SEC-Z-01 清理后入库：**15 处明文口令 → 0 处**，扫描 0 命中，`.git` **无历史污染**（本仓库为首次提交，交付包内无 `.git`）。
|
||
- 目录重建时已重新扫描一次硬编码凭据，未新增命中；`application.yml` 的口令仅从 `${DB_PASS}` 取，无默认值。
|
||
- 口令**未轮换**，登记为待确认项，判据见 `docs/handover/02_SEC-Z-01_敏感信息扫描报告.md` 第四节。
|
||
|
||
### Known Issues
|
||
|
||
以下问题在交付包中即存在，本次整理**未修改代码**（改动会变更受控哈希，需走会签）：
|
||
|
||
- `src/main/resources/application.yml` 注释残留"本地库已有 83 表""从 V1.0.1 起递增"，实际为 87 表、终态 `1.0.28`；`baseline-description` 仍是 `baseline-83-tables`。
|
||
- `config/GatewayProperties.java` 的 `auth.enabled` 默认 `false`，共享密钥默认占位值 `change-me-in-production`；上线前必须注入真实值并打开，否则 `/internal/**` 只靠网络闸防护。
|
||
- 工程内无 `src/test`，无单元测试；验证依赖 155 条外部证据脚本（未随仓库交付）。
|
||
- `03_Z-02` 给的源码树摘要 `5E9F894B…` 无法用文中描述的算法复现（缺分隔符、大小写、路径前缀规则），已试 60 余种组合。只能作标识引用，不作校验凭据。
|
||
- 交付包行尾不统一（14 个文件 CRLF、其余 LF），**未归一化**——归一化会改变整树字节，使摘要复核失效；`.gitattributes` 设为 `* -text` 原样保存。
|
||
- A-Z-01／02／03 未关闭；并发 PULL 与真机未覆盖。
|