Files

T

jackyu66gitandCursor 19d3cd5945 refactor(ECR-001): 接入 ESS 并完成结构对齐 Phase A–E

绑定 ESS 双轨治理，拆分超大 H5 页与 Go 引擎，抽出 membership 服务，
并将 star/fortune 重命名为 outlook（JSON 双写兼容）；同时修复 /psy API 代理与首页 + 菜单层级。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-05 17:51:40 +08:00

4.3 KiB

Raw Blame History

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

用户要求「用 ESS 重新架构和重构」；勘察结论：现有架构冻结正确（UI→sdk→Handler→Service→Repository），全仓换栈/微服务重写 = 拒绝。
真实债务（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 再去扩展已删路径。
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

4.3 KiB Raw Blame History Unescape Escape