lixi
3f3a5cc50b
CI / docs-build (push) Successful in 1m29s
`api_key=volcengine.api_key` 这类**依赖注入传参**被 KEY-ASSIGN 判为疑似凭证。 这是规则的真缺口而非代码问题：行里没有任何秘密，而做 DI 的代码到处都是这种 写法——绕过一次就得在每个调用点绕过，那等于把规则废掉。故改规则。 新增 ALLOW_REFERENCE，刻意收得很紧以免开后门： - 值必须是**未加引号**的小写起首标识符引用（真密钥要么带引号，要么不是标识符形状） - 只允许**恰好一个点且随即行尾** - 连字符不在字符集内 对抗性夹具验证（三真三假）： - 拦下 `api_key = "sk-T3Blbk…"`（OpenAI 形态） - 拦下 `secret_key: "AKID…"`（腾讯云形态） - 拦下 `auth_token=eyJ….eyJ….Sfl…`（**三段式 JWT——两个点，故不落进放行**） - 放行 `api_key=lowercase.reference` / `api_key = settings.api_key` / `api_token: config.authToken` 原 5 形态泄漏夹具复验仍 8 条命中，一条不少。 另更正口径：脚本头与 git-workflow.md 仍写「三仓同构」，实际已是四仓—— patbond-ai 是唯一持有 AI 服务商凭证的仓，漏同步它风险最大。四仓 md5 已一致 （4945940093b4b8413b7d3eec8bf6a5ec），四仓 --all 全绿。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
65 lines
5.2 KiB
Markdown
65 lines
5.2 KiB
Markdown
# Git 工作流规范
|
||
|
||
适用于三个仓库：`patbond-api`（dev）、`patbond-flutter`（dev）、`patbond-doc`（main）。
|
||
|
||
## 分支模型
|
||
|
||
- **patbond-api / patbond-flutter**：`dev` 为集成分支，保持随时可构建（门禁全绿）。日常改动小步直接提交到 `dev`。
|
||
- **patbond-doc**：直接提交 `main`。
|
||
- **何时开 feature 分支**：改动跨多天、有破坏性风险（如大规模重构、依赖升级）、或多人并行同一仓库时，从最新 `dev` 拉出 `feat/<主题>` / `fix/<主题>` 分支，完成后合回并删除分支。短命分支，不留长期分叉。
|
||
|
||
## 提交信息约定
|
||
|
||
格式：`<前缀>: <中文主题>`，前缀取 `feat` / `fix` / `refactor` / `docs` / `test` / `chore`。
|
||
|
||
- 主题一句话说清做了什么；涉及架构决策时在主题或正文引用 ADR 编号（如 `（ADR-005）`）。
|
||
- 正文用列表写关键改动与**验收证据**（测试数量与结果、门禁命令输出结论），让提交自证可用。
|
||
- 一次提交做一件事，可独立回退；不把无关改动混进同一提交。
|
||
|
||
示例（既有惯例）：
|
||
|
||
```text
|
||
feat: 迁移珊瑚橙主题体系并新增认证基础组件（ADR-005）
|
||
|
||
- 新增 BrandMark/AppTextField 等 5 个组件及 6 个 widget 测试
|
||
- 门禁：dart format（0 changed）/ flutter analyze（0 issues）/ flutter test（7 passed）
|
||
```
|
||
|
||
## 禁止事项
|
||
|
||
- **不提交敏感配置与构建产物**：本地 `application.yml`、`target/`、`build/`、`.dart_tool/`、`.idea/`、密钥凭据一律不入库（.gitignore 已覆盖，提交前 `git status` 逐一核对暂存清单）。配置只提交 `*.sample`；任何关键/敏感信息只能存在于被忽略的文件或 `.sample` 占位中。
|
||
- **不提交测试产生的数据**：测试运行产生的数据文件、数据库导出、临时输出一律不入库。测试代码可以入库，但必须放在标准测试目录（Java 为 `src/test/`，Flutter 为 `test/`），不得散落在业务代码目录。
|
||
- **不 force push 共享分支**（`dev` / `main`）。个人 feature 分支整理历史后如需强推，用 `git push --force-with-lease`。
|
||
- **不修改已推送的 Flyway 迁移**（呼应开发计划 4.3 节）：`V1__*.sql` 等已进入 `dev` 的版本化迁移视为不可变，schema 变更一律新增 `V<n+1>__*.sql`。
|
||
- 不改写已推送的提交历史（rebase/amend 仅限未推送内容）。
|
||
|
||
## 凭证防泄漏检查（ADR-021）
|
||
|
||
两层检查共用同一规则表，单一来源为各仓入库的 `scripts/check-secrets.sh`（纯 shell，零外部依赖；**四仓**副本内容同构，调整规则时四仓同步提交——`patbond-ai` 是唯一持有 AI 服务商凭证的仓，尤其不可漏）：
|
||
|
||
1. **本地 pre-commit（推荐，每人每仓启用一次）**：
|
||
|
||
```bash
|
||
cd <你的工作区>/<仓名>
|
||
git config core.hooksPath scripts/hooks
|
||
```
|
||
|
||
之后每次 `git commit` 自动扫描暂存区内容与文件名。注意 `core.hooksPath` 会整体接管 hooks 目录（当前三仓无其他自定义 hook）。`git commit --no-verify` 可绕过，但仅限确认误报时使用——CI 兜底仍会拦。
|
||
2. **CI 兜底（强制）**：四仓 `ci.yml` 在 checkout 后的首个 step 运行同一脚本的 `--all` 模式，对全部已跟踪文件扫描（本次 push 变更文件的超集），命中即红，禁止合入。
|
||
|
||
规则覆盖（细节以脚本内规则表为准，不在文档重复维护，避免两处漂移）：云厂商 AccessKey 形态（AWS/腾讯云/阿里云前缀）、**AI 服务商密钥形态（Anthropic `sk-ant-`、OpenAI `sk-` / `sk-proj-` / `sk-svcacct-`）**、MinIO 默认凭证、独立成行的私钥 PEM 头、access/secret key **与 api key/secret/token、auth token** 与 JWT/签名密钥的实值赋值、配置类文件中非 `${}` 注入形态的数据库口令、`.env`/credentials/密钥导出 CSV 文件本体误入版本库。允许清单：`${}` 注入形态、占位值（changeme、your-xxx、`<占位>`、`xxx` 等）与明显示例值，以及**依赖注入的传参引用**（如 `api_key=settings.api_key`——行里没有任何秘密，而做 DI 的代码到处都是这种写法）。后者收得很紧：值必须是未加引号的小写起首标识符、只允许恰好一个点且随即行尾，故三段式 JWT 与 `sk-ant-…` 这类前缀仍会被拦。配置真实值仍只允许存在于被 gitignore 的文件中，占位只进 `.sample`。
|
||
|
||
手动全量自查：`sh scripts/check-secrets.sh --all`（在仓库根目录执行）。
|
||
|
||
**拦下真实云凭证后的第一动作是去云控制台轮换/禁用该密钥**，之后才是清理提交历史——只清历史不轮换等于没有处理。
|
||
|
||
## 提交前本地门禁（未来 CI 将执行同一清单）
|
||
|
||
| 仓库 | 必跑命令 | 通过标准 |
|
||
| --- | --- | --- |
|
||
| patbond-api | `JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test` | BUILD SUCCESS，0 失败（需 Docker 供 Testcontainers） |
|
||
| patbond-flutter | `dart format --output=none --set-exit-if-changed lib test`<br>`flutter analyze`<br>`flutter test` | 0 changed / No issues / All tests passed |
|
||
| patbond-doc | `mkdocs build --strict -d <临时目录>` | exit 0，零 warning；不把 `site/` 落进仓库 |
|
||
|
||
门禁不绿不提交。CI 载体（审计 M3 后半）落地后将原样执行上表命令作为合入门禁。
|