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.4 KiB

Raw Blame History

ENGINEERING_SPEC — ECR-001 Structural Realignment

回答「怎么实现」。默认 move/extract，禁止 rewrite。

Doc	Link
ECR	`docs/ECR/ECR-001-structural-realignment.md`
PRODUCT_SPEC	`docs/PRODUCT_SPEC/ECR-001-structural-realignment.md`
Coding	`.ai/coding.md`（≤50 行函数 · ≤400 行文件）
Go boundaries	`.ai/architecture/go-services.md`

Diagnosis summary（Evidence）

区域	现状	目标
调用链	已符合冻结架构	保持
栈	Go/gin + Vue3 + PG	锁定（见 `docs/TECH_STACK.md`）
H5 页面体积	多页 >400 行，首页/合盘 >1000	拆至 ≤400；逻辑进 `composables/`
Go service 地图	membership/order 文档有、包无	抽 `service/membership` · `service/order`（或合并 membership 包内 order）
引擎包	`internal/{portrait,relation,star,ask,scale,…}` + `service/*`	文档写清：engine=纯计算，service=用例+权益
词表张力	`star/fortune` · JSON `lucky`	子 ECR：内部改名；对外字段兼容策略
packages	sdk 已用；types 薄；无 hooks 目录	补 types；建 `src/composables/`
Legacy	静态资源已删	同步 `LEGACY.md` / CLAUDE Legacy 段

Module Design

Phase A — Governance（可与文档同批，仍无 apps 行为改）

项	值
Responsibility	固化 ESS↔`.ai/` 双轨；更新过时 Legacy 描述
Can	ADR-0007、Profile/Rules 指针、LEGACY.md
Cannot	改业务代码
Layer	docs / `.ai`

Phase B — H5 page decomposition

项	值
Responsibility	拆超标 SFC；抽 composable；不改路由契约
Can	新组件、`src/composables/*`、样式随迁
Cannot	改 API path、改 Tab IA、夹带视觉改版
Layer	`apps/user-h5`
Priority files	`HomePage.vue` · `SynastryPage.vue` · `StarProfilePage.vue` · `ReportPage.vue` · `ProfilePage.vue` · `AskPage.vue`

门槛：每个目标页 ≤400 行；单函数 ≤50 行（模板段合理除外，脚本逻辑必须拆）。

Phase C — Go service map alignment

项	值
Responsibility	将 Membership/Order 从 `service/report` 迁出；handler 仅改 import/构造
Can	新包、搬移方法、补接口在 handler 侧
Cannot	改 SQL 语义、改 HTTP 路径、改裁剪规则
Layer	`apps/api/internal/service/*` · `handler/report.go`
Tests	`internal/integration` Membership / Order 路径必跑

Phase D — Engine file splits

项	值
Responsibility	`relation/engine.go`、过大 star 文件按纯函数块拆文件
Can	同包多文件；导出表面兼容
Cannot	改计分结果；跨层把 engine 逻辑塞进 handler
Layer	`internal/relation` · `internal/star` · `internal/portrait`

Phase E — Lexicon / package hygiene（子 ECR 建议）

项	值
Responsibility	消解 `fortune` 包名与对外 `lucky` 张力
Can	内部 rename；兼容 alias；必要时 OpenAPI 标注 deprecated
Cannot	无 ADR 破坏已上线客户端字段
Layer	api + sdk/types + 可能 H5

本父 ECR 不直接开工 Phase E 代码；先立 ECR-002。

Phase F — packages + api surface

项	值
Responsibility	types 与 sdk 方法与 OpenAPI/`proto/openapi.yaml` 对齐；页面禁止旁路
Can	补类型与 client 方法
Cannot	页面 `fetch`；扩大任意 `any`
Layer	`packages/*` · `apps/user-h5/src/api`

Interfaces（约束）

Handler (bind/validate)
  → Service (use-case + entitlement)
    → Engine packages (pure-ish compute; no gin.Context)
    → Repository (SQL)

Membership 判定不得下沉到 Repository 或 H5。

Data Model

无 schema 变更（父 ECR）。若 Phase E 需列迁移 → 子 ECR + .ai/database.md。

Error Handling

Case	Behavior
拆分后编译失败	禁止合并；恢复单文件直至测试绿
集成测试红	阻断 Phase Done
误改文案	Reviewer BLOCK

Config / Constants

不新增环境变量。本地仍：本机 Go + Vite + compose 仅 DB。

Test Plan Pointer

见 docs/HANDOFF/ECR-001-implementation-plan.md §Tests。
映射 ECR Acceptance + .ai/testing.md L0–L3。

Migration / API Impact

父 ECR：无公共 API / DB migration。
Phase E：另案。

4.4 KiB Raw Blame History Unescape Escape