# release/portal_src —— 门户的"受管外壳 + 不入库内嵌件"（2026-09-11）

## 这是什么

`release/portal.html`（20.23 MB 单文件门户）里 **99.3% 是内嵌的交付文档正文** —— 28 个
`<template>`（治理清单分册、单机/整机报告、仿真台面板…），只有约 138 KB 是门户自己的壳
（样式、脚本、导航、面板结构）。原先整份文件都在版本库里，于是每次重算产物都往 git 里塞 20 MB。

本目录把两者拆开：**壳受管、内嵌件与合成结果不入库**，而且拆→装能回到**逐字节相同**的文件。

| 路径 | 入库 | 说明 |
|---|---|---|
| `shell.html` | ✅ | 门户外壳 138.5 KB。内嵌件处留标记 `<!--@TEMPLATE:<id>-->`；资料索引处留 `<!--@GOVERNANCE_SOURCES-->` |
| `manifest.json` | ✅ | 各件 sha256、条数、期望的 `portal.html` sha256、行尾约定、说明 |
| `README.md` | ✅ | 本文件 |
| `templates/<id>.html` | ❌ 产物 | 28 个内嵌交付文档正文，共 20.04 MB（交付件内容） |
| `governance_sources.json` | ❌ 产物 | 脱敏资料索引 + `source_sha256`，1.5 KB |
| `../portal.html` | ❌ 产物 | 装配结果；服务/网关直接读它 |

未入库的三项**不随包体缺失**：它们就在本目录/上一层，随包分发、参与运行；只是不进版本库。
`manifest.json` 里留了它们的 sha256，用来做漂移检测。

## 重建

```bat
.venv\Scripts\python.exe scripts\portal_build.py            :: 装配 → release\portal.html (含契约结论段)
.venv\Scripts\python.exe scripts\portal_build.py --verify   :: 装配到临时文件, 与现有门户逐字节比对
.venv\Scripts\python.exe scripts\portal_build.py --check    :: 各源件与 manifest 的 sha256 漂移检查
.venv\Scripts\python.exe scripts\portal_build.py --extract  :: 从现有门户重新拆出本目录 (一次性/重置用)
.venv\Scripts\python.exe scripts\portal_build.py --no-claims:: 只装外壳与内嵌件, 不注入契约结论段
```

**期望结果**：`--verify` 打印两行相同的 sha256 并给出 `逐字节一致`，退出码 0。

当前基线（本包，出厂状态）：

```
release/portal.html   20,226,052 B   sha256 9b6aabeb6ca18d15…
```

## 两个必须知道的坑

1. **行尾必须是 LF**。门户通体 LF（0 处 CRLF）。Python 文本模式在 Windows 上写文件会把 `\n`
   转成 `\r\n` —— 20 MB 文件整体改写，`/api/version` 里的 `portal_sha256` 与页面指纹全变。
   所以 `portal_build.py` 全程字节级读写（`rd`/`wr`），两个就地注入器
   （`guanlan_portal_fix_anchors.py`、`guanlan_portal_inject_claims.py`）写文件都带 `newline=""`，
   装配末尾还有一道 CRLF 自检 —— 触发就直接报错，不留一个"看起来一样"的文件。
2. **契约结论段是产物，不在壳里**。`<section id="contract-claims">` 由
   `scripts/guanlan_portal_inject_claims.py` 在装配最后注入，内容来自
   `outputs/<场站>/guanlan/derived/portal_claims.json`（事实契约派生物）。
   因此 `--extract` 会把它从壳里剥掉，装配时重新生成；**没有产物时装配出的门户会缺这一段**，
   这正是"产物不在则内容不在"的预期行为。

## 相关

- 契约与产物地图：`docs/数据目录结构与落位约定_v0.2.md` §6
- 产物进出 git 的约定与那次误提交的复盘：仓根 `.gitignore` 注释 + git 提交历史（`_修复记录_*` 类目录已按 2026-09-12 用户令不再随包/不再保留）
- 人工检查空状态：`scripts/products_state.py --off/--on/--status`