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
parent 583133dd09
commit 19d3cd5945
75 changed files with 4199 additions and 2505 deletions
@@ -0,0 +1,45 @@
+# Handoff
+
+**From:** ARCHITECT  
+**To:** ENGINEER  
+**ECR:** ECR-001  
+**State:** design → ready_for_engineering（Phase A/B 待领取）  
+**Date:** 2026-08-05  
+
+## Artifacts
+
+- [x] ECR (Approved) — `docs/ECR/ECR-001-structural-realignment.md`
+- [x] PRODUCT_SPEC — `docs/PRODUCT_SPEC/ECR-001-structural-realignment.md`
+- [x] ENGINEERING_SPEC — `docs/ENGINEERING_SPEC/ECR-001-structural-realignment.md`
+- [x] RISK_REVIEW — N/A
+- [x] IMPLEMENTATION_PLAN / TEST_PLAN — `docs/HANDOFF/ECR-001-implementation-plan.md`
+- [x] TRACEABILITY updated
+- [ ] TEST_REPORT / CODE_REVIEW — Engineer per Phase
+- [x] ADR-0007 — `.ai/adr/0007-ess-ai-dual-track.md`
+
+## Restrictions — Do not modify
+
+- 公共 API URL / envelope
+- 用户可见文案与交互语义（除非子 ECR）
+- 技术栈与 monorepo 边界
+- 一次 PR 多个 Phase
+- `internal/star/fortune` 破坏性重命名（归 ECR-002）
+
+## Goal for receiver
+
+1. 领取 **Phase A**（文档对齐）或直接 **Phase B**（H5 拆页，推荐先做最大痛点）。
+2. 为该 Phase 建 `docs/TASKS/TASK-*-ECR001-phaseX.yaml`，`role: engineer`。
+3. 实现后：`ess-validate --phase coding` + 本仓 DoD Review Report。
+4. 绿则更新 `docs/STATE/` owner → reviewer。
+
+## Done for this hop
+
+- [x] 架构诊断：全仓重写否决；分阶段结构对齐
+- [x] ESS 工件齐备
+- [x] 双轨 ADR Accepted
+
+## References
+
+- `docs/PROJECT_PROFILE.md`
+- `.ai/coding.md` · `.ai/architecture.md` · `.ai/architecture/go-services.md`
+- Evidence：H5/Go 行数勘察（2026-08-05）
@@ -0,0 +1,29 @@
+# Handoff
+
+**From:** ENGINEER  
+**To:** REVIEWER  
+**ECR:** ECR-001 Phase B  
+**State:** coding → review  
+**Date:** 2026-08-05  
+
+## Artifacts
+- [x] Code — HomePage / SynastryPage 拆分
+- [x] TEST_REPORT — `docs/TEST_REPORT/ECR-001-phaseB.md`
+- [x] Task — `docs/TASKS/TASK-20260805-ECR001-phaseB.yaml`
+- [ ] CODE_REVIEW — Reviewer
+
+## What changed
+- `HomePage.vue` 1065 → 133：`components/home/*` + `useHomePage` / `useHomeMood` / `homeCatalog`
+- `SynastryPage.vue` 1015 → 187：`components/synastry/*` + `useSynastryPage`
+- 无 API / 文案语义 / 路由变更意图
+
+## Restrictions still active
+- 勿混 Phase C–F
+- 勿改 fortune / membership 抽出（其它 Phase）
+
+## Goal for Reviewer
+- 确认无行为漂移；抽查首页与合盘关键路径
+- PASS 则 STATE.owner → release_manager 或按流程回 Architect 开下一 Phase Task
+
+## Done for this hop
+- [x] Phase B 两优先页拆完且 build/单测绿
@@ -0,0 +1,70 @@
+# Implementation Plan: ECR-001
+
+**Author:** Architect Agent  
+**For:** Engineer Agent  
+
+## Scope reminder
+
+**Allowed / Forbidden：** 见 `docs/ECR/ECR-001-structural-realignment.md`。  
+**默认：无用户可见行为变更。**
+
+## Steps（按序；每步独立 PR + Task）
+
+### Phase A — Governance docs（可 Architect 收尾 / Engineer 轻触）
+
+1. 确认 ADR-0007 已存在且 Profile 已指向双轨。
+2. 更新 `LEGACY.md` + `CLAUDE.md` Legacy 段：标明静态 `css/js/pages/yuxingu.html` 已删除；勿再扩展。
+3. 同步 `.ai/architecture/go-services.md`：**标注** membership/order 当前寄居于 report（实现前真相），并写「目标态」指向 Phase C。
+
+### Phase B — H5 拆页（优先）
+
+1. `HomePage.vue`：抽入口九宫格、推荐区、档案摘要 → components/composables。
+2. `SynastryPage.vue`：图表 / 表单 / 结果区拆分。
+3. 其余超标页按 ENGINEERING_SPEC 优先级逐个拆。
+4. 每页：`npm run build:h5`；相关 vitest；必要时 e2e 主路径。
+
+### Phase C — Go membership/order 抽出
+
+1. 新建 `internal/service/membership`（含 GetMembership / 配额相关从 report 迁入的用例）。
+2. Order 创建迁入 `membership` 或独立 `order` 包（二选一，Prefer：`membership` 内 order 若文件仍 <400）。
+3. `ReportHandler` 改为依赖新 service；路由注册不变。
+4. 跑 `go test ./...` + `internal/integration` Membership。
+
+### Phase D — Engine 拆文件
+
+1. `relation/engine.go` 按纯函数/段落拆多文件（同包）。
+2. star 过大文件同类处理。
+3. 引擎单测全绿；禁止改 golden 输出除非测试本有误。
+
+### Phase E — 另立 ECR-002（本计划仅占位）
+
+fortune 包名 / `lucky` 字段卫生 → 不在本父 ECR 编码。
+
+### Phase F — packages 补强
+
+1. 对照 `proto/openapi.yaml` 补 `@yuxingu/types`。
+2. sdk 缺方法补齐；H5 只经 client。
+
+## Files likely touched
+
+| Phase | Paths |
+|-------|--------|
+| A | `LEGACY.md` · `CLAUDE.md` · `.ai/architecture/go-services.md` · `.ai/adr/0007-*` |
+| B | `apps/user-h5/src/pages/*` · `components/*` · `composables/*` |
+| C | `apps/api/internal/service/report/*` · `service/membership/*` · `handler/report.go` · `httpserver` wire |
+| D | `apps/api/internal/relation/*` · `star/*` |
+| F | `packages/types` · `packages/sdk` · `apps/user-h5/src/api` |
+
+## Tests to add
+
+- 搬移/抽函数处：保留或增加表驱动单测
+- Phase C：集成测试不得删减
+- Phase B：优先现有 `PortraitPage.spec.ts` 模式补关键页 smoke（若拆出纯函数）
+
+## Out of scope
+
+- 真支付、新功能、微服务、换栈、Phase E 字段破坏性变更
+
+## Risks
+
+见 ECR Risk 表。Engineer 遇「必须改行为才能编译」→ **停**，回 Architect 开子 ECR。
@@ -0,0 +1,24 @@
+# Handoff
+
+**From:** ENGINEER  
+**To:** REVIEWER  
+**ECR:** ECR-001 Phase A–E · ECR-002  
+**Date:** 2026-08-05  
+
+## Delivered
+
+| Phase | Result |
+|-------|--------|
+| A | LEGACY/ADR/go-services 已对齐（membership 抽出后文档更新） |
+| B | 先前完成 |
+| C | `internal/service/membership`；ReportHandler 接线；URL 不变 |
+| D | relation + star engine 同包拆分 |
+| E | ECR-002：`star/outlook`；双写 `fortune`/`outlook` |
+
+## Verify
+- `go test ./internal/relation/... ./internal/star/... ./internal/integration/` PASS
+- `go build ./cmd/server` PASS
+
+## Restrictions
+- 勿删 JSON `fortune` 旧键（须客户端迁移后再做）
+- Phase F（packages）未做
@@ -0,0 +1,25 @@
+# Implementation Report — ECR-001 Phase B
+
+**Author:** Engineer  
+**Date:** 2026-08-05  
+
+## Scope delivered
+Phase B only：优先拆分 HomePage + SynastryPage。
+
+## Structure
+```
+apps/user-h5/src/
+  composables/useHomeMood.ts, useHomePage.ts, useSynastryPage.ts
+  lib/homeCatalog.ts (+ spec)
+  components/home/* (6)
+  components/synastry/* (3)
+  pages/HomePage.vue, SynastryPage.vue
+```
+
+## Non-goals respected
+无 API / schema / 文案语义变更；未做 Phase C–F。
+
+## Verify
+- build:h5 PASS
+- homeCatalog vitest PASS
+- ess-validate coding（见会话日志）