name	code-style
description	代码风格规范 / Code style conventions。在编写、编辑、评审 Python 代码时使用。包括类型注解、Decimal 精度、Docstring、模块组织等规范。Use when writing, editing, or reviewing Python code. Enforces type hints, Decimal precision, docstrings, and module organization.

Python code style for fund-portfolio-bot

本 Skill 强调编码规范中最关键、最容易被忽略的规则。

完整编码规范见 CLAUDE.md 第 3 节（核心约束）。分层架构约束见 .claude/skills/architecture/SKILL.md。

When to use

在以下场景使用本 Skill（触发词：代码风格、类型注解、Docstring、精度、code style、type hints、docstring）：

生成新的 Python 模块（尤其是 src/ 下）
修改现有函数或类
做代码重构或代码评审
用户提到"类型注解"、"Decimal"、"文档"、"代码规范"时

类型与数值正确性

所有函数参数与返回值都应添加类型注解。
优先使用现代类型语法：
- list[str], dict[str, Decimal], X | None
- 避免使用 List / Optional 等老式写法，除非项目已有统一约定。
金额、净值、份额等金融相关字段一律使用 Decimal。
不要使用 float 做任何金融计算。

Docstring 与注释

公开的类与函数应该有简洁的中文 docstring，说明：
- 主要职责
- 关键业务约束或注意点
Docstring 不需要重复类型信息（类型以注解为准）。
数字标签注释（CLI 层规范）：
- 函数内部用 # 1. # 2. # 3. 标记逻辑步骤
- 示例：# 1. 解析参数 → # 2. 调用 Flow → # 3. 格式化输出
注释只在业务规则不直观时补充解释，避免噪音注释。

模块与类内部结构

原则：入口在上，工具在下；公开在上，私有在下。

类内部顺序：

__init__
公共方法
以 _ 开头的私有辅助方法

模块内部顺序：

import（按标准库 / 第三方 / 本地分组）
公共类与公共函数
仅模块内部使用的私有工具函数（例如 _helper_*）

命名惯例

状态类字段或枚举值用小写字符串，例如：
- "normal", "delayed", "pending"
文件名、函数名、变量名：snake_case
类名：PascalCase
CLI 层函数命名（v0.4.2+ 统一规范）：
- _parse_args()：参数解析函数
- _format_*()：格式化输出辅助函数（如 _format_result(), _format_fees()）
- _do_*()：命令执行函数（如 _do_buy(), _do_list(), _do_confirm()）
- main()：CLI 主入口，只做路由

分层与配置相关约束

core 层代码不要从 adapters 或 app 导入。
业务逻辑中避免直接使用 os.getenv：
- 优先通过已有的配置模块或适配层获取配置。

DCA & AI 分工命名规范

本项目是 AI 驱动 的投资工具。在 DCA、历史扫描、AI 分析相关代码中，严格遵循 "规则算事实，AI 做解释" 的分工原则，通过命名来强化这个边界。

规则层数据模型

规则层只输出可重算的结构化事实，严禁直接生成主观结论。

后缀	定义	模块内示例	跨模块示例
`*Facts`	结构化事实快照（日期、金额、间隔等）	`Facts`	`DcaFacts`
`*Check`	规则验证结果（命中+偏差+说明）	`Check`	`DayCheck`
`*Flag`	异常标记（不下结论，仅标记）	`Flag`	`Flag`
`*Draft`	建议方案（不入库，内存结构）	`Draft`	`PlanDraft`
`*Result`	内部中间聚合（如回填结果）	`Result`	`BackfillResult`
`*Report`	CLI/AI 展示用报告	`Report`	`ScanReport`

简化原则：模块路径已包含领域信息时，可省略前缀；跨模块导出时保留上下文。

Flow 函数动词

动词	约束	模块内示例	跨模块示例
`build_*()`	只读计算，返回 `*Facts`	`build_facts()`	`build_dca_facts()` (批次为参数)
`scan_*()`	只读无副作用（幂等）	`scan()`	`scan_trading_history()`
`draft_*()`	返回 `*Draft`，不入库	`draft()`	`draft_dca_plan()`
`backfill_*()`	写操作，修改数据库	`backfill()`	`backfill_dca()` (不需要 for_batch)

关键原则：

看到 scan_ / build_ / draft_ 就知道安全可调（只读）
看到 backfill_ 就要警惕会修改数据库
参数而非函数名来表达"对什么"（batch_id, fund_code 等是参数）

AI 层（预留）

AI 基于规则层的 *Facts 生成语义解释，仅写入解释性字段，不修改核心数据。

*Insight：洞察（如"这笔交易可能是限额"）
*Explanation：自然语言解释
*Label：分类标签

提交前检查

在可能的情况下：

运行静态检查（例如项目中配置的 ruff check --fix .）。
快速浏览本次 diff，确认：
- 风格清理没有改变业务行为
- 没有遗留调试代码（例如 print、breakpoint()）。

Install Skill

SKILL.md