@michaelxwb/code-flow 0.5.1

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

@@ -0,0 +1,52 @@
+# 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

@@ -0,0 +1,56 @@
+---
+description: 写/改组件时适用：props、hooks、渲染、UI 样式约束
+---
+
+# 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
+- Props 必须类型化（TS interface / PropTypes / defineProps），可选项给默认值
+- 组件文件名与导出组件名一致，使用 PascalCase
+- 单组件文件 ≤ 300 行，超出拆成子组件或提取 hook
+- 组件内禁止直接修改 props，需改值通过事件 / 回调上抛
+- **样式与逻辑/数据分离**：样式走 CSS Modules / 原子类 / 设计 token，不与数据获取或业务逻辑混在同一处；展示组件不发起请求
+
+## Patterns
+- 拆分容器组件（数据获取 / 状态）与展示组件（纯 UI），便于测试和复用
+- 复用逻辑提取为 hook（`useXxx`）/ composable，禁止跨组件复制粘贴
+- 列表渲染必须给 `key`，且 `key` 稳定唯一，避免使用数组索引
+- 受控表单优先；非受控仅用于不需要回读值的场景
+- 样式遵循设计系统：间距用 4 的倍数，强调色 ≤ 2 种
+
+## Anti-Patterns
+- 禁止在组件内直接修改 props 或 store 内部状态
+- 禁止把大量逻辑塞进 JSX 表达式，复杂条件提取变量或子组件
+- 禁止用 `index` 作为列表 `key`（顺序变更会触发错误复用）
+- 禁止省略 `alt` / `aria-*` 等可访问性属性

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

@@ -0,0 +1,41 @@
+---
+description: 新建/移动前端文件时适用：目录结构、路由/页面/组件存放约束
+---
+
+# 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
+- 通用组件放 `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/`
+
+## Anti-Patterns
+- 禁止在 `src/` 下随意新增未登记的一级目录
+- 禁止页面与组件互相循环引用
+- 禁止把仅本组件用的 hook / 类型上提到全局目录

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

@@ -0,0 +1,46 @@
+---
+description: 写前端代码时适用：类型、lint、错误处理、测试、状态管理质量约束
+---
+
+# 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
+- 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，避免每个调用方重复
+- 关键路径补端到端测试或组件交互测试
+
+## Anti-Patterns
+- 禁止在 render / setup 中发起未受控的副作用（用 `useEffect` / `onMounted`）
+- 禁止把后端错误直接抛给用户（如 SQL / stack trace）
+- 禁止用 `// @ts-ignore` 绕过类型错误，必须修复或改为 `@ts-expect-error` 加注释
+- 禁止在组件中直接修改 store 内部状态，必须走 action / mutation

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

@@ -0,0 +1,57 @@
+# 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/design/design-frontend.md

@@ -0,0 +1,247 @@
+# {模块名称} 前端模块需求与设计简报
+
+> **文档编号**: FE-{模块代号}-{版本号}
+> **文档版本**: v1.0
+> **创建日期**: YYYY-MM-DD
+> **文档状态**: 草稿 / 评审中 / 已批准
+
+**评审边界说明**:
+- **需求评审**: 第 2 章（需求分析）→ 通过后锁定需求基线
+- **设计评审**: 第 3 章（前端技术设计）→ 通过后锁定设计基线
+
+**ID 体系**: US（来自 PRD，可选）、FEAT（功能）、CMP（组件）、NFR（非功能指标）
+场景编号：S-（正常）、E-（异常）、B-（边界，按需）
+
+**填写约定**: 框架中立——按实际框架（React / Vue / Svelte 等）替换示例为真实写法。表内数值/阈值均为**示例**，必须替换为真实目标或删除；无实测依据填"待定"。标注 `[按需]` 的章节不适用时整节删除，不要留空表。
+
+---
+
+## 目录
+
+- [1. 文档控制](#1-文档控制)
+- [2. 需求分析](#2-需求分析)
+  - [2.1 需求概述](#21-需求概述-必填)
+  - [2.2 功能方案](#22-功能方案-必填)
+  - [2.3 范围与边界](#23-范围与边界-必填)
+  - [2.4 验收条件](#24-验收条件-必填)
+- [3. 前端技术设计](#3-前端技术设计)
+  - [3.1 技术选型](#31-技术选型-必填)
+  - [3.2 页面与路由结构](#32-页面与路由结构-必填)
+  - [3.3 组件设计](#33-组件设计-必填)
+  - [3.4 组件接口契约](#34-组件接口契约-必填)
+  - [3.5 状态与数据流](#35-状态与数据流-必填)
+  - [3.6 UI 状态](#36-ui-状态-必填)
+  - [3.7 样式方案](#37-样式方案-必填)
+  - [3.8 可访问性与兼容性](#38-可访问性与兼容性-按需)
+- [4. 风险与依赖](#4-风险与依赖)
+- [附录：术语表](#附录术语表)
+
+---
+
+## 1. 文档控制
+
+### 1.1 责任人
+
+| 角色 | 姓名 | 职责范围 |
+|------|------|---------|
+| 开发负责人 | | 技术方案、代码实现 |
+| 设计/交互 | | 视觉与交互稿（如有） |
+
+### 1.2 修订历史
+
+| 版本 | 日期 | 作者 | 变更描述 |
+|------|------|------|---------|
+| v0.1 | YYYY-MM-DD | | 初始草稿 |
+
+---
+
+## 2. 需求分析
+
+### 2.1 需求概述 [必填]
+
+| 项目 | 内容 |
+|------|------|
+| **模块名称** | |
+| **需求类型** | 新页面 / 组件 / 交互优化 / 重构 |
+| **业务背景** | （需求来源、触发原因） |
+| **核心目标** | （一句话说明要达成的用户价值） |
+
+---
+
+### 2.2 功能方案 [必填]
+
+| 功能ID | 功能名称 | 功能描述 | 优先级 | 来源 |
+|--------|---------|---------|--------|------|
+| FEAT-01 | | | P0 | US-01 |
+
+> 来源：引用 PRD 中的 US-XX；无 PRD 时留空。
+
+---
+
+### 2.3 范围与边界 [必填]
+
+| 类别 | 内容 |
+|------|------|
+| **范围（In Scope）** | 本次覆盖的页面/组件/交互 |
+| **非范围（Out of Scope）** | 明确**不做**的部分 |
+| **有意妥协 / 技术债** | 本次接受的取舍（无则填"无"） |
+
+---
+
+### 2.4 验收条件 [必填]
+
+> 交互层面的可验证场景，写到可转 e2e / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。
+
+**正常场景**
+
+| 场景ID | 功能ID | 优先级 | 操作步骤 | 预期 UI 结果 |
+|--------|--------|--------|---------|-------------|
+| S-01 | FEAT-01 | P0 | 1. <操作> | <可见结果> |
+
+**异常场景**
+
+| 场景ID | 功能ID | 触发条件 | UI 表现 |
+|--------|--------|---------|---------|
+| E-01 | FEAT-01 | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
+
+**非功能指标** [按需]
+
+| 指标ID | 指标名称 | 目标值 | 测量方法 |
+|--------|---------|-------|---------|
+| NFR-PERF-01 | 首屏 / 交互响应 | 待定 | Lighthouse / 实测 |
+
+---
+
+## 3. 前端技术设计
+
+### 3.1 技术选型 [必填]
+
+| 类别 | 选型 | 版本 | 选型理由 |
+|------|------|------|---------|
+| 框架 | （React / Vue / Svelte…） | | |
+| 状态管理 | （局部 / Redux / Zustand / Pinia / stores…） | | |
+| 路由 | | | |
+| 样式方案 | （Tailwind / CSS Modules / styled-components…） | | |
+| 数据请求 | （fetch 封装 / axios / react-query / SWR…） | | |
+
+---
+
+### 3.2 页面与路由结构 [必填]
+
+| 页面 | 路由 | 布局 | 说明 |
+|------|------|------|------|
+| | `/path` | | |
+
+> 新增页面 → 路由配置 + 入口；与现有路由层级一致。
+
+---
+
+### 3.3 组件设计 [必填]
+
+**组件树**（容器/展示分离）
+
+```
+<Page>                       # 容器：数据获取 + 状态
+└─ <FeaturePanel>            # 容器
+   ├─ <ItemList>             # 展示：纯 UI，props 驱动
+   │  └─ <ItemRow>           # 展示
+   └─ <ActionBar>            # 展示，事件回调上抛
+```
+
+| 组件ID | 组件名 | 类型 | 复用来源/去向 | 职责 |
+|--------|--------|------|--------------|------|
+| CMP-01 | | 容器/展示 | 新建 / 复用现有 | |
+
+> **分层纪律**：容器组件负责数据与状态，展示组件纯 UI（props in / events out）；复用逻辑提取为 hook/composable，禁止跨组件复制粘贴。
+
+---
+
+### 3.4 组件接口契约 [必填]
+
+> 替代后端的"接口设计"——前端的接口是组件的 Props / Events。
+
+**CMP-01 `<组件名>`**
+
+| Props | 类型 | 必填 | 默认 | 说明 |
+|-------|------|------|------|------|
+| | | | | |
+
+| Events / 回调 | 载荷类型 | 触发时机 |
+|--------------|---------|---------|
+| `onXxx` | | |
+
+> 组件内**禁止直接修改 props**，改值通过事件/回调上抛。
+
+---
+
+### 3.5 状态与数据流 [必填]
+
+**状态划分**
+
+| 状态 | 作用域（local / shared store） | 形状（shape） | 读写方 |
+|------|------------------------------|--------------|--------|
+| | | | |
+
+**数据流**
+
+```
+用户操作 → 事件处理 → Service(API 封装) → Store/State → 重渲染
+```
+
+**数据获取层**：API 调用必须经 `services/`（或等价封装）统一发起，**组件 / 展示层不出现裸 `fetch`/`axios`**；组件通过 hook/composable 消费。
+
+| Service 方法 | 对应后端接口 | 调用方组件/hook |
+|-------------|-------------|----------------|
+| `getXxx()` | `GET /...` | |
+
+---
+
+### 3.6 UI 状态 [必填]
+
+> 每个涉及异步/交互的视图列出四态，禁止只处理成功路径。
+
+| 视图/交互 | loading | empty | error | success |
+|----------|---------|-------|-------|---------|
+| | （骨架/转圈） | （空态文案/插画） | （错误提示+重试） | （正常内容） |
+
+---
+
+### 3.7 样式方案 [必填]
+
+| 维度 | 约定 |
+|------|------|
+| **样式与逻辑分离** | 样式走 CSS Modules / 原子类 / 设计 tokens，不与数据获取/业务逻辑混在同一处 |
+| **设计 tokens** | 间距/颜色/字号引用 token，不散落魔法值 |
+| **响应式断点** | （列出断点与适配策略） |
+
+---
+
+### 3.8 可访问性与兼容性 [按需]
+
+| 维度 | 要求 |
+|------|------|
+| 可访问性 | 语义标签、`alt`/`aria-*`、键盘可达、焦点管理 |
+| 浏览器/设备兼容 | （目标范围） |
+
+---
+
+## 4. 风险与依赖 [按需]
+
+| 风险ID | 描述 | 影响 | 应对 |
+|--------|------|------|------|
+| | | | |
+
+---
+
+## 附录：术语表
+
+| 术语 | 定义 |
+|------|------|
+| US / FEAT / NFR | 用户故事 / 功能项 / 非功能需求 |
+| CMP | Component，组件 |
+| 容器组件 | 负责数据获取与状态的组件 |
+| 展示组件 | 纯 UI、props 驱动、事件上抛的组件 |
+
+---
+
+*文档结束*