digital-psychology/docs/BACKEND_DESIGN/BD-2026-012-star-alignment.md

Backend Design: ECR-012 星座对齐收口

Architect 产出；Engineer 只消费本文件。
实现纪律：$ESS_ROOT/technology-governance/BACKEND_STANDARD.md
项目分层权威：.ai/architecture.md

Field	Value
ID	BD-2026-012
ECR	ECR-012
Change Level	L2
Status	Approved
Approved	2026-08-07（Human）
Author	Architect
Date	2026-08-07
Risk	Low

---

Context

• 问题 / 目标：星座/合盘主路径已落地，需 Spec 对齐、H5/报告页一致、测试加厚；默认 不改表结构。
• 非目标：真支付、新模块、换星历、Ops。
• 相关 Spec：star-profile.md；前序 ECR-003（fortune→outlook）。

Architecture Change

• 是否改变分层边界：No
• 受影响层：Application（internal/star 仅按需）· API 文档 · UI（user-h5）

Module Changes

Module	Layer	Change	Must NOT
internal/star / outlook / synastry	Domain/App	仅修偏离 Spec 的 summary/detail 键或文案	新表；换 ephemeris
handler reports/synastry	API	契约不变则不动；OpenAPI 描述可补	Handler SQL
user-h5 star/synastry/report	UI	对齐面板、卫生、分享、测试	直连 DB；真支付
packages/types · sdk	Shared	仅当 OpenAPI/DTO 需同步	发明新领域同义词

Data Flow

Profile(birth*)
  → POST /reports/star | /reports/synastry
  → star engine / synastry.BuildReport
  → GrowthReport summary(outlook, charts, …) + gated detail
  → H5 StarProfilePage | Synastry* | ReportPage
  →（可选）pay-mock deep_access → detail 可见

API Changes

• 契约：proto/openapi.yaml
• 变更：默认 None（路径与语义保持）；允许描述/$ref 补强
• 兼容：禁止重新引入 summary.fortune

Database Changes

• 表 / 字段：无
• Migration Required：NO

Migration Plan

• Required：NO
• 回滚：代码回滚即可

Failure Handling

• 无档案 / 缺生日：Empty 表单（现有）
• detail 无权益：服务端剥离（现有，须保持测试）
• 旧报告缺 outlook：H5 空态，不伪造 fortune

Test Plan

• Unit：outlook bundle keys；H5 fortuneBundleFrom
• Integration：TestFlowStarDeepAccess · synastry charts keys · 禁用词
• E2E：p2 star 路径 mock 含 outlook

Rollback Plan

• git revert 本 ECR；无数据迁移

---

Backend Change Boundary

Change Level: L2
Change: star/synastry Spec alignment (mostly H5 + tests; optional star package hygiene)

Affected:
  Domain: StarProfile / Synastry (existing)
  Application: internal/star* (optional)
  Infrastructure: none (no migration)
  API: OpenAPI docs only (default)
  Migration: Not required
  Tests: integration + H5 + e2e
  Risk: Low

Architecture Regression Check

• 无 Handler 直连 DB
• 不改鉴权面
• 未引入非默认中间件 / 新星历依赖
• 未简化分层
• 无 summary.fortune 回归