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 还是缺。
130 lines
8.2 KiB
Markdown
130 lines
8.2 KiB
Markdown
# 鹤仆·守望 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`](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/ 原始交付包指纹与迁移脚本哈希
|
||
├── .env.example 环境变量清单模板（20 项，真实 .env 不入库）
|
||
├── .gitattributes 行尾与二进制策略
|
||
├── .editorconfig 缩进与编码
|
||
├── CHANGELOG.md 版本记录
|
||
├── CONTRIBUTING.md 分支、提交信息、迁移与契约的硬规则
|
||
├── SECURITY.md 敏感信息禁止清单与泄露处置
|
||
└── LICENSE 专有软件声明（非开源）
|
||
```
|
||
|
||
## 三、快速开始
|
||
|
||
```bash
|
||
# 1) 构建（需要 JDK 21 与 Maven；离线环境加 -o，有私服加 -s <settings.xml>）
|
||
cd aomin-gateway
|
||
mvn -DskipTests clean package
|
||
# 产物：target/aomin-gateway-0.0.1-SNAPSHOT.jar
|
||
|
||
# 2) 配置环境变量（20 个变量的清单见仓库根 .env.example）
|
||
cd ..
|
||
cp .env.example .env # 把 DB_PASS 填上，其余按需改
|
||
set -a; . ./.env; set +a # 工程不会自动读 .env，必须加载进进程环境
|
||
|
||
# 3) 启动（DB_PASS 必填，缺失时应用立即退出，不会回退到任何内置口令）
|
||
export DB_USER=aomin
|
||
java -jar aomin-gateway/target/aomin-gateway-0.0.1-SNAPSHOT.jar --server.port=8080 --server.address=0.0.0.0
|
||
|
||
# 4) 自检
|
||
curl -s http://127.0.0.1:8080/health
|
||
```
|
||
|
||
`.env.example` 是变量清单模板，含数据库、Redis、内部接口鉴权、业务密钥、短信、告警、分区维护、模拟器共 20 项，每项都注明默认值与是否必须替换。真实的 `.env` 不入库。
|
||
|
||
正常返回需同时满足 `db: connected`、`tables: 87`、`flyway: 1.0.28`、`status: UP`。
|
||
|
||
建库、环境变量、systemd 单元、Flyway 校验和不符的处理，全部在 [`aomin-gateway/README.md`](aomin-gateway/README.md)。
|
||
|
||
演示前端与模拟器的跑法在 [`demo/README.md`](demo/README.md)。
|
||
|
||
## 四、文档索引
|
||
|
||
| 需要知道什么 | 看哪里 |
|
||
|---|---|
|
||
| 这批源码的来历、包里有什么、怎么用 | [`docs/handover/00_包内容与使用说明.md`](docs/handover/00_包内容与使用说明.md) |
|
||
| 15 处明文各自改成了什么 | [`docs/handover/01_SEC-Z-01_最小安全清理差异清单.md`](docs/handover/01_SEC-Z-01_最小安全清理差异清单.md) |
|
||
| 敏感信息扫描范围、方法、盲区、轮换结论 | [`docs/handover/02_SEC-Z-01_敏感信息扫描报告.md`](docs/handover/02_SEC-Z-01_敏感信息扫描报告.md) |
|
||
| 清理前后指纹、构建步骤、首提交顺序 | [`docs/handover/03_Z-02_清理后哈希与构建说明.md`](docs/handover/03_Z-02_清理后哈希与构建说明.md) |
|
||
| 155 条证据能证明什么、不能证明什么 | [`docs/handover/04_155条证据适用边界.md`](docs/handover/04_155条证据适用边界.md) |
|
||
| 五个内部接口的字段与状态机 | [`docs/contract/内部五接口定义.md`](docs/contract/内部五接口定义.md)、[`docs/contract/状态机.md`](docs/contract/状态机.md) |
|
||
| 接入接口的机读契约 | [`docs/contract/6_J-00_接入接口规格_V1.8_OpenAPI.yaml`](docs/contract/6_J-00_接入接口规格_V1.8_OpenAPI.yaml) |
|
||
| 原始交付包与迁移脚本的哈希 | [`docs/reference/原始交付包指纹.md`](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`](LICENSE)。
|
||
|
||
---
|
||
|
||
*本仓库由周工交付的 SEC-Z-01 清理后源码整理而来，用于建立 M-Z 主干。*
|