鹤仆·守望 S 线一期　M-Z 业务底座

鹤仆·守望老人安全监测平台 S 线一期的中段业务层唯一主骨架，承接 J-00 V1.8.1 的五个内部接入接口与 /api/v1/** 业务接口。数据库为唯一事实源，Flyway 管理全部迁移，不接受手工改表。

本仓库同时是 M 域接入与内部契约的存放地，作为团队唯一的代码事实来源。

一、版本基线

项	值
模型版本	V1.9（已冻结；本次仅为 SEC-Z-01 最小安全清理，未升 V1.10）
内部契约	J-00 1.8.1
迁移序列	Flyway 1.0.28（12 条），产出 87 张业务表
技术栈	JDK 21 · Spring Boot 3.3.5 · MyBatis-Plus 3.5.7 · MySQL 8.0 · Redis 7
源码树摘要	5E9F894B0D1071969A968F2A9B1451279ADF39D423148186886BFD064398F286
证据批次	R20261113-112443，11 组 / 155 条 / 失败 0

源码树摘要是交付方给出的整树指纹。它的算法在本仓库无法复现（描述缺分隔符与大小写规则，试过 60 余种组合均对不上），因此只作标识引用，不作校验凭据。真正可校验的是 docs/reference/SHA256SUMS_源码树.txt：84 行标准 sha256sum 清单，sha256sum -c 直接可用，导入时自校验 84/84 通过。

二、目录结构

.
├── aomin-gateway/        后端 Maven 工程（87 文件，构建与部署见其 README）
│   ├── pom.xml
│   ├── start-gateway.bat Windows 本地启动器（GBK + chcp 936）
│   └── src/main/
│       ├── java/cn/aomin/gateway/    业务代码
│       └── resources/
│           ├── application.yml       无任何内置口令
│           └── db/migration/         Flyway 12 条（V1.0.0 ~ V1.0.28）
├── demo/                 演示前端 + 设备模拟器（**不是正式三端**）
│   ├── web/              运营后台、家属端、地图选点（静态页）
│   └── sim/sim_device.py 扮演网关 + 7 台设备，只调 I-01／I-02／I-12
├── docs/
│   ├── handover/         交付与安全清理材料（Z-01／Z-02）
│   ├── contract/         接口契约：J-00 规格、OpenAPI、内部五接口、状态机
│   └── reference/        原始交付包指纹与迁移脚本哈希
├── .gitattributes        行尾与二进制策略
├── .editorconfig         缩进与编码
├── CHANGELOG.md          版本记录
├── CONTRIBUTING.md       分支、提交信息、迁移与契约的硬规则
├── SECURITY.md           敏感信息禁止清单与泄露处置
└── LICENSE               专有软件声明（非开源）

三、快速开始

# 1) 构建（需要 JDK 21 与 Maven；离线环境加 -o，有私服加 -s <settings.xml>）
cd aomin-gateway
mvn -DskipTests clean package
# 产物：target/aomin-gateway-0.0.1-SNAPSHOT.jar

# 2) 启动（DB_PASS 必填，缺失时应用立即退出，不会回退到任何内置口令）
export DB_PASS='<口令>'
export DB_USER=aomin
java -jar target/aomin-gateway-0.0.1-SNAPSHOT.jar --server.port=8080 --server.address=0.0.0.0

# 3) 自检
curl -s http://127.0.0.1:8080/health

正常返回需同时满足 db: connected、tables: 87、flyway: 1.0.28、status: UP。

建库、环境变量、systemd 单元、Flyway 校验和不符的处理，全部在 aomin-gateway/README.md。

演示前端与模拟器的跑法在 demo/README.md。

四、文档索引

需要知道什么	看哪里
这批源码的来历、包里有什么、怎么用	docs/handover/00_包内容与使用说明.md
15 处明文各自改成了什么	docs/handover/01_SEC-Z-01_最小安全清理差异清单.md
敏感信息扫描范围、方法、盲区、轮换结论	docs/handover/02_SEC-Z-01_敏感信息扫描报告.md
清理前后指纹、构建步骤、首提交顺序	docs/handover/03_Z-02_清理后哈希与构建说明.md
155 条证据能证明什么、不能证明什么	docs/handover/04_155条证据适用边界.md
五个内部接口的字段与状态机	docs/contract/内部五接口定义.md、docs/contract/状态机.md
接入接口的机读契约	docs/contract/6_J-00_接入接口规格_V1.8_OpenAPI.yaml
原始交付包与迁移脚本的哈希	docs/reference/原始交付包指纹.md

五、已知边界与不一致

接手上手前必须知道这些，否则容易误判。

项	实际情况
演示前端是否随包交付	docs/handover/00 第二节称"没给演示前端"，但实际交付包内含 8 个文件，已整理到 demo/。该说明为早于补包的旧稿，以实际文件为准
迁移镜像目录	原包内 03_数据库与Flyway迁移/ 与工程内 db/migration/ 是同一套 12 条的两次出现。仓库只保留工程内一套（避免两处漂移），镜像已核为逐字节一致，指纹见 docs/reference/
application.yml 注释	注释里"本地库已有 83 表""从 V1.0.1 起"是历史残留，实际 87 表、终态 1.0.28。未改动——改动会变更受控哈希，需走会签
内部签名开关	auth.enabled 默认 false，共享密钥默认占位值 change-me-in-production。上线前必须从环境变量注入并打开，见 SECURITY.md
数据库口令轮换	未轮换，登记为待确认项，见 docs/handover/02 第四节
A-Z-01／02／03	未关闭。作者自测通过，仍需接收方复验签认，本仓库不构成关闭
并发 PULL	未覆盖（v20 是串行 10 条），由谢工按完整矩阵补测
真机	未覆盖，等黄工真机窗口
单元测试	工程内无 src/test，验证依赖 155 条外部证据脚本（不随仓库交付）
源码树摘要	交付方给的 5E9F894B… 无法用文档描述的算法复现，改用逐文件清单校验，见 docs/reference/
行尾	交付包内 14 个文件是 CRLF、其余 LF，属既有状态。未归一化（会改变整树字节，使摘要复核失效），.gitattributes 设为 * -text

六、什么不进仓库

不进	原因
target/、*.jar	构建产物，可由源码重建
.env、*.local.yml、*.pem、*.key	可能含口令与私钥
证据原始数据（raw/、日志、截图）	体积大、每轮重跑全变，按受控目录单独交付
99_应急恢复（非正式路径）	应急手段，不是主干迁移序列，放进来容易被当成常规路径
评审用虚构台账数据	演示数据，不属于主干
任何明文口令	SEC-Z-01 已清零，一个字符都没有；新增一处即事故，见 SECURITY.md

七、范围

一期只做 S 线（麦乐克 + 豪恩两条通路）。G 线、H 线、探视、结算、钱包不在本期。内部接口 /internal/** 只允许内网访问，依赖来源白名单，不要暴露到公网。

八、许可

专有软件，版权归奥敏所有，非开源。未经书面许可不得复制、分发或用于本项目之外，详见 LICENSE。

---

本仓库由周工交付的 SEC-Z-01 清理后源码整理而来，用于建立 M-Z 主干。