# ECR-001

**Title:** 愈心谷结构对齐重构（Evidence-first · 非全仓重写）  
**Status:** Approved  
**Date:** 2026-08-05  
**Change Level:** L3（治理双轨 + 结构边界）/ 实现分阶段按 L2 拆单  

## Change

在 **不更换技术栈、不破坏 P1/P2 已发布 API 行为** 的前提下，用 ESS 流程把仓库从「可运行的 P1 Complete」对齐到可长期演进的结构：双轨治理固化、超标大文件拆分、Go 域包边界澄清、词表/包名卫生、共享 packages 补强。

## Motivation

1. 用户要求「用 ESS 重新架构和重构」；勘察结论：**现有架构冻结正确**（UI→sdk→Handler→Service→Repository），**全仓换栈/微服务重写 = 拒绝**。
2. 真实债务（Evidence）：
   - H5 多页远超 `.ai/coding.md` 400 行硬偏好：`HomePage.vue` 1065、`SynastryPage.vue` 1015、`StarProfilePage.vue` 686 等。
   - Go 引擎单文件偏大：`internal/relation/engine.go` 463、`internal/star/engine.go` 337。
   - `go-services.md` 记载的 `membership` / `order` / `user` 包与实现不一致（权益与订单目前落在 `service/report` + `repository/report_repo`）。
   - 存在 `internal/star/fortune` 包名与 JSON `fortune`/`lucky` 字段，与 `.ai/forbidden.md` / lexicon「禁吉凶恐吓词、禁 fortune 包名」存在张力。
   - `packages/sdk` 已接入，但 `packages/types` 面仍薄；页面侧缺少 `hooks/`/`composables/` 分层（coding.md 期望）。
   - Legacy 静态前端已在 `9f65c11` 大量删除；`LEGACY.md` / 入口文案需同步，避免 Agent 再去扩展已删路径。
3. ESS 已 bind；需正式 ECR 才能进入分阶段 Engineer 实现。

## Scope

### Allowed

- 更新/新增：`docs/**` ESS 工件、`.ai/adr/`（双轨治理 ADR）、必要时同步 `.ai/architecture/go-services.md` / `LEGACY.md` 描述
- **行为不变** 的结构重构：Vue 拆组件/composable、Go 按职责拆文件/子包、补测试保持绿
- 将 `membership`/`order` 从 `report` 服务中 **抽出独立 service 包**（URL 与 envelope 不变）
- 内部包重命名计划（如 `fortune` → lexicon 合规名）+ 必要时 OpenAPI/字段迁移 ADR（单独子 ECR）
- 增强 `packages/types` / sdk 方法面，页面继续经 `@/api/client` → sdk

### Forbidden

- 换语言/换前端框架/拆微服务/引入 GraphQL 作主 API
- 改变 `{code,message,data}` 或无 ADR 改公共 URL
- 混入新功能行为或扩 P2 产品能力
- Architect / 本 ECR 交付物直接改 `apps/`/`packages/` 生产实现（实现归 Engineer + 子 Task）
- Docker-only 日常开发工作流
- 一次性「大爆炸」PR 覆盖全部 Phase

## Risk

| Risk | Mitigation |
|------|------------|
| 大页拆分导致 UI 回归 | 每 Phase 单关注点；L0 build + 相关单测/e2e；禁止改文案/交互语义 |
| 抽 membership/order 破坏权益裁剪 | 先搬移再改内部 API；集成测试 `p1_flows` Membership 必绿 |
| fortune 重命名破坏客户端 | 单独子 ECR；先内部包名，JSON 字段需兼容期或版本策略 |
| 双轨文档冲突 | ADR-0007：冲突时领域/DoD 以 `.ai/` 为准，流程以 ESS `docs/` 为准 |
| 范围膨胀成重写 | Acceptance 明确「无行为变更」；Reviewer 卡混 feature |

## Acceptance Criteria

- [ ] ADR-0007（`.ai/` ↔ ESS 双轨）Accepted 并写入 Profile Pointers
- [ ] ENGINEERING_SPEC + IMPLEMENTATION_PLAN 分 Phase A–F 可执行
- [ ] 每个实现 Phase 有独立 Task Contract；单 PR 单 Phase
- [ ] Phase 完成后：相关 `go test` / `build:h5` / 既有 e2e 主路径不回归
- [ ] 超标页/引擎有明确拆分目标与「完成后行数」门槛（见 ENGINEERING_SPEC）
- [ ] TRACEABILITY / CHANGELOG / STATE 已更新
- [ ] TEST_REPORT greened per Phase（Engineer）
- [ ] Docs + CHANGELOG

## Rollback

- 治理文档：revert `docs/` + ADR commit
- 代码 Phase：git revert 该 Phase PR；DB 无迁移则无需 rollback schema（本 ECR 默认无 schema 变更；若子 ECR 含迁移则按其 Rollback）

## Risk Review

- Path: N/A（非交易域）

## Linked

- PRODUCT_SPEC: `docs/PRODUCT_SPEC/ECR-001-structural-realignment.md`
- ENGINEERING_SPEC: `docs/ENGINEERING_SPEC/ECR-001-structural-realignment.md`
- IMPLEMENTATION_PLAN: `docs/HANDOFF/ECR-001-implementation-plan.md`
- HANDOFF: `docs/HANDOFF/ECR-001-architect-to-engineer.md`
- ADR: `.ai/adr/0007-ess-ai-dual-track.md`（待写入）
- TRACEABILITY row: Yes