代码流程可视化规范

本 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);

示例数据表：

典型查询：

-- 场景说明：什么时候需要这样查？
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

XxxWrapper

XxxItem

对比示例：

# ❌ 过度包装
@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: 确定分析目标

回答以下问题：

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

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

end_restriction

EndRestrictionResult

bool

check_trading_status

CheckStatusResult

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

❌ 表格没有重点

✅ 突出业务含义

❌ 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 的核心价值：

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

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