jackyu66gitandCursor
19d3cd5945
绑定 ESS 双轨治理，拆分超大 H5 页与 Go 引擎，抽出 membership 服务， 并将 star/fortune 重命名为 outlook（JSON 双写兼容）；同时修复 /psy API 代理与首页 + 菜单层级。 Co-authored-by: Cursor <cursoragent@cursor.com>
81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
# 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
|