docs(migration): establish preservation-first charter
This commit is contained in:
leefer
@@ -0,0 +1,23 @@
|
||||
# 小白复盘仓库执行约束
|
||||
|
||||
本文件对仓库内所有后续编码任务生效。任何智能体在修改文件前必须完整读取：
|
||||
|
||||
1. `docs/migration/原版保真迁移总纲.md`
|
||||
2. `docs/migration/保真迁移状态.json`
|
||||
3. `docs/migration/next失败冻结记录.md`
|
||||
4. 与本次功能有关的原版源码、页面和测试
|
||||
|
||||
## 不可违反
|
||||
|
||||
- 当前根目录原版是唯一功能、视觉、交互、动画和计算基线。
|
||||
- `next/`是失败冻结实现，禁止部署、继续开发或作为新迁移代码来源。
|
||||
- 后续迁移是原代码保真式整理，不是重写、重新设计或更换技术栈。
|
||||
- 不得根据规格说明书重新实现已经存在的功能；规格书只用于盘点，冲突必须交给用户裁决。
|
||||
- 不得改变用户可观察行为。源码可以移动、拆分和调整引用，但输出必须等价。
|
||||
- 不确定是否有用的代码默认保留。没有引用扫描、运行证据和新旧对比，不得删除。
|
||||
- 每次只处理一个完整纵向功能切片，并同步更新迁移账本和状态文件。
|
||||
- 每个切片必须具有原版基线、新版结果、API/数据库对比、页面与交互对比及Git回档点。
|
||||
- 不以新实现自身测试通过、目录更整齐或代码行数减少证明迁移成功。
|
||||
- 未经用户人工确认，不得宣称视觉等价、完成迁移、切换Docker/NAS或删除原版。
|
||||
|
||||
如果任务要求与以上约束冲突，停止迁移并向用户说明冲突，不自行选择新产品行为。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 迁移文档入口
|
||||
|
||||
后续恢复迁移工作时按以下顺序读取，禁止从历史阶段文档直接继续：
|
||||
|
||||
1. [`../../AGENTS.md`](../../AGENTS.md)：仓库级不可违反约束。
|
||||
2. [`原版保真迁移总纲.md`](原版保真迁移总纲.md)：当前唯一有效的迁移方法。
|
||||
3. [`保真迁移状态.json`](保真迁移状态.json)：机器可读当前状态和下一步。
|
||||
4. [`保真迁移账本.md`](保真迁移账本.md)：连续检查点、资产处置和决策记录。
|
||||
5. [`next失败冻结记录.md`](next失败冻结记录.md)：失败实现的隔离边界。
|
||||
|
||||
`重建迁移章程.md`及`next/`内阶段文档均是失败过程历史记录，不再指导后续实施。
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"updated_at": "2026-07-30T22:51:21+08:00",
|
||||
"status": "preparation",
|
||||
"migration_mode": "behavior_preserving_source_migration",
|
||||
"source_of_truth": "current_original_webapp_runtime_and_source",
|
||||
"source_root": ".",
|
||||
"target_root": null,
|
||||
"failed_roots": [
|
||||
"next"
|
||||
],
|
||||
"current_slice": null,
|
||||
"last_checkpoint": "xiaobai-preservation-migration-charter-20260730",
|
||||
"next_action": "inventory_original_assets_and_propose_target_structure_before_copying_code",
|
||||
"authoritative_documents": [
|
||||
"AGENTS.md",
|
||||
"docs/migration/原版保真迁移总纲.md",
|
||||
"docs/migration/保真迁移账本.md",
|
||||
"docs/migration/next失败冻结记录.md"
|
||||
],
|
||||
"hard_invariants": [
|
||||
"do_not_use_next_as_migration_source",
|
||||
"do_not_rewrite_existing_product_behavior",
|
||||
"do_not_change_technology_stack_without_explicit_user_approval",
|
||||
"preserve_visual_interaction_animation_calculation_and_data_semantics",
|
||||
"require_old_new_differential_evidence_for_every_slice",
|
||||
"keep_original_runtime_available",
|
||||
"do_not_delete_uncertain_code"
|
||||
],
|
||||
"open_decisions": [
|
||||
"target_directory_name",
|
||||
"target_directory_structure",
|
||||
"migration_slice_order"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
# 小白复盘保真迁移账本
|
||||
|
||||
> 当前状态：准备期，尚未开始业务代码迁移
|
||||
|
||||
本账本是上下文恢复和人工审计的连续记录。任何迁移提交必须在同一提交中更新本文件及
|
||||
`保真迁移状态.json`。
|
||||
|
||||
## 固定事实
|
||||
|
||||
- 原版根目录是唯一产品和视觉基线。
|
||||
- `next/`已被用户否决并冻结，不进入后续迁移。
|
||||
- 新目标目录尚未命名或建立。
|
||||
- 后续采用原代码保真式迁移，不重新实现，不更换技术栈。
|
||||
|
||||
## 当前检查点
|
||||
|
||||
| 日期 | 提交或标签 | 事件 | 结论 |
|
||||
|---|---|---|---|
|
||||
| 2026-07-30 | `xiaobai-next-rejected-20260730` | 冻结失败的`next/`实现 | 禁止部署或继续开发 |
|
||||
| 2026-07-30 | `xiaobai-preservation-migration-charter-20260730` | 建立保真迁移总纲、状态和恢复协议 | 尚未开始新迁移 |
|
||||
|
||||
## 资产处置登记
|
||||
|
||||
开始清查后，每个资产必须登记，禁止只记录已迁移项而遗漏未处理项。
|
||||
|
||||
| 原位置/符号 | 类型 | 消费者 | 处置 | 新位置 | 等价证据 | 状态 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 待清查 | - | - | 待定 | - | - | 未开始 |
|
||||
|
||||
处置只允许：`原样保留`、`移动`、`合并重复`、`待定`、`确认废弃`。
|
||||
|
||||
## 切片记录
|
||||
|
||||
每个切片记录以下内容：原版基线、复制范围、必要路径调整、差异测试、人工验收、未关闭问题和回档提交。
|
||||
当前没有进行中的切片。
|
||||
|
||||
## 决策记录
|
||||
|
||||
| 日期 | 决策 | 原因 |
|
||||
|---|---|---|
|
||||
| 2026-07-30 | 原版运行行为优先，规格书只用于盘点 | 防止再次依据文字重新开发 |
|
||||
| 2026-07-30 | 不使用`next/`作为后续迁移起点 | 用户确认其视觉、布局和基础功能不可用 |
|
||||
| 2026-07-30 | 目标结构确认前不创建业务目录 | 防止目录先行后再次补写功能 |
|
||||
|
||||
## 恢复工作检查
|
||||
|
||||
- [ ] 已阅读`AGENTS.md`与保真迁移总纲。
|
||||
- [ ] 已读取状态JSON和本账本最后一项。
|
||||
- [ ] 已确认Git工作区和基线提交。
|
||||
- [ ] 已确认没有修改`next/`或正式数据。
|
||||
- [ ] 已说明当前切片及新旧等价证据。
|
||||
- [ ] 已在编辑前确认没有未关闭差异。
|
||||
@@ -0,0 +1,128 @@
|
||||
# 小白复盘原版保真迁移总纲
|
||||
|
||||
> 状态：准备期
|
||||
> 建立日期：2026-07-30
|
||||
> 迁移性质：保行为、保视觉、保数据语义的源代码整理
|
||||
|
||||
## 1. 唯一目标
|
||||
|
||||
以当前可运行原版`webapp`为唯一母版，在尚未命名的新目录中建立更容易检索、理解和人工维护的
|
||||
代码结构。迁移后的系统必须继续使用原版已经验收的功能、视觉、布局、动画、计算逻辑和交互，
|
||||
不得依据说明文字重新开发一个相似产品。
|
||||
|
||||
本次工作相当于把原文件柜中的有效原件逐项分类搬入新文件柜，而不是重新制作原件。
|
||||
|
||||
## 2. 事实裁决顺序
|
||||
|
||||
发生不一致时按以下顺序处理：
|
||||
|
||||
1. 用户在当前或后续对话中的明确决定。
|
||||
2. 原版在相同代码、数据、账号、配置、日期、主题和视口下的真实运行行为。
|
||||
3. 原版源码、数据库结构、静态资产和现有测试共同证明的行为。
|
||||
4. 《小白复盘完整产品规格说明书》用于盘点和解释，不得自行覆盖原版行为。
|
||||
5. 无法确定时记录为待裁决，保持原状，不推测、不补全。
|
||||
|
||||
只有用户明确指出原版是Bug或要求改变时，才允许产生用户可观察差异，并必须单独记录。
|
||||
|
||||
## 3. 必须保持不变
|
||||
|
||||
- 全部页面、入口、功能和细节能力。
|
||||
- PC与移动端布局、尺寸、字体、颜色、间距、滚动和响应式行为。
|
||||
- 日间、夜间、加载、空、错误、禁用、悬停、选中和完成状态。
|
||||
- 动画素材、形态、时序、过场、循环、静音和减少动态效果行为。
|
||||
- API路径、请求、响应、错误语义和流式传输行为。
|
||||
- 数据来源职责、日期、单位、复权、缺失、覆盖率、新鲜度和降级规则。
|
||||
- 权限、会员、管理员标识、账户隔离和私有数据边界。
|
||||
- 情绪、竞价、股池、选股、问天及统计计算结果。
|
||||
- 数据库现有记录、唯一约束、历史兼容和后台任务语义。
|
||||
|
||||
## 4. 允许与禁止
|
||||
|
||||
允许：
|
||||
|
||||
- 移动文件并调整导入路径。
|
||||
- 将巨型文件按已经存在的职责拆分。
|
||||
- 抽出实际重复且行为相同的实现，让原调用方指向唯一实现。
|
||||
- 为原行为增加刻画测试、API快照、数据库对比和视觉回归。
|
||||
- 删除已证明无引用、无运行路径、无视觉影响、无数据兼容责任的代码。
|
||||
|
||||
禁止：
|
||||
|
||||
- 更换前端框架、后端框架、数据库或主要技术栈。
|
||||
- 重写已经存在的页面、样式、动画、公式或数据流程。
|
||||
- 以新的设计令牌、组件库或架构偏好改变最终视觉。
|
||||
- 先建立空架构，再依据规格书补写功能。
|
||||
- 以“更合理”为由修复未被用户确认的原版行为。
|
||||
- 复制`next/`中的产品实现进入新的迁移目录。
|
||||
- 为追求行数、文件数或测试数量而删除有效代码或制造空抽象。
|
||||
|
||||
## 5. 迁移单位
|
||||
|
||||
代码不能像独立照片一样任意逐文件搬运。每次迁移一个完整纵向切片：
|
||||
|
||||
```text
|
||||
用户入口 -> 页面结构 -> 样式与动画 -> 前端状态 -> API -> 业务计算 -> 数据库/外部数据
|
||||
```
|
||||
|
||||
切片内部可以先原样复制，再在保持输出不变的前提下拆分。不得只搬页面而稍后重写接口，也不得先
|
||||
重建全部后端再补前端。
|
||||
|
||||
## 6. 固定工作流
|
||||
|
||||
1. 冻结原版基线提交，使用数据副本，不写正式数据。
|
||||
2. 建立资产清单和依赖图，逐项标记保留、移动、合并、待定或确认废弃。
|
||||
3. 先规划目标目录职责；未确认前不建立业务代码。
|
||||
4. 为待迁移切片记录原版API、数据库副作用、页面状态、截图和交互流程。
|
||||
5. 从原版复制对应实现和资产，只调整迁移所必需的路径与依赖。
|
||||
6. 对新旧版本执行同输入差异测试，结果不等价则回退本切片。
|
||||
7. 等价后才允许拆分或去重；每次拆分再次执行同一组差异测试。
|
||||
8. 更新迁移账本、状态文件和Git回档点，再进入下一个切片。
|
||||
9. 所有切片完成后执行全量并行验收，用户确认前不切换部署。
|
||||
|
||||
## 7. 等价证据
|
||||
|
||||
每个切片至少同时具备：
|
||||
|
||||
| 证据 | 要求 |
|
||||
|---|---|
|
||||
| 源码映射 | 原文件、符号和资产到新位置的逐项记录 |
|
||||
| API差异 | 同请求的状态码、字段、值、顺序和错误一致 |
|
||||
| 数据库差异 | 同操作的新增、修改、删除和事务结果一致 |
|
||||
| 计算差异 | 固定输入得到逐字段相同结果 |
|
||||
| 页面差异 | 同数据、主题和视口的截图及结构比较 |
|
||||
| 交互差异 | 点击、键盘、滚动、弹窗、动画和刷新流程一致 |
|
||||
| 人工确认 | 用户确认视觉与使用感受没有偏差 |
|
||||
|
||||
新版本自身的单元测试只能作为辅助，不能代替新旧差异证据。
|
||||
|
||||
## 8. 删除规则
|
||||
|
||||
任何代码只有同时满足以下条件才可不迁移或删除：
|
||||
|
||||
1. 静态引用和动态注册扫描均无消费者。
|
||||
2. 运行覆盖和真实浏览器流程未经过该路径。
|
||||
3. 不承担数据库迁移、历史兼容、配置读取或资源加载责任。
|
||||
4. 删除后原版与迁移版的全量差异测试仍一致。
|
||||
5. 迁移账本记录理由、证据和恢复提交。
|
||||
|
||||
条件不足时标记`待定`并保留，不能凭代码外观判断。
|
||||
|
||||
## 9. 上下文恢复协议
|
||||
|
||||
每次新任务、上下文压缩或执行中断后，必须先完成：
|
||||
|
||||
1. 读取仓库根目录`AGENTS.md`。
|
||||
2. 读取本总纲、`保真迁移状态.json`及迁移账本。
|
||||
3. 确认`next/`仍处于失败冻结状态。
|
||||
4. 检查Git状态、当前基线提交和最后回档点。
|
||||
5. 查看正在迁移切片的原版证据与未关闭差异。
|
||||
6. 在继续编辑前向用户简述当前阶段、硬约束和下一步。
|
||||
|
||||
不得根据聊天摘要重新发明阶段、技术栈或验收口径。
|
||||
|
||||
## 10. 当前边界
|
||||
|
||||
- `next/`已失败冻结，不是迁移起点。
|
||||
- 当前尚未确定新目录名称、目标目录结构和迁移阶段。
|
||||
- 在完成原版资产清查和用户确认总体方案前，不开始复制业务代码。
|
||||
- 原版保持唯一可运行产品，不执行Docker切换或数据清理。
|
||||
@@ -1,5 +1,10 @@
|
||||
# 小白复盘完整产品规格说明书
|
||||
|
||||
> **2026-07-30保真迁移补充裁决：** 当前任务不再是依据本文“从零重建”，而是整理迁移原版源码。
|
||||
> 原版真实运行行为、源码、样式和资产是保真基线；本文只用于功能盘点和解释。本文与原版不一致时
|
||||
> 不得由实施者自行按本文重写，必须保持原状并交由用户裁决。完整约束见
|
||||
> [`../migration/原版保真迁移总纲.md`](../migration/原版保真迁移总纲.md)。
|
||||
|
||||
> 文档性质：产品事实与重建规格（Single Source of Product Truth）
|
||||
> 适用场景：在不读取旧代码、不依赖历史对话的前提下，从零重建“小白复盘”
|
||||
> 基准日期：2026-07-29
|
||||
|
||||
Reference in New Issue
Block a user