1694 lines
57 KiB
Markdown
1694 lines
57 KiB
Markdown
---
|
||
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 | 部署+清理+验证 | 完成迁移 |
|