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