taiwan-payroll

Open-source движок расчёта обязательных взносов Тайваня по трудовому/медицинскому страхованию и пенсии (勞健保勞退). По зарплате и статусу застрахованного вычисляет нагрузку всех сторон по трудовому страхованию (вкл. страхование занятости), медицинскому страхованию, пенсии (勞退), страхованию от профзаболеваний и дополнительному взносу медстрахования второго поколения. Также покрывает удержание подоходного налога с зарплаты, неполный месяц при приёме/увольнении в середине месяца, файлы отчётности по доп. медвзносу и расчёт пенсии по старости.

• 🧮 Онлайн-расчёт: https://taiwan-payroll.vercel.app (без установки, прямо в браузере)
• 🔌 Три интерфейса: TypeScript (npm), Python (PyPI, чистая stdlib), MCP-сервер (для вызова ИИ-ассистентами)
• 📑 Сверка с официальным: таблицы разрядов и ставки взяты из публикаций надзорных органов; результаты по-битово сверены с официальными «золотыми» примерами
• 🔁 Кросс-языковая согласованность: TS и Python читают один data/ и гоняют один testdata/, результаты идентичны по-битово
• 📦 Ноль зависимостей рантайма: core не тянет ни одного runtime-пакета

Позиционируется как «расчётный движок», а не «гарантия соответствия праву». Встроены официальные параметры 2024–2026 (民國 113–115) годов.

Установка

npm install taiwan-payroll      # TypeScript / Node
pip install taiwan-payroll      # Python

Быстрый старт

import { createPayrollEngine } from 'taiwan-payroll';

const engine = createPayrollEngine({ year: 2026 });
const r = engine.calculate({
  monthlySalary: 42000,
  identity: 'category1',
  dependents: 1,
  employmentInsurance: true,
  pensionSelfContribution: 0.06,
});

console.log(r.employee); // { labor: 1050, health: 1302, pensionSelf: 2520, total: 4872 }
console.log(r.employer.occupational); // нагрузка работодателя по профзаболеваниям

Доп. медвзнос второго поколения и неполный месяц

// Доп. взнос (6 видов дохода: bonus/parttime/professional/dividend/interest/rent)
engine.calculateSupplementary({ type: 'bonus', amount: 200000, monthlyInsuredSalary: 42000 });
// → { type: 'bonus', chargeable: 32000, rate: '0.0211', premium: 675 }

// Приём/увольнение в середине месяца (трудовое/проф. страхование/пенсия — по дням; медстрахование — по принципу «принадлежность на конец месяца»)
engine.calculateProrated({ monthlySalary: 29500, startDate: '2026-03-08' });
// → { ..., days: { insured: 23 }, healthCharged: true }

Неполный месяц по медстрахованию — по «принципу принадлежности на конец месяца»: взнос за полный месяц по страхователю на конец месяца — за месяц приёма берётся полный месяц, за месяц увольнения не берётся. Это практическое правило Управления медстрахования (не по дням, не связано с порогом 15-го числа).

Файлы отчётности (доп. медвзнос)

Из данных отчётности генерируется «файл декларации доп. страхового взноса» Управления медстрахования (CSV / Big5), покрывая 6 видов дохода: премия(62), зарплата по совместительству(63), профдеятельность(65), дивиденды(66), проценты(67), аренда(68). Каждый генератор по-битово сверен с официальными примерами, TS и Python дают идентичный результат.

import { generateSupplementaryBonusFiling } from 'taiwan-payroll';

const { filename, content } = generateSupplementaryBonusFiling({
  year: 2026,
  filingDate: '20260901',
  unit: { taxId: '11111111', name: '甲公司', phone: '0227065866', email: 'a@b.tw', contactName: '王小明' },
  records: [
    { action: 'I', payDate: '20260615', payeeId: 'A123456789', payeeName: '李四',
      bonusAmount: 50000, insuredSalary: 31800, ytdBonusCumulative: 150000, unitCode: '123456789' },
  ],
});
// filename: 'DPR111111111150901001.csv'
// content: строка Unicode; реальный файл — в Big5, при сохранении пишите в кодировке Big5.

• Премия/совместительство/профдеятельность/проценты/аренда: построчный взнос считает движок. Дивиденды (generateSupplementaryDividendFiling) — из-за дивидендов акциями/вычетов работодателя построчный взнос предоставляет вызывающая сторона (есть удобная функция calcDividendPremium).
• Вывод — «файл данных» для загрузки через официальный портал. Кодировка Big5: в TS кодирует вызывающая сторона, в Python есть to_big5_bytes() (core остаётся без зависимостей).
• Детали API — на сайте доков /docs/api.

Расчёт пенсии по старости

По официальным формулам Управления трудового страхования рассчитываются три вида пенсии по старости (все сверены с официальными значениями/формулами, TS ≡ Python):

import { calcOldAgePension, calcOldAgeLumpSum, calcOldAgeSinglePayment, getYearData } from 'taiwan-payroll';
const d = getYearData(2026);
calcOldAgePension(d, { avgInsuredSalary: 32000, years: 35, months: 6 });     // ежемесячный аннуитет (лучшая из двух формул, можно раньше/позже)
calcOldAgeLumpSum(d, { avgInsuredSalary: 30000, years: 10 });                // единовременная по старости
calcOldAgeSinglePayment(d, { avgInsuredSalary: 30000, preSixtyYears: 20 });  // разовое получение (старая система баллов)

• Пенсия по старости: лучшая из двух формул (среднее×стаж×0.775%+3000 vs ×1.55%), смещение раньше/позже claimOffsetMonths (±4%/год, предел ±5 лет (±20%)); поля averageHighestInsuredSalary, statutoryClaimAge.
• Единовременная: за каждый полный год стажа — 1 месяц; после 60 лет стаж учитывается максимум 5 лет.
• Разовое получение: система баллов (первые 15 лет — 1 балл/год, сверх — 2 балла/год, до 60 предел 45, суммарный предел 50); среднее берётся за 36 месяцев до снятия со страхования.
• Расчёт только справочный, фактически — по утверждению Управления трудового страхования.

Архитектура

• data/{year}.json — единый источник истины, годовые параметры законодательства (таблицы разрядов, ставки), проверяются JSON Schema.
• testdata/ — языконезависимые «золотые» тестовые векторы (официальные примеры с source) — основа согласованности поведения между языками.
• packages/core — TypeScript-движок без зависимостей рантайма.

Другие языки и интерфейсы

• Python: pip install taiwan-payroll, чистая stdlib, API соответствует версии TS (PyPI).
• MCP-сервер: позволяет Claude и др. ассистентам вызывать расчёт напрямую. Удалённый эндпойнт без установки https://taiwan-payroll.simoko.workers.dev/mcp (Streamable HTTP) или локально npx taiwan-payroll-mcp (stdio, npm).
• Размещён в официальном MCP Registry (io.github.supra126/taiwan-payroll), Smithery (установка в один клик) и Glama.
• Онлайн-калькулятор и полный API: https://taiwan-payroll.vercel.app

Источники данных (2026 / 民國115)

Пункт	Надзорный орган	№ документа
Таблица разрядов застрахованной зарплаты трудового страхования (11 разрядов, предел 45 800)	勞動部勞保局	勞動保2字第1140091863號令
Таблица месячных отчислений пенсии (62 разряда, предел 150 000)	勞動部勞保局	勞動福3字第1140153598號令
Таблица разрядов страхования от профзаболеваний (21 разряд, предел 72 800)	勞動部勞保局	職災保險法§17
Таблица разрядов медстрахования (58 разрядов, предел 313 000)	衛福部健保署	衛部保字第1140153424號令

Ставки: трудовое страхование 12,5% (вкл. страхование занятости 1%), медстрахование 5,17%, пенсия (работодатель) 6%, профзаболевания в среднем 0,21%, доп. медвзнос 2,11%.

Сейчас встроены три года — 113／114／115 (2024／2025／2026); таблицы разрядов и № документов каждого года — в sources файла data/{year}.json; год задаётся через createPayrollEngine({ year }), доступные годы — через getAvailableYears().

Разработка

pnpm install
pnpm validate:data   # проверить data schema, непрерывность разрядов, формат векторов
pnpm -r test         # прогнать все золотые тестовые векторы
pnpm typecheck

Дисклеймер

Пакет реализован по публичным нормам и публикациям надзорных органов; результаты расчёта только справочные, фактическая сумма к уплате — по платёжкам Управления трудового и медицинского страхования. Пакет не является юридической или бухгалтерской консультацией.

License

MIT