# 仓库目录与产物边界说明

## 最新复审（2026-09-30 20:53）

P0-03 已按本文范围复审通过：部署源码独立克隆正式构建、发布模块完整测试、发布清单和实际远端包校验、构建后索引检查均通过，未删除既有文件。证据见《Linux生产流程测试记录》同日章节。换行导致的原始构建输入差异转入 P0-04 继续整改，不把目录边界复审等同于可重复构建或完整生产放行。

## 一、源码和产物分离

| 目录 | 用途 | Git 边界 |
|---|---|---|
| `backend/` | Go 服务端、运维入口、就近单元测试 | 源码、模块锁和迁移纳入；运行数据、二进制排除 |
| `frontend/` | Web 页面、页面旁测试和依赖锁 | 源码和锁文件纳入；依赖、构建及覆盖率输出排除 |
| `desktop/` | 范围外历史源码 | 保留源码；二进制和 dist 排除，不进入正式发布 |
| `deploy/` | 安装、卸载、服务模板和正式部署测试 | 脚本、模板及测试纳入；远程临时数据排除 |
| `build/` | 发布构建入口及本地构建工作目录 | 仅构建脚本和说明纳入，其余产物排除 |
| `doc/` | 中文需求、设计、操作说明和脱敏验收结论 | 文档纳入，不嵌入凭据和数据库内容 |
| `tests/` | 正式跨模块测试 | 测试源码纳入；不强制迁移模块旁既有测试 |
| `scripts/` | 经审查的开发辅助工具 | 当前仅说明；禁止新增临时脚本替代验收 |
| `release/` | 可分发候选包 | 仅说明纳入，包和 manifest 留本地或发布存储 |
| `artifacts/` | 脱敏测试输出与证据 | 仅说明纳入，完整结果单独留存 |
| `.runtime/`、`.deploy-stage/` | 本机运行与部署暂存 | 全部排除 |

已有发布目录仍可位于 `build/`。`release/` 是分发边界，不要求复制或删除历史包。本次整理不物理删除现有文件。

## 二、忽略规则与例外

仓库 `.gitignore` 覆盖各层级的可执行文件、归档、依赖、dist、日志、临时补丁、浏览器常用缓存目录、数据库和旁路文件、环境凭据及常见私钥名。自定义浏览器用户目录必须置于 `.runtime/`，远端下载文件必须置于 `.deploy-stage/`，避免凭文件名猜测遗漏。

不可整体忽略 `*.pem` 或 `*.sql`：`backend/internal/certificate/trust/` 的 PEM 是 ACME Staging 公共 CA 证书，数据库迁移 SQL 是正式源码。它们继续纳入 Git。测试使用的合成密钥应在隔离临时目录生成；真实私钥只允许存于产品受保护存储。

忽略规则只降低误提交风险，不是安全扫描器：任意文件名都可能包含秘密；已跟踪文件也不会因为新增规则自动取消跟踪。因此提交前仍须检查索引、差异和文件内容，禁止以 `git add -f` 绕过边界提交产物。生产配置不得用 `.env.example` 的例外名存放。

## 三、核对方法

在项目根目录执行以下只读检查：

```powershell
git status --short --untracked-files=all
git ls-files
git check-ignore -v --no-index -- .runtime/probe.json release/probe.zip artifacts/probe.json
git diff --check
git diff --cached --stat
```

正式回归测试在 `backend/` 执行：

```powershell
go test -count=1 ./internal/releasearchive -run 'TestRepositoryIgnore'
```

测试复制仓库 `.gitignore` 到临时 Git 仓库，禁用用户级和系统级 Git 配置，逐项验证应忽略和应保留的路径，并比较实际受跟踪文件清单。不使用开发机专属排除规则作为证据。测试自身创建的隔离临时目录由测试框架管理，不删除工作区已有文件。

## 四、复审边界

P0-03 的源码边界可通过 Git 和隔离回归复核；不得据此标记 SSH、证书签发、系统服务或恢复验收通过。独立克隆构建证据沿用对应源码提交记录，应用代码或发布逻辑变化后须重新构建验证。