npm package: @lanrengroup/common
Description: Technical analysis utilities extracted from lanren project
Latest version: 1.0.2

# lanren-common

`lanren-common` 是懒人投资（lanren）项目生态中的核心公共函数库。

该包旨在统一提取并维护多个子项目（包括主站 `lanren`、后台任务 `lanren-bg-api`、中间件 `lanren-railway-api`，以及提供数据支持的 Python 服务 `stock-kline-py` 相关的跨语言标准）中高度复用的业务逻辑。主要涵盖**股票技术分析**和**多市场规则处理（A股/港股/美股）**。

采用 Node ESM 标准，可直接在服务端与现代前端环境中使用。

## NPM 包发布与登录说明

由于本包发布至官方 NPM Registry (https://registry.npmjs.org/)，请在修改代码后，按照以下步骤进行编译与发布：

### 1. 登录 NPM
进入 `lanren-common` 目录并登录。如果无法在浏览器中打开授权页面，推荐使用命令行直接输入账号密码的 legacy 模式：

```bash
cd lanren-common
npm login --auth-type=legacy
```
*提示：你需要拥有 `@lanrengroup` 组织的发布权限。*

### 2. 编译与发布
每次修改完 `src` 下的源码后，务必先编译，然后再发布：

```bash
# 1. 重新编译 TypeScript 到 dist 目录
npm run build

# 2. 更新版本号 (例如 1.0.1 -> 1.0.2)
npm version patch

# 3. 发布到 NPM
# 如果你的 NPM 账号启用了 2FA（双因素认证），必须在发布时附带 OTP 验证码：
npm publish --access public --otp=你的6位验证码
```

---

## 安装

在各个独立项目中，你可以直接通过 NPM 安装：

```bash
npm install @lanrengroup/common
```

## 使用示例

```js
import { getTechAnalysis, technical, market } from 'lanren-common';

// 股票技术分析主入口
const tech = await getTechAnalysis(klineData, endDate);

// 分别使用子模块
const { calculateIndicators, analyzeTrend } = technical;
const { getMarketType, marketCode2Name } = market;
```

## 导出清单

### 根入口（index.js）
- `getTechAnalysis(klineData, endDate)` —— 综合技术分析主函数
- `technical` —— 技术指标与趋势分析命名空间（见下）
- `market` —— 市场工具命名空间（见下）

### technical 子模块（lib/technical/index.js）
提供专业的股票技术分析、指标计算及趋势预判。

- `getTechAnalysis` —— 同上，可被直接导入
- 重导出以下全部指标与趋势函数：

#### 指标函数（lib/technical/indicators/index.js）
- `calculateIndicators(klineData)` —— 一键计算全部指标
- `calculateRSI(prices, period=14)` —— 相对强弱指标
- `calculateMACD(prices)` —— 指数平滑异同移动平均线
- `calculateKDJ(prices, highs, lows)` —— 随机指标
- `calculateBOLL(prices)` —— 布林带
- `calculateIchimoku(prices)` —— 一目均衡表
- `calculateOBV(klineData)` —— 能量潮指标
- `calculateSAR(highs, lows)` —— 停损点转向指标
- `calculateFibonacci(prices)` —— 斐波那契回撤
- `calculateBIAS(prices)` —— 乖离率
- `calculateVolumeRatio(klineData)` —— 量比
- `calculateMagicNine(prices)` —— 神奇九转
- `calculateDragonSignal({ macd, kdj, rsi, prices })` —— 龙系信号
- `calculateChipDistribution(prices)` —— 筹码分布
- `calculateMA(prices)` —— 多周期移动平均线
- `calculateWR(prices, highs, lows)` —— 威廉指标
- `calculateDMI(prices, highs, lows)` —— 动向指标
- `calculateTRIX(prices)` —— 三重指数平滑平均线

#### 趋势/策略分析（lib/technical/analyzers/trendAnalyzer.js）
- `analyzeTrend({ indicators, currentPrice, prevPrice, klineData })` —— 综合趋势研判与形态识别

#### 通用工具（lib/technical/common/index.js）
- `calculateMA10(klineData)`
- `analyzeUptrendPullback(klineData, ma10Data, baseVolume)` —— 上涨回调策略分析
- `generateStrategyAnalysis(...)` —— 策略综合评分与操作建议生成
- `getConfidenceLevel(score)` —— 评估置信度级别
- `combinePriceTrend(short, mid, long)` —— 多周期趋势合并

### market 子模块（lib/market/index.js）
处理 A股、港股、美股 等不同金融市场的代码规则、API参数映射以及名称转换。

- `marketParamsMap` —— 市场代码→东财 API 参数映射表 (支持 105纳斯达克/106纽交所/116港股/0深交所/1上交所)
- `marketNewTypeMap` —— 市场类型简称映射 (us/hk/a)
- `marketCode2Name(marketCode)` —— 市场代码/类型转换为中文市场名称
- `getMarketFromCode(code)` —— 根据股票代码推断旧版市场编号 (用于东财接口等)
- `getNewMarketFromCode(code)` —— 根据股票代码推断新版市场类型 ('a' | 'hk' | 'us')
- `getMarketType(code)` —— 严格匹配并返回 `'a' | 'hk' | 'us' | null`
- `getMarketInfo(code)` —— 解析股票后缀，返回 `{ market, type }` 完整信息
- `market2ItickMarket(code)` —— 转换为 itick 平台支持的市场标识

## 发布日志
- 1.0.0  初始发布，提取完整技术指标与趋势分析
- 1.1.0  新增 market 工具模块，补充跨市场编码相关处理函数
- 1.1.1  完善 README 介绍，强化多端复用定位