mystocks_spec 治理体系：红线、功能树与变更门禁

mystocks_spec 最显著的工程特色是多层治理体系——以 STANDARDS.md 为唯一事实来源，FUNCTION_TREE 锁业务能力，OpenSpec 管变更，PR 三道门禁保证交付质量。这套体系让大型仓库（22.5 万符号、28 万关系）在多 CLI 协作下仍能保持秩序。

一、治理金字塔

                  ┌─────────────────────────────┐
                  │  STANDARDS.md (V3.1)        │  ← 工程红线 + 审批门禁 SOT
                  │  唯一事实来源                │
                  └────────────┬────────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
┌───────▼────────┐    ┌────────▼────────┐    ┌────────▼────────┐
│ FUNCTION_TREE  │    │   OpenSpec      │    │  PR 门禁链      │
│ 业务能力真相源 │    │   变更工作流    │    │  质量+安全+审查 │
└────────────────┘    └─────────────────┘    └─────────────────┘

冲突优先级：STANDARDS.md > 领域 SOT（如 openstock-consumer-boundary）> DOMAIN_BOUNDARIES.md > CLAUDE.md/AGENTS.md。

二、STANDARDS.md 工程红线（V3.1 核心）

2.1 主线对齐与结果可见准则（最高准则）

系统可用性是最高验收标准。代码变更、文档报告、门禁通过、测试绿灯本身都不构成任务完成；主线任务必须产出可视化、可复现的运行结果。

关键子规则： - 任务分层准入：任何任务开始前必须判定为 P0/P2/P3 - P0：启动、服务可用、页面访问、路由/API/store/数据流、主业务链路阻塞 - P2：测试整理、文档漂移、归档、dirty cleanup、lint、TODO 元数据 - P3：未来能力准备、优化、polish - 主线优先于细节治理：P0 主线不可运行时，禁止推进无关的 P2/P3 - 业务能力链是最小有效单元：不得以单个文件/wrapper/测试/归档项作为完成口径 - 禁止超前修复未来未启用功能：禁止为风格统一/测试绿灯/未来铺垫提前修改无活跃路由的代码 - 5 天滚动主线周期：no-source 审计 → P0 修复 → 页面/接口联通 → 业务 smoke → closeout - 反碎片化熔断：连续两次提交只减少局部规范噪音却没消除运行阻塞 → 立即停止，退回主线审计

2.2 方案先行准则

任何涉及菜单结构、UI/UX 风格、核心架构的变更，必须先提交《技术方案/设计草案》。只有用户明确回复"批准/同意/执行"后方可启动代码修改。未经审批的自主变更视为无效交付，必须无条件回滚。

2.3 共享规则归一化

STANDARDS.md 是以下规则的唯一事实来源：主线对齐准则、方案先行准则、六步走战略、Docker 一等公民原则、迁移收口规则。CLAUDE.md/AGENTS.md/GEMINI.md 只引用，不复制正文。

2.4 治理节奏与批量盘点

  • 新需求即时治理：范围清楚、风险同类、门禁通过的小包及时提交，禁止长期积攒跨风险 dirty state
  • 同域 no-source 批量盘点：可合并为一个治理节点、一份报告、一张决策表
  • Dirty worktree 执行细则：遵循 DIRTY_WORKTREE_CLEANUP_GUIDE.md

2.5 OpenStock 消费者边界专项 SOT

领域专项约束，独立文件管理（见 openstock-消费者边界与数据源迁移）。

三、六步走开发战略

步 原则 解决的问题
1. 契约先行 OpenAPI（FastAPI 路由 + Pydantic Schema + 导出 openapi.json）是唯一事实来源，Markdown/手写类型不得充当并行真值 避免"接口分裂"
2. 单体骨架 Core → Domain → Infra → Application → UI/API 严格分层，禁止底层依赖上层 避免"循环依赖"
3. Mock 驱动 MSW 或后端 Mock 模式，前端不等后端即可独立视觉验收 避免"前端等后端"
4. 垂直切片 一次打通一个 Feature 的 DB → Service → API → UI 避免"连不上库"
5. 集成与可观测性 RequestId 全链路追踪 + /health/ready 探针 + 前端启动校验后端 避免"隐形白屏"
6. 自动化防护网 路由/Layout 修改必须跑 scripts/run_e2e_pm2.sh 全量冒烟 避免"修好 A 坏了 B"

四、技术工程红线（节选）

前端红线

  • App.vue 严禁硬编码业务组件，必须 <router-view /> 渲染
  • 视觉属性必须引用 artdeco-tokens.scss 变量，禁止硬编码样式
  • 所有业务 Tab 必须在 UI 预留 Request ID 展示位（TRACE_ID 显化）
  • Composable 协作定位：1 消费者 → ./composables/ 同目录共存；2+ 消费者 → src/composables/
  • 前端收口优先级：结构性语法/类型 → PM2 服务状态 → E2E/smoke → 纯视觉 polish；禁止以视觉微调推迟收口

后端红线

  • 所有 global 变量必须模块顶层显式初始化为 None（单例防御）
  • 重构后必须全局搜索清理废弃模块引用（导入安全性）
  • 所有 API 必须返回 UnifiedResponse 包装结构（响应标准化）

环境一致性

  • ecosystem.config.js 及配套环境是"一等公民"，严禁碎片化命令行启动

五、迁移收口与技术债治理

单一真相源规则：同一职责只允许一个主实现/主入口/主注册点。兼容层、镜像目录、过渡模块只能作迁移桥接，不能长期升级为并行第二套。

迁移必须自带收口条件：实施前必须明确目标真相源 + 需保留的兼容面。

文件体积红线：Python 800 行、Vue/TS 500 行、测试 1000 行。超限必须拆分。

技术债治理细则：docs/standards/technical-debt-governance-charter-v1.md。

六、FUNCTION_TREE 业务能力真相源

docs/FUNCTION_TREE.md（v1.1.7）是功能版图、功能域导航、任务映射与边界对齐的参考。

维护规则（9 条）： 1. 新增功能必须新增功能节点，同步主入口/依赖入口/验证入口 2. 功能删除/合并/拆分/迁移必须同批次更新本文件 3. 影响规范/代码/页面/测试/运行入口的改动必须同步"领域入口"表 4. 状态变化必须同步状态标签（✅/🚧/📝/⚠️/🔒/🧪） 5. OpenSpec/任务卡/PR 必须引用稳定 ID（如 {#domain-01}），不用自由文本 6. 新增主路由/主页面/主 API 必须同步主入口与边界说明 7. 兼容层/旧页面/shim 退役必须同批次更新并明确继任入口 8. 同一时间只允许一个 active mainline 治理节点 9. 主线节点关闭必须引用可视化、可复现的运行结果

当前 active mainline：B4.013 Runtime Mainline Bring-Up（先证明程序能跑，再处理细节治理）。

七、OpenSpec 变更工作流

openspec/ 目录管理所有能力新增/架构调整。流程：

proposal.md (为什么 + 改什么 + 影响)
  ↓
design.md (上下文 + 目标 + 架构 + 迁移计划 + 风险)
  ↓
tasks.md (分阶段任务清单 + 验收检查)
  ↓
specs/{capability}/spec.md (固化的规格)
  ↓
archive/ (完成后归档)

当前 active changes（20 个非归档）涵盖：OpenStock 外置、extra-source-adapter 契约、fundflow-mixin 迁移、ArtDeco 设计门禁、风险管理系统、mainline 对齐治理、后端路由统一响应契约、脏 worktree 清理治理等。

固化 specs（已通过的规格）：含 30+ 能力，包括统一响应格式、类型安全生成、适配器模式、CSRF 保护、ArtDeco 设计治理、数据质量治理、数据源运行时服务、broker 对账等。

八、PR 三道门禁

每个 PR 必须通过：

  1. 质量门：TS 类型检查零结构性错误 + Python pytest/ruff/black + 前端 Vitest/Playwright/stylelint
  2. 安全门：secrets 扫描 + audit + SAST
  3. 审查门：code review

PR 模板要求声明：本次改动属于哪个功能域、影响哪个 FUNCTION_TREE 节点、修改了哪些入口文档、提供了哪些验证证据。

九、多 CLI 协作（main + worktree 模式）

分支 角色 工件
main 协调角色，用 .FILE_OWNERSHIP 分配任务，监控 Worker 进度 TASK.md / TASK-REPORT.md
非 main（worktree） Worker 角色 worktree 根目录下的 TASK.md + TASK-REPORT.md

强制：遵守 .multi-cli-tasks/guides/MULTI_CLI_WORKTREE_MANAGEMENT.md（v3.2）；main 不承载功能开发；新功能在 worktree/dev-* 分支开发并以 PR 合并。

十、辅助工具层

工具 定位 用途
GitNexus 代码图谱（22.5 万符号、28 万关系、300 执行流） 编辑前 gitnexus_impact 分析影响范围；提交前 gitnexus_detect_changes 确认范围；重命名必须用 gitnexus_rename
OPENDOG 项目观察与安全门控辅助层 agent-guidance / verification / unused / data-risk；输出仅 advisory，不替代 git/test/项目原生检查
context-mode MCP 上下文窗口治理 ctx doctor / ctx stats
graphiti_memory MCP 跨会话事实检索 search_memory_facts / add_memory
zread 仓库 wiki 与模块地图 先读 .zread/wiki/current

GitNexus 规则：编辑任何符号前必须 gitnexus_impact({target, direction: "upstream"})；HIGH/CRITICAL 风险必须先报告用户；禁止 find-and-replace 重命名。

十一、治理体系的科学性

这套体系解决了大型 AI 协作仓库的几个核心痛点：

  1. 文档漂移 → 真相源分层 + 唯一事实来源 + 引用优先于复制
  2. AI 自主实施失控 → 方案先行准则 + OpenSpec 工作流 + 用户审批门
  3. 细节治理抢占主线 → P0/P2/P3 分层 + 主线优先 + 反碎片化熔断
  4. 完成标准模糊 → 结果可见准则 + 业务能力链最小单元 + 5 天滚动周期
  5. 多 CLI 协作混乱 → main/worktree 角色分工 + FUNCTION_TREE 稳定 ID
  6. 兼容层无限膨胀 → 迁移收口规则 + 单一真相源 + 退役清单固化
  7. 代码改动影响不可预测 → GitNexus 影响分析 + 强制 impact 检查

相关页面：mystocks-spec-项目全景、openstock-消费者边界与数据源迁移、Hermes 工具链与开发规范全景。