@core / invoices

1.0.1 ▾

1.0.1

已验证MIT

GitHub

从订单生成西班牙发票：合法编号、简易/完整发票、更正发票和 VeriFactu 风格哈希链

代码8 个文件上下文约 852 个 token扫描通过

约 852 个 token→ src/lib/invoices/AGENTS.md→ .cursor/rules/genpm-core-invoices.mdc

这正是你的 AI 在 src/lib/invoices 中工作时读取的内容。不会向其上下文添加其他任何内容。

@core/invoices — rules for AI agents

Purpose

Spanish invoices for paid orders (@core/orders): correlative numbering per series and year without gaps, simplified invoice up to the legal limit and full invoice above it, credit notes (rectificativas por diferencias) for refunds in their own series, full invoices that replace simplified ones when the customer gives their tax details, printable HTML with the mandatory content, and VeriFactu-style registration records: each record carries the SHA-256 hash of the previous one (format verified against the AEAT example) and the AEAT verification QR URL. Invoices are never edited or deleted. Tables: invoices, invoice_counters, invoice_records.

Scope of 1.0 (tell the person): this package prepares the data required by RD 1007/2023 and Order HAC/1177/2024, but it does not yet sign records (non-VeriFactu mode) nor send them to the AEAT (VeriFactu mode), and it is not a certified billing system. Deadlines changed several times (RD-ley 15/2025 set 2027; in October 2026 the Ministry announced a move to October 2028): check the current official calendar with the AEAT or a tax advisor.

Map

index.ts — invoiceOrder, rectifyRefund, rectifyInFull, remainingToRectify, replaceSimplified, verifyChain, invoiceHtml, invoiceQrUrl, invoicesAdminResource.
invoices.ts — issuing and order events. verifactu.ts — hash input, hash, Madrid dates, amounts, QR URL. html.ts — printable invoice.

Integration

Env: INVOICE_ISSUER_NIF, INVOICE_ISSUER_NAME, INVOICE_ISSUER_ADDRESS; optional INVOICE_SERIES (default A; credit notes use <series>R), INVOICE_VAT_RATE (default 21, prices include VAT), INVOICE_RETAIL=1 (simplified limit 3,000 € instead of 400 €), INVOICE_QR_ENV=test while testing.
Migrations as in src/lib/db/AGENTS.md. Import @/lib/invoices once at startup (e.g. src/genpm/commerce.ts): it issues invoices when orders are paid and credit notes when they are refunded (background jobs, retried).
Admin: add invoicesAdminResource({ printPath: (i) => \/invoices/${i.number}` })tosrc/genpm/admin.ts`.
Printable page for the owner (protected by invoices:read) or the customer (signed order link): return new Response(invoiceHtml(inv, { qrImageSrc }), { headers: { 'content-type': 'text/html' } }). Generate the QR image from invoiceQrUrl(inv) with a QR library in the app.
Verify: pay a test order → invoice A<year>-000001; refund part → credit note AR<year>-000001 with a negative total; verifyChain(nif) returns ok: true.

Conventions

Lines add up to the total: products at their pre-discount amount, one "Discount" line, "Shipping (<method>)" and "Tax" if added on top.
"Rectify in full" (admin, rectifyInFull) credits only what earlier credit notes left; it refuses when nothing remains.
All lines use one VAT rate in 1.0; mixed rates (reduced, exempt) need per-line taxes before using this package.
Issue invoices in EUR only; convert other currencies before.
Keep invoices and records at least as long as tax law requires (typically 4–6 years); never prune these tables.

Don't

Don't edit, renumber or delete invoices or records; correct with credit notes.
Don't print "VERI*FACTU" on invoices until records are actually sent to the AEAT.
Don't present this package as certified or as legal/tax advice.

# @core/invoices — rules for AI agents

## Purpose
Spanish invoices for paid orders (@core/orders): correlative numbering per series and year without gaps, simplified
invoice up to the legal limit and full invoice above it, credit notes (rectificativas por diferencias) for refunds in
their own series, full invoices that replace simplified ones when the customer gives their tax details, printable HTML
with the mandatory content, and VeriFactu-style registration records: each record carries the SHA-256 hash of the
previous one (format verified against the AEAT example) and the AEAT verification QR URL. Invoices are never edited
or deleted. Tables: `invoices`, `invoice_counters`, `invoice_records`.

**Scope of 1.0 (tell the person):** this package prepares the data required by RD 1007/2023 and Order HAC/1177/2024,
but it does not yet sign records (non-VeriFactu mode) nor send them to the AEAT (VeriFactu mode), and it is not a
certified billing system. Deadlines changed several times (RD-ley 15/2025 set 2027; in October 2026 the Ministry
announced a move to October 2028): check the current official calendar with the AEAT or a tax advisor.

## Map
- `index.ts` — `invoiceOrder`, `rectifyRefund`, `rectifyInFull`, `remainingToRectify`, `replaceSimplified`, `verifyChain`, `invoiceHtml`, `invoiceQrUrl`, `invoicesAdminResource`.
- `invoices.ts` — issuing and order events. `verifactu.ts` — hash input, hash, Madrid dates, amounts, QR URL. `html.ts` — printable invoice.

## Integration
1. Env: `INVOICE_ISSUER_NIF`, `INVOICE_ISSUER_NAME`, `INVOICE_ISSUER_ADDRESS`; optional `INVOICE_SERIES` (default `A`;
   credit notes use `<series>R`), `INVOICE_VAT_RATE` (default 21, prices include VAT), `INVOICE_RETAIL=1` (simplified
   limit 3,000 € instead of 400 €), `INVOICE_QR_ENV=test` while testing.
2. Migrations as in `src/lib/db/AGENTS.md`. Import `@/lib/invoices` once at startup (e.g. `src/genpm/commerce.ts`):
   it issues invoices when orders are paid and credit notes when they are refunded (background jobs, retried).
3. Admin: add `invoicesAdminResource({ printPath: (i) => \`/invoices/${i.number}\` })` to `src/genpm/admin.ts`.
4. Printable page for the owner (protected by `invoices:read`) or the customer (signed order link):
   return `new Response(invoiceHtml(inv, { qrImageSrc }), { headers: { 'content-type': 'text/html' } })`. Generate the QR
   image from `invoiceQrUrl(inv)` with a QR library in the app.
5. Verify: pay a test order → invoice `A<year>-000001`; refund part → credit note `AR<year>-000001` with a negative total;
   `verifyChain(nif)` returns `ok: true`.

## Conventions
- Lines add up to the total: products at their pre-discount amount, one "Discount" line, "Shipping (<method>)" and "Tax" if added on top.
- "Rectify in full" (admin, `rectifyInFull`) credits only what earlier credit notes left; it refuses when nothing remains.
- All lines use one VAT rate in 1.0; mixed rates (reduced, exempt) need per-line taxes before using this package.
- Issue invoices in EUR only; convert other currencies before.
- Keep invoices and records at least as long as tax law requires (typically 4–6 years); never prune these tables.

## Don't
- Don't edit, renumber or delete invoices or records; correct with credit notes.
- Don't print "VERI*FACTU" on invoices until records are actually sent to the AEAT.
- Don't present this package as certified or as legal/tax advice.

应用 .genpmignore 后将被注入的确切目录树。固定于

src/lib/invoices/index.ts只读 · 6912dca

// @core/invoices — API pública. Al importarlo emite facturas al pagarse los pedidos y rectificativas en los reembolsos.
export { invoicesAdminResource } from './admin.ts';
export { INVOICE_TITLES, invoiceHtml } from './html.ts';
export {
  InvoiceError,
  invoiceOrder,
  invoiceQrUrl,
  issuer,
  linesOf,
  rectifyInFull,
  rectifyRefund,
  registerInvoicing,
  remainingToRectify,
  replaceSimplified,
  simplifiedLimit,
  split,
  verifyChain,
} from './invoices.ts';
export { type Invoice, type InvoiceLine, type InvoiceRecord, invoiceCounters, invoiceRecords, invoices, type Party } from './schema.ts';
export { type AltaFields, type AnulacionFields, amountText, huella, huellaInput, madridTimestamp, qrUrl, spanishDate } from './verifactu.ts';

版本	提交	发布时间	扫描
1.0.1	6912dca	6小时前	扫描通过

$genpm add @core/invoices

注入到: src/lib/invoices
提交
标签: v1.0.1
需要: @core/contracts ^1.0.0 @core/db ^1.0.0 @core/orders ^1.0.0
npm: zod ^4.0.0
Env: INVOICE_ISSUER_NIF INVOICE_ISSUER_NAME INVOICE_ISSUER_ADDRESS INVOICE_SERIES INVOICE_VAT_RATE INVOICE_RETAIL INVOICE_QR_ENV
质量: 100/100
安装量: 0 / 30天
发布时间: 6小时前 · genpm-system

README 徽章

[![genpm](https://api.genpm.net/v1/badge/@core/invoices.svg)](https://genpm.net/p/@core/invoices)