dbis_core/CHART_OF_ACCOUNTS_MIGRATION_INSTRUCTIONS.md

# Chart of Accounts - Migration Instructions

## ✅ Files Created

1. **Migration Script**: `scripts/run-chart-of-accounts-migration.sh`
2. **Initialization Script**: `scripts/initialize-chart-of-accounts.ts`
3. **Prisma Model**: Already added to `prisma/schema.prisma`

---

## 🚀 Quick Start

### Option 1: Automated Script (Recommended)

```bash
cd dbis_core

# Set DATABASE_URL or ensure .env file exists
export DATABASE_URL="postgresql://dbis:password@192.168.11.100:5432/dbis_core"

# Run the automated script
./scripts/run-chart-of-accounts-migration.sh
```

### Option 2: Manual Steps

```bash
cd dbis_core

# 1. Set DATABASE_URL
export DATABASE_URL="postgresql://dbis:password@192.168.11.100:5432/dbis_core"

# 2. Generate Prisma client
npx prisma generate

# 3. Create and apply migration
npx prisma migrate dev --name add_chart_of_accounts

# 4. Initialize accounts
ts-node scripts/initialize-chart-of-accounts.ts
```

---

## 📋 Prerequisites

1. **Database Connection**: Ensure `DATABASE_URL` is set or exists in `.env` file
2. **Node.js**: Node.js and npm installed
3. **Dependencies**: Run `npm install` if not already done

---

## 🔧 Database Connection

### Local Development

Create a `.env` file in `dbis_core/`:

```env
DATABASE_URL=postgresql://user:password@localhost:5432/dbis_core
```

### Production (Proxmox)

Based on deployment docs, the database is at:
- **Host**: 192.168.11.100
- **Port**: 5432
- **Database**: dbis_core
- **User**: dbis
- **Password**: (from deployment docs)

```env
DATABASE_URL=postgresql://dbis:8cba649443f97436db43b34ab2c0e75b5cf15611bef9c099cee6fb22cc3d7771@192.168.11.100:5432/dbis_core
```

---

## ✅ Verification

After running the migration and initialization:

```bash
# Check accounts via API (if API is running)
curl http://localhost:3000/api/accounting/chart-of-accounts

# Or check directly in database
psql $DATABASE_URL -c "SELECT COUNT(*) FROM chart_of_accounts;"
psql $DATABASE_URL -c "SELECT account_code, account_name, category FROM chart_of_accounts WHERE level = 1;"
```

---

## 🐛 Troubleshooting

### Error: DATABASE_URL not found
- Create `.env` file with `DATABASE_URL`
- Or export it: `export DATABASE_URL="..."`

### Error: Migration already exists
- If migration was partially applied, you can:
  - Reset: `npx prisma migrate reset` (⚠️ deletes data)
  - Or mark as applied: `npx prisma migrate resolve --applied add_chart_of_accounts`

### Error: Prisma client not generated
- Run: `npx prisma generate`

### Error: TypeScript compilation
- Install ts-node: `npm install -g ts-node` or `npm install --save-dev ts-node`
- Or build first: `npm run build`

---

## 📊 Expected Results

After successful initialization:

- ✅ **50+ accounts** created in `chart_of_accounts` table
- ✅ **5 main categories**: Assets, Liabilities, Equity, Revenue, Expenses
- ✅ **All accounts** have USGAAP and IFRS classifications
- ✅ **Hierarchical structure** with parent-child relationships

---

## 🔄 Re-initialization

If you need to re-initialize (e.g., after schema changes):

```bash
# Option 1: Delete and re-create (⚠️ deletes existing accounts)
psql $DATABASE_URL -c "TRUNCATE TABLE chart_of_accounts CASCADE;"
ts-node scripts/initialize-chart-of-accounts.ts

# Option 2: Use upsert (safe, updates existing)
# The initializeChartOfAccounts() function uses upsert, so it's safe to run multiple times
ts-node scripts/initialize-chart-of-accounts.ts
```

---

## 📝 Next Steps

After migration and initialization:

1. **Verify accounts**: Check that all accounts were created
2. **Test API**: Ensure API endpoints work
3. **Link to Ledger**: Update ledger service to use chart of accounts codes
4. **Generate Reports**: Use chart of accounts for financial statements

---

**Status**: ✅ Ready to run migration and initialization!