ProStock/.kilocode/rules/project_rules.md

# ProStock 项目规则

本项目使用 Kilo Code 规则系统来确保代码质量和一致性。

## 项目概述

- **项目名称**: ProStock
- **主要语言**: Python
- **框架**: 待定
- **代码目录**: `src/`
- **配置目录**: `config/`

## 核心原则

1. **代码质量**: 所有代码必须符合 Python PEP 8 编码规范
2. **类型提示**: 建议为公共函数和类添加类型注解
3. **文档字符串**: 使用 Google 风格的 docstring
4. **测试覆盖**: 关键业务逻辑应有对应的单元测试

## Python 运行规范

**⚠️ 本项目强制使用 uv 作为 Python 包管理器和运行工具。禁止直接使用 `python` 或 `pip` 命令。**

### 禁止的命令 ❌

```bash
# 禁止直接使用 python
python -c "..."           # 禁止！
python script.py          # 禁止！
python -m pytest          # 禁止！
python -m pip install     # 禁止！

# 禁止直接使用 pip
pip install -e .          # 禁止！
pip install package       # 禁止！
pip list                  # 禁止！
```

### 正确的 uv 用法 ✅

```bash
# 运行 Python 代码
uv run python -c "..."           # ✅ 正确
uv run python script.py          # ✅ 正确

# 安装依赖
uv pip install -e .              # ✅ 正确
uv pip install package           # ✅ 正确

# 运行测试
uv run pytest                    # ✅ 正确
uv run pytest tests/test_sync.py # ✅ 正确
```

## 目录结构规范

```
project/
├── src/              # 源代码主目录
├── config/           # 配置文件目录（禁止直接读取）
├── docs/             # 文档目录
├── tests/            # 测试目录
├── .kilocode/        # Kilo Code 配置
│   └── rules/        # 规则文件
├── requirements.txt  # 依赖管理
└── README.md         # 项目说明
```

## 文件命名规范

- **Python 文件**: 使用小写下划线命名法 (`snake_case.py`)
- **配置文件**: 使用小写下划线命名法 (`config_settings.py`)
- **测试文件**: 使用 `test_` 前缀 (`test_example.py`)
- **常量文件**: 使用 `constants_` 前缀 (`constants_sizes.py`)

## 代码组织

- 每个 Python 模块应尽可能保持简洁，职责单一
- 避免在 `__init__.py` 中放置过多逻辑
- 使用相对导入 (`from .module import ...`) 而非绝对导入
- 配置应集中管理，避免硬编码

## 导入顺序规范

```python
# 1. 标准库导入
import os
import sys
from datetime import datetime

# 2. 第三方库导入
import pandas as pd
from flask import Flask

# 3. 本地应用导入
from src.config.settings import Settings
from src.models.user import User
```

## 提交前检查

在提交代码前，请确保：
- [ ] 所有代码通过类型检查（如使用 mypy）
- [ ] 代码格式符合规范（使用 black/isort）
- [ ] 没有未使用的导入或变量
- [ ] 关键功能有对应的测试
- [ ] 文档已更新（如需要）