52 lines
3.4 KiB
Markdown
52 lines
3.4 KiB
Markdown
# 仓库目录与产物边界说明
|
||
|
||
## 一、源码和产物分离
|
||
|
||
| 目录 | 用途 | 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、证书签发、系统服务或恢复验收通过。独立克隆构建证据沿用对应源码提交记录，应用代码或发布逻辑变化后须重新构建验证。
|