diff --git a/CLAUDE.md b/CLAUDE.md index 2bf196eb..3296fed4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ npx skills add longbridge/developers -g -y ### Critical Rules 1. **LongBridge CLI is user-installed** — NEVER bundle it in the app -2. **Symbol validation** — Validate with `/^[A-Z0-9]{1,5}\.(US|HK|SG|SH|SZ|HAS)$/` before exec +2. **Symbol validation** — Validate with `/^[A-Z0-9]{1,6}\.(US|HK|SG|SH|SZ|HAS)$/` before exec. The body is 1–6 characters: A-share codes such as `600519.SH` are 6 digits, so a 5-character limit rejects valid listings. 3. **Use execa array params** — Never string concatenation for commands 4. **Session isolation** — Use `atomFamily` for per-session state diff --git a/docs/api-reference.md b/docs/api-reference.md index 573d68da..43f45d49 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -16,6 +16,8 @@ Complete reference for all LongBridge CLI commands used by Finance Agent. | Indices | `.US` | `.VIX.US`, `.SPX.US` | Start with `.` | | Crypto | `.HAS` | `BTCUSD.HAS` | LongBridge crypto suffix | +The code before the suffix is 1–6 letters or digits. Shanghai and Shenzhen listings use 6-digit codes (`600519.SH`); a 5-character limit rejects them. Codes longer than 6 characters (`6005191.SH`, `TOOLONG.US`) are not valid Folio symbols. + --- ## Market Data Commands diff --git a/packages/longbridge-tools/src/validator.ts b/packages/longbridge-tools/src/validator.ts index 39ef1506..b6890f49 100644 --- a/packages/longbridge-tools/src/validator.ts +++ b/packages/longbridge-tools/src/validator.ts @@ -1,7 +1,7 @@ import { LongBridgeError } from './errors.ts'; // Symbol format: AAPL.US, 0700.HK, 600519.SH, 0388.HK, etc. -// Allow 1-5 chars of A-Z and 0-9 +// 1–6 characters. A-share listings are 6 digits; a 5-character limit rejects them. const SYMBOL_REGEX = /^[A-Z0-9]{1,6}\.(US|HK|SG|SH|SZ|HAS)$/; export function validateSymbol(symbol: string): boolean { diff --git a/packages/shared/src/portfolio-import/parsers.test.ts b/packages/shared/src/portfolio-import/parsers.test.ts index d4bb4896..d58022f0 100644 --- a/packages/shared/src/portfolio-import/parsers.test.ts +++ b/packages/shared/src/portfolio-import/parsers.test.ts @@ -46,6 +46,24 @@ describe('checkSymbol', () => { it('rejects unknown market suffixes', () => { expect(checkSymbol('AAPL.XX').ambiguous).toBe(true) }) + + it('does not treat over-long codes as canonical symbols', () => { + for (const symbol of ['6005191.SH', 'TOOLONG.US', 'DELISTED.US']) { + const check = checkSymbol(symbol) + expect(check.ambiguous).toBe(true) + expect(check.issue).toContain('not a recognized ticker') + } + const bare = checkSymbol('6005191') + expect(bare.ambiguous).toBe(true) + expect(bare.issue).toContain('not a recognized ticker') + expect(bare.issue).not.toContain('6005191.US') + }) + + it('still hints a market suffix for a 6-character bare ticker', () => { + const check = checkSymbol('600519') + expect(check.ambiguous).toBe(true) + expect(check.issue).toContain('600519.US') + }) }) describe('toFiniteNumber', () => { @@ -79,6 +97,43 @@ describe('toFiniteNumber', () => { expect(toFiniteNumber(' 1,234.56 ')).toBe(1234.56) }) + it('reads HK$, US$, yuan, and ISO currency glued onto the number', () => { + expect(toFiniteNumber('HK$1,234.50')).toBe(1234.5) + expect(toFiniteNumber('hk$180.5')).toBe(180.5) + expect(toFiniteNumber('US$180.50')).toBe(180.5) + expect(toFiniteNumber('¥180.5')).toBe(180.5) + expect(toFiniteNumber('¥1,600')).toBe(1600) + expect(toFiniteNumber('CN¥180')).toBe(180) + expect(toFiniteNumber('RMB 180.5')).toBe(180.5) + expect(toFiniteNumber('180.50 USD')).toBe(180.5) + expect(toFiniteNumber('320 HKD')).toBe(320) + expect(toFiniteNumber('-HK$12.5')).toBe(-12.5) + expect(toFiniteNumber('-$0.00')).toBe(0) + expect(toFiniteNumber('USD')).toBeUndefined() + expect(toFiniteNumber('HK$')).toBeUndefined() + }) + + it('reads accounting parentheses and a trailing minus as negative amounts', () => { + expect(toFiniteNumber('(180.50)')).toBe(-180.5) + expect(toFiniteNumber('($1,234.56)')).toBe(-1234.56) + expect(toFiniteNumber('(HK$12.5)')).toBe(-12.5) + expect(toFiniteNumber('(¥180.5)')).toBe(-180.5) + expect(toFiniteNumber('1,234.56-')).toBe(-1234.56) + expect(toFiniteNumber('($0.00)')).toBe(0) + expect(toFiniteNumber('()')).toBeUndefined() + expect(toFiniteNumber('($)')).toBeUndefined() + expect(toFiniteNumber('-45.2')).toBe(-45.2) + }) + + it('folds fullwidth digits and separators before parsing', () => { + expect(toFiniteNumber('1,234.56')).toBe(1234.56) + expect(toFiniteNumber('$180.50')).toBe(180.5) + expect(toFiniteNumber('¥180')).toBe(180) + expect(toFiniteNumber('(180.50)')).toBe(-180.5) + expect(toFiniteNumber('-45.2')).toBe(-45.2) + expect(toFiniteNumber(',,,')).toBeUndefined() + }) + it('does not coerce a trailing percent into a number', () => { for (const value of ['100%', '12.5%', '-3.25%', '0%', '1,000%', ' 100 % ', '$12.5%']) { expect(toFiniteNumber(value)).toBeUndefined() @@ -152,6 +207,32 @@ describe('parseCsv', () => { expect(mapped).toMatchObject({ symbol: 'AAPL.US', quantity: 1000, costPrice: 180.5, issues: [] }) }) + it('ignores zero-width characters glued to headers and numbers', () => { + const rows = parseCsv('\u200BSymbol,Quantity,Cost\nAAPL.US,1\u200B000,180.5') + expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 1000, costPrice: 180.5, confidence: 1, issues: [] }) + const wordJoiner = parseCsv('\u2060代码,数量,成本\n0700.HK,500,320') + expect(wordJoiner[0]).toMatchObject({ symbol: '0700.HK', quantity: 500, costPrice: 320, confidence: 1, issues: [] }) + expect(toFiniteNumber('1\u200B,000')).toBe(1000) + expect(toFiniteNumber('\u200B')).toBeUndefined() + }) + + it('parses fullwidth quantity and cost cells', () => { + const [row] = parseCsv('代码,数量,成本\n600519.SH,10,1,600.50') + expect(row).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600.5, confidence: 1, issues: [] }) + }) + + it('parses parenthesized cost cells as negative amounts', () => { + const [row] = parseCsv('Symbol,Quantity,Cost\nAAPL.US,(100),"(HK$1,234.50)"') + expect(row).toMatchObject({ symbol: 'AAPL.US', quantity: -100, costPrice: -1234.5, confidence: 1, issues: [] }) + }) + + it('parses currency-prefixed cost cells from a brokerage CSV', () => { + const rows = parseCsv('Symbol,Quantity,Cost,Currency\nAAPL.US,"1,000","US$180.50",USD\n0700.HK,500,HK$320,HKD\n600519.SH,10,¥1600,CNY') + expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 1000, costPrice: 180.5, currency: 'USD', confidence: 1, issues: [] }) + expect(rows[1]).toMatchObject({ symbol: '0700.HK', quantity: 500, costPrice: 320, currency: 'HKD' }) + expect(rows[2]).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600, currency: 'CNY' }) + }) + it('flags 100% and 12.5% quantity and cost for confirmation instead of booking them', () => { const [both] = parseCsv('Symbol,Quantity,Cost\nAAPL.US,100%,12.5%') expect(both.quantity).toBeUndefined() @@ -274,6 +355,24 @@ describe('parseCsv', () => { expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5 }) }) + it('keeps Price as a cost fallback only when no specific cost column exists', () => { + const rows = parseCsv('Symbol,Price,Shares\nAAPL.US,180.5,100') + expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5, confidence: 1, issues: [] }) + }) + + it('uses the specific cost column when an earlier Price column is also present', () => { + const rows = parseCsv('Symbol,Price,Cost,Qty\nAAPL.US,190.25,180.5,100\n0700.HK,330,320,500') + expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5, confidence: 1, issues: [] }) + expect(rows[1]).toMatchObject({ symbol: '0700.HK', quantity: 500, costPrice: 320 }) + }) + + it('prefers Avg Cost and 成本 over a generic price column', () => { + const english = parseCsv('Ticker,Price,Avg Cost,Shares\nAAPL.US,190.25,180.5,100') + expect(english[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5 }) + const chinese = parseCsv('代码,价格,成本,数量\n600519.SH,1700,1600,10') + expect(chinese[0]).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600, confidence: 1, issues: [] }) + }) + it('supports an explicit headerMapping override', () => { const rows = parseCsv('Ticker,Avg Cost,Units\nAAPL.US,180.5,100', { symbol: 'Ticker', cost: 'Avg Cost', quantity: 'Units' }) expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', quantity: 100, costPrice: 180.5 }) @@ -313,6 +412,14 @@ describe('parseCsv', () => { expect(parseCsv('\n\n')).toEqual([]) }) + it('keeps an over-long symbol for review instead of importing it as clean', () => { + const [row] = parseCsv('Symbol,Quantity,Cost\nTOOLONG.US,100,180.5\n600519.SH,10,1600') + expect(row.confidence).toBe(0.3) + expect(row.issues.some((issue) => issue.includes('not a recognized ticker'))).toBe(true) + const valid = parseCsv('Symbol,Quantity,Cost\n600519.SH,10,1600')[0] + expect(valid).toMatchObject({ symbol: '600519.SH', quantity: 10, costPrice: 1600, confidence: 1, issues: [] }) + }) + it('keeps a row when a required column is missing (review required)', () => { const rows = parseCsv('Symbol,Cost\nAAPL.US,180.5') expect(rows[0]).toMatchObject({ symbol: 'AAPL.US', costPrice: 180.5 }) diff --git a/packages/shared/src/portfolio-import/parsers.ts b/packages/shared/src/portfolio-import/parsers.ts index 1f19d607..f344ddee 100644 --- a/packages/shared/src/portfolio-import/parsers.ts +++ b/packages/shared/src/portfolio-import/parsers.ts @@ -10,11 +10,15 @@ */ import type { ImportSource, PortfolioImportRow } from '@finagent/core' -/** Canonical symbol: 1–8 alphanumerics plus a known market suffix. */ -export const SYMBOL_RE = /^[A-Z0-9]{1,8}\.(US|HK|SG|SH|SZ|HAS)$/ +/** + * Canonical symbol: 1–6 alphanumerics plus a known market suffix. + * Matches `symbolSchema` / Longbridge validation. A-share codes are 6 digits; + * 7–8 character bodies are not canonical and must not import as clean rows. + */ +export const SYMBOL_RE = /^[A-Z0-9]{1,6}\.(US|HK|SG|SH|SZ|HAS)$/ /** Bare ticker with no market suffix — usable, but ambiguous (review). */ -export const BARE_TICKER_RE = /^[A-Z0-9]{1,8}$/ +export const BARE_TICKER_RE = /^[A-Z0-9]{1,6}$/ /** * A plain decimal with one trailing `%`, after thousands separators, `$`, and @@ -42,18 +46,24 @@ export const HEADER_ALIASES: Record = { symbol: ['symbol', 'ticker', 'code', 'stock', '代码', '股票代码', '证券代码'], name: ['name', 'company', 'stockname', '名称', '股票名称', '证券名称'], quantity: ['quantity', 'qty', 'shares', '数量', '持股数量', '股数', '持仓数量'], + // Specific cost headers come first. `price` / `价格` are fallbacks only: + // a leftmost "Price" column must not steal the value when "Cost" or + // "Avg Cost" is also present. cost: [ 'cost', 'costprice', 'cost price', - 'price', 'avgcost', 'avg cost', + 'averagecost', + 'average cost', '成本', '成本价', '买入价', '持仓成本', '均价', + '价格', + 'price', ], currency: ['currency', 'ccy', '货币', '币种'], account: ['account', '账户', '账号', '组合'], @@ -99,11 +109,60 @@ export function checkSymbol(raw: string): SymbolCheck { } } +/** Map fullwidth digits and separators onto the ASCII forms `Number` understands. */ +function foldNumericWidth(value: string): string { + return value + .replace(/[0-9]/g, (digit) => String.fromCharCode(digit.charCodeAt(0) - 0xfee0)) + .replace(/./g, '.') + .replace(/,/g, ',') + .replace(/[-−]/g, '-') + .replace(/$/g, '$') +} + +/** + * Accounting exports write negatives as `(180.50)` or `180.50-`. + * Fullwidth parentheses are accepted. A normal leading minus is left for + * the numeric parse. + */ +function takeAccountingSign(value: string): { text: string; negative: boolean } { + let text = value.trim() + let negative = false + const wrapped = /^(?:\(|()\s*(.*?)\s*(?:\)|))$/.exec(text) + if (wrapped) { + negative = true + text = wrapped[1].trim() + } + if (text.endsWith('-') && !/^[+-]/.test(text)) { + negative = true + text = text.slice(0, -1).trim() + } + return { text, negative } +} + +/** + * Drop currency markers brokerage exports glue onto a number. + * `HK$1,234.50`, `US$180`, `¥180.5`, `180.50 USD` all reduce to the digits. + * A leading sign is preserved (`-HK$12` stays negative). + */ +function stripCurrencyAffixes(value: string): string { + let text = value.trim() + const sign = text.startsWith('-') || text.startsWith('+') ? text[0] : '' + if (sign !== '') text = text.slice(1).trim() + text = text.replace(/^(?:HK|US|S|A|C)\s*\$\s*/i, '') + text = text.replace(/^(?:CN|RMB)\s*[¥¥]\s*/i, '') + text = text.replace(/^(?:RMB|CNY|USD|HKD|SGD|EUR|GBP|AUD|CAD)\s*/i, '') + text = text.replace(/^[¥¥€£$]\s*/, '') + text = text.replace(/\s*(?:RMB|CNY|USD|HKD|SGD|EUR|GBP|AUD|CAD)\s*$/i, '') + text = text.replace(/\s*[$¥¥€£]\s*$/, '') + return `${sign}${text.trim()}` +} + /** * Coerce a CSV/paste cell to a finite number. Strings with thousands - * separators or a leading `$` are handled. A trailing `%` is not stripped: - * `100%` and `12.5%` stay non-numeric so they cannot be booked as 100 / 12.5. - * Empty/null/non-numeric → undefined. + * separators, currency affixes (`$`, `HK$`, `US$`, `¥`, `USD`), full-width + * digits or accounting negatives (`(180.50)`, `180.50-`) are handled. + * A trailing `%` is not stripped: `100%` and `12.5%` stay non-numeric so + * they cannot be booked as 100 / 12.5. Empty/null/non-numeric → undefined. */ export function toFiniteNumber(value: unknown): number | undefined { if (typeof value === 'number') { @@ -112,13 +171,17 @@ export function toFiniteNumber(value: unknown): number | undefined { if (typeof value !== 'string') { return undefined } - const cleaned = stripNumericDecorations(value) + const accounting = takeAccountingSign(foldNumericWidth(stripInvisible(value))) + const trimmed = stripCurrencyAffixes(accounting.text) + const cleaned = stripNumericDecorations(trimmed) // Number('') is zero, but formatting alone does not supply a numeric value. - if (cleaned === '') { + if (cleaned === '' || cleaned === '+' || cleaned === '-') { return undefined } const parsed = Number(cleaned) - return Number.isFinite(parsed) ? parsed : undefined + if (!Number.isFinite(parsed)) return undefined + if (parsed === 0) return 0 + return accounting.negative ? -Math.abs(parsed) : parsed } // ── CSV ──────────────────────────────────────────────────────────────────── @@ -188,8 +251,29 @@ export function splitCsvLine(line: string, delimiter: CsvDelimiter = csvDelimite return cells } +/** Characters `trim` does not remove, but spreadsheets and web paste often insert. */ +const INVISIBLE_CHARS = /[\uFEFF\u200B\u200C\u200D\u2060]/g + +function stripInvisible(value: string): string { + return value.replace(INVISIBLE_CHARS, '') +} + function normalizeHeaderCell(cell: string): string { - return cell.trim().toLowerCase().replace(/[\s_\-]/g, '') + return stripInvisible(cell).trim().toLowerCase().replace(/[\s_\-]/g, '') +} + +/** + * Pick a column by alias specificity, not by leftmost match. + * The first alias that appears anywhere in the row wins, so a generic + * fallback such as `price` does not override an earlier specific header + * that happens to sit further right. + */ +function columnForAliases(cells: readonly string[], aliases: readonly string[]): number { + for (const alias of aliases) { + const index = cells.indexOf(normalizeHeaderCell(alias)) + if (index >= 0) return index + } + return -1 } /** Field → resolved column index for one CSV file. */ @@ -221,7 +305,7 @@ export function resolveCsvColumns( found = cells.indexOf(normalizeHeaderCell(explicit)) } if (found === -1) { - found = cells.findIndex((cell) => HEADER_ALIASES[field].some((alias) => normalizeHeaderCell(alias) === cell)) + found = columnForAliases(cells, HEADER_ALIASES[field]) } if (found >= 0) byIndex.set(found, field) }