---
change: betterauth-hono-drizzle-migration
design-doc: docs/superpowers/specs/2026-07-03-betterauth-hono-drizzle-migration-design.md
base-ref: ca3511d57d9b9b5b52afe02ca4ffc7fa112bc404
---

# NestJS → HonoJS + better-auth + Drizzle + PGlite/PostgreSQL 迁移实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 将 apps/server 从 NestJS + TypeORM + MySQL/better-sqlite3 全栈替换为 HonoJS + Drizzle ORM + better-auth + PGlite(dev)/PostgreSQL(prod)，保持 60+ API 端点兼容、49 权限点不变、前端零改动。

**Architecture:** HonoJS 作为 HTTP 框架，better-auth 接管认证与 RBAC，Drizzle ORM 替代 TypeORM 管理 16 张表，PGlite 提供零 Docker 的本地开发体验，PostgreSQL 用于生产。中间件栈：CORS → RateLimit → better-auth JWT → PermissionCheck → ZodValidator → Route Handler。

**Tech Stack:** Hono 4.x, @hono/node-server, better-auth, drizzle-orm, @electric-sql/pglite, pg, zod, @hono/zod-validator, hono-rate-limiter, exceljs, pdfkit, bcryptjs

## Global Constraints

- Node.js ≥ 20, TypeScript 5.x, pnpm (monorepo)
- 所有 API 端点路径和响应格式必须与 NestJS 版本保持兼容
- 49 个权限码（14 分组）完整保留，前端 `@RequirePermission` 等效逻辑零改动
- 4 个预设角色（admin/supervisor/teacher/institution）权限分配不变
- PGlite 数据文件路径：`apps/server/pglite-data/`，加入 .gitignore
- better-auth JWT payload 必须包含 `{ sub: id, username, permissions: string[] }`
- 开发命令：`tsx watch src/index.ts`（热重载），构建：`tsc -p tsconfig.build.json`

---

### Task 1: 项目初始化与环境搭建

**Files:**
- Modify: `apps/server/package.json`
- Create: `apps/server/tsconfig.build.json`
- Modify: `apps/server/tsconfig.json`
- Modify: `turbo.json`
- Create: `apps/server/.gitignore`（追加 pglite-data/）

**Interfaces:**
- Produces: `pnpm dev` 可启动空 Hono 服务器在 :3003

- [ ] **Step 1: 更新 package.json — 替换依赖和 scripts**

```bash
cd apps/server
# 移除 NestJS 相关依赖
pnpm remove @nestjs/common @nestjs/core @nestjs/config @nestjs/jwt @nestjs/passport \
  @nestjs/platform-express @nestjs/throttler @nestjs/typeorm @nestjs/cli \
  @nestjs/schematics @nestjs/testing typeorm mysql2 better-sqlite3 \
  passport passport-jwt passport-local class-transformer class-validator \
  reflect-metadata rxjs multer @types/multer @types/better-sqlite3 @types/express

# 安装新依赖
pnpm add hono @hono/node-server better-auth drizzle-orm @electric-sql/pglite pg \
  exceljs pdfkit bcryptjs zod @hono/zod-validator hono-rate-limiter dotenv

# 安装 dev 依赖
pnpm add -D drizzle-kit tsx @types/pg @types/bcryptjs @types/pdfkit
```

更新 `apps/server/package.json` scripts：
```json
{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/index.js",
    "typecheck": "tsc -p tsconfig.build.json --noEmit",
    "db:push": "drizzle-kit push",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    "db:seed": "tsx src/db/seed.ts"
  }
}
```

- [ ] **Step 2: 创建 tsconfig.build.json**

```json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "test"]
}
```

- [ ] **Step 3: 更新 turbo.json**

确保 `apps/server` 的 build 和 dev pipeline 配置正确（移除 NestJS 特有配置）：

```json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "typecheck": {
      "dependsOn": ["^build"]
    }
  }
}
```

- [ ] **Step 4: 创建最小 Hono 入口验证项目可启动**

创建 `apps/server/src/index.ts`：
```typescript
import { Hono } from 'hono';
import { serve } from '@hono/node-server';

const app = new Hono();

app.get('/api/health', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString() }));

const port = Number(process.env.PORT) || 3003;
console.log(`Server running on http://localhost:${port}`);
serve({ fetch: app.fetch, port });
```

- [ ] **Step 5: 验证启动**

```bash
cd apps/server && pnpm dev
# 预期：Server running on http://localhost:3003
# curl http://localhost:3003/api/health → {"status":"ok","timestamp":"..."}
```

- [ ] **Step 6: Commit**

```bash
git add apps/server/package.json apps/server/pnpm-lock.yaml apps/server/tsconfig.build.json \
  apps/server/tsconfig.json turbo.json apps/server/.gitignore apps/server/src/index.ts
git commit -m "feat: initialize HonoJS project structure, replace NestJS dependencies"
```

---

### Task 2: 数据库 Schema 定义 — 认证相关表

**Files:**
- Create: `apps/server/src/db/schema/auth.ts`
- Create: `apps/server/src/db/schema/index.ts`
- Create: `apps/server/drizzle.config.ts`

**Interfaces:**
- Produces: `users`, `roles`, `permissions`, `user_roles`, `role_permissions` 5 张 Drizzle 表定义
- Consumes: Task 1 (项目结构)

- [ ] **Step 1: 创建 drizzle.config.ts**

```typescript
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema/index.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    host: process.env.DB_HOST || 'localhost',
    port: Number(process.env.DB_PORT) || 5432,
    user: process.env.DB_USERNAME || 'postgres',
    password: process.env.DB_PASSWORD || 'postgres',
    database: process.env.DB_DATABASE || 'gongxue',
    ssl: process.env.DB_SSL === 'true',
  },
});
```

- [ ] **Step 2: 定义 Drizzle schema — auth.ts（认证 5 表）**

```typescript
// apps/server/src/db/schema/auth.ts
import { pgTable, serial, varchar, boolean, timestamp, integer, primaryKey } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  username: varchar('username', { length: 50 }).unique().notNull(),
  passwordHash: varchar('password_hash', { length: 255 }).notNull(),
  name: varchar('name', { length: 50 }),
  isActive: boolean('is_active').default(true).notNull(),
  lastLoginAt: timestamp('last_login_at'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const roles = pgTable('roles', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 30 }).unique().notNull(),
  description: varchar('description', { length: 200 }),
  isSystem: boolean('is_system').default(false).notNull(),
  status: integer('status').default(1).notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const permissions = pgTable('permissions', {
  id: serial('id').primaryKey(),
  code: varchar('code', { length: 50 }).unique().notNull(),
  name: varchar('name', { length: 50 }).notNull(),
  group: varchar('group', { length: 30 }).notNull(),
  description: varchar('description', { length: 200 }),
});

export const userRoles = pgTable('user_roles', {
  userId: integer('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(),
  roleId: integer('role_id').references(() => roles.id, { onDelete: 'cascade' }).notNull(),
}, (t) => ({ pk: primaryKey({ columns: [t.userId, t.roleId] }) }));

export const rolePermissions = pgTable('role_permissions', {
  roleId: integer('role_id').references(() => roles.id, { onDelete: 'cascade' }).notNull(),
  permissionId: integer('permission_id').references(() => permissions.id, { onDelete: 'cascade' }).notNull(),
}, (t) => ({ pk: primaryKey({ columns: [t.roleId, t.permissionId] }) }));

// Relations
export const usersRelations = relations(users, ({ many }) => ({
  userRoles: many(userRoles),
}));

export const rolesRelations = relations(roles, ({ many }) => ({
  userRoles: many(userRoles),
  rolePermissions: many(rolePermissions),
}));

export const permissionsRelations = relations(permissions, ({ many }) => ({
  rolePermissions: many(rolePermissions),
}));

export const userRolesRelations = relations(userRoles, ({ one }) => ({
  user: one(users, { fields: [userRoles.userId], references: [users.id] }),
  role: one(roles, { fields: [userRoles.roleId], references: [roles.id] }),
}));

export const rolePermissionsRelations = relations(rolePermissions, ({ one }) => ({
  role: one(roles, { fields: [rolePermissions.roleId], references: [roles.id] }),
  permission: one(permissions, { fields: [rolePermissions.permissionId], references: [permissions.id] }),
}));
```

- [ ] **Step 3: 创建 schema barrel 导出**

```typescript
// apps/server/src/db/schema/index.ts
export * from './auth';
```

- [ ] **Step 4: Commit**

```bash
git add apps/server/drizzle.config.ts apps/server/src/db/schema/auth.ts apps/server/src/db/schema/index.ts
git commit -m "feat: add Drizzle schema for auth tables (users, roles, permissions, user_roles, role_permissions)"
```

---

### Task 3: 数据库 Schema 定义 — 业务表

**Files:**
- Create: `apps/server/src/db/schema/student.ts`
- Create: `apps/server/src/db/schema/room.ts`
- Create: `apps/server/src/db/schema/occupancy.ts`
- Create: `apps/server/src/db/schema/expense.ts`
- Create: `apps/server/src/db/schema/bill.ts`
- Modify: `apps/server/src/db/schema/index.ts`

**Interfaces:**
- Produces: `students`, `rooms`, `occupancies`, `room_expenses`, `personal_expenses`, `bills`, `bill_items` 7 张表
- Consumes: Task 2 (schema barrel)

- [ ] **Step 1: students 表**

```typescript
// apps/server/src/db/schema/student.ts
import { pgTable, serial, varchar, timestamp } from 'drizzle-orm/pg-core';

export const students = pgTable('students', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 50 }).notNull(),
  phone: varchar('phone', { length: 20 }),
  idNumber: varchar('id_number', { length: 30 }),
  gender: varchar('gender', { length: 10 }),
  ethnicity: varchar('ethnicity', { length: 20 }),
  emergencyContact: varchar('emergency_contact', { length: 50 }),
  emergencyPhone: varchar('emergency_phone', { length: 20 }),
  status: varchar('status', { length: 20 }).default('active').notNull(),
  organization: varchar('organization', { length: 100 }),
  supervisor: varchar('supervisor', { length: 50 }),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});
```

- [ ] **Step 2: rooms 表**

```typescript
// apps/server/src/db/schema/room.ts
import { pgTable, serial, varchar, integer, timestamp } from 'drizzle-orm/pg-core';

export const rooms = pgTable('rooms', {
  id: serial('id').primaryKey(),
  roomNumber: varchar('room_number', { length: 20 }).unique().notNull(),
  building: varchar('building', { length: 50 }),
  floor: integer('floor'),
  capacity: integer('capacity').notNull(),
  status: varchar('status', { length: 20 }).default('available').notNull(),
  roomType: varchar('room_type', { length: 20 }),
  gender: varchar('gender', { length: 10 }),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});
```

- [ ] **Step 3: occupancies 表**

```typescript
// apps/server/src/db/schema/occupancy.ts
import { pgTable, serial, integer, varchar, date, timestamp } from 'drizzle-orm/pg-core';
import { students } from './student';
import { rooms } from './room';

export const occupancies = pgTable('occupancies', {
  id: serial('id').primaryKey(),
  studentId: integer('student_id').references(() => students.id, { onDelete: 'cascade' }).notNull(),
  roomId: integer('room_id').references(() => rooms.id, { onDelete: 'cascade' }).notNull(),
  checkInDate: date('check_in_date').notNull(),
  checkOutDate: date('check_out_date'),
  price: integer('price'),
  status: varchar('status', { length: 20 }).default('active').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});
```

- [ ] **Step 4: expenses 表（room_expenses + personal_expenses）**

```typescript
// apps/server/src/db/schema/expense.ts
import { pgTable, serial, integer, varchar, decimal, date, timestamp } from 'drizzle-orm/pg-core';
import { rooms } from './room';
import { students } from './student';

export const roomExpenses = pgTable('room_expenses', {
  id: serial('id').primaryKey(),
  roomId: integer('room_id').references(() => rooms.id, { onDelete: 'cascade' }).notNull(),
  name: varchar('name', { length: 100 }).notNull(),
  amount: decimal('amount', { precision: 10, scale: 2 }).notNull(),
  periodStart: date('period_start').notNull(),
  periodEnd: date('period_end').notNull(),
  status: varchar('status', { length: 20 }).default('active').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const personalExpenses = pgTable('personal_expenses', {
  id: serial('id').primaryKey(),
  studentId: integer('student_id').references(() => students.id, { onDelete: 'cascade' }).notNull(),
  name: varchar('name', { length: 100 }).notNull(),
  amount: decimal('amount', { precision: 10, scale: 2 }).notNull(),
  periodStart: date('period_start').notNull(),
  periodEnd: date('period_end').notNull(),
  status: varchar('status', { length: 20 }).default('active').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});
```

- [ ] **Step 5: bills 表（bills + bill_items）**

```typescript
// apps/server/src/db/schema/bill.ts
import { pgTable, serial, integer, varchar, decimal, date, timestamp } from 'drizzle-orm/pg-core';
import { students } from './student';

export const bills = pgTable('bills', {
  id: serial('id').primaryKey(),
  studentId: integer('student_id').references(() => students.id, { onDelete: 'cascade' }).notNull(),
  billNumber: varchar('bill_number', { length: 50 }).notNull(),
  totalAmount: decimal('total_amount', { precision: 10, scale: 2 }).notNull(),
  status: varchar('status', { length: 20 }).default('pending').notNull(),
  periodStart: date('period_start'),
  periodEnd: date('period_end'),
  issuedAt: timestamp('issued_at').defaultNow().notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const billItems = pgTable('bill_items', {
  id: serial('id').primaryKey(),
  billId: integer('bill_id').references(() => bills.id, { onDelete: 'cascade' }).notNull(),
  name: varchar('name', { length: 100 }).notNull(),
  amount: decimal('amount', { precision: 10, scale: 2 }).notNull(),
  type: varchar('type', { length: 20 }).notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});
```

- [ ] **Step 6: Commit**

```bash
git add apps/server/src/db/schema/
git commit -m "feat: add Drizzle schema for business tables (students, rooms, occupancies, expenses, bills)"
```

---

### Task 4: 数据库 Schema 定义 — 其他表 + 连接工厂 + Seed

**Files:**
- Create: `apps/server/src/db/schema/classroom.ts`
- Create: `apps/server/src/db/schema/deposit.ts`
- Create: `apps/server/src/db/schema/operation-log.ts`
- Modify: `apps/server/src/db/schema/index.ts`（导出所有 16 表）
- Create: `apps/server/src/db/index.ts`（连接工厂）
- Create: `apps/server/src/db/seed.ts`（幂等 seed）

**Interfaces:**
- Produces: `classrooms`, `tenants`, `classroom_rentals`, `deposits`, `operation_logs` 5 张表 + DB 连接工厂 + seed 脚本
- Consumes: Tasks 2-3 (schema 定义)

- [ ] **Step 1: 剩余 5 张业务表定义**

```typescript
// apps/server/src/db/schema/classroom.ts
import { pgTable, serial, varchar, integer, decimal, timestamp } from 'drizzle-orm/pg-core';

export const classrooms = pgTable('classrooms', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 100 }).notNull(),
  capacity: integer('capacity'),
  location: varchar('location', { length: 200 }),
  pricePerDay: decimal('price_per_day', { precision: 10, scale: 2 }),
  status: varchar('status', { length: 20 }).default('available').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const tenants = pgTable('tenants', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 100 }).notNull(),
  contactPerson: varchar('contact_person', { length: 50 }),
  phone: varchar('phone', { length: 20 }),
  notes: varchar('notes', { length: 500 }),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export const classroomRentals = pgTable('classroom_rentals', {
  id: serial('id').primaryKey(),
  classroomId: integer('classroom_id').references(() => classrooms.id, { onDelete: 'cascade' }).notNull(),
  tenantId: integer('tenant_id').references(() => tenants.id, { onDelete: 'cascade' }).notNull(),
  rentalDate: date('rental_date').notNull(),
  startTime: varchar('start_time', { length: 10 }),
  endTime: varchar('end_time', { length: 10 }),
  price: decimal('price', { precision: 10, scale: 2 }),
  status: varchar('status', { length: 20 }).default('active').notNull(),
  notes: varchar('notes', { length: 500 }),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

// apps/server/src/db/schema/deposit.ts
export const deposits = pgTable('deposits', {
  id: serial('id').primaryKey(),
  studentId: integer('student_id').references(() => students.id, { onDelete: 'cascade' }).notNull(),
  amount: decimal('amount', { precision: 10, scale: 2 }).notNull(),
  notes: varchar('notes', { length: 500 }),
  status: varchar('status', { length: 20 }).default('active').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

// apps/server/src/db/schema/operation-log.ts
export const operationLogs = pgTable('operation_logs', {
  id: serial('id').primaryKey(),
  userId: integer('user_id'),
  username: varchar('username', { length: 50 }),
  module: varchar('module', { length: 50 }),
  action: varchar('action', { length: 50 }),
  targetId: integer('target_id'),
  targetType: varchar('target_type', { length: 50 }),
  detail: text('detail'),
  ipAddress: varchar('ip_address', { length: 50 }),
  userAgent: varchar('user_agent', { length: 500 }),
  status: varchar('status', { length: 20 }).default('success'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});
```

- [ ] **Step 2: 数据库连接工厂**

```typescript
// apps/server/src/db/index.ts
import { drizzle } from 'drizzle-orm/pglite';
import { PGlite } from '@electric-sql/pglite';
import { drizzle as drizzlePg } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';
import * as schema from './schema';

const isProd = process.env.NODE_ENV === 'production';

function createDevDb() {
  const client = new PGlite('pglite-data');
  return drizzle(client, { schema });
}

function createProdDb() {
  const pool = new Pool({
    host: process.env.DB_HOST || 'localhost',
    port: Number(process.env.DB_PORT) || 5432,
    user: process.env.DB_USERNAME || 'postgres',
    password: process.env.DB_PASSWORD || 'postgres',
    database: process.env.DB_DATABASE || 'gongxue',
    ssl: process.env.DB_SSL === 'true',
  });
  return drizzlePg(pool, { schema });
}

export const db = isProd ? createProdDb() : createDevDb();
```

- [ ] **Step 3: 幂等 seed 脚本**

基于现有 `rbac.service.ts` 中的 `seedData()` 逻辑，改写为 Drizzle 版本（49 权限码 + 4 预设角色 + admin 用户）。保持相同的 seed 数据内容，用 Drizzle `insert...onConflictDoNothing` 实现幂等。

核心流程：
1. 插入 49 权限码（`onConflictDoNothing`，按 code 唯一键）
2. 插入 4 预设角色（`onConflictDoNothing`，按 name 唯一键）
3. 查询所有权限和角色，构建角色-权限关联
4. 按 group 匹配权限给各角色（超管=全部，宿管=8组，老师=student:view，机构=3组）
5. 初始化 admin 用户（若 users 表为空），密码 bcrypt hash，分配超管角色

完整代码参考现有 `rbac.service.ts:120-191` 的 seedData 逻辑。

- [ ] **Step 4: Commit**

```bash
git add apps/server/src/db/
git commit -m "feat: add remaining Drizzle schemas, DB connection factory, and idempotent seed script"
```

---

### Task 5: better-auth 实例配置

**Files:**
- Create: `apps/server/src/auth/index.ts`
- Create: `apps/server/src/lib/env.ts`（环境变量加载）

**Interfaces:**
- Produces: `auth` 实例（含 username + jwt + admin 插件）、`getAuth` / `getSession` 工具函数
- Consumes: Tasks 2-4 (schema + db)

- [ ] **Step 1: 环境变量工具**

```typescript
// apps/server/src/lib/env.ts
import { config } from 'dotenv';
config();

export const env = {
  PORT: Number(process.env.PORT) || 3003,
  NODE_ENV: process.env.NODE_ENV || 'development',
  DB_HOST: process.env.DB_HOST || 'localhost',
  DB_PORT: Number(process.env.DB_PORT) || 5432,
  DB_USERNAME: process.env.DB_USERNAME || 'postgres',
  DB_PASSWORD: process.env.DB_PASSWORD || 'postgres',
  DB_DATABASE: process.env.DB_DATABASE || 'gongxue',
  BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET || 'dorm-billing-jwt-secret-key-2024',
  BETTER_AUTH_URL: process.env.BETTER_AUTH_URL || 'http://localhost:3003',
  ADMIN_PASSWORD: process.env.ADMIN_PASSWORD || 'admin123',
};
```

- [ ] **Step 2: better-auth 实例配置**

```typescript
// apps/server/src/auth/index.ts
import { betterAuth } from 'better-auth';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import { username, jwt, admin } from 'better-auth/plugins';
import { db } from '../db';
import * as schema from '../db/schema';
import { env } from '../lib/env';

export const auth = betterAuth({
  database: drizzleAdapter(db, {
    provider: 'pg',
    schema: {
      users: schema.users,
      roles: schema.roles,
      permissions: schema.permissions,
      userRoles: schema.userRoles,
      rolePermissions: schema.rolePermissions,
    },
  }),
  emailAndPassword: {
    enabled: false,
  },
  plugins: [
    username(),
    jwt({
      jwt: {
        secret: env.BETTER_AUTH_SECRET,
        expiresIn: '7d',
      },
    }),
    admin(),
  ],
  hooks: {
    after: {
      // JWT 签发后注入 permissions 到 claims
      createJwt: async (ctx) => {
        // 查询用户角色和权限，注入 permissions 数组到 JWT payload
      },
    },
  },
});

// 便捷导出
export const getSession = auth.api.getSession;
```

**注意**: better-auth JWT plugin + admin plugin 的 `createJwt` hook 需要在 build 阶段验证具体 API。根据 better-auth 文档，可能需要通过 hook 或 middleware 注入 `permissions` 到 JWT claims。如果 hook 不支持，备选方案是在登录接口中自行组装 JWT claims。

- [ ] **Step 3: 验证 better-auth 初始化无错误**

```bash
cd apps/server && pnpm typecheck
```

- [ ] **Step 4: Commit**

```bash
git add apps/server/src/auth/ apps/server/src/lib/
git commit -m "feat: configure better-auth instance with username, jwt, and admin plugins"
```

---

### Task 6: JWT 认证中间件 + 权限检查中间件

**Files:**
- Create: `apps/server/src/middleware/auth.ts`
- Create: `apps/server/src/middleware/permission.ts`

**Interfaces:**
- Produces: `authMiddleware`（等效 JwtAuthGuard）、`requirePermission(code)`（等效 @RequirePermission）
- Consumes: Task 5 (auth 实例)

- [ ] **Step 1: JWT 认证中间件**

```typescript
// apps/server/src/middleware/auth.ts
import { createMiddleware } from 'hono/factory';
import { getSession } from '../auth';

// 全局认证中间件：从 Authorization header 提取 JWT，校验并注入 session 到 context
export const authMiddleware = createMiddleware(async (c, next) => {
  const authHeader = c.req.header('Authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    // 不直接拒绝，留给下游 permission 中间件处理
    return next();
  }
  const token = authHeader.slice(7);
  try {
    const session = await getSession(token);
    if (session) {
      c.set('session', session);
      c.set('user', session.user);
    }
  } catch {
    // token 无效，继续（权限中间件会拒绝）
  }
  await next();
});
```

- [ ] **Step 2: 权限检查中间件**

```typescript
// apps/server/src/middleware/permission.ts
import { createMiddleware } from 'hono/factory';

// 路由级权限检查中间件（等效 @RequirePermission 装饰器）
export function requirePermission(code: string) {
  return createMiddleware(async (c, next) => {
    const session = c.get('session');
    if (!session) {
      return c.json({ message: '未登录', statusCode: 401 }, 401);
    }
    const perms: string[] = session.user?.permissions || [];
    // 拥有通配符 *（超管）或指定权限码即可通过
    if (perms.includes('*') || perms.includes(code)) {
      return next();
    }
    return c.json({ message: '权限不足', statusCode: 403 }, 403);
  });
}
```

- [ ] **Step 3: 更新 index.ts 挂载中间件**

```typescript
// apps/server/src/index.ts 增加：
import { authMiddleware } from './middleware/auth';
app.use('/api/*', authMiddleware);
```

- [ ] **Step 4: Commit**

```bash
git add apps/server/src/middleware/
git commit -m "feat: implement JWT auth middleware and permission check middleware"
```

---

### Task 7: 登录接口

**Files:**
- Create: `apps/server/src/routes/auth.ts`
- Modify: `apps/server/src/index.ts`（挂载路由）

**Interfaces:**
- Produces: `POST /api/auth/login`、`GET /api/auth/profile`
- Consumes: Tasks 5-6 (auth 实例 + 中间件)

- [ ] **Step 1: 实现认证路由**

```typescript
// apps/server/src/routes/auth.ts
import { Hono } from 'hono';
import { auth } from '../auth';
import { db } from '../db';
import * as schema from '../db/schema';
import { eq } from 'drizzle-orm';
import { requirePermission } from '../middleware/permission';
import { logOperation } from '../middleware/operation-log';

const authRoute = new Hono();

// POST /api/auth/login — 包装 better-auth signInUsername
authRoute.post('/login', async (c) => {
  const { username, password } = await c.req.json();
  const ip = c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || 'unknown';
  const ua = (c.req.header('user-agent') || '').substring(0, 500);

  try {
    const result = await auth.api.signInUsername({
      body: { username, password },
      headers: c.req.raw.headers,
    });

    // 查询完整用户信息（含角色、权限）
    const user = await db.query.users.findFirst({
      where: eq(schema.users.username, username),
      with: { userRoles: { with: { role: { with: { rolePermissions: { with: { permission: true } } } } } },
    });

    // 收集权限码
    const permSet = new Set<string>();
    const roleNames: string[] = [];
    if (user?.userRoles) {
      for (const ur of user.userRoles) {
        if (ur.role?.status === 1) {
          roleNames.push(ur.role.name);
          for (const rp of ur.role.rolePermissions || []) {
            if (rp.permission) permSet.add(rp.permission.code);
          }
        }
      }
    }

    // 更新登录时间
    await db.update(schema.users).set({ lastLoginAt: new Date() }).where(eq(schema.users.id, user!.id));

    // 记录操作日志
    await db.insert(schema.operationLogs).values({
      userId: user!.id, username, module: '认证', action: '登录成功',
      ipAddress: ip, userAgent: ua, status: 'success',
    });

    return c.json({
      access_token: result?.token,
      user: { id: user!.id, username: user!.username, name: user!.name, roles: roleNames, permissions: [...permSet] },
    });
  } catch (e: any) {
    await db.insert(schema.operationLogs).values({
      username, module: '认证', action: '登录失败',
      detail: e.message || '密码错误', ipAddress: ip, userAgent: ua, status: 'fail',
    });
    return c.json({ message: e.message || '用户名或密码错误', statusCode: 401 }, 401);
  }
});

// GET /api/auth/profile — 获取当前用户信息
authRoute.get('/profile', requirePermission('dashboard:view'), (c) => {
  const user = c.get('user');
  return c.json(user);
});

export { authRoute };
```

- [ ] **Step 2: 挂载路由到主 app**

```typescript
// 在 apps/server/src/index.ts 中添加：
import { authRoute } from './routes/auth';
app.route('/api/auth', authRoute);
```

- [ ] **Step 3: Commit**

```bash
git add apps/server/src/routes/auth.ts apps/server/src/index.ts
git commit -m "feat: implement login endpoint (POST /api/auth/login) with failed attempt tracking"
```

---

### Task 8: 用户管理 CRUD 路由

**Files:**
- Create: `apps/server/src/routes/users.ts`
- Modify: `apps/server/src/index.ts`

**Interfaces:**
- Produces: `GET/POST/PUT/DELETE /api/users`、`PUT /api/users/:id/reset-password`
- Consumes: Task 6 (中间件)、Task 4 (db)

- [ ] **Step 1: 实现用户管理路由**

基于现有 `rbac.service.ts` 的 `findAllUsers`、`createUser`、`updateUser`、`resetPassword`、`deleteUser` 方法，转换为 Drizzle 查询。

```typescript
// apps/server/src/routes/users.ts
import { Hono } from 'hono';
import { db } from '../db';
import * as schema from '../db/schema';
import { eq } from 'drizzle-orm';
import bcrypt from 'bcryptjs';
import { requirePermission } from '../middleware/permission';
import { logOperation } from '../middleware/operation-log';

const usersRoute = new Hono();

// GET /api/users
usersRoute.get('/', requirePermission('user:view'), async (c) => {
  const users = await db.query.users.findMany({
    with: { userRoles: { with: { role: true } } },
    orderBy: (users, { desc }) => [desc(users.createdAt)],
  });
  return c.json(users.map((u) => ({
    id: u.id, username: u.username, name: u.name,
    isActive: u.isActive, lastLoginAt: u.lastLoginAt,
    createdAt: u.createdAt, updatedAt: u.updatedAt,
    roles: u.userRoles?.map((ur) => ({ id: ur.role.id, name: ur.role.name })) || [],
  })));
});

// POST /api/users
usersRoute.post('/', requirePermission('user:create'), async (c) => {
  const { username, password, name, roleIds } = await c.req.json();
  const existing = await db.query.users.findFirst({ where: eq(schema.users.username, username) });
  if (existing) return c.json({ message: '用户名已存在' }, 400);
  const hash = await bcrypt.hash(password, 10);
  const [user] = await db.insert(schema.users).values({ username, passwordHash: hash, name }).returning();
  if (roleIds?.length) {
    await db.insert(schema.userRoles).values(roleIds.map((rid: number) => ({ userId: user.id, roleId: rid })));
  }
  return c.json({ message: '用户创建成功' });
});

// PUT /api/users/:id
usersRoute.put('/:id', requirePermission('user:edit'), async (c) => {
  const id = Number(c.req.param('id'));
  const { username, name, isActive, roleIds } = await c.req.json();
  // ... 更新逻辑（参考 rbac.service.ts:305-322）
  await db.update(schema.users).set({ name, isActive, username }).where(eq(schema.users.id, id));
  // 更新角色关联
  await db.delete(schema.userRoles).where(eq(schema.userRoles.userId, id));
  if (roleIds?.length) {
    await db.insert(schema.userRoles).values(roleIds.map((rid: number) => ({ userId: id, roleId: rid })));
  }
  return c.json({ message: '更新成功' });
});

// PUT /api/users/:id/reset-password
usersRoute.put('/:id/reset-password', requirePermission('user:reset-password'), async (c) => {
  const id = Number(c.req.param('id'));
  const { password } = await c.req.json();
  await db.update(schema.users).set({ passwordHash: await bcrypt.hash(password, 10) }).where(eq(schema.users.id, id));
  return c.json({ message: '密码已重置' });
});

// DELETE /api/users/:id
usersRoute.delete('/:id', requirePermission('user:delete'), async (c) => {
  const id = Number(c.req.param('id'));
  const user = await db.query.users.findFirst({ where: eq(schema.users.id, id) });
  if (!user) return c.json({ message: '用户不存在' }, 404);
  if (user.username === 'admin') return c.json({ message: '不能删除默认管理员' }, 400);
  await db.delete(schema.users).where(eq(schema.users.id, id));
  return c.json({ message: '用户已删除' });
});

export { usersRoute };
```

- [ ] **Step 2: Commit**

```bash
git add apps/server/src/routes/users.ts apps/server/src/index.ts
git commit -m "feat: implement user management CRUD routes (GET/POST/PUT/DELETE /api/users)"
```

---

### Task 9: 角色管理 CRUD 路由 + 权限查询

**Files:**
- Create: `apps/server/src/routes/roles.ts`
- Create: `apps/server/src/routes/permissions.ts`
- Modify: `apps/server/src/index.ts`

**Interfaces:**
- Produces: `GET/POST/PUT/DELETE /api/roles`、`GET /api/permissions`、`GET /api/permissions/tree`
- Consumes: Task 6 (中间件)

- [ ] **Step 1: 角色管理路由**

基于 `rbac.service.ts:193-238`，转换为 Drizzle：

```typescript
// apps/server/src/routes/roles.ts
import { Hono } from 'hono';
import { db } from '../db';
import * as schema from '../db/schema';
import { eq } from 'drizzle-orm';
import { requirePermission } from '../middleware/permission';

const rolesRoute = new Hono();

rolesRoute.get('/', requirePermission('role:view'), async (c) => {
  const roles = await db.query.roles.findMany({
    with: { rolePermissions: { with: { permission: true } } },
    orderBy: (roles, { asc }) => [asc(roles.id)],
  });
  return c.json(roles.map((r) => ({
    ...r,
    permissions: r.rolePermissions?.map((rp) => rp.permission) || [],
  })));
});

rolesRoute.post('/', requirePermission('role:create'), async (c) => {
  const { name, description, permissionIds } = await c.req.json();
  const [role] = await db.insert(schema.roles).values({ name, description }).returning();
  if (permissionIds?.length) {
    await db.insert(schema.rolePermissions).values(
      permissionIds.map((pid: number) => ({ roleId: role.id, permissionId: pid }))
    );
  }
  return c.json(role);
});

rolesRoute.put('/:id', requirePermission('role:edit'), async (c) => {
  const id = Number(c.req.param('id'));
  const role = await db.query.roles.findFirst({ where: eq(schema.roles.id, id) });
  if (!role) return c.json({ message: '角色不存在' }, 404);
  const { name, description, permissionIds } = await c.req.json();
  if (role.isSystem && name !== undefined) return c.json({ message: '系统角色不可改名' }, 400);
  await db.update(schema.roles).set({ name, description }).where(eq(schema.roles.id, id));
  if (permissionIds !== undefined) {
    await db.delete(schema.rolePermissions).where(eq(schema.rolePermissions.roleId, id));
    if (permissionIds.length > 0) {
      await db.insert(schema.rolePermissions).values(
        permissionIds.map((pid: number) => ({ roleId: id, permissionId: pid }))
      );
    }
  }
  return c.json({ message: '更新成功' });
});

rolesRoute.delete('/:id', requirePermission('role:delete'), async (c) => {
  const id = Number(c.req.param('id'));
  const role = await db.query.roles.findFirst({ where: eq(schema.roles.id, id) });
  if (!role) return c.json({ message: '角色不存在' }, 404);
  if (role.isSystem) return c.json({ message: '系统角色不可删除' }, 400);
  await db.delete(schema.roles).where(eq(schema.roles.id, id));
  return c.json({ message: '角色已删除' });
});

export { rolesRoute };
```

- [ ] **Step 2: 权限查询路由**

```typescript
// apps/server/src/routes/permissions.ts
import { Hono } from 'hono';
import { db } from '../db';
import { requirePermission } from '../middleware/permission';

const permissionsRoute = new Hono();

permissionsRoute.get('/', requirePermission('dashboard:view'), async (c) => {
  const perms = await db.query.permissions.findMany({
    orderBy: (permissions, { asc }) => [asc(permissions.group), asc(permissions.code)],
  });
  return c.json(perms);
});

permissionsRoute.get('/tree', requirePermission('dashboard:view'), async (c) => {
  const perms = await db.query.permissions.findMany({
    orderBy: (permissions, { asc }) => [asc(permissions.group), asc(permissions.code)],
  });
  const map = new Map<string, typeof perms>();
  for (const p of perms) {
    if (!map.has(p.group)) map.set(p.group, []);
    map.get(p.group)!.push(p);
  }
  return c.json(Array.from(map.entries()).map(([group, permissions]) => ({ group, permissions })));
});

export { permissionsRoute };
```

- [ ] **Step 3: Commit**

```bash
git add apps/server/src/routes/roles.ts apps/server/src/routes/permissions.ts apps/server/src/index.ts
git commit -m "feat: implement role management CRUD and permission query routes"
```

---

### Task 10: 学生管理路由

**Files:**
- Create: `apps/server/src/routes/students.ts`
- Modify: `apps/server/src/index.ts`

**Interfaces:**
- Produces: `GET/POST/PUT/DELETE /api/students`、`PUT /api/students/:id/restore`、`POST /api/students/batch-delete`
- Consumes: Task 6 (中间件)、Task 4 (db)

- [ ] **Step 1: 实现学生 CRUD**

基于现有 `students.controller.ts`（274 行），逐方法转换为 Hono + Drizzle 版本。关键转换：

| NestJS | HonoJS |
|--------|--------|
| `@Query('name')` | `c.req.query('name')` |
| `@Param('id')` | `c.req.param('id')` |
| `@Body() dto` | `await c.req.json()` |
| `this.service.findAll({...})` | `db.query.students.findMany({...})` |
| `this.service.create(dto)` | `db.insert(schema.students).values({...})` |
| `this.service.update(+id, dto)` | `db.update(schema.students).set({...}).where(eq(...))` |
| `this.service.remove(+id)` | `db.update(...).set({ status: 'archived' })`（软删除） |

需要保持的 API 行为：
- 列表支持 `?name=`, `?status=`, `?includeArchived=true` 查询参数
- 删除 = 软删除（设置 status='archived'），非物理删除
- 批量删除 = `POST /api/students/batch-delete` + `{ ids: number[] }`
- 恢复 = `PUT /api/students/:id/restore`（设置 status='active'）

完整代码约 200 行（参考 students.controller.ts）。

- [ ] **Step 2: 挂载路由、操作日志中间件集成**

在路由 handler 中调用 `logOperation(c, { userId, username, module, action, ... })` 记录操作日志。

- [ ] **Step 3: Commit**

```bash
git add apps/server/src/routes/students.ts apps/server/src/index.ts
git commit -m "feat: implement student CRUD routes with soft-delete, batch ops, and restore"
```

---

### Task 11: 学生 Excel 导入导出

**Files:**
- Modify: `apps/server/src/routes/students.ts`（追加导出、导入、模板端点）
- Create: `apps/server/src/utils/excel.ts`（可选）

**Interfaces:**
- Consumes: Task 10 (学生基础 CRUD)

- [ ] **Step 1: Excel 导出**

转换为 HonoJS 的 `c.body()` 方式：

```typescript
// GET /api/students/export
studentsRoute.get('/export', requirePermission('student:export'), async (c) => {
  const includeArchived = c.req.query('includeArchived') === 'true';
  const students = await db.query.students.findMany({
    where: includeArchived ? undefined : (students, { ne }) => [ne(students.status, 'archived')],
  });
  const workbook = new ExcelJS.Workbook();
  const ws = workbook.addWorksheet('学生名单');
  // ... 列定义（同 NestJS 版本 students.controller.ts:47-62）
  for (const s of students) { ws.addRow({...}); }
  const buffer = await workbook.xlsx.writeBuffer();
  return c.body(buffer as any, 200, {
    'Content-Type': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    'Content-Disposition': 'attachment; filename=students.xlsx',
  });
});
```

- [ ] **Step 2: 模板下载**

```typescript
// GET /api/students/template
studentsRoute.get('/template', requirePermission('student:view'), async (c) => {
  // ... 同 NestJS students.controller.ts:93-129
  const buffer = await workbook.xlsx.writeBuffer();
  return c.body(buffer as any, 200, { 'Content-Type': '...', 'Content-Disposition': 'attachment; filename=student_template.xlsx' });
});
```

- [ ] **Step 3: Excel 导入**

```typescript
// POST /api/students/import
studentsRoute.post('/import', requirePermission('student:import'), async (c) => {
  const body = await c.req.parseBody();
  const file = body['file'] as File;
  const arrayBuffer = await file.arrayBuffer();
  const buffer = Buffer.from(arrayBuffer);
  const workbook = new ExcelJS.Workbook();
  await workbook.xlsx.load(buffer);
  // ... 解析逻辑（同 NestJS students.controller.ts:228-270）
  return c.json(result);
});
```

- [ ] **Step 4: Commit**

```bash
git add apps/server/src/routes/students.ts
git commit -m "feat: implement student Excel import/export and template download"
```

---

### Task 12: 宿舍管理路由

**Files:**
- Create: `apps/server/src/routes/rooms.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 实现宿舍 CRUD**

基于 `rooms.controller.ts` / `rooms.service.ts`，转换为 Hono + Drizzle。端点：
- `GET /api/rooms` — 列表（支持 ?building=, ?status=, ?roomType=）
- `GET /api/rooms/:id` — 详情
- `POST /api/rooms` — 创建
- `PUT /api/rooms/:id` — 更新
- `DELETE /api/rooms/:id` — 删除（检查无活跃入住记录）

约 150 行代码。

- [ ] **Step 2: Commit**

```bash
git add apps/server/src/routes/rooms.ts apps/server/src/index.ts
git commit -m "feat: implement room CRUD routes"
```

---

### Task 13: 入住管理路由

**Files:**
- Create: `apps/server/src/routes/occupancies.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 实现入住管理 CRUD + Excel 导入**

端点：
- `GET /api/occupancies` — 列表（含 student/room join 数据）
- `POST /api/occupancies` — 办理入住
- `PUT /api/occupancies/:id` — 更新（调换宿舍）
- `DELETE /api/occupancies/:id` — 退宿（设置 checkOutDate + status='inactive'）
- `POST /api/occupancies/import` — Excel 导入

约 180 行代码。

- [ ] **Step 2: Commit**

```bash
git add apps/server/src/routes/occupancies.ts apps/server/src/index.ts
git commit -m "feat: implement occupancy management routes with Excel import"
```

---

### Task 14: 费用管理路由

**Files:**
- Create: `apps/server/src/routes/expenses.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 实现宿舍费用 + 个人费用**

端点（统一在 `/api/expenses` 下）：
- `GET /api/expenses/room` — 宿舍费用列表（含 room join）
- `POST /api/expenses/room` — 录入宿舍费用
- `PUT /api/expenses/room/:id` — 编辑
- `DELETE /api/expenses/room/:id` — 删除
- `POST /api/expenses/room/import` — Excel 导入
- `GET /api/expenses/personal` — 个人费用列表（含 student join）
- `POST /api/expenses/personal` — 录入
- `PUT /api/expenses/personal/:id` — 编辑
- `DELETE /api/expenses/personal/:id` — 删除
- `POST /api/expenses/personal/import` — Excel 导入

约 250 行代码。

- [ ] **Step 2: Commit**

```bash
git add apps/server/src/routes/expenses.ts apps/server/src/index.ts
git commit -m "feat: implement room and personal expense management routes"
```

---

### Task 15: 账单管理路由

**Files:**
- Create: `apps/server/src/routes/bills.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 实现账单 CRUD + 生成 + Excel/PDF 导出**

端点：
- `GET /api/bills` — 列表（含 student join，?status=, ?studentId=）
- `POST /api/bills` — 生成账单（自动汇总 student 的活跃费用 → bill_items）
- `PUT /api/bills/:id` — 更新
- `DELETE /api/bills/:id` — 删除
- `PUT /api/bills/:id/confirm` — 确认账单
- `GET /api/bills/export-excel` — Excel 导出
- `GET /api/bills/:id/pdf` — PDF 导出（PDFKit）

PDF 生成使用 `c.body(buffer, 200, { 'Content-Type': 'application/pdf' })`。

约 300 行代码。

- [ ] **Step 2: Commit**

```bash
git add apps/server/src/routes/bills.ts apps/server/src/index.ts
git commit -m "feat: implement bill management routes with Excel/PDF export"
```

---

### Task 16: 押金管理路由

**Files:**
- Create: `apps/server/src/routes/deposits.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 实现押金 CRUD**

端点：`GET/POST/PUT/DELETE /api/deposits`。约 100 行代码。

- [ ] **Step 2: Commit**

```bash
git add apps/server/src/routes/deposits.ts apps/server/src/index.ts
git commit -m "feat: implement deposit CRUD routes"
```

---

### Task 17: 教室与租赁方管理路由

**Files:**
- Create: `apps/server/src/routes/classrooms.ts`
- Create: `apps/server/src/routes/tenants.ts`
- Create: `apps/server/src/routes/classroom-rentals.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 教室 CRUD**（含 Excel 导入，约 150 行）
- [ ] **Step 2: 租赁方 CRUD**（约 80 行）
- [ ] **Step 3: 租赁订单 CRUD**（约 150 行）

合并为一个 commit。

- [ ] **Step 4: Commit**

```bash
git add apps/server/src/routes/classrooms.ts apps/server/src/routes/tenants.ts \
  apps/server/src/routes/classroom-rentals.ts apps/server/src/index.ts
git commit -m "feat: implement classroom, tenant, and classroom rental management routes"
```

---

### Task 18: 操作日志与数据面板路由

**Files:**
- Create: `apps/server/src/routes/operation-logs.ts`
- Create: `apps/server/src/routes/dashboard.ts`
- Modify: `apps/server/src/index.ts`

- [ ] **Step 1: 操作日志查询路由**

端点：
- `GET /api/operation-logs` — 分页列表（?page=, ?limit=, ?module=, ?action=, ?username=）
- `GET /api/operation-logs/:id` — 详情

约 80 行代码。

- [ ] **Step 2: 数据面板路由**

端点：`GET /api/dashboard` — 聚合统计（学生数、宿舍占用率、费用总额、账单状态分布）。按现有 `dashboard.service.ts` 逻辑转换为 Drizzle 聚合查询。

约 60 行代码。

- [ ] **Step 3: Commit**

```bash
git add apps/server/src/routes/operation-logs.ts apps/server/src/routes/dashboard.ts apps/server/src/index.ts
git commit -m "feat: implement operation log query and dashboard aggregation routes"
```

---

### Task 19: 操作日志记录中间件

**Files:**
- Create: `apps/server/src/middleware/operation-log.ts`
- Modify: 所有路由文件（集成日志记录调用）

- [ ] **Step 1: 实现日志记录工具函数**

```typescript
// apps/server/src/middleware/operation-log.ts
import { db } from '../db';
import * as schema from '../db/schema';

interface LogParams {
  userId?: number; username?: string;
  module: string; action: string;
  targetId?: number; targetType?: string;
  detail?: string; ipAddress?: string;
  userAgent?: string; status?: 'success' | 'fail';
}

export async function logOperation(
  c: any, // Hono Context
  params: Omit<LogParams, 'ipAddress' | 'userAgent'>
) {
  const ip = c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || 'unknown';
  const ua = (c.req.header('user-agent') || '').substring(0, 500);
  await db.insert(schema.operationLogs).values({
    userId: params.userId, username: params.username,
    module: params.module, action: params.action,
    targetId: params.targetId, targetType: params.targetType,
    detail: params.detail, ipAddress: ip, userAgent: ua,
    status: params.status || 'success',
  });
}
```

- [ ] **Step 2: 在所有写操作路由中集成日志记录**

登录、学生创建/编辑/删除、宿舍创建/编辑/删除等所有写操作调用 `logOperation()`。

- [ ] **Step 3: Commit**

```bash
git add apps/server/src/middleware/operation-log.ts
git commit -m "feat: implement operation log middleware with automatic IP/UA capture"
```

---

### Task 20: 限流 + CORS + 全局错误处理中间件

**Files:**
- Create: `apps/server/src/middleware/rate-limit.ts`
- Create: `apps/server/src/middleware/error-handler.ts`
- Modify: `apps/server/src/index.ts`（挂载中间件栈）

- [ ] **Step 1: Rate Limiter 配置**

```typescript
// apps/server/src/middleware/rate-limit.ts
import { rateLimiter } from 'hono-rate-limiter';

export const rateLimitMiddleware = rateLimiter({
  windowMs: 60 * 1000, // 1 分钟
  limit: 100,
  standardHeaders: true,
  legacyHeaders: false,
  keyGenerator: (c) => c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || 'unknown',
});
```

- [ ] **Step 2: CORS 配置**

```typescript
// 在 apps/server/src/index.ts 中：
import { cors } from 'hono/cors';
app.use('*', cors({ origin: '*', credentials: true }));
```

- [ ] **Step 3: 全局错误处理**

```typescript
// apps/server/src/middleware/error-handler.ts
import { createMiddleware } from 'hono/factory';

export const errorHandler = createMiddleware(async (c, next) => {
  try {
    await next();
  } catch (err: any) {
    console.error('[Error]', err.message || err);
    return c.json({
      message: err.message || '服务器内部错误',
      statusCode: err.status || 500,
    }, err.status || 500);
  }
});
```

- [ ] **Step 4: 组装中间件栈**

```typescript
// apps/server/src/index.ts 最终中间件顺序：
app.use('*', errorHandler);
app.use('*', cors({ origin: '*', credentials: true }));
app.use('/api/*', rateLimitMiddleware);
app.use('/api/*', authMiddleware);
```

- [ ] **Step 5: Commit**

```bash
git add apps/server/src/middleware/ src/index.ts
git commit -m "feat: add CORS, rate limiter, and global error handler middleware"
```

---

### Task 21: Zod 校验集成

**Files:**
- Modify: 所有路由文件（为 POST/PUT 端点添加 Zod schema 校验）
- Create: `apps/server/src/utils/validate.ts`

- [ ] **Step 1: 创建通用校验工具**

```typescript
// apps/server/src/utils/validate.ts
import { z } from 'zod';
import { zValidator } from '@hono/zod-validator';

export { z, zValidator };
```

- [ ] **Step 2: 为主要 DTO 定义 Zod schema**

为 student、room、occupancy、expense、bill、user、role 的 POST/PUT body 添加 Zod 校验。示例：

```typescript
// 在 students.ts 中：
import { zValidator, z } from '../utils/validate';

const createStudentSchema = z.object({
  name: z.string().min(1).max(50),
  phone: z.string().max(20).optional(),
  idNumber: z.string().max(30).optional(),
  gender: z.string().max(10).optional(),
  // ...
});

studentsRoute.post('/', requirePermission('student:create'), zValidator('json', createStudentSchema), async (c) => {
  const dto = c.req.valid('json');
  // ...
});
```

- [ ] **Step 3: Commit**

```bash
git add apps/server/src/utils/validate.ts apps/server/src/routes/
git commit -m "feat: integrate Zod validation for all POST/PUT endpoints"
```

---

### Task 22: 部署配置更新

**Files:**
- Modify: `apps/server/Dockerfile`
- Modify: `docker-compose.yml`
- Modify: `apps/server/.env.example`
- Create: `apps/server/.env`

- [ ] **Step 1: 更新 Dockerfile**

移除 NestJS 构建依赖，适配 HonoJS：

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3003
CMD ["node", "dist/index.js"]
```

- [ ] **Step 2: 更新 docker-compose.yml**

- 移除 `mysql` 服务和 `mysql_data` volume
- 后端依赖改为 external PostgreSQL（通过环境变量连接）
- 更新 `backend` 服务的环境变量列表（移除 DB_TYPE，添加 DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD/DB_DATABASE/BETTER_AUTH_SECRET）

- [ ] **Step 3: 更新 .env 示例**

```
PORT=3003
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=gongxue
BETTER_AUTH_SECRET=your-secret-key-change-in-production
ADMIN_PASSWORD=admin123
```

- [ ] **Step 4: Commit**

```bash
git add apps/server/Dockerfile docker-compose.yml apps/server/.env.example apps/server/.env
git commit -m "chore: update Dockerfile, docker-compose, and env config for HonoJS + PostgreSQL"
```

---

### Task 23: 清理 NestJS 残留 + 最终验证

**Files:**
- Delete: 所有 NestJS 特有文件和目录（见下方列表）
- Modify: `apps/server/package.json`（清理残留 dep）

- [ ] **Step 1: 删除 NestJS 残留文件**

```bash
cd apps/server
rm -rf src/app.module.ts src/app.controller.ts src/app.service.ts src/app.controller.spec.ts
rm -rf src/auth/strategies/ src/auth/guards/ src/auth/decorators/ src/auth/auth.module.ts
rm -rf src/entities/
rm -rf src/students/students.module.ts src/rooms/rooms.module.ts
rm -rf src/occupancies/occupancies.module.ts src/expenses/expenses.module.ts
rm -rf src/bills/bills.module.ts src/deposits/deposits.module.ts
rm -rf src/classrooms/classrooms.module.ts src/classroom-rentals/classroom-rentals.module.ts
rm -rf src/tenants/tenants.module.ts src/operation-logs/operation-logs.module.ts
rm -rf src/dashboard/dashboard.module.ts src/rbac/rbac.module.ts
rm -rf src/common/ src/global.d.ts
rm -rf nest-cli.json test/
```

- [ ] **Step 2: 验证 pnpm remove 清理所有 NestJS 依赖**

```bash
cd apps/server
pnpm remove @nestjs/common @nestjs/core @nestjs/config @nestjs/jwt @nestjs/passport \
  @nestjs/platform-express @nestjs/throttler @nestjs/typeorm @nestjs/cli \
  @nestjs/schematics @nestjs/testing typeorm mysql2 better-sqlite3 \
  passport passport-jwt passport-local class-transformer class-validator \
  reflect-metadata rxjs multer @types/multer @types/better-sqlite3 @types/express \
  @types/passport-jwt @types/passport-local 2>/dev/null || true
```

- [ ] **Step 3: 构建验证**

```bash
cd apps/server && pnpm typecheck && pnpm build
# 预期：无类型错误，dist/index.js 生成成功
```

- [ ] **Step 4: 启动验证**

```bash
cd apps/server && pnpm dev
# curl http://localhost:3003/api/health → 200
```

- [ ] **Step 5: Commit**

```bash
git add -A apps/server/
git commit -m "chore: remove all NestJS residual files and dependencies, finalize HonoJS migration"
```

---

### Task 24: 端到端兼容性验证清单

**检查项（手动 + 自动化）**:
- [ ] 24.1 所有 60+ API 端点可正常访问（对照 NestJS 端点列表逐一验证）
- [ ] 24.2 登录 → JWT token → 受保护路由 全流程可用
- [ ] 24.3 49 个权限点检查正常（admin/supervisor/teacher/institution 权限隔离）
- [ ] 24.4 Excel 导入导出 round-trip（导出 → 修改 → 导入 → 验证）
- [ ] 24.5 PDF 账单生成可用
- [ ] 24.6 操作日志记录完整（登录、CRUD 操作均有日志）
- [ ] 24.7 Rate limiter 生效（100 req/min）
- [ ] 24.8 PGlite 开发环境零 Docker 启动
- [ ] 24.9 前端 23 个页面功能回归正常（无 API 兼容性错误）

此 task 检查项确认后勾选。

---

## 执行顺序与依赖图

```
Task 1  ─────────────────────────────────────────────────────────────┐
  ↓                                                                   │
Task 2 (auth schema) ──→ Task 3 (biz schema) ──→ Task 4 (other + db) │
  ↓                        ↓                       ↓                  │
Task 5 (better-auth) ←────┴───────────────────────┘                  │
  ↓                                                                   │
Task 6 (auth middleware)                                              │
  ↓                                                                   │
Task 7 (login)                                                        │
  ↓                                                                   │
Task 8 (users CRUD) ──→ Task 9 (roles + permissions)                 │
  ↓                        ↓                                          │
Task 10 (students) ←──────┴─────────────────────────────────────┐    │
  ↓                                                               │    │
Task 11 (student Excel)                                          │    │
  ↓                                                               │    │
Task 12 (rooms) ──→ Task 13 (occupancies) ──→ Task 14 (expenses) │    │
                      ↓                           ↓               │    │
                      └──────────→ Task 15 (bills)               │    │
                                      ↓                           │    │
Task 16 (deposits) ←─────────────────┘                           │    │
  ↓                                                               │    │
Task 17 (classroom + tenant + rental)                             │    │
  ↓                                                               │    │
Task 18 (logs + dashboard) ←─────────────────────────────────────┘    │
  ↓                                                                   │
Task 19 (log middleware)  ←── 可与其他路由同时进行                     │
  ↓                                                                   │
Task 20 (rate-limit + CORS + error)                                   │
  ↓                                                                   │
Task 21 (Zod validation)                                              │
  ↓                                                                   │
Task 22 (deploy config) ──→ Task 23 (cleanup) ──→ Task 24 (verify)   │
  ↑                                                                   │
  └── 可与 Task 10-21 并行 ←─────────────────────────────────────────┘
```

## 分批实施建议

| 批次 | Tasks | 预计工作量 | 关键产出 |
|------|-------|-----------|---------|
| 批 1 (基础) | 1-6 | 全局基础 | Hono + Drizzle + better-auth 可启动 |
| 批 2 (认证) | 7-9 | 认证 + RBAC | 登录/用户/角色/权限全功能 |
| 批 3 (核心业务) | 10-15 | 学生/宿舍/费用/账单 | 核心模块可用 |
| 批 4 (其他业务) | 16-18 | 押金/教室/日志 | 全模块完成 |
| 批 5 (横切) | 19-21 | 中间件 | 日志/限流/校验 |
| 批 6 (收尾) | 22-24 | 部署+清理+验证 | 完成迁移 |