68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# 文档重建与 Git 重置操作方案
|
|
|
|
> 旧文档清理已完成；本文保留为尚未执行的 Git 重建与代码归位方案。当前任务不重建 `.git/`、不移动业务代码、不提交。
|
|
|
|
## 1. 重建目标
|
|
|
|
新事实层级为：产品宪章 → 主 PRD → 领域文档 → 架构与契约 → 实现状态 → 代码。新目录采用 `product/`、`domain/`、`architecture/`、`contracts/`、`operations/`。旧文档的有效内容完成迁移和核对后删除，不保留 archive、bak 或长期重定向页。
|
|
|
|
## 2. 旧文档迁移（已完成）
|
|
|
|
旧 `concept/`、`design/`、`development/`、`api/` 和 `roadmap/` 已删除，不保留 archive、bak 或长期重定向页。有效的稳定标识、枚举、ID、事件和错误码已归入 `contracts/contract-glossary.md`；目标语义归入 product/domain/architecture，当前实现差距归入能力矩阵。后续发现遗漏时从 Git 历史提取单项证据并归入当前事实层级，不恢复旧树。
|
|
|
|
## 3. Git 重建前三重备份
|
|
|
|
删除旧 `.git/` 前必须创建并验证三种彼此独立的备份：
|
|
|
|
| 备份 | 覆盖内容 | 验证 |
|
|
| --- | --- | --- |
|
|
| Git Bundle | 可达分支、标签和提交历史 | `git bundle verify`；在临时目录克隆并核对引用/提交 |
|
|
| 工作区快照 | 已跟踪、未跟踪、暂存和未提交文件的完整当前状态 | 解包到临时目录，与源工作区清单逐项比对 |
|
|
| 哈希清单 | 备份产物及工作区文件的路径、大小、摘要 | 在独立位置重新计算并零差异校验 |
|
|
|
|
备份产物必须写到项目目录外，避免随 `.git/` 或工作树清理被删除。验证失败时立即停止，不得继续重置。
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
I[冻结重建窗口与盘点工作区] --> B1[生成 Git Bundle]
|
|
I --> B2[生成完整工作区快照]
|
|
I --> B3[生成哈希清单]
|
|
B1 --> V[临时位置恢复验证]
|
|
B2 --> V
|
|
B3 --> V
|
|
V --> OK{三者均验证通过?}
|
|
OK -- 否 --> STOP[停止，修复备份]
|
|
OK -- 是 --> G[才允许进入 Git 重建]
|
|
```
|
|
|
|
## 4. 现有代码项目外封存
|
|
|
|
在新 Git 初始化前，将现有业务代码完整封存到项目外位置，保留工作区快照和哈希对应关系。封存件只作审计与归位输入，不直接作为新仓库首提交，也不得在原项目中留下 `.bak` 副本。
|
|
|
|
## 5. 新 Git 首提交
|
|
|
|
首提交只包含：
|
|
|
|
- 新文档事实体系；
|
|
- 仓库治理文件；
|
|
- 不含真实秘密的示例配置；
|
|
- 文档/契约校验脚本；
|
|
- 四服务空骨架。
|
|
|
|
不得包含现有业务代码、真实 `.env`/密钥、数据库、日志、构建产物、旧文档 archive 或项目内封存副本。首提交前检查路径、许可证、忽略规则、示例配置和空骨架边界。
|
|
|
|
## 6. 代码归位
|
|
|
|
代码以契约先行方式从项目外封存件逐批归位：
|
|
|
|
1. 选择 P0/P1/P2 中一个可验收纵向闭环。
|
|
2. 先确认产品/领域语义、契约和四服务归属。
|
|
3. 审计旧代码：可复用、需重写、应删除、依赖与安全问题。
|
|
4. 归入灵台、神识、乾坤或琉璃镜；禁止为省事混回职责。
|
|
5. 补契约测试、端到端场景、安全/迁移/恢复测试。
|
|
6. 更新能力矩阵，独立提交；不以大批量文件搬运冒充功能完成。
|
|
|
|
## 7. 停止条件
|
|
|
|
任一情况发生即停止：备份或恢复验证失败、哈希不一致、无法解释未跟踪文件、真实秘密进入候选提交、目标契约尚未确认、服务边界不清、身份连续性或数据删除风险未处理、首提交范围超出清单。
|