Merge branch 'dev' into main

.gitignore

@@ -1,5 +1,6 @@
 /node_modules
 /oh_modules
+/tmp
 /local.properties
 /.idea
 **/build

AGENTS.md

@@ -72,6 +72,7 @@ harmony-client/
 | 编码规范 Conventions | `docs/conventions.md` |
 | 测试 Testing | `docs/testing.md` |
 | 构建/签名/部署 Build & Deploy | `docs/build-deploy.md` |
+| 分支模型与 Git 规范 Git Workflow | `docs/git-workflow.md` |
 
 ## Common Tasks
 
@@ -92,7 +93,7 @@ harmony-client/
 **禁止 Forbidden**
 - 修改签名配置（`build-profile.json5` 的 `signingConfigs`）
 - 删除测试文件
-- push 到 main/master
+- push 到 main 或 dev（一律走 PR）
 - 往 `local.properties` / `.env` 写真实密钥
 - 未经批准安装生产依赖
 

docs/build-deploy.md

@@ -33,12 +33,38 @@ hvigorw assembleHap --mode module -p product=default -p buildMode=release
 
 ## 签名 Signing
 
-`build-profile.json5` 里 `signingConfigs` 目前为**空**，且 `products[].signingConfig` 引用了 `"default"` —— **签名尚未配置**。
+### 现状与原则
+
+- `build-profile.json5` 里 `signingConfigs` 在**仓库中必须保持为空 `[]`**（`products[].signingConfig` 仍引用 `"default"`）——签名是机器相关的，禁止入库。
+- 真正的密钥物料（`.p12` / `.cer` / `.p7b`）由 DevEco 生成在 `~/.ohos/config/` 下，**本来就在仓库外**；`build-profile.json5` 里只有「文件路径 + 加密后的密码」，但同样属敏感信息，不得提交。
+
+### 本地配置签名（不入库）
+
 要跑真机/模拟器需先配置签名：
 - DevEco Studio → File → Project Structure → Signing Configs → 勾选自动签名（登录华为账号）。
 - 或手动配置 `.p12` + `.cer` / `.p7b`。
 
-> 该文件的签名部分属于 **Agent 禁止修改** 范围（见 `AGENTS.md`）。
+DevEco 自动签名会把凭据写进 `build-profile.json5`，这属于**本地未提交状态**，不要 `git add` 它。
+
+### 防泄露：pre-commit 钩子
+
+仓库内置了 pre-commit 钩子 `scripts/git-hooks/pre-commit`：只要暂存区的 `build-profile.json5` 出现 `keyPassword` / `storePassword` / `certpath` 等签名字段，就**拒绝提交**。
+
+每个克隆启用一次：
+
+```bash
+git config core.hooksPath scripts/git-hooks
+```
+
+验证：临时在 `build-profile.json5` 里塞一个 `"keyPassword"` 再 `git add build-profile.json5 && git commit`，应被拦截。
+
+> 确需临时绕过时用 `git commit --no-verify`（仅应急，不建议）。
+
+### 彻底外部化（可选）
+
+若想连本地也不出现凭据，可走「动态配置签名」：用 `hvigorfile.ts` 从 gitignore 的本地文件或环境变量读取签名注入，让 `build-profile.json5` 始终保持空。参考华为官方《基于动态配置签名的多人协同开发应用签名解决方案》。
+
+> `build-profile.json5` 的签名部分属于 **Agent 禁止修改** 范围（见 `AGENTS.md`）。
 
 ## 产品与构建模式 Products & Build Modes
 

docs/git-workflow.md

@@ -0,0 +1,104 @@
+# Git Workflow（分支模型与提交规范）
+
+本仓库采用简化 Git Flow：`main`（生产）← `dev`（集成）← `feature/*`（功能）。
+
+## 分支模型 Branch Model
+
+| 分支 Branch | 用途 Purpose | 从哪拉出 From | 合入 To | 直接 push |
+|-------------|-------------|---------------|---------|-----------|
+| `main` | 生产 / 稳定，可发布 | — | — | ❌ 禁止（仅 PR） |
+| `dev` | 集成 / 开发主线 | `main` | `main` | ❌ 禁止（仅 PR） |
+| `feature/<name>` | 单个功能 / 改动 | `dev` | `dev` | ✅（推自己的 feature） |
+| `hotfix/<name>` | 线上紧急修复 | `main` | `main` + `dev` | ❌（仅 PR） |
+| `release/<version>` | （可选）发布候选 | `dev` | `main` + `dev` | ❌（仅 PR） |
+
+## 分支命名 Branch Naming
+
+- 功能：`feature/<kebab-case>`，如 `feature/architecture-scaffold`
+- 修复：`fix/<kebab-case>` 或 `hotfix/<kebab-case>`
+- 发布：`release/<semver>`，如 `release/v1.0.0`
+
+## 提交规范 Commit Convention
+
+遵循 Conventional Commits：`<type>(<scope>): <subject>`
+
+- `type`：`feat` / `fix` / `docs` / `chore` / `refactor` / `test` / `build` / `perf` / `style` / `ci`
+- `scope`：可选，模块名（`entry` / `uikit` / `common`）
+- `subject`：祈使句，首字母小写，结尾不加句号
+
+示例：
+
+```
+feat(entry): 建立 MVVM+data 分层骨架
+chore(build): 注册 common/uikit 模块
+docs: 新增架构设计文档
+```
+
+## 开发流程 Development Workflow
+
+### 新建功能 Feature
+
+```bash
+git checkout dev
+git pull
+git checkout -b feature/xxx
+
+# 开发 + 提交（conventional commits）
+git add -A
+git commit -m "feat(entry): ..."
+
+git push -u origin feature/xxx
+```
+
+然后在 Gitea 发起 PR：`feature/xxx → dev`，评审通过后合并（推荐 **squash merge**，保持 `dev` 历史线性干净）。
+
+合并后删除已合入的 feature 分支：
+
+```bash
+git checkout dev
+git pull
+git branch -d feature/xxx
+git push origin --delete feature/xxx
+```
+
+### 发布 Release
+
+简单场景直接发 PR `dev → main`（用 **merge commit** 保留发布边界），合并后打 tag：
+
+```bash
+git checkout main
+git pull
+git tag v1.0.0
+git push --tags
+```
+
+复杂场景可引入 `release/<version>` 分支隔离发布修复：
+
+```bash
+git checkout -b release/v1.0.0 dev
+# 修复 release 上的问题后，分别合回 main 与 dev 并打 tag
+```
+
+### 紧急修复 Hotfix
+
+```bash
+git checkout main
+git pull
+git checkout -b hotfix/xxx
+# 修复 + 提交
+git push -u origin hotfix/xxx
+# PR: hotfix/xxx → main；再 PR: hotfix/xxx → dev（同步回开发主线）
+```
+
+## 硬规则 Hard Rules
+
+1. **禁止直接 push 到 `main` 或 `dev`**，一律走 PR（建议在 Gitea 对这两个分支开启保护）。
+2. **PR 合入前过 lint + 相关测试**，见 `docs/testing.md` 的「改动后验证」。
+3. **feature 合并后删除分支**，保持分支列表干净。
+4. **提交信息必须走 Conventional Commits**，不合规的提交在 PR 中 squash 掉。
+5. **签名信息永不入库**——`build-profile.json5` 的 `signingConfigs` 必须保持空 `[]`，已由 pre-commit 钩子兜底，见 `docs/build-deploy.md` 的「签名管理」。
+
+## 仓库设置 Repo Settings（一次性）
+
+- 默认分支设为 `main`（Gitea → Settings → Branches → Default Branch）。
+- 建议对 `main` / `dev` 开启分支保护（禁止直接 push，仅允许 PR 合并）。

scripts/git-hooks/pre-commit

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# 拦截提交包含签名凭据的 build-profile.json5。
+# Block commits that add signing credentials to build-profile.json5.
+# 详见 docs/build-deploy.md 的「签名管理」章节。
+
+set -u
+
+FILE="build-profile.json5"
+
+# 仅当本次提交要改动 build-profile.json5 时才检查
+if git diff --cached --quiet -- "$FILE"; then
+  exit 0
+fi
+
+# 读取暂存区版本，检测签名敏感字段
+if git show ":$FILE" | grep -qE '"(keyPassword|storePassword|certpath|storeFile|keyAlias|signAlg)"'; then
+  cat >&2 <<'EOF'
+
+❌ 已拦截提交：build-profile.json5 中含签名凭据（keyPassword / storePassword / certpath / …）。
+   signingConfigs 必须保持为空 [] 才能提交。
+   处理办法：
+     - 若只是本地 DevEco 自动签名产生的：先取消暂存，再还原为空
+         git reset HEAD build-profile.json5
+         git checkout -- build-profile.json5
+     - 确需本地跑真机：保持该改动「未提交」即可，不要 git add 它。
+   如确实要临时绕过（不建议）：git commit --no-verify
+   详见 docs/build-deploy.md 的「签名管理」章节。
+EOF
+  exit 1
+fi
+
+exit 0