# ENGINEERING_SPEC — ECR-001 Structural Realignment

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

## Related

| 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（约束）

```text
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：另案。