name	code-flow-viz
description	用于梳理和可视化代码流程，生成清晰的 ASCII 流程图、数据流图和表格分析。适用于已有代码的梳理、新功能设计的说明、以及技术文档的编写。

代码流程可视化规范

本 Skill 提供一套可复用的模板和方法，用于梳理代码流程、生成可视化文档。

核心原则：用文字和 ASCII 图表讲清楚"数据从哪来、经过哪些层、最后到哪去"。

When to use

在以下场景使用本 Skill：

用户询问"某个功能是怎么工作的"
新增功能需要设计数据流
重构前需要梳理现有逻辑
编写技术文档或架构说明
代码评审时需要可视化调用链

核心模板

1. 完整流程图（多场景对比）

适用于：梳理一个功能的多种使用场景（如手动 vs 自动、成功 vs 失败）

┌─────────────────────────────────────────────────────────────────────┐
│                    功能名称（如：限额管理全生命周期）                  │
└─────────────────────────────────────────────────────────────────────┘

═══════════════════════════════════════════════════════════════════════
场景 1：场景名称（如：自动查询限额状态）
═══════════════════════════════════════════════════════════════════════

  用户命令
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│  uv run python -m src.cli.xxx ...                               │
└────────────────┬────────────────────────────────────────────────┘
                 │
                 ▼
        ┌────────────────┐
        │  CLI 层         │  调用 Flow 函数
        │  _do_xxx()      │ ────────────────────┐
        └────────────────┘                      │
                                                ▼
                                   ┌──────────────────────────┐
                                   │  Flow 层                  │
                                   │  xxx_flow()               │
                                   └───────┬──────────────────┘
                                           │
                                           ▼
                              ┌─────────────────────────────┐
                              │  Data 层                     │
                              │  XxxRepo / XxxClient         │
                              └────────┬─────────────────────┘
                                       │
                                       ▼
                          ┌────────────────────────────┐
                          │  外部系统 / 数据库          │
                          │  (SQLite / API / etc)      │
                          └──────────┬─────────────────┘
                                     │ 返回数据
                                     ▼
                    ┌──────────────────────────────────┐
                    │  数据处理（解析/转换）            │
                    └─────────────┬────────────────────┘
                                  │
                                  ▼
                        ┌──────────────────────┐
                        │  返回值数据类         │  ← 说明为什么保留/简化
                        │  (Result / Item / ...)│
                        └──────────┬───────────┘
                                   │
                                   ▼
                        ┌──────────────────────┐
                        │  CLI 层格式化输出     │
                        └──────────────────────┘
                                   │
                                   ▼
    ╔══════════════════════════════════════════════════╗
    ║  终端输出示例                                     ║
    ║  （用框线包围，突出最终用户看到的效果）            ║
    ╚══════════════════════════════════════════════════╝

═══════════════════════════════════════════════════════════════════════
场景 2：另一个场景
═══════════════════════════════════════════════════════════════════════
（重复上述结构，突出差异点）

2. 数据库表结构说明

适用于：解释某个功能涉及的数据库表

CREATE TABLE table_name (
    id INTEGER PRIMARY KEY AUTOINCREMENT,  -- ← 说明主键作用
    field1 TEXT NOT NULL,                  -- 说明字段含义
    field2 TEXT,                           -- NULL 的业务含义
    ...
);

-- 索引（说明为什么需要这个索引）
CREATE INDEX idx_xxx ON table_name(field1, field2);

示例数据表：

id	field1	field2	field3	说明
42	value1	value2	value3	解释这条记录的业务含义
43	...	...	...	...

典型查询：

-- 场景说明：什么时候需要这样查？
SELECT * FROM table_name 
WHERE condition1 = ? 
  AND (condition2 IS NULL OR condition2 >= ?);

3. 分层调用链图（简化版）

适用于：快速说明函数调用关系

CLI 层 (_do_xxx)
    │
    └─> Flow 层 (xxx_flow)
            │
            ├─> Data/Repo (xxx_repo.get)
            │       │
            │       └─> SQLite (SELECT ...)
            │
            └─> Data/Client (xxx_client.fetch)
                    │
                    └─> 外部 API (HTTP GET ...)

4. 数据类设计分析表

适用于：评估中间数据类是否必要

类名	字段数	用途	判定	理由
`XxxResult`	6	多字段聚合 + CLI 展示	✅ 保留	满足"最小必要原则"
`XxxWrapper`	1	单字段包装	❌ 删除	过度包装，直接返回原始类型
`XxxItem`	3	列表明细项	✅ 保留	有业务语义

对比示例：

# ❌ 过度包装
@dataclass
class XxxResult:
    field: SomeType  # 只有一个字段

def xxx_flow() -> XxxResult:
    return XxxResult(field=value)

# ✅ 简化后
def xxx_flow() -> SomeType:  # 直接返回
    return value

5. 业务关键点标注

适用于：突出业务规则和设计决策

┌─────────────────────────────────────────────────────────────┐
│                      业务关键点                              │
├──────────────────────┬──────────────────────────────────────┤
│   为什么这样设计？    │          具体决策                     │
├──────────────────────┼──────────────────────────────────────┤
│ • 数据精度           │ 金额用 Decimal，2 位小数              │
│ • 幂等性             │ 按 (fund_code, date) 唯一约束         │
│ • 可追溯性           │ record_id 作为全局唯一标识            │
└──────────────────────┴──────────────────────────────────────┘

使用方法

Step 1: 确定分析目标

回答以下问题：

用户想了解哪个功能的流程？
这个功能有几种场景？（成功/失败、手动/自动等）
涉及哪些层次？（CLI → Flow → Data → DB/API）
关键数据类有哪些？为什么设计成这样？

Step 2: 选择合适的模板

多场景对比 → 模板 1（完整流程图）
单一流程 → 模板 3（分层调用链）
数据库设计 → 模板 2（表结构 + 示例数据）
数据类评估 → 模板 4（分析表）

Step 3: 填充内容

原则：

用 ASCII 图表代替长篇文字
用箭头（│ ▼ ┐ ┘ └ ├ ─）串联数据流
用框线（┌ ┐ └ ┘ │ ─）分隔层次
用双线框（╔ ╗ ╚ ╝ ║ ═）突出用户可见部分
在关键节点加注释（← 说明）

符号使用规范：

符号	用途	示例
`│ ▼`	垂直流向	数据从上到下
`→ ←`	水平说明	`record_id: int ← 数据库主键`
`┌ ┐ └ ┘`	单线框	包围代码块、命令
`╔ ╗ ╚ ╝`	双线框	突出终端输出、重要结果
`═══`	分隔线	分隔不同场景

Step 4: 添加对比分析

Before vs After（重构场景）：

# Before（问题版本）
...代码...

# 问题：
# - 过度包装
# - 字段冗余
# - 增加认知负担

# After（改进版本）
...代码...

# 改进：
# - 直接返回有意义类型
# - 减少中间层
# - 降低维护成本

实际案例

案例 1：限额管理流程（完整版）

（见上面的模板 1 示例，展开 4 个场景的完整流程）

案例 2：数据类评估（fund_restriction 模块）

函数	之前返回	现在返回	判定	原因
`add_restriction`	`AddRestrictionResult`(6字段)	保留	✅	CLI 需要展示所有字段
`end_restriction`	`EndRestrictionResult`(4字段)	`bool`	❌	只需要成功/失败
`check_trading_status`	`CheckStatusResult`(2字段)	`ParsedRestriction \| None`	❌	只是简单包装

输出清单（Checklist）

生成流程可视化文档时，确保包含：

顶层概述（功能目标、涉及模块）
场景枚举（成功/失败、手动/自动等）
分层流程图（CLI → Flow → Data → 外部）
数据库表结构（如果涉及）
示例数据和查询（帮助理解）
关键数据类说明（为什么保留/简化）
设计原因（为什么这样做？）
未来扩展点（TODO 或预留接口）

反模式（不要这样做）

❌ 纯文字描述流程

首先调用 CLI 层的 _do_xxx 函数，然后 _do_xxx 会调用 Flow 层的 xxx_flow 函数，
xxx_flow 再调用 Data 层的 xxx_repo.get 方法...

✅ 用 ASCII 图表

CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite

❌ 表格没有重点

字段	类型
id	int
name	str

✅ 突出业务含义

字段	类型	说明	业务约束
id	int	主键	自动生成，全局唯一
name	str	基金名称	非空，用于展示

❌ SQL 没有场景说明

SELECT * FROM table WHERE id = ?;

✅ 带业务场景

-- 场景：用户查询某条限制记录详情
SELECT * FROM fund_restrictions WHERE id = ?;

-- 场景：DCA 分析时检查某日是否被限额
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);

与其他 Skill 的协作

code-style：输出代码示例时遵循编码规范
architecture：流程图需符合分层架构约束
dev-workflow：梳理流程前先读取相关代码和文档

总结

本 Skill 的核心价值：

可复用的模板：减少从零开始的时间
统一的视觉风格：ASCII 图 + 表格 + 框线
业务视角：不只是代码流程，更关注"为什么"
对比分析：重构前后、多场景对比
清单检查：确保不遗漏关键信息

使用频率：每次需要解释"某个功能怎么工作"时都可以用。

code-flow-viz

Install Skill

SKILL.md