diff --git a/.ai/domain/README.md b/.ai/domain/README.md index 40f3fc4..4288839 100644 --- a/.ai/domain/README.md +++ b/.ai/domain/README.md @@ -3,5 +3,10 @@ | File | Purpose | |---|---| | [../domain.md](../domain.md) | Tech ↔ 用户名 | -| [domain-map.md](domain-map.md) | Bounded contexts（冻结） | +| [domain-map.md](domain-map.md) | Bounded contexts（P1 冻结 + Ops Wave 0 Draft） | | [erd.md](erd.md) | P1 表结构草案（冻结） | +| [boundary-rules.md](boundary-rules.md) | BC owns / allowed / forbidden（**P0** · Wave 0） | +| [glossary.yaml](glossary.yaml) | 工程/API 唯一词（与 lexicon 双轨） | +| [entity-catalog.md](entity-catalog.md) | 概念级实体目录（无 migration） | + +Ops Contract-First 归档：`docs/WAVE0/`。 diff --git a/.ai/domain/boundary-rules.md b/.ai/domain/boundary-rules.md new file mode 100644 index 0000000..d36a31e --- /dev/null +++ b/.ai/domain/boundary-rules.md @@ -0,0 +1,239 @@ +# Bounded Context Boundary Rules + +> Wave 0 · **P0 资产** · AI / Engineer 只读；变更须 Architect + Human +> 运行时权威副本：`.ai/domain/boundary-rules.md` + +Status: `Draft`（Human Review 后 Frozen） + +--- + +## 如何读 + +- **owns**：该 BC **唯一写权威**（修改入口）。 +- **does_not_own**：明示禁止「顺手改」。 +- **allowed**：允许的依赖（多为读或经门面）。 +- **forbidden**：禁止的依赖（含跨 BC 写支付/会员等）。 + +违反本文件 = Reviewer **BLOCK**（架构回归）。 + +--- + +## Admin_Auth_Audit + +```yaml +Admin_Auth_Audit: + owns: + - AdminAccount + - AdminSession + - AuditLog + does_not_own: + - UserStatus + - MembershipPlan + - Entitlement + allowed: + - Admin_RBAC.read + forbidden: + - Payment.write + - C端业务聚合根的隐式写入 +``` + +## Admin_RBAC + +```yaml +Admin_RBAC: + owns: + - AdminRole + - AdminPermission + does_not_own: + - User + - Profile + - Membership + allowed: + - Admin_Auth_Audit.write_audit + forbidden: + - Payment + - Membership.write + - DeviceAuth.user_token_issue +``` + +## Identity_Profile + +```yaml +Identity_Profile: + owns: + - User + - Profile + - DeviceIdentity + - UserStatus + - BehaviorSnapshot + - PsychologicalTagSet + does_not_own: + - MembershipPlan + - Entitlement + - Order + - Payment + - RedemptionCode + allowed: + - Analytics_OpsB.read + forbidden: + - Payment + - Membership.write +``` + +## Membership_Orders + +```yaml +Membership_Orders: + owns: + - MembershipPlan + - Entitlement + - Membership + - Order + - DeepAccess + - RedemptionCode + - Payment # mock 今；真支付适配器后置，仍归本 BC + does_not_own: + - UserStatus + - AdminRole + - FilterRule + allowed: + - Identity_Profile.read + forbidden: + - Ask_Ops.write_prompt + - Content_Safety.rule_mutate_via_order +``` + +## Analytics_OpsB + +```yaml +Analytics_OpsB: + owns: + - AnalyticsSession + - AnalyticsEvent + does_not_own: + - User + - Membership + allowed: + - Identity_Profile.read_ids_only + forbidden: + - Payment + - 采集 PII 正文（生日/问答全文等） +``` + +## Ops_Content + +```yaml +Ops_Content: + owns: + - HomeTool + - ScalePublishState + does_not_own: + - Scale 题目正文编辑器（未开 ECR 前禁止扩张） + allowed: + - Explore_Reports.publish_gate + forbidden: + - Community + - Payment +``` + +## Account_Risk + +```yaml +Account_Risk: + owns: + - RiskFlag + - BanRecord + does_not_own: + - MembershipPlan + allowed: + - Identity_Profile.UserStatus.transition # 经明确应用服务 + - Admin_Auth_Audit.write_audit + forbidden: + - Payment.refund_silent +``` + +## Content_Safety + +```yaml +Content_Safety: + owns: + - FilterRule + - ModerationCase + - BlockPolicy + - CrisisEvent + - CrisisPolicy + does_not_own: + - Membership + - Payment + - AdminRole + allowed: + - Identity_Profile.read + - Ask_Ops.read_session_meta + forbidden: + - Membership.write + - Payment +``` + +## Ask_Ops + +```yaml +Ask_Ops: + owns: + - AskSessionView + - QualityFeedback + - HandoffCase + - SystemPrompt + - KnowledgeSource + - KnowledgeChunk + - ToolDefinition + does_not_own: + - Payment + - MembershipPlan + - UserStatus + allowed: + - Identity_Profile.read + - Content_Safety.evaluate + forbidden: + - Payment + - Membership.write + - Admin_RBAC.write +``` + +## Ops_CMS_NoUGC + +```yaml +Ops_CMS_NoUGC: + owns: + - Banner + - FeedSlot + - ScheduledPublication + does_not_own: + - UGC Post + - CommentGraph + - TrustScore + allowed: + - Admin_RBAC.check + forbidden: + - Community + - 用户生成内容入库为主路径 +``` + +## Community + +```yaml +Community: + status: Forbidden + owns: [] + note: feature-map UGC 广场 [No]；开启须 L3 ADR + 新 Capability +``` + +--- + +## 反模式（禁止） + +```text +AskService → load User → update Membership → charge Payment +UserService.updateMembership() +Content_Safety 直接改 Entitlement +Ops_CMS 引入「用户帖子」表却声称 NoUGC +``` diff --git a/.ai/domain/domain-map.md b/.ai/domain/domain-map.md index debada8..a3345d7 100644 --- a/.ai/domain/domain-map.md +++ b/.ai/domain/domain-map.md @@ -23,6 +23,26 @@ --- +## Ops Platform Bounded Contexts（Wave 0 Draft） + +> 详细 owns/forbidden：[`boundary-rules.md`](boundary-rules.md) · 词表：[`glossary.yaml`](glossary.yaml) · 实体：[`entity-catalog.md`](entity-catalog.md) +> 归档：`docs/WAVE0/domain/` · Capability：`docs/WAVE0/capability/ops-capability-map.md` +> **不修改**上方 P1 不变量；Ops BC 实现须独立 ECR。 + +| Context | Capability | Status | +|---|---|---| +| Admin_Auth_Audit | AdminGovernance | Shipped Ops-A | +| Admin_RBAC | AdminGovernance | Draft → ECR-013A | +| Analytics_OpsB | GrowthInsights / UserIntelligence(read) | Shipped Ops-B | +| Ops_Content | ExploreConfig (partial) | Shipped Ops-C | +| Account_Risk | AccountLifecycle | Draft | +| Content_Safety | ContentSafety · CrisisCare | Draft | +| Ask_Ops | AskOperations · AICoreConfig | Draft | +| Ops_CMS_NoUGC | OpsCMS | Draft | +| Community | — | **Forbidden** | + +--- + ## Context diagram ``` diff --git a/.ai/domain/entity-catalog.md b/.ai/domain/entity-catalog.md new file mode 100644 index 0000000..5f7ab1f --- /dev/null +++ b/.ai/domain/entity-catalog.md @@ -0,0 +1,43 @@ +# Entity Catalog（Wave 0 · 概念级） + +> 仅登记名称、归属 BC、Capability、生命周期备注。**不建表、不写 migration。** +> 与 [`glossary.yaml`](glossary.yaml) · [`boundary-rules.md`](boundary-rules.md) 一致。 + +Status: `Draft` + +| Entity | BC | Capability | Notes | +|--------|----|------------|-------| +| AdminAccount | Admin_Auth_Audit | AdminGovernance | 已存在 Ops-A | +| AdminSession | Admin_Auth_Audit | AdminGovernance | 已存在 | +| AuditLog | Admin_Auth_Audit | AdminGovernance | 已存在；只追加 | +| AdminRole | Admin_RBAC | AdminGovernance | **ECR-013A** | +| AdminPermission | Admin_RBAC | AdminGovernance | **ECR-013A** | +| User | Identity_Profile | AccountLifecycle | 已存在 | +| Profile | Identity_Profile | UserIntelligence | 已存在 | +| UserStatus | Identity_Profile | AccountLifecycle | **ECR-013B** 状态机 | +| AccountStateTransition | Identity_Profile | AccountLifecycle | **ECR-013B** | +| BehaviorSnapshot | Identity_Profile | UserIntelligence | 未来读模型 | +| PsychologicalTagSet | Identity_Profile | UserIntelligence | 未来读模型 | +| MembershipPlan | Membership_Orders | CommerceEntitlement | 配置面后置 ECR | +| Entitlement | Membership_Orders | CommerceEntitlement | 后置 | +| RedemptionCode | Membership_Orders | CommerceEntitlement | 后置 | +| Membership | Membership_Orders | CommerceEntitlement | 已存在 | +| Order | Membership_Orders | CommerceEntitlement | 已存在 | +| DeepAccess | Membership_Orders | CommerceEntitlement | 已存在 | +| Payment | Membership_Orders | CommerceEntitlement | mock；真支付最后 | +| HomeTool | Ops_Content | ExploreConfig | 已存在 Ops-C | +| ScalePublishState | Ops_Content | ExploreConfig | 已存在 | +| AnalyticsSession / Event | Analytics_OpsB | GrowthInsights | 已存在 Ops-B | +| FilterRule | Content_Safety | ContentSafety | 后置 | +| ModerationCase | Content_Safety | ContentSafety | 后置 | +| CrisisEvent / CrisisPolicy | Content_Safety | CrisisCare | 后置 | +| SystemPrompt / Knowledge* / ToolDefinition | Ask_Ops | AICoreConfig | 后置 | +| AskSessionView / QualityFeedback | Ask_Ops | AskOperations | 后置 | +| Banner / FeedSlot | Ops_CMS_NoUGC | OpsCMS | 后置 | +| UGC* | Community | — | **Forbidden** | + +## 状态机预告（ECR-013B · 仅文档） + +`UserStatus`: `active` → `disabled` | `banned` | `suspended`； +`banned` / `disabled` → C 端 DeviceAuth **拒绝**（细则写入 013B AC）。 +`deleted` soft-delete **不在 013B**（另开）。 diff --git a/.ai/domain/glossary.yaml b/.ai/domain/glossary.yaml new file mode 100644 index 0000000..252bb85 --- /dev/null +++ b/.ai/domain/glossary.yaml @@ -0,0 +1,116 @@ +# domain glossary — engineering / API unique terms + +# Wave 0 Draft. Runtime copy: .ai/domain/glossary.yaml +# User-facing copy stays in .ai/product/lexicon.md +# Conflict: Architect + Human resolve; do not invent synonyms in code. + +version: "0.1.0" +status: draft + +terms: + AdminRole: + zh: 管理员角色 + bc: Admin_RBAC + forbidden: [admin_group, privilege_group] + + AdminPermission: + zh: 管理员权限点 + bc: Admin_RBAC + forbidden: [acl_flag, authz_bit] + + AuditLog: + zh: 操作审计日志 + bc: Admin_Auth_Audit + forbidden: [admin_history] + + UserStatus: + zh: 用户账户状态 + bc: Identity_Profile + values: [active, disabled, banned, suspended] + forbidden: [user_flag, account_level] + + AccountStateTransition: + zh: 账户状态迁移 + bc: Identity_Profile + forbidden: [status_patch_log] + + MembershipPlan: + zh: 会员套餐 + bc: Membership_Orders + forbidden: [package, vip_level, 订阅档, sku_vip] + + Entitlement: + zh: 权益 + bc: Membership_Orders + forbidden: [privilege_pack, benefit_bundle] + + RedemptionCode: + zh: 兑换码 + bc: Membership_Orders + forbidden: [gift_card, activation_key_alias] + + DeepAccess: + zh: 深度版 + bc: Membership_Orders + forbidden: [Unlock, unlock_report] + + BehaviorSnapshot: + zh: 行为快照 + bc: Identity_Profile + forbidden: [user_track_dump] + + PsychologicalTagSet: + zh: 心理标签集 + bc: Identity_Profile + forbidden: [psy_labels_raw] + + FilterRule: + zh: 过滤规则 + bc: Content_Safety + forbidden: [badword_only] + + ModerationCase: + zh: 审核工单 + bc: Content_Safety + forbidden: [review_ticket_ugc] + + CrisisEvent: + zh: 危机事件 + bc: Content_Safety + forbidden: [suicide_flag_public] + + CrisisPolicy: + zh: 危机策略 + bc: Content_Safety + forbidden: [kill_switch_generic] + + SystemPrompt: + zh: 系统提示词 + bc: Ask_Ops + forbidden: [god_prompt] + + KnowledgeSource: + zh: 知识源 + bc: Ask_Ops + forbidden: [rag_file] + + KnowledgeChunk: + zh: 知识块 + bc: Ask_Ops + forbidden: [embedding_row_ui] + + ToolDefinition: + zh: 工具定义 + bc: Ask_Ops + forbidden: [function_call_config_loose] + + Banner: + zh: 运营横幅 + bc: Ops_CMS_NoUGC + forbidden: [story_feed_ugc] + + Community: + zh: （禁止能力） + bc: Community + status: forbidden + forbidden: [ugc_plaza, 社区广场] diff --git a/.ai/product/feature-map.md b/.ai/product/feature-map.md index 22daa74..df450c0 100644 --- a/.ai/product/feature-map.md +++ b/.ai/product/feature-map.md @@ -227,14 +227,16 @@ UI **不出现「塔罗」**。禁止神谕吉凶、恐吓话术。 ## 7. 运营后台（内部 · 非 C 端 Tab） -详见 Spec：[feature-spec/ops-admin.md](feature-spec/ops-admin.md) · ECR-006 +详见 Spec：[feature-spec/ops-admin.md](feature-spec/ops-admin.md) · ECR-006 +**演进规范（Wave 0）：** [`docs/WAVE0/`](../../docs/WAVE0/) · Capability Map · boundary-rules · Contract-First（禁止 Feature 堆砌进实现） | 分期 | 内容 | |---|---| | Phase A `[Ops]` | 登录 · 用户/订单查询 · 会员授予 · 审计 · `apps/admin-h5`（ECR-006 Closed） | | Phase B `[Ops]` | 行为分析：自有埋点 + 管理端「数据」看板（**ECR-007 Closed** · Spec `ops-analytics.md`） | | Phase C `[Ops]` | 内容：首页宫格 CRUD · 测评上下架（**ECR-008 Closed** · Spec `ops-content.md`） | -| Phase D+ | 商业加深 · RBAC · 封禁 · 推送（各开独立 ECR） | +| Phase D+ | **Contract-First**：Capability→BC→Domain→API(+contract_diff)→四类 AC，再 ECR 切片。首波 **ECR-013A** Admin RBAC → **ECR-013B** AccountLifecycle。详见 `docs/WAVE0/`。 | +| 排除 | **UGC / 社区广场**（M10.2）仍 `[No]`；真支付最后 | 不计入 P1 Complete；不进入五 Tab。 diff --git a/docs/WAVE0/VALIDATION_REPORT.md b/docs/WAVE0/VALIDATION_REPORT.md new file mode 100644 index 0000000..528039b --- /dev/null +++ b/docs/WAVE0/VALIDATION_REPORT.md @@ -0,0 +1,78 @@ +# WAVE 0 Validation Report + +Date: 2026-08-07 +Authorization: Human Start Authorization — Execute Wave 0 Contract-First Foundation +Profile: ARCHITECT（无 apps 实现） + +--- + +## Constraints check + +| Constraint | Result | +|------------|--------| +| only `docs/**` + `.ai/domain/**` + `.ai/product/**` | PASS | +| no `apps/**` | PASS | +| no migration | PASS | +| no API/OpenAPI implement change for new RBAC | PASS | +| no ECR-013A/B coding | PASS | +| Loop kernel unchanged | PASS（仅 Domain 文档） | + +--- + +## Locked Artifact List + +```text +docs/WAVE0/ +├── capability/ops-capability-map.md PASS +├── domain/domain-map.md PASS +├── domain/boundary-rules.md PASS +├── domain/glossary.yaml PASS +├── domain/entity-catalog.md PASS +├── contracts/OPS-CONTRACT-TEMPLATE.md PASS +├── contracts/contract_diff.template.yaml PASS (P0) +├── governance/contract-first-rules.md PASS +├── feature-map/feature-map-update.md PASS +└── VALIDATION_REPORT.md PASS (this file) + +Runtime sync: +.ai/domain/boundary-rules.md PASS +.ai/domain/glossary.yaml PASS +.ai/domain/entity-catalog.md PASS +.ai/domain/domain-map.md (Ops section) PASS +.ai/domain/README.md PASS +.ai/product/feature-map.md §7 PASS +docs/CONTRACT_DIFF/README.md PASS (dir ready; no ECR instance) +``` + +--- + +## Quality gates (content) + +| Check | Result | +|-------|--------| +| Capability map 回答「业务能力」而非页面清单 | PASS | +| Community / UGC Forbidden | PASS | +| boundary-rules 含 owns / does_not_own / allowed / forbidden | PASS | +| contract_diff 升为 P0 模板 | PASS | +| ECR-013 拆为 013A/013B 仅文档预告 | PASS | +| glossary 与 lexicon 双轨声明 | PASS | + +--- + +## Verdict + +**WAVE 0 FOUNDATION: PASS** +**Status: `WAVE0 FROZEN CANDIDATE`（待 Human Review Freeze）** + +下一闸门（仍须 Human Start Authorization，Loop 不自启）： + +1. Human Review Checklist（Capability / Boundary / Glossary / Contract / Agent Governance） +2. 明文 **Freeze** 后，方可授权 **ECR-013A Admin RBAC** 契约定义（仍非 coding） + +--- + +## Non-goals confirmed + +- 不改 Engineering Loop v1.1 +- 不实现 M1–M10 +- 不真支付 · 不 UGC diff --git a/docs/WAVE0/capability/ops-capability-map.md b/docs/WAVE0/capability/ops-capability-map.md new file mode 100644 index 0000000..a1966ad --- /dev/null +++ b/docs/WAVE0/capability/ops-capability-map.md @@ -0,0 +1,150 @@ +# Ops Capability Map（L0） + +> Wave 0 · Contract-First · **不是** M1–M10 页面清单 +> 权威副本路径：`docs/WAVE0/capability/ops-capability-map.md` +> 回答：**系统提供什么业务能力？** 而非「有哪些功能页」。 + +Status: `Draft`（Human Review 后可标 Frozen） + +--- + +## 原则 + +1. Capability = 可独立演进的**业务能力**（Purpose + Owned Concepts + 默认 BC）。 +2. 禁止把 Capability 写成路由、按钮、Tab。 +3. 一个 Capability 可映射多个 BC（读模型旁挂允许）；**写所有权**仍以 `boundary-rules` 为准。 +4. M1–M10 仅作**追溯标签**（Trace），不得驱动实现顺序。 + +--- + +## Capability Catalog + +### UserIntelligence + +| 字段 | 内容 | +|------|------| +| Purpose | 让运营理解用户的心理与行为旅程（洞察，非改命） | +| Bounded Contexts | `Identity_Profile`（主）· `Analytics_OpsB`（读） | +| Owned Concepts | `UserProfileView` · `BehaviorSnapshot` · `PsychologicalTagSet` · `InsightReport` | +| Does not own | `MembershipPlan` · `Payment` · `AskMessage` 正文运营改写 | +| Trace | M1.1 | + +### AccountLifecycle + +| 字段 | 内容 | +|------|------| +| Purpose | 管理终端用户账户可用状态与合法迁移 | +| Bounded Contexts | `Identity_Profile` · `Account_Risk` | +| Owned Concepts | `UserStatus` · `AccountStateTransition` | +| Does not own | `Membership` 权益发放 · `AdminRole` | +| Trace | M1.2 · M1.6（封禁与状态交集见 Account_Risk） | + +### CommerceEntitlement + +| 字段 | 内容 | +|------|------| +| Purpose | 定义并履约「谁在何时拥有何种可读/可调用权益」 | +| Bounded Contexts | `Membership_Orders` | +| Owned Concepts | `MembershipPlan` · `Entitlement` · `RedemptionCode` · `Order` · `DeepAccess` | +| Does not own | `UserStatus` · 内容正文 | +| Trace | M1.3–1.5 ·（真支付适配后置） | + +### ExploreConfig + +| 字段 | 内容 | +|------|------| +| Purpose | 运营可配置探索供给（量表/星座/节律/卡片）而不改引擎分层 | +| Bounded Contexts | `Explore_Reports` + 各引擎 Config 面 | +| Owned Concepts | `ScaleDefinition` · `StarConfig` · `RhythmConfig` · `ImageCardDeck` | +| Does not own | C 端报告生成运行时不变式（仍归引擎 BC） | +| Trace | M2.* | + +### AskOperations + +| 字段 | 内容 | +|------|------| +| Purpose | 运营可观测与干预 AI 对话质量（非替代咨询执业） | +| Bounded Contexts | `Ask_Ops` | +| Owned Concepts | `AskSessionView` · `QualityFeedback` · `HandoffCase` | +| Does not own | `Membership` 扣费 · `Payment` | +| Trace | M3.* | + +### AICoreConfig + +| 字段 | 内容 | +|------|------| +| Purpose | 管理 Prompt / RAG / Tools 配置，支撑可复现的 AI 行为 | +| Bounded Contexts | `Ask_Ops`（可后拆 `AI_Config`） | +| Owned Concepts | `SystemPrompt` · `KnowledgeSource` · `KnowledgeChunk` · `ToolDefinition` | +| Does not own | 用户隐私原文长期外泄通道 | +| Trace | M4.* · M5.* | + +### ContentSafety + +| 字段 | 内容 | +|------|------| +| Purpose | 输入/输出内容合规过滤与人工审核兜底 | +| Bounded Contexts | `Content_Safety` | +| Owned Concepts | `FilterRule` · `ModerationCase` · `BlockPolicy` | +| Does not own | `Membership` · `Payment` | +| Trace | M6.* | + +### CrisisCare + +| 字段 | 内容 | +|------|------| +| Purpose | 识别高危意图并触发熔断与干预路径（生命安全优先于功能） | +| Bounded Contexts | `Content_Safety`（可后拆 `Crisis`） | +| Owned Concepts | `CrisisEvent` · `CrisisPolicy` · `InterventionOutcome` | +| Does not own | 医疗诊断结论 | +| Trace | M7.* | + +### GrowthInsights + +| 字段 | 内容 | +|------|------| +| Purpose | 成长报告自动化与运营级增长指标口径 | +| Bounded Contexts | `Explore_Reports` · `Analytics_OpsB` | +| Owned Concepts | `ReportTemplate` · `OpsMetricSnapshot` · `FunnelDefinition` | +| Does not own | 广告投放系统 | +| Trace | M8.* | + +### AdminGovernance + +| 字段 | 内容 | +|------|------| +| Purpose | 后台最小权限、隐私合规请求与可追溯审计 | +| Bounded Contexts | `Admin_Auth_Audit` · `Admin_RBAC` | +| Owned Concepts | `AdminAccount` · `AdminRole` · `AdminPermission` · `AuditLog` · `PrivacyRequest` | +| Does not own | C 端业务聚合根写入（经各 BC API） | +| Trace | M9.* | + +### OpsCMS + +| 字段 | 内容 | +|------|------| +| Purpose | 运营自有内容位（Banner/栏目）定时发布，**非**用户生产内容 | +| Bounded Contexts | `Ops_CMS_NoUGC` | +| Owned Concepts | `Banner` · `FeedSlot` · `ScheduledPublication` | +| Does not own | UGC Post / Comment Graph | +| Trace | M10.1 | + +### Community — **NO** + +| 字段 | 内容 | +|------|------| +| Purpose | — | +| Status | **Forbidden**（feature-map UGC 广场 `[No]`） | +| Note | 若未来要做，须独立 Community BC + L3 ADR + 新 ECR；不得塞进 OpsCMS | +| Trace | M10.2 排除 | + +--- + +## Capability → 首波 ECR 追溯（非实现顺序外的功能堆） + +| 优先实现 Capability | 建议首张 ECR | +|---------------------|--------------| +| `AdminGovernance`（RBAC 最小） | **ECR-013A** | +| `AccountLifecycle` | **ECR-013B**（依赖 013A） | + +其余 Capability 仅登记，**Wave 0 不实现**。 diff --git a/docs/WAVE0/contracts/OPS-CONTRACT-TEMPLATE.md b/docs/WAVE0/contracts/OPS-CONTRACT-TEMPLATE.md new file mode 100644 index 0000000..e1bb013 --- /dev/null +++ b/docs/WAVE0/contracts/OPS-CONTRACT-TEMPLATE.md @@ -0,0 +1,111 @@ +# OPS Contract Template（L0–L4 · Loop 强制） + +> Wave 0 · 每张实现向 ECR / Feature Spec **编码前**必须填满 +> 路径：`docs/WAVE0/contracts/OPS-CONTRACT-TEMPLATE.md` + +复制为：`docs/PRODUCT_SPEC/ECR-xxx-.md` 或 Feature Spec 内嵌同等章节。 + +--- + +## Meta + +| 字段 | 值 | +|------|-----| +| ECR | | +| Status | Draft \| Approved | +| Capability (L0) | 例：`AdminGovernance` | +| Bounded Context (L1) | 例：`Admin_RBAC` | +| Change Level | L2 \| L3 | + +--- + +## L0 Capability + +| 字段 | 内容 | +|------|------| +| Capability ID | | +| Purpose（一句话业务能力） | | +| Why now | | +| Non-goals | | + +禁止写页面/按钮清单。 + +--- + +## L1 Bounded Context + +| 字段 | 内容 | +|------|------| +| Primary BC | | +| owns / does_not_own | 引用或摘录 `boundary-rules.md` | +| allowed / forbidden deps | | + +--- + +## L2 Domain + +| Entity | 不变式 / 状态机 | +|--------|-----------------| +| | | + +Glossary 词必须已在 `.ai/domain/glossary.yaml` 登记。 + +--- + +## L3 API Contract + +| Method | Path | 语义 | +|--------|------|------| +| | | | + +- OpenAPI：`proto/openapi.yaml` 同步意图 +- BD：`docs/BACKEND_DESIGN/BD-*-*.md` +- **必交** [`contract_diff` 模板](contract_diff.template.yaml) → 实例：`docs/CONTRACT_DIFF/ECR-xxx.yaml` + +信封：`{code,message,data}`。Admin ≠ DeviceAuth。 + +--- + +## L4 Acceptance Criteria + +每个 AC 必须有稳定 ID（如 `AC-F-01`）。 + +### Functional AC + +| ID | Given | When | Then | +|----|-------|------|------| +| AC-F-01 | | | | + +### Security AC + +| ID | Given | When | Then | +|----|-------|------|------| +| AC-S-01 | Admin 无权限 | 调用 API | 403 且 AuditLog 有记录 | + +### Performance AC + +| ID | Given | When | Then | +|----|-------|------|------| +| AC-P-01 | N=（写明） | 打开 admin 列表 | P95 <（写明）ms | + +### Observability AC + +| ID | Given | When | Then | +|----|-------|------|------| +| AC-O-01 | 状态迁移发生 | — | AuditLog 存在；若有 trace 则含 trace_id | + +危机类另加 **Safety AC**（独立节，不在本通用表省略生命安全）。 + +--- + +## Evidence（实现后） + +- TEST_REPORT 映射全部 AC-ID +- contract_diff.breaking_change 解释完毕 +- Reviewer 核对 boundary-rules + +--- + +## Forbidden（本切片） + +显式列出：真支付 / UGC / 其他 Capability 偷渡项。 diff --git a/docs/WAVE0/contracts/contract_diff.template.yaml b/docs/WAVE0/contracts/contract_diff.template.yaml new file mode 100644 index 0000000..c5f5b53 --- /dev/null +++ b/docs/WAVE0/contracts/contract_diff.template.yaml @@ -0,0 +1,34 @@ +# contract_diff — template (P0 · required per implement ECR) + +# Copy to: docs/CONTRACT_DIFF/ECR-xxx.yaml +# Guardian / Reviewer: reject coding Approve if missing or breaking without migration notes. + +ecr: ECR-XXX +capability: "" # L0 id +bounded_context: "" # L1 id +change: + type: additive # additive | breaking | deprecate +breaking_change: false +migration_required: false +compatibility_notes: "" + +entities: + - name: ExampleEntity + before: null + after: + fields: + - id + - name + +apis: + - method: GET + path: /api/v1/admin/example + change: added # added | modified | removed + request_delta: null + response_delta: null + +security_impact: + - "AdminAuth required" + +observability_impact: + - "writes AuditLog on mutate" diff --git a/docs/WAVE0/domain/boundary-rules.md b/docs/WAVE0/domain/boundary-rules.md new file mode 100644 index 0000000..d36a31e --- /dev/null +++ b/docs/WAVE0/domain/boundary-rules.md @@ -0,0 +1,239 @@ +# Bounded Context Boundary Rules + +> Wave 0 · **P0 资产** · AI / Engineer 只读；变更须 Architect + Human +> 运行时权威副本：`.ai/domain/boundary-rules.md` + +Status: `Draft`（Human Review 后 Frozen） + +--- + +## 如何读 + +- **owns**：该 BC **唯一写权威**（修改入口）。 +- **does_not_own**：明示禁止「顺手改」。 +- **allowed**：允许的依赖（多为读或经门面）。 +- **forbidden**：禁止的依赖（含跨 BC 写支付/会员等）。 + +违反本文件 = Reviewer **BLOCK**（架构回归）。 + +--- + +## Admin_Auth_Audit + +```yaml +Admin_Auth_Audit: + owns: + - AdminAccount + - AdminSession + - AuditLog + does_not_own: + - UserStatus + - MembershipPlan + - Entitlement + allowed: + - Admin_RBAC.read + forbidden: + - Payment.write + - C端业务聚合根的隐式写入 +``` + +## Admin_RBAC + +```yaml +Admin_RBAC: + owns: + - AdminRole + - AdminPermission + does_not_own: + - User + - Profile + - Membership + allowed: + - Admin_Auth_Audit.write_audit + forbidden: + - Payment + - Membership.write + - DeviceAuth.user_token_issue +``` + +## Identity_Profile + +```yaml +Identity_Profile: + owns: + - User + - Profile + - DeviceIdentity + - UserStatus + - BehaviorSnapshot + - PsychologicalTagSet + does_not_own: + - MembershipPlan + - Entitlement + - Order + - Payment + - RedemptionCode + allowed: + - Analytics_OpsB.read + forbidden: + - Payment + - Membership.write +``` + +## Membership_Orders + +```yaml +Membership_Orders: + owns: + - MembershipPlan + - Entitlement + - Membership + - Order + - DeepAccess + - RedemptionCode + - Payment # mock 今；真支付适配器后置，仍归本 BC + does_not_own: + - UserStatus + - AdminRole + - FilterRule + allowed: + - Identity_Profile.read + forbidden: + - Ask_Ops.write_prompt + - Content_Safety.rule_mutate_via_order +``` + +## Analytics_OpsB + +```yaml +Analytics_OpsB: + owns: + - AnalyticsSession + - AnalyticsEvent + does_not_own: + - User + - Membership + allowed: + - Identity_Profile.read_ids_only + forbidden: + - Payment + - 采集 PII 正文（生日/问答全文等） +``` + +## Ops_Content + +```yaml +Ops_Content: + owns: + - HomeTool + - ScalePublishState + does_not_own: + - Scale 题目正文编辑器（未开 ECR 前禁止扩张） + allowed: + - Explore_Reports.publish_gate + forbidden: + - Community + - Payment +``` + +## Account_Risk + +```yaml +Account_Risk: + owns: + - RiskFlag + - BanRecord + does_not_own: + - MembershipPlan + allowed: + - Identity_Profile.UserStatus.transition # 经明确应用服务 + - Admin_Auth_Audit.write_audit + forbidden: + - Payment.refund_silent +``` + +## Content_Safety + +```yaml +Content_Safety: + owns: + - FilterRule + - ModerationCase + - BlockPolicy + - CrisisEvent + - CrisisPolicy + does_not_own: + - Membership + - Payment + - AdminRole + allowed: + - Identity_Profile.read + - Ask_Ops.read_session_meta + forbidden: + - Membership.write + - Payment +``` + +## Ask_Ops + +```yaml +Ask_Ops: + owns: + - AskSessionView + - QualityFeedback + - HandoffCase + - SystemPrompt + - KnowledgeSource + - KnowledgeChunk + - ToolDefinition + does_not_own: + - Payment + - MembershipPlan + - UserStatus + allowed: + - Identity_Profile.read + - Content_Safety.evaluate + forbidden: + - Payment + - Membership.write + - Admin_RBAC.write +``` + +## Ops_CMS_NoUGC + +```yaml +Ops_CMS_NoUGC: + owns: + - Banner + - FeedSlot + - ScheduledPublication + does_not_own: + - UGC Post + - CommentGraph + - TrustScore + allowed: + - Admin_RBAC.check + forbidden: + - Community + - 用户生成内容入库为主路径 +``` + +## Community + +```yaml +Community: + status: Forbidden + owns: [] + note: feature-map UGC 广场 [No]；开启须 L3 ADR + 新 Capability +``` + +--- + +## 反模式（禁止） + +```text +AskService → load User → update Membership → charge Payment +UserService.updateMembership() +Content_Safety 直接改 Entitlement +Ops_CMS 引入「用户帖子」表却声称 NoUGC +``` diff --git a/docs/WAVE0/domain/domain-map.md b/docs/WAVE0/domain/domain-map.md new file mode 100644 index 0000000..a4649b0 --- /dev/null +++ b/docs/WAVE0/domain/domain-map.md @@ -0,0 +1,32 @@ +# Domain Map — Ops Platform 增量（Wave 0） + +> 本文件为 Wave 0 归档；**运行时权威**同步至 [`.ai/domain/domain-map.md`](../../../.ai/domain/domain-map.md)「Ops Platform」节。 +> P1 工程 BC 表仍冻结；此处**追加**运营平台 BC，不改写 P1 不变量（除非另开 ADR）。 + +Status: `Draft` + +--- + +## 既有 BC（摘要 · 勿在 Wave 0 修改所有权） + +Identity · Profile · Discovery · Relation · Ask · Companion · StarProfile · LifeRhythm · ImageCard · Commerce · Consult — 见 `.ai/domain/domain-map.md`。 + +--- + +## Ops Platform BCs（Wave 0 登记） + +| Context | Owns（概念级） | Capability | 状态 | +|---------|----------------|------------|------| +| `Admin_Auth_Audit` | AdminAccount · AdminSession · AuditLog | AdminGovernance | **已落地** Ops-A | +| `Admin_RBAC` | AdminRole · AdminPermission | AdminGovernance | **草案** → ECR-013A | +| `Analytics_OpsB` | AnalyticsSession · AnalyticsEvent · 聚合读模型 | GrowthInsights / UserIntelligence（读） | **已落地** Ops-B | +| `Ops_Content` | HomeTool · ScalePublishState | ExploreConfig（部分） | **已落地** Ops-C | +| `Account_Risk` | RiskFlag · BanRecord（与 UserStatus 协作） | AccountLifecycle | 草案 | +| `Content_Safety` | FilterRule · ModerationCase · CrisisEvent | ContentSafety · CrisisCare | 草案 | +| `Ask_Ops` | AskSessionView · QualityFeedback · SystemPrompt… | AskOperations · AICoreConfig | 草案 | +| `Ops_CMS_NoUGC` | Banner · FeedSlot | OpsCMS | 草案 | +| `Community` | — | — | **Forbidden** | + +边界细节：[`boundary-rules.md`](boundary-rules.md)。 +实体目录：[`entity-catalog.md`](entity-catalog.md)。 +词表：[`glossary.yaml`](glossary.yaml)。 diff --git a/docs/WAVE0/domain/entity-catalog.md b/docs/WAVE0/domain/entity-catalog.md new file mode 100644 index 0000000..5f7ab1f --- /dev/null +++ b/docs/WAVE0/domain/entity-catalog.md @@ -0,0 +1,43 @@ +# Entity Catalog（Wave 0 · 概念级） + +> 仅登记名称、归属 BC、Capability、生命周期备注。**不建表、不写 migration。** +> 与 [`glossary.yaml`](glossary.yaml) · [`boundary-rules.md`](boundary-rules.md) 一致。 + +Status: `Draft` + +| Entity | BC | Capability | Notes | +|--------|----|------------|-------| +| AdminAccount | Admin_Auth_Audit | AdminGovernance | 已存在 Ops-A | +| AdminSession | Admin_Auth_Audit | AdminGovernance | 已存在 | +| AuditLog | Admin_Auth_Audit | AdminGovernance | 已存在；只追加 | +| AdminRole | Admin_RBAC | AdminGovernance | **ECR-013A** | +| AdminPermission | Admin_RBAC | AdminGovernance | **ECR-013A** | +| User | Identity_Profile | AccountLifecycle | 已存在 | +| Profile | Identity_Profile | UserIntelligence | 已存在 | +| UserStatus | Identity_Profile | AccountLifecycle | **ECR-013B** 状态机 | +| AccountStateTransition | Identity_Profile | AccountLifecycle | **ECR-013B** | +| BehaviorSnapshot | Identity_Profile | UserIntelligence | 未来读模型 | +| PsychologicalTagSet | Identity_Profile | UserIntelligence | 未来读模型 | +| MembershipPlan | Membership_Orders | CommerceEntitlement | 配置面后置 ECR | +| Entitlement | Membership_Orders | CommerceEntitlement | 后置 | +| RedemptionCode | Membership_Orders | CommerceEntitlement | 后置 | +| Membership | Membership_Orders | CommerceEntitlement | 已存在 | +| Order | Membership_Orders | CommerceEntitlement | 已存在 | +| DeepAccess | Membership_Orders | CommerceEntitlement | 已存在 | +| Payment | Membership_Orders | CommerceEntitlement | mock；真支付最后 | +| HomeTool | Ops_Content | ExploreConfig | 已存在 Ops-C | +| ScalePublishState | Ops_Content | ExploreConfig | 已存在 | +| AnalyticsSession / Event | Analytics_OpsB | GrowthInsights | 已存在 Ops-B | +| FilterRule | Content_Safety | ContentSafety | 后置 | +| ModerationCase | Content_Safety | ContentSafety | 后置 | +| CrisisEvent / CrisisPolicy | Content_Safety | CrisisCare | 后置 | +| SystemPrompt / Knowledge* / ToolDefinition | Ask_Ops | AICoreConfig | 后置 | +| AskSessionView / QualityFeedback | Ask_Ops | AskOperations | 后置 | +| Banner / FeedSlot | Ops_CMS_NoUGC | OpsCMS | 后置 | +| UGC* | Community | — | **Forbidden** | + +## 状态机预告（ECR-013B · 仅文档） + +`UserStatus`: `active` → `disabled` | `banned` | `suspended`； +`banned` / `disabled` → C 端 DeviceAuth **拒绝**（细则写入 013B AC）。 +`deleted` soft-delete **不在 013B**（另开）。 diff --git a/docs/WAVE0/domain/glossary.yaml b/docs/WAVE0/domain/glossary.yaml new file mode 100644 index 0000000..252bb85 --- /dev/null +++ b/docs/WAVE0/domain/glossary.yaml @@ -0,0 +1,116 @@ +# domain glossary — engineering / API unique terms + +# Wave 0 Draft. Runtime copy: .ai/domain/glossary.yaml +# User-facing copy stays in .ai/product/lexicon.md +# Conflict: Architect + Human resolve; do not invent synonyms in code. + +version: "0.1.0" +status: draft + +terms: + AdminRole: + zh: 管理员角色 + bc: Admin_RBAC + forbidden: [admin_group, privilege_group] + + AdminPermission: + zh: 管理员权限点 + bc: Admin_RBAC + forbidden: [acl_flag, authz_bit] + + AuditLog: + zh: 操作审计日志 + bc: Admin_Auth_Audit + forbidden: [admin_history] + + UserStatus: + zh: 用户账户状态 + bc: Identity_Profile + values: [active, disabled, banned, suspended] + forbidden: [user_flag, account_level] + + AccountStateTransition: + zh: 账户状态迁移 + bc: Identity_Profile + forbidden: [status_patch_log] + + MembershipPlan: + zh: 会员套餐 + bc: Membership_Orders + forbidden: [package, vip_level, 订阅档, sku_vip] + + Entitlement: + zh: 权益 + bc: Membership_Orders + forbidden: [privilege_pack, benefit_bundle] + + RedemptionCode: + zh: 兑换码 + bc: Membership_Orders + forbidden: [gift_card, activation_key_alias] + + DeepAccess: + zh: 深度版 + bc: Membership_Orders + forbidden: [Unlock, unlock_report] + + BehaviorSnapshot: + zh: 行为快照 + bc: Identity_Profile + forbidden: [user_track_dump] + + PsychologicalTagSet: + zh: 心理标签集 + bc: Identity_Profile + forbidden: [psy_labels_raw] + + FilterRule: + zh: 过滤规则 + bc: Content_Safety + forbidden: [badword_only] + + ModerationCase: + zh: 审核工单 + bc: Content_Safety + forbidden: [review_ticket_ugc] + + CrisisEvent: + zh: 危机事件 + bc: Content_Safety + forbidden: [suicide_flag_public] + + CrisisPolicy: + zh: 危机策略 + bc: Content_Safety + forbidden: [kill_switch_generic] + + SystemPrompt: + zh: 系统提示词 + bc: Ask_Ops + forbidden: [god_prompt] + + KnowledgeSource: + zh: 知识源 + bc: Ask_Ops + forbidden: [rag_file] + + KnowledgeChunk: + zh: 知识块 + bc: Ask_Ops + forbidden: [embedding_row_ui] + + ToolDefinition: + zh: 工具定义 + bc: Ask_Ops + forbidden: [function_call_config_loose] + + Banner: + zh: 运营横幅 + bc: Ops_CMS_NoUGC + forbidden: [story_feed_ugc] + + Community: + zh: （禁止能力） + bc: Community + status: forbidden + forbidden: [ugc_plaza, 社区广场] diff --git a/docs/WAVE0/feature-map/feature-map-update.md b/docs/WAVE0/feature-map/feature-map-update.md new file mode 100644 index 0000000..f64ed60 --- /dev/null +++ b/docs/WAVE0/feature-map/feature-map-update.md @@ -0,0 +1,17 @@ +# feature-map §7 更新说明（Wave 0） + +> 本文件记录对 `.ai/product/feature-map.md` §7 的拟议/已应用变更。 +> 权威仍以 `.ai/product/feature-map.md` 为准。 + +## 变更意图 + +将 Phase D+ 从「功能愿望清单」改为： + +- **Capability-First + Contract Gate** +- 实现仅经 ECR 切片（013A RBAC → 013B AccountLifecycle → …） +- M10.2 UGC / 社区保持 `[No]` +- 真支付最后 + +## 应用状态 + +**已应用到** [`.ai/product/feature-map.md`](../../../.ai/product/feature-map.md) §7（2026-08-07 Wave 0）。 diff --git a/docs/WAVE0/governance/contract-first-rules.md b/docs/WAVE0/governance/contract-first-rules.md new file mode 100644 index 0000000..5bbf1a0 --- /dev/null +++ b/docs/WAVE0/governance/contract-first-rules.md @@ -0,0 +1,74 @@ +# Contract-First Rules（Ops Platform · Wave 0） + +> Engineering Loop（v1.1 FROZEN）= **通用执行框架** +> Ops Platform = **被 Loop 执行的一个 Domain** +> **禁止**因产品变复杂而改 Loop 内核。 + +Status: `Draft` → Human Review + +--- + +## Start Authorization + +- Wave / ECR 进入执行须 **Human 明文 Start Authorization**。 +- Loop **不自启**。 + +--- + +## 允许 / 禁止路径（Wave 0） + +| 允许 | 禁止 | +|------|------| +| `docs/**` | `apps/**` | +| `.ai/domain/**` | `internal/service/**`（经 apps/api） | +| `.ai/product/**`（feature-map / lexicon / feature-spec 登记） | database migration | +| | frontend / backend implementation | +| | 开实现向 ECR coding | +| | 真支付 · UGC 社区实现 | + +--- + +## 契约栈（冻结语义） + +```text +Capability → BC → Domain → API (+ contract_diff) → AC(四类) → ECR → Evidence → Archive +``` + +任一层缺失 → Architect **停**；不得 Builder。 + +--- + +## 必需 Artifact（实现向 ECR） + +1. Capability 归属（L0） +2. boundary-rules 兼容声明（L1） +3. glossary 词已登记（L2） +4. OpenAPI + BD（L3） +5. **`docs/CONTRACT_DIFF/ECR-xxx.yaml`（P0 必需）** +6. Functional / Security / Performance / Observability AC（L4） +7. TEST_REPORT 映射 AC-ID + +--- + +## Loop 角色对齐（不改 Loop） + +| Loop 角色 | 本 Domain 动作 | +|-----------|----------------| +| Architect | 写 L0–L4 + boundary + glossary + contract_diff | +| Contract Gate | Human Approve + ess-validate architect | +| Builder | 仅 Change Boundary 内实现 | +| Validator | AC + contract_diff + tests | +| Guardian | boundary-rules · 无架构回归 | +| Final Approval | Closed · TRACEABILITY · Archive | + +--- + +## Wave 0 完成定义 + +- `docs/WAVE0/**` 锁定清单齐全 +- `.ai/domain/{boundary-rules,glossary,entity-catalog}.md|yaml` 已同步 +- feature-map §7 已指向 Contract-First +- `VALIDATION_REPORT.md` PASS +- **无** apps 变更 + +下一闸门：Human Review Wave 0 → 再授权 **ECR-013A**（仅 RBAC）。