@michaelxwb/code-flow 0.8.1 → 1.0.0

package/src/core/code-flow/specs/backend/_map.md

@@ -1,56 +0,0 @@
-# Backend Retrieval Map
-
-> AI 导航地图：定位后端代码结构和关键模块。可由 `/cf-learn --map` 重生成，建议按真实项目手动校准。
-
-## Purpose
-
-后端服务，负责 API 暴露、业务逻辑与数据持久化。默认假设为分层架构（API → Service → Model）。
-
-## Architecture
-
-- Framework: 任意 Web 框架（FastAPI / Express / Spring / Gin 等）
-- ORM/Driver: 与数据库匹配的官方/主流驱动
-- Database: 关系型为主（PostgreSQL / MySQL），可叠加缓存（Redis）
-- Auth: Token-based（JWT / OAuth2 / Session）
-- Async: 必要时引入消息队列或后台任务（Celery / Bull / BullMQ）
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `src/main.*` | 应用入口，初始化框架、路由、中间件 |
-| `src/api/router.*` | 路由注册，统一前缀与版本 |
-| `src/services/` | 业务逻辑实现，禁止跨层调用 ORM |
-| `src/models/` | 数据模型定义（ORM / Schema） |
-| `src/crud/`（或 `repositories/`） | 数据访问层，业务只依赖此抽象 |
-| `src/config/` | 配置加载，环境变量优先 |
-
-## Module Map
-
-```
-src/
-├── api/         # 接口层：路由 + 请求/响应 schema 校验
-├── services/    # 业务逻辑层：纯函数为主，便于测试
-├── models/      # 数据模型（ORM 或 ODM）
-├── crud/        # 数据访问层（repositories），业务只调 CRUD 不碰 ORM
-├── migrations/  # DB 迁移脚本（可回滚或幂等）
-├── errors/      # 错误码→message 常量，按业务模块拆分
-├── schemas/     # DTO / 请求响应类型
-├── middleware/  # 认证、日志、限流、CORS
-├── utils/       # 工具函数，无业务依赖
-└── config/      # 配置与环境变量
-```
-
-## Data Flow
-
-```
-Request → Middleware(auth/log) → Router → Handler(API)
-        → Service(业务) → Model(DB/Cache) → Response
-```
-
-## Navigation Guide
-
-- 新增 API → `api/` 加路由 + `schemas/` 定义请求响应 + `services/` 实现业务
-- 新增表 → `models/` 定义模型 + `migrations/` 加迁移脚本
-- 错误处理 → 抛业务异常类，由中间件统一转 HTTP 响应
-- 配置项 → `config/` 集中管理，禁止散落 `os.environ`/`process.env`

package/src/core/code-flow/specs/backend/code-quality-performance.md

@@ -1,59 +0,0 @@
----
-id: backend-code-quality-performance
-description: 写后端代码时适用：错误处理、测试、超时重试、缓存等质量与性能约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-backend-quality-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Backend Code Quality & Performance
-
-## Examples
-
-> ✅/❌ 对照示例对 AI 的引导远强于规则条文——新写规范优先用这个格式（cf-learn 候选会自动生成草稿）。
-
-✅ 显式错误处理
-
-```python
-try:
-    result = service.call()
-except ServiceError as exc:
-    logger.warning("call failed: %s", exc)
-    raise
-```
-
-❌ 静默吞异常
-
-```python
-try:
-    result = service.call()
-except Exception:
-    pass
-```
-
-
-## Rules
-- [RULE-backend-quality-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- 所有公开函数 / 方法必须有类型注解（type hints / 类型签名）
-- 异常必须显式处理或显式上抛，禁止 `except Exception: pass` / `catch (e) {}` 静默吞掉
-- 外部依赖调用（HTTP / RPC / DB）必须设置超时，关键调用补重试 + 指数退避
-- 单元测试覆盖核心业务路径：happy path + 边界 + 错误分支，每个需求 ≥ 1 个用例
-
-## Patterns
-- 缓存可计算结果以减少重复 IO，明确缓存 key、TTL 与失效策略
-- 重 IO 用异步或批处理，CPU 密集任务下沉到 worker / 队列
-- 资源（连接、文件、锁）使用 `with` / `using` / `defer` 确保释放
-- 性能敏感路径加监控指标（QPS / P95 延迟 / 错误率）
-
-## Avoid
-- 禁止在请求链路中吞掉异常导致客户端拿到错误结果却无日志
-- 禁止无超时的外部调用（容易导致线程 / 协程泄漏）
-- 禁止用循环模拟批量操作（DB 批量 / 网络批量必须用原生批量 API）
-- 禁止把缓存失败当致命错误，缓存层必须可降级为直接查询

package/src/core/code-flow/specs/backend/database.md

@@ -1,51 +0,0 @@
----
-id: backend-database
-description: 涉及数据库/ORM/迁移/查询时适用：schema 与数据访问约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-backend-database-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Backend Database
-
-## Examples
-
-✅ 参数化查询，明确列出字段
-
-```python
-cur.execute("SELECT id, name FROM users WHERE email = %s", (email,))
-```
-
-❌ 字符串拼接用户输入（SQL 注入）+ `SELECT *`
-
-```python
-cur.execute(f"SELECT * FROM users WHERE email = '{email}'")
-```
-
-## Rules
-- [RULE-backend-database-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- 所有 SQL 必须参数化，禁止字符串拼接 / 模板插值用户输入
-- 迁移脚本必须可回滚，或写成幂等脚本（`IF NOT EXISTS` / `ON CONFLICT`）
-- 事务边界明确：跨表写入必须在同一事务内，禁止"半提交"状态
-- 涉及索引/锁的 schema 变更必须评估线上影响，大表慎用 `ALTER TABLE` 阻塞操作
-- 每个 model 必须有对应 CRUD 抽象层（`crud/<model>.py` 或 `repositories/<Model>Repo`），业务代码只调 CRUD，禁止在 service / handler 直接写 ORM 查询或裸 SQL
-
-## Patterns
-- 读写分离场景显式标注读库/写库，强一致读走主库
-- N+1 查询用预加载（`joinedload` / `include` / `Preload`）解决
-- 大批量写入分批 + commit，避免单事务过大
-- 缓存与数据库一致性：先写库再失效缓存（`cache-aside`）
-- CRUD 基类统一实现 `get / list / create / update / delete / bulk_*`，子类只扩展模型特有查询
-
-## Avoid
-- 禁止在事务内发起外部 HTTP / RPC 调用，超时会导致连接池耗尽
-- 禁止在循环中执行单条 `INSERT` / `UPDATE`，必须批量化
-- 禁止在 ORM 之外手写 SQL 时绕过参数绑定
-- 禁止用 `SELECT *` 上线，明确列出字段控制传输与索引

package/src/core/code-flow/specs/backend/directory-structure.md

@@ -1,54 +0,0 @@
----
-id: backend-directory-structure
-description: 新建/移动后端文件时适用：目录结构与模块组织约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-backend-directory-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Backend Directory Structure
-
-## Examples
-
-✅ 魔法值集中到 `constants/`，命名引用
-
-```python
-# constants/order.py
-ORDER_PAID = 1
-# service：if order.status == ORDER_PAID: ...
-```
-
-❌ 业务代码散落硬编码字面量
-
-```python
-if order.status == 1 and role == "admin":   # 魔法数字 / 魔法字符串
-    ...
-```
-
-## Rules
-- [RULE-backend-directory-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- 接口层放 `api/`，业务逻辑放 `services/`，数据模型放 `models/`，禁止跨层倒置依赖
-- 入口文件（`main.*`）只做框架装配，不写业务代码
-- 配置统一放 `config/`，禁止在业务代码中直接读 `os.environ` / `process.env`
-- 常量集中放 `constants/`，按业务模块拆分（`constants/order.py`、`constants/user.py`），禁止在业务代码中散落硬编码字面量（魔法数字 / 字符串 / 状态码）
-- 数据访问层独立放 `crud/` 或 `repositories/`，业务层依赖 CRUD 抽象，不直接依赖 ORM
-- 新增一级目录必须同步更新导航地图与 `__init__` / `index` 索引
-
-## Patterns
-- 模块按业务域拆分（如 `services/order/`、`services/user/`），目录深度建议 ≤ 3 层
-- 公共工具放 `utils/`，无业务依赖；与业务相关的 helper 放对应 service 子目录
-- 常量命名用 UPPER_SNAKE_CASE，枚举优先使用语言原生 `Enum`
-- 测试目录与源码同构（`tests/services/order/test_*`）
-
-## Avoid
-- 禁止在根目录堆放脚本与临时代码，临时脚本放 `scripts/` 并命名清晰
-- 禁止在 `models/` 里写业务逻辑，模型仅定义结构与简单关联
-- 禁止把常量直接写在业务代码里（如 `if status == 1` / `role == "admin"`），必须引用 `constants/` 中的命名常量
-- 禁止单文件超过 500 行或单函数超过 50 行

package/src/core/code-flow/specs/backend/logging.md

@@ -1,50 +0,0 @@
----
-id: backend-logging
-description: 涉及日志/调试/监控时适用：日志级别、格式、追踪约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-backend-logging-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Backend Logging
-
-## Examples
-
-✅ 结构化字段 + 脱敏 + 保留堆栈
-
-```python
-logger.info("login", extra={"user_id": uid, "request_id": rid})
-logger.error("pay failed", exc_info=True)
-```
-
-❌ 明文 token + `print` 吞掉堆栈
-
-```python
-print(f"login token={token}")          # 泄露敏感字段 + 非日志框架
-logger.error("failed")                 # 丢失原始错误与上下文
-```
-
-## Rules
-- [RULE-backend-logging-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- 关键路径（请求入口、外部调用、DB 写入、异常分支）必须输出结构化日志
-- 日志中禁止出现明文密码、token、身份证号等敏感字段，需在记录前脱敏
-- 每条请求日志必须包含 `request_id`，串联整个调用链
-- 日志级别遵循：`DEBUG`（开发）/ `INFO`（业务事件）/ `WARN`（可恢复异常）/ `ERROR`（需告警）
-
-## Patterns
-- 统一字段命名：`request_id`、`user_id`、`route`、`status`、`latency_ms`、`error`
-- 异常日志必须带堆栈（`exc_info=True` 或等价机制）
-- 高频路径用采样日志，避免 IO 阻塞主流程
-- 日志输出到 stdout/stderr，由部署环境采集，禁止业务代码写文件
-
-## Avoid
-- 禁止在循环或热路径中无脱敏地打印请求体
-- 禁止用 `print` / `console.log` 替代日志框架
-- 禁止吞掉异常仅打 `logger.error("failed")`，必须保留原始错误与上下文

package/src/core/code-flow/specs/backend/platform-rules.md

@@ -1,55 +0,0 @@
----
-id: backend-platform-rules
-description: 涉及 API 设计/部署/配置/版本兼容时适用：平台规则
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-backend-platform-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Backend Platform Rules
-
-## Examples
-
-✅ 走统一封装 + 错误码常量
-
-```python
-return success(data)
-raise BizError(ORDER_NOT_FOUND)   # 错误码定义在 errors/order.py
-```
-
-❌ handler 手拼响应结构 + 硬编码 message
-
-```python
-return {"code": 1, "message": "order not found", "data": None}
-```
-
-## Rules
-- [RULE-backend-platform-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- API 变更必须保持向后兼容；破坏性变更走新版本路径（`/v2/...`）并保留旧版本至少一个发布周期
-- 配置项分环境管理（dev / staging / prod），敏感值走密钥管理服务，禁止入库
-- 新增外部依赖必须更新部署文档与 `requirements` / `package.json` 锁文件
-- 灰度 / 实验性功能必须由 feature flag 控制，默认关闭
-- API 响应必须走统一封装：`success(data)` / `fail(code, message?)`，handler 禁止手写 `{code, message, data}` 字面量
-- 错误码 → message 映射定义为常量，按业务模块拆分（`errors/order.py`、`errors/user.py`），错误码全局唯一，禁止重复
-
-## Patterns
-- API 响应统一结构：`{ code, message, data }`（`code=0` 表示成功），全项目一致
-- 错误码命名空间：模块前缀 + 顺序号（如订单错误码 `10xxx`、用户 `20xxx`），便于定位归属
-- 异常 → 错误码：自定义业务异常类携带 `code`，由中间件统一转 `fail(code)` 响应
-- 配置加载优先级：环境变量 > 配置文件 > 默认值
-- 健康检查端点（`/healthz`、`/readyz`）必须独立于业务认证
-- 部署前跑 smoke test，覆盖核心路径
-
-## Avoid
-- 禁止在生产环境开启 `DEBUG` / 详细堆栈输出
-- 禁止把 secret 写进代码库或 dev 配置文件
-- 禁止破坏性 API 变更不通知调用方直接发布
-- 禁止 feature flag 长期遗留，上线稳定后必须清理
-- 禁止在 handler 里直接拼响应结构或硬编码错误 message，必须引用 `errors/` 常量并走 `success / fail` 封装

package/src/core/code-flow/specs/frontend/_map.md

@@ -1,52 +0,0 @@
-# Frontend Retrieval Map
-
-> AI 导航地图：定位前端代码结构和关键模块。可由 `/cf-learn --map` 重生成，建议按真实项目手动校准。
-
-## Purpose
-
-前端单页 / 多页应用，负责用户交互、页面渲染与 API 调用。默认假设为基于组件的 SPA。
-
-## Architecture
-
-- Framework: 任意主流框架（React / Vue / Svelte / Solid 等）
-- Language: TypeScript（推荐）或 JavaScript + JSDoc
-- State: 局部状态优先，跨组件共享走集中式（Redux / Zustand / Pinia）
-- Routing: 框架官方路由（React Router / Vue Router / 文件路由）
-- Styling: 原子化（Tailwind）或模块化（CSS Modules / styled-components）
-- Build: Vite / Webpack / Next.js 等
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `src/main.*` | 应用入口，挂载 Root |
-| `src/App.*` | 根组件，注册路由与全局 Provider |
-| `src/router.*` | 路由定义 |
-| `src/services/` | API 调用封装 |
-
-## Module Map
-
-```
-src/
-├── components/   # 通用 UI 组件，无业务依赖
-├── pages/        # 页面级组件（路由叶子）
-├── hooks/        # 业务复用逻辑（React）/ composables（Vue）
-├── stores/       # 状态管理
-├── services/     # API 调用层
-├── utils/        # 纯函数工具
-├── types/        # 类型定义
-└── styles/       # 全局样式 / 主题
-```
-
-## Data Flow
-
-```
-User Action → Event Handler → Service(API) → Store/State → Re-render
-```
-
-## Navigation Guide
-
-- 新增页面 → `pages/` 添加组件 + 路由配置
-- 新增组件 → `components/` 按业务域分子目录，复用优先
-- API 调用 → 统一走 `services/`，不在组件内裸 fetch
-- 状态管理 → 跨组件状态走 `stores/`，组件通过 hook / composable 消费

package/src/core/code-flow/specs/frontend/component-specs.md

@@ -1,68 +0,0 @@
----
-id: frontend-component-specs
-description: 写/改组件时适用：props、hooks、渲染、UI 样式约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-frontend-component-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Component Specs
-
-## Examples
-
-✅ 稳定唯一 key + 改值经回调上抛
-
-```tsx
-{items.map((it) => <Row key={it.id} item={it} onChange={onChange} />)}
-```
-
-❌ 用数组 index 作 key + 组件内直接改 props
-
-```tsx
-{items.map((it, i) => { it.value = next; return <Row key={i} item={it} />; })}
-```
-
-✅ 容器/展示分离 + 样式走 token，展示组件不碰数据获取
-
-```tsx
-// 展示组件：纯 props 驱动，样式用 class/token，无请求
-const OrderRow = ({ order, onSelect }: Props) =>
-  <div className={styles.row} onClick={() => onSelect(order.id)}>{order.title}</div>;
-```
-
-❌ 展示组件内自取数据 + 内联魔法样式
-
-```tsx
-const OrderRow = ({ id }) => {
-  const [o, setO] = useState(); useEffect(() => { fetch(`/orders/${id}`)... }, []);
-  return <div style={{ margin: 13, color: '#3a7' }}>{o?.title}</div>;
-};
-```
-
-## Rules
-- [RULE-frontend-component-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- Props 必须类型化（TS interface / PropTypes / defineProps），可选项给默认值
-- 组件文件名与导出组件名一致，使用 PascalCase
-- 单组件文件 ≤ 300 行，超出拆成子组件或提取 hook
-- 组件内禁止直接修改 props，需改值通过事件 / 回调上抛
-- **样式与逻辑/数据分离**：样式走 CSS Modules / 原子类 / 设计 token，不与数据获取或业务逻辑混在同一处；展示组件不发起请求
-
-## Patterns
-- 拆分容器组件（数据获取 / 状态）与展示组件（纯 UI），便于测试和复用
-- 复用逻辑提取为 hook（`useXxx`）/ composable，禁止跨组件复制粘贴
-- 列表渲染必须给 `key`，且 `key` 稳定唯一，避免使用数组索引
-- 受控表单优先；非受控仅用于不需要回读值的场景
-- 样式遵循设计系统：间距用 4 的倍数，强调色 ≤ 2 种
-
-## Avoid
-- 禁止在组件内直接修改 props 或 store 内部状态
-- 禁止把大量逻辑塞进 JSX 表达式，复杂条件提取变量或子组件
-- 禁止用 `index` 作为列表 `key`（顺序变更会触发错误复用）
-- 禁止省略 `alt` / `aria-*` 等可访问性属性

package/src/core/code-flow/specs/frontend/directory-structure.md

@@ -1,53 +0,0 @@
----
-id: frontend-directory-structure
-description: 新建/移动前端文件时适用：目录结构、路由/页面/组件存放约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-frontend-directory-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Frontend Directory Structure
-
-## Examples
-
-✅ 三层分离：service 发请求 → hook/composable 管状态 → 组件纯展示
-
-```ts
-// services/order.ts — 只管 HTTP，不含状态
-export const fetchOrder = (id: string) => http.get(`/orders/${id}`);
-// hooks/useOrder.ts — 管 loading/error/data，复用逻辑收口于此
-export const useOrder = (id: string) => { /* 调 fetchOrder，返回 { data, loading, error } */ };
-// components/OrderCard.tsx — 纯展示，消费 hook
-const { data, loading, error } = useOrder(id);
-```
-
-❌ 组件内裸 `fetch`，请求/状态/样式糊在一处
-
-```tsx
-const order = await fetch(`/orders/${id}`).then((r) => r.json());
-```
-
-## Rules
-- [RULE-frontend-directory-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- 通用组件放 `src/components/`，页面级组件放 `src/pages/`，业务复用逻辑放 `src/hooks/`（或 `composables/`）
-- **接口调用独立成层**：API 调用必须在 `src/services/` 封装；组件 / hook / composable 经 service 消费，**禁止组件或视图层内裸 `fetch` / `axios`**
-- 类型定义放 `src/types/`（共享）或与组件同目录（局部），禁止散落
-- 新增一级目录必须更新路由 / 入口索引与导航地图
-
-## Patterns
-- 组件目录按业务域分子目录（`components/order/`、`components/user/`）
-- 页面与路由一一对应，路由配置集中在 `router.*`
-- 资源文件（图片 / 字体）放 `src/assets/`，构建工具处理 hash 与压缩
-- 测试文件与源码同目录（`Foo.test.tsx`）或镜像放 `tests/`
-
-## Avoid
-- 禁止在 `src/` 下随意新增未登记的一级目录
-- 禁止页面与组件互相循环引用
-- 禁止把仅本组件用的 hook / 类型上提到全局目录

package/src/core/code-flow/specs/frontend/quality-standards.md

@@ -1,58 +0,0 @@
----
-id: frontend-quality-standards
-description: 写前端代码时适用：类型、lint、错误处理、测试、状态管理质量约束
-stages: [design, plan, code, review]
-enforcement: required
-verifiers:
-  - rule: RULE-frontend-quality-001
-    type: manual
-    config:
-      checklist: Confirm all Guidance and Avoid items for this Spec.
-      owner: project-owner
----
-
-# Frontend Quality Standards
-
-## Examples
-
-✅ `unknown` 收敛 + 异步三态
-
-```ts
-setState("loading");
-try {
-  const raw: unknown = await api.fetch();
-  setState("success", parse(raw));
-} catch (e) {
-  setState("error", toMessage(e));
-}
-```
-
-❌ `any` + `@ts-ignore` + 只处理成功路径
-
-```ts
-// @ts-ignore
-const data: any = await api.fetch();
-render(data);
-```
-
-## Rules
-- [RULE-frontend-quality-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
-
-## Guidance
-- TypeScript 项目禁止使用 `any`，未知类型用 `unknown` 并显式收敛
-- 组件统一使用函数组件（React）/ 组合式 API（Vue 3），禁止类组件新增
-- 关键交互（提交 / 删除 / 支付）必须有错误提示与 loading 状态
-- 异步操作必须处理 loading / success / error 三态，禁止只处理成功路径
-- 提交前必须通过 lint 与 type check，禁止 `eslint-disable` / `@ts-ignore` 滥用
-
-## Patterns
-- 跨组件状态用集中式状态管理，避免 prop drilling 超过 2 层
-- 表单校验在提交前完成，错误信息定位到具体字段
-- 网络请求统一处理 401 / 403 / 5xx，避免每个调用方重复
-- 关键路径补端到端测试或组件交互测试
-
-## Avoid
-- 禁止在 render / setup 中发起未受控的副作用（用 `useEffect` / `onMounted`）
-- 禁止把后端错误直接抛给用户（如 SQL / stack trace）
-- 禁止用 `// @ts-ignore` 绕过类型错误，必须修复或改为 `@ts-expect-error` 加注释
-- 禁止在组件中直接修改 store 内部状态，必须走 action / mutation

package/src/core/code-flow/specs/shared/_map.md

@@ -1,57 +0,0 @@
-# Shared Specs Navigation Map
-
-> 跨项目的共享模板和规范
-
-## Purpose
-
-共享模板供 `cf-task:align` 和 `cf-task:prd` 命令使用，为文档生成提供规范约束。
-
-## Templates
-
-### PRD Templates
-
-| 文件 | 用途 | 适用场景 |
-|------|------|---------|
-| `prd-template.md` | 产品需求文档 | 需求早期阶段，在设计之前 |
-
-### Design Templates
-
-| 文件 | 用途 | 适用场景 |
-|------|------|---------|
-| `design/design-lite.md` | 轻量设计简报 | 功能开发/CLI/Bug修复/小型重构 |
-| `design/design-full.md` | 完整设计文档 | 跨系统集成/性能优化/架构演进/中大型功能 |
-
-> 两档模板均覆盖：接口设计（API/CLI/函数三形态）、性能与容量设计、可执行验收（场景即 TC）。design-full 额外含方案选型 ADR 决策记录与 §6 需求追溯矩阵。
-
-## Workflow
-
-```
-需求 → cf-task:prd → PRD (.prd.md)
-       ↓ （align 读取 .prd.md 派生）
-       → cf-task:align → 设计 (.design.md)
-       ↓ （plan 读取 .design.md 拆解）
-       → cf-task:plan → 任务
-```
-
-## Selection Guide
-
-```
-需求阶段（还未明确用户与场景）：
-  → cf-task:prd 生成 PRD
-
-设计阶段（已有 PRD 或已明确做什么）：
-  → cf-task:align 生成设计简报
-    - 输入 .prd.md → 派生模式（继承目标/用户/功能/范围）
-    - 输入文本 → 新建模式（从零对话）
-
-复杂度判断：
-  简单功能/脚本/Bugfix → design-lite.md
-  复杂系统/跨模块/性能优化 → design-full.md
-```
-
-## Usage
-
-1. `cf-task:prd` 命令引用 `prd-template.md` 生成 PRD
-2. `cf-task:align` 命令引用 `design/design-lite.md` 或 `design/design-full.md` 生成设计文档
-3. PRD 的 US/FEAT ID 被 design 的功能清单"来源"列引用，形成追溯链
-4. 性能敏感需求：align 在出技术方案时即按最优性能设计，落点 design-lite §3.4 / design-full §3.5，并在 §6 矩阵闭合 US→FEAT→API→TC

package/src/core/code-flow/specs/shared/scenarios-template.md

@@ -1,55 +0,0 @@
----
-id: scenarios-template
-description: Scenario-first acceptance source template (not auto-injected)
-stages: [design]
-enforcement: advisory
----
-
-# {需求名} 验收场景
-
-> 本文件是验收场景的唯一源。design 文档只写实现逻辑并引用场景 ID；任务文件只登记 owner 与执行命令。
->
-> 以下是可通过场景质量检查的订单示例，使用时替换为本需求的真实行为与路径。将 YAML 放到 `<需求>.scenarios.md` 的 frontmatter 或作为整个 YAML 文件保存；不要把模板自身的 Spec 元数据当成场景源。`checks` 在 plan 生成真实 check ID 后绑定，空列表不能通过需要测试登记的 verify-plan。
-
-```yaml
-schema: 1
-requirement: 订单创建
-scenarios:
-  - id: S-01
-    title: 登录用户通过浏览器创建订单
-    priority: P0            # P0 / P1 / P2；E2E 只允许 P0/P1 关键旅程
-    level: e2e              # unit / component / contract / integration / system / capacity / e2e / manual
-    exec: deferred          # auto / deferred / manual / aspirational
-    env: browser            # none / local / local-api / browser / external / staging / capacity / ci / production
-    components: [browser, frontend, api, db]
-    boundary: 真实浏览器 → 订单 API → 数据库
-    preconditions: [用户已登录，购物车含一件库存充足的商品]
-    steps: [在浏览器点击提交订单]
-    expected: [订单列表新增一条状态为 created 的订单]
-    expected_refs: [{expected: 1, steps: [1]}]  # 从 1 开始，逐个 expected 引用步骤或已声明断言 ID
-    why_e2e: 真实浏览器登录态与订单持久化跨前后端，需要联合验证
-    trigger_paths: [src/frontend/*, src/orders/*]
-    smoke: true             # check 与收集到的测试都必须登记 smoke marker
-    defer_reason: 在需求终验阶段运行真实浏览器链路
-    owner: TASK-001
-    target_phase: review    # plan / code / review / ci / release
-    features: [FEAT-01]
-    design_refs: [API-01]    # 对应设计必须定义 FEAT-01 / API-01
-    rules: []
-    checks: []              # plan 阶段绑定；一个场景可多个 check
-```
-
-> **测试层级决策**：UI 交互/布局/字段顺序 → `component`；DTO/OpenAPI/错误码 →
-> `contract`；鉴权/事务/模块边界/进程内 API → `integration`；API/CLI/后台全链路 →
-> `system`；容量 → `capacity` 或 capacity 标签；只有真实浏览器 +
-> 真实后端 + 真实 DB/鉴权的关键旅程才用 `E2E`。E2E 不是“用户可见结果”的默认层。
-
-> CAS 409 示例：contract 检查冲突响应，component 检查表单保留，integration 用真实存储验证并发写入；分别登记 check，按 expected 映射必要成员。低层覆盖完整时可以不新增 E2E；仅为剩余跨边界接线风险选择 E2E，说明独特故障、已有低层覆盖及剩余风险，由设计评审判断理由。
->
-> ✅ CAS 用 contract + component + 真实存储 integration；聚合补零用数据 contract + component；关系绑定用真实存储 integration。Cookie 身份隔离与 SSE 断线恢复仍可保留针对性的浏览器 E2E，验证低层无法证明的跨边界接线。
->
-> ❌ 因用户看得到结果就为每个表单、聚合或关系操作新增一条 E2E；也不要只改旧 E2E 的层级后继承历史通过证据。
->
-> **质量门禁**：E2E 必须声明浏览器 env/组件、匹配的 boundary、why_e2e、步骤和具体预期；非 smoke 必须有 trigger_paths。每个 expected 必须引用存在的步骤或断言，deferred 必须有原因、owner 与 target_phase。
->
-> `scenarios parse --quality` 检查语义，`design lint` 检查设计 ID 闭环，`acceptance manifest --verify-plan` 还检查 Spec Gate 与真实测试登记/收集。start 按当前 TASK 的 E2E 与全局 smoke 生成 e2e_plan，不额外扩大本任务验收范围。收集通过不能替代真实执行证据；配置示例见工具文档 `docs/acceptance-contract.md`。