| name | admin-business |
| description | Use when generating or enhancing business-specific admin dashboards - automatically detects if admin exists, then either generates complete admin backend or adds BI reports module with decision dashboard, 4减4增 analytics, and data-driven insights following the Next.js + Shadcn-ui stack. v3.3 adds smart seed data generation based on business context. |
| version | 3.3.0 |
| depends | [".42cog/real/real.md",".42cog/cog/cog.md"] |
| generates | [".42cog/spec/admin-{business}.spec.md","src/admin/","src/admin/scripts/seed/","src/admin/app/reports/"] |
| reference | https://github.com/arhamkhnz/next-shadcn-admin-dashboard |
AI Agent Note: This skill generates or enhances admin dashboards based on business context. v3.2 adds intelligent detection: if admin exists, it adds BI reports module; if not, generates complete admin. Reports follow the 4减4增 framework for data-driven decision making. v3.3 adds smart seed generation with context-aware test data creation based on detected business entities.
Overview
Generate or enhance admin backends based on business context. v3.3 introduces smart seed generation capability:
Mode A - Full Generation (no admin exists):
- Complete admin backend with all features from v3.1
Mode B - BI Reports Enhancement (admin exists):
- [v3.2 NEW] Decision Dashboard (决策驾驶舱)
- [v3.2 NEW] 4减4增 Analytics Framework
- [v3.2 NEW] Conversion Funnel Reports (R1)
- [v3.2 NEW] Revenue Analytics (R2)
- [v3.2 NEW] Retention & Churn Analysis (R3)
- [v3.2 NEW] Referral Tracking (R4)
- [v3.2 NEW] Cost Monitoring (C1-C4)
Core Features (all versions):
- Business-specific entity management pages
- Full CRUD operations with soft delete
- Action menu for row-level operations
- Workflows aligned with business processes
- Role-based access control for business rules
Tech Stack
Reference: https://github.com/arhamkhnz/next-shadcn-admin-dashboard
| Category | Technology | Description |
|---|
| Framework | Next.js 14 | App Router |
| Language | TypeScript | Type safety |
| Styling | Tailwind CSS | Atomic CSS |
| Components | Shadcn-ui | Customizable components |
| Validation | Zod | Schema validation |
| State | Zustand | Lightweight state management |
| URL State | Nuqs | Search params management |
| Database | Neon | Serverless PostgreSQL |
| Auth | Neon Auth | Authentication solution |
| Tables | TanStack Tables | Data tables |
| Forms | React Hook Form | Form handling |
| Command Palette | kbar | Command+K interface |
| Linting | ESLint + Prettier | Code quality |
| Git Hooks | Husky | Pre-commit checks |
Workflow
Phase 0: Admin Detection [v3.2 NEW]
First, automatically detect if admin already exists:
## Detection Checklist
1. **Directory Structure Check**
- [ ] src/admin/ exists?
- [ ] src/app/admin/ exists?
- [ ] src/app/(admin)/ exists?
2. **Route Check**
- [ ] /admin route defined?
- [ ] Admin layout.tsx exists?
- [ ] Admin page.tsx exists?
3. **Feature Check**
- [ ] Dashboard component exists?
- [ ] User management exists?
- [ ] Entity CRUD pages exist?
4. **Database Check**
- [ ] Admin-specific tables exist? (audit_logs, admin_users, etc.)
Detection Output:
[detection]
admin_exists = {true|false}
admin_path = "{detected path or null}"
existing_features = ["{feature1}", "{feature2}"]
missing_features = ["{feature1}", "{feature2}"]
recommended_mode = "{full_generation|bi_enhancement}"
Mode Selection:
| Condition | Mode | Action |
|---|
| No admin found | Mode A: Full Generation | Execute Phase 1-5 (complete admin) |
| Admin exists, no reports | Mode B: BI Enhancement | Execute Phase 6 only (add reports) |
| Admin exists with reports | Mode C: Report Upgrade | Enhance existing reports |
Phase 1: Business Context Collection
First, ask the user these questions:
## Business Context Questionnaire
1. **Business Type**: What type of product/service is this?
- Examples: personal blog, e-commerce platform, logistics system, SaaS tool, online education...
2. **Core Entities**: What are the 3-5 most important entities in this business?
- Examples: users, articles, orders, products, courses...
3. **User Roles**: What admin roles exist? What are their responsibilities?
- Examples: super admin, content editor, customer service, finance...
4. **Key Workflows**: What are the most frequent daily management operations?
- Examples: content review, order processing, ticket handling...
5. **Data Reporting Needs**: What core metrics need to be tracked?
- Examples: DAU, conversion rate, revenue, inventory...
Phase 2: Business Entity Modeling
Based on collected information, generate business cognitive expression:
# Business Cognitive Expression Template
[business]
name = "{business_name}"
type = "{business_type}" # blog | ecommerce | logistics | saas | education | ...
domain = "admin.{project}.com"
[business.entities]
primary = ["{entity1}", "{entity2}", "{entity3}"]
secondary = ["{entity4}", "{entity5}"]
[business.roles]
super_admin = ["*"]
{role1} = ["{entity1}:*", "{entity2}:read"]
{role2} = ["{entity3}:read", "{entity3}:update"]
[business.workflows]
{workflow1} = ["{step1}", "{step2}", "{step3}"]
{workflow2} = ["{step1}", "{step2}"]
[business.metrics]
kpi = ["{metric1}", "{metric2}", "{metric3}", "{metric4}"]
Phase 3: Business Template Matching
Select base template based on business type, then customize:
| Type | Core Entities | Key Pages |
|---|
| blog | posts, categories, tags, comments, media | Post editor, comment moderation |
| ecommerce | products, orders, customers, coupons, inventory | Order processing, inventory alerts |
| logistics | shipments, tracks, stations, drivers, vehicles | Dispatch center, exception handling |
| saas | tenants, users, plans, subscriptions, tickets | Tenant management, billing |
| education | courses, sections, lessons, students, enrollments | Course builder, progress tracking |
See references/business-templates.md for detailed entity definitions.
Phase 4: Code Generation
Generate code structure based on business model:
src/admin/
├── app/
│ ├── layout.tsx # Admin layout
│ ├── page.tsx # Dashboard
│ ├── login/page.tsx # Login page
│ ├── {entity1}/ # Entity 1 management
│ │ ├── page.tsx # List page
│ │ ├── new/page.tsx # Create page
│ │ └── [id]/page.tsx # Detail/Edit page
│ ├── {entity2}/ # Entity 2 management
│ │ └── ...
│ ├── reports/page.tsx # Data reports
│ ├── settings/page.tsx # System settings
│ └── audit-logs/page.tsx # Audit logs
├── components/
│ ├── layout/
│ │ ├── sidebar.tsx # Sidebar (dynamic menu)
│ │ └── header.tsx # Header
│ ├── {entity1}/ # Entity 1 components
│ │ ├── columns.tsx # Table column definitions
│ │ ├── form.tsx # Form component
│ │ └── actions.tsx # Action buttons
│ └── shared/
│ ├── data-table.tsx # Generic data table
│ ├── status-badge.tsx # Status badge
│ └── confirm-dialog.tsx # Confirmation dialog
├── lib/
│ ├── db.ts # Database connection
│ ├── auth.ts # Auth logic
│ ├── mask.ts # Data masking
│ └── audit.ts # Audit logging
└── types/
└── {business}.ts # Business type definitions
Phase 5: Universal Constraints Check (4+3 Framework)
All generated admin backends must satisfy these constraints.
4+3 Constraint Structure: Aligns with working memory capacity (4±1 items). For typical personal applications, 4+3 constraints are sufficient. For complex applications, use layered constraints: project-level, subsystem-level, module-level.
Required Constraints (4 items, non-negotiable)
## A1: Independent Entry
- Reality Constraint: Admin uses independent subdomain (admin.xxx.com)
- Rationale: Security isolation, clear permissions, independent deployment
- Reference: WeChat Work uses admin.work.weixin.qq.com, Aliyun uses account.aliyun.com
## A2: Independent Login
- Reality Constraint: No shared frontend session, requires admin-specific credentials
- Rationale: Permission separation, prevent regular users from accessing admin
## A3: Data Masking
- Reality Constraint: Sensitive info (email, phone, address) partially masked
- Format: Phone displayed as 138****5678, email as ab***@gmail.com
- Rationale: User privacy protection, compliance requirements (GDPR, data protection laws)
## A4: Audit Logging
- Reality Constraint: Record all admin operations (actor, timestamp, action type, changes)
- Rationale: Compliance traceability, troubleshooting, prevent misoperations
Optional Constraints (3 items, recommended)
## A5: UI Theme
- Constraint: Support light/dark mode toggle
- Rationale: User preference, reduced eye strain for long sessions
- Implementation: next-themes or CSS variables
## A6: Left Sidebar Navigation
- Constraint: Navigation positioned on left side
- Rationale: Established user habit, follows admin dashboard conventions
- Implementation: Collapsible sidebar with icon-only mode
## A7: List Pagination
- Constraint: Paginated lists, default 20 items per page
- Rationale: Performance optimization, better UX for large datasets
- Implementation: Server-side pagination with page/limit params
Quick Start
# 1. Invoke this skill
# User: /admin-business
# AI: Please tell me about your business type and core entities...
# 2. Install dependencies
bun add drizzle-orm @neondatabase/serverless zustand nuqs
bun add @tanstack/react-table react-hook-form @hookform/resolvers zod
bun add recharts date-fns kbar
bun add -d drizzle-kit
# 3. Install Shadcn components
bunx shadcn@latest add button card table input form dialog select badge dropdown-menu
# 4. Database migration
bun run db:push
# 5. Start development
bun dev
Output Checklist
After executing this skill:
| Output | Description |
|---|
spec/admin-{business}.spec.md | Business admin specification |
src/admin/app/ | Admin pages |
src/admin/components/ | Business components |
src/admin/lib/ | Business logic |
src/db/schema/{entity}.ts | Database schema |
Related Skills
| Skill | Relationship |
|---|
| admin-scaffold | Base: provides generic admin skeleton |
| admin-better-auth | Extension: adds authentication |
| admin-data-reports | Extension: adds data reports |
| admin-backup | Extension: adds backup functionality |
Phase 5: Seed - Test Data Generation [v3.0 NEW]
Goal: Generate 100+ realistic test data records per business entity with correct relationships and realistic status distribution for validation and demo purposes.
5.1 Data Generation Principles
| Property | Requirement | Description |
|---|
| Quantity | ≥ 100 per core entity | Related entities 20-50, logs 500+ |
| Realism | Use Faker.js with Chinese locale | Names, addresses, phones match local format |
| Relations | 100% valid foreign keys | No orphan data |
| Status Distribution | Match real business ratios | e.g., orders: 60% delivered, 15% shipped... |
| Time Distribution | Simulate business growth | Earlier = fewer, recent = more |
5.2 Status Distribution Rules
const statusDistribution = {
post: { draft: 0.15, published: 0.80, archived: 0.05 },
order: {
pending_payment: 0.05, paid: 0.10, shipped: 0.15,
delivered: 0.60, completed: 0.08, cancelled: 0.02
},
comment: { pending: 0.10, approved: 0.85, rejected: 0.05 },
tenant: { trial: 0.20, active: 0.70, suspended: 0.05, churned: 0.05 },
};
5.3 Seed Commands
# Install Faker dependency
bun add -d @faker-js/faker
# Generate blog test data (100 base count)
bun run scripts/seed-generator.ts blog --count=100
# Generate ecommerce test data (200 base count)
bun run scripts/seed-generator.ts ecommerce --count=200
# Generate SaaS test data (150 base count)
bun run scripts/seed-generator.ts saas --count=150
# Output SQL format
bun run scripts/seed-generator.ts blog --format=sql --output=seed.sql
5.4 Data Volume per Business Type
| Type | Core Entity | Base Count | Related Data | Total Records |
|---|
| blog | posts | 100 | categories(15), tags(50), comments(200), media(50) | ~415 |
| ecommerce | products, orders | 100/250 | categories(20), customers(50), coupons(30) | ~450 |
| saas | tenants | 100 | plans(4), users(300), subscriptions(80), tickets(150) | ~634 |
5.5 Seed Script Structure
src/admin/scripts/seed/
├── index.ts # Main entry
├── utils.ts # Utility functions
├── blog.seed.ts # Blog data generator
├── ecommerce.seed.ts # E-commerce data generator
└── saas.seed.ts # SaaS data generator
Enhanced Features [v3.0 NEW]
6.1 Bulk Operations
| Feature | Description | Implementation |
|---|
| Bulk Delete | Delete multiple selected items | Checkbox + Bulk Action |
| Bulk Status Change | e.g., bulk publish, bulk approve | Dropdown Action |
| Bulk Export | Export selected data to CSV | csv-stringify |
6.2 Import/Export
| Feature | Format | Use Case |
|---|
| Export CSV | UTF-8 BOM | Excel compatible |
| Export Excel | xlsx | Full formatting |
| Import CSV | Template download + validation | Batch create/update |
6.3 Advanced Search
| Feature | Description |
|---|
| Multi-field Search | Search title, content, tags simultaneously |
| Filter Combination | Status + Category + Date Range |
| Save Search | Save frequently used filters |
| Search History | Last 10 search queries |
6.4 Keyboard Shortcuts
Integrated kbar command palette with shortcuts:
| Shortcut | Function |
|---|
⌘ + K | Open command palette |
⌘ + / | Show shortcut help |
⌘ + N | Create new record |
⌘ + S | Save |
⌘ + F | Search |
⌘ + E | Export |
6.5 Real-time Notifications
import { toast } from 'sonner';
// Success notification
toast.success('Saved successfully', {
description: 'Data has been updated',
action: { label: 'Undo', onClick: handleUndo },
});
Entity Management [v3.1 NEW]
CRUD Operations Pattern
Each business entity should have complete CRUD operations:
| Operation | Trigger | UI Component | Server Action |
|---|
| Create | Page button | Dialog + Form | createEntity() |
| Read | List/Detail page | Table / Card | getEntities() / getEntityById() |
| Update | Row action menu | Dialog + Form | updateEntity() |
| Delete | Row action menu | AlertDialog | deleteEntity() |
Soft Delete Implementation
// Schema: Add deletedAt field
export const entity = sqliteTable("entity", {
id: text("id").primaryKey(),
name: text("name").notNull(),
createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
updatedAt: integer("updatedAt", { mode: "timestamp" }).notNull(),
deletedAt: integer("deletedAt", { mode: "timestamp" }), // Soft delete marker
})
// Query: Filter out deleted records by default
export async function getEntities(params: { includeDeleted?: boolean } = {}) {
const { includeDeleted = false } = params
const conditions = []
if (!includeDeleted) {
conditions.push(isNull(entity.deletedAt))
}
return db.select().from(entity).where(and(...conditions))
}
Action Menu Component
export function EntityActions({ entity }: { entity: Entity }) {
const [editOpen, setEditOpen] = useState(false)
const [deleteOpen, setDeleteOpen] = useState(false)
return (
<>
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button variant="ghost" size="icon">
<MoreHorizontal className="h-4 w-4" />
</Button>
</DropdownMenuTrigger>
<DropdownMenuContent align="end">
<DropdownMenuItem asChild>
<Link href={`/admin/entities/${entity.id}`}>
<Eye className="mr-2 h-4 w-4" /> View
</Link>
</DropdownMenuItem>
<DropdownMenuItem onClick={() => setEditOpen(true)}>
<Pencil className="mr-2 h-4 w-4" /> Edit
</DropdownMenuItem>
<DropdownMenuItem
onClick={() => setDeleteOpen(true)}
className="text-destructive"
>
<Trash2 className="mr-2 h-4 w-4" /> Delete
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
<EditEntityDialog entity={entity} open={editOpen} onOpenChange={setEditOpen} />
<DeleteEntityDialog entity={entity} open={deleteOpen} onOpenChange={setDeleteOpen} />
</>
)
}
Required Shadcn Components
bunx shadcn@latest add dialog alert-dialog dropdown-menu checkbox
Phase 6: BI Reports Module [v3.2 NEW]
Goal: Add comprehensive BI reports to existing admin dashboards, enabling data-driven decision making based on the 4减4增 (4-reduce 4-increase) framework.
6.1 When to Use This Phase
Execute Phase 6 when:
- Admin dashboard already exists (Mode B detected in Phase 0)
- User requests "add reports", "add analytics", "add BI dashboard"
- Existing admin lacks data visualization capabilities
6.2 Decision Dashboard (决策驾驶舱)
The core concept: Admin dashboard is your Decision Cockpit, not just a feature collection.
Data → Insights → Decisions → Actions
Dashboard Structure:
src/admin/app/reports/
├── page.tsx # Main decision dashboard
├── conversion/page.tsx # R1: Conversion reports
├── revenue/page.tsx # R2: Revenue analytics
├── retention/page.tsx # R3: Retention analysis
├── referral/page.tsx # R4: Referral tracking
├── costs/page.tsx # C1-C4: Cost monitoring
└── _components/
├── stats-overview.tsx # Today/Monthly overview cards
├── conversion-funnel.tsx # User conversion funnel
├── revenue-chart.tsx # Revenue trend charts
├── churn-analysis.tsx # Churn rate analysis
├── referral-metrics.tsx # NPS and referral stats
└── cost-breakdown.tsx # API costs, margins
6.3 Report Types (Based on 4减4增 Framework)
Today's Overview (今日核心数据)
| Metric | Description | Formula |
|---|
| New Users | Today's registrations | COUNT(users WHERE createdAt = today) |
| Active Users | Today's active users | COUNT(DISTINCT sessions WHERE date = today) |
| Conversion Rate | Free to paid conversion | paying_users / total_users * 100 |
| Today's Revenue | Revenue generated today | SUM(payments WHERE date = today) |
Monthly Overview (本月核心数据)
| Metric | Description | Formula |
|---|
| MRR | Monthly Recurring Revenue | SUM(active_subscriptions.price) |
| Total Users | All registered users | COUNT(users) |
| Paying Users | Active subscribers | COUNT(subscriptions WHERE status = 'active') |
| Churned Users | Users who cancelled | COUNT(subscriptions WHERE status = 'cancelled' AND cancelled_at = this_month) |
Cost Monitoring (成本监控)
| Metric | Description | Formula |
|---|
| API Calls | Total API requests | COUNT(api_logs) |
| API Cost | Cost of API usage | SUM(api_logs.cost) |
| Gross Margin | Revenue minus costs | (revenue - costs) / revenue * 100 |
6.4 R1: Conversion Funnel Reports (增付费转化)
// Conversion funnel visualization
interface FunnelStep {
name: string;
value: number;
rate: number;
}
const conversionFunnel: FunnelStep[] = [
{ name: 'Visitors', value: 10000, rate: 100 },
{ name: 'Registered', value: 2500, rate: 25 },
{ name: 'Activated', value: 1500, rate: 60 },
{ name: 'Paying', value: 375, rate: 25 },
];
// Key decisions enabled:
// - "Conversion dropped 37% - check pricing page"
// - "78% users stuck at Onboarding Step 2 - optimize UX"
Report Components:
- Funnel visualization chart
- Conversion rate trend (daily/weekly/monthly)
- Onboarding completion rates
- A/B test results tracking
6.5 R2: Revenue Analytics (增客单价)
// Subscription distribution analysis
interface PlanDistribution {
plan: string;
users: number;
percentage: number;
revenue: number;
}
const planDistribution: PlanDistribution[] = [
{ plan: 'Basic', users: 92, percentage: 90, revenue: 828 },
{ plan: 'Pro', users: 5, percentage: 5, revenue: 145 },
{ plan: 'Team', users: 5, percentage: 5, revenue: 495 },
];
// Key metrics:
// - ARPU (Average Revenue Per User): total_revenue / total_users
// - Price point effectiveness
// - Upsell opportunities
Report Components:
- Plan distribution pie chart
- ARPU trend line
- Pricing tier comparison
- Upgrade/downgrade flow
6.6 R3: Retention Analysis (增复购率)
// Churn analysis
interface ChurnData {
month: string;
churnRate: number;
renewalRate: number;
lostMRR: number;
}
// Key alerts:
// - "15% churn this month (was 10% last month)"
// - "80% of churned users last logged in 3+ days before expiry"
// - "Users with < 2 logins/week have 5x higher churn risk"
Report Components:
- Cohort retention heatmap
- Churn rate trend
- At-risk user list (7 days before expiry, low activity)
- LTV (Lifetime Value) analysis
- Renewal reminder effectiveness
6.7 R4: Referral Tracking (增推荐率)
// Referral metrics
interface ReferralMetrics {
nps: number; // Net Promoter Score (-100 to +100)
referralRate: number; // % of users who referred
kFactor: number; // Viral coefficient
referralConversion: number; // Referred user conversion rate
}
// Key insights:
// - "NPS: 45 (30% satisfied users not referring - improve entry point)"
// - "Referred users have 2x higher LTV"
Report Components:
- NPS gauge chart
- Referral funnel
- Top referrers leaderboard
- Referral channel effectiveness
6.8 C1-C4: Cost Monitoring (降本四策)
// Cost breakdown
interface CostMetrics {
apiCalls: number;
apiCost: number;
infrastructureCost: number;
grossMargin: number;
burnRate: number;
}
// Decisions enabled:
// - "API costs up 20% - optimize caching"
// - "Gross margin 91.8% - healthy"
Report Components:
- API usage trend
- Cost breakdown by service
- Margin trend
- Cost per user (CAC trend)
6.9 Weekly Decision Calendar
A practical pattern for using the reports:
| Day | Focus | Key Reports | Decisions |
|---|
| Monday | Weekly planning | Dashboard overview | Identify priorities |
| Wednesday | User analysis | Conversion, Retention | Optimize onboarding |
| Friday | Weekly review | Revenue, Export weekly report | Plan next week |
| Sunday | Incident review | Audit logs | Quick issue location |
6.10 Report Generation Code Structure
src/admin/
├── app/reports/
│ ├── page.tsx # Decision dashboard
│ ├── conversion/
│ │ ├── page.tsx # R1 conversion reports
│ │ └── _components/
│ │ ├── funnel-chart.tsx
│ │ └── conversion-trend.tsx
│ ├── revenue/
│ │ ├── page.tsx # R2 revenue analytics
│ │ └── _components/
│ │ ├── plan-distribution.tsx
│ │ └── arpu-chart.tsx
│ ├── retention/
│ │ ├── page.tsx # R3 retention analysis
│ │ └── _components/
│ │ ├── cohort-heatmap.tsx
│ │ ├── churn-trend.tsx
│ │ └── at-risk-users.tsx
│ ├── referral/
│ │ ├── page.tsx # R4 referral tracking
│ │ └── _components/
│ │ ├── nps-gauge.tsx
│ │ └── referral-funnel.tsx
│ └── costs/
│ ├── page.tsx # C1-C4 cost monitoring
│ └── _components/
│ ├── cost-breakdown.tsx
│ └── margin-trend.tsx
├── lib/
│ ├── reports/
│ │ ├── conversion.ts # Conversion calculations
│ │ ├── revenue.ts # Revenue calculations
│ │ ├── retention.ts # Retention calculations
│ │ ├── referral.ts # Referral calculations
│ │ └── costs.ts # Cost calculations
│ └── utils/
│ └── date-ranges.ts # Date range utilities
└── components/reports/
├── date-range-picker.tsx # Date range selector
├── metric-card.tsx # Reusable metric card
├── trend-indicator.tsx # Up/down trend badge
└── export-button.tsx # Export to CSV/Excel
6.11 Quick Start (Mode B)
# When admin exists, only add reports module:
# 1. Install chart dependencies
bun add recharts date-fns
# 2. Add required Shadcn components
bunx shadcn@latest add tabs chart
# 3. Generate reports module
# AI will create src/admin/app/reports/ structure
# 4. Add navigation entry
# Update sidebar to include "Reports" menu item
# 5. Start development
bun dev
# Access reports at http://localhost:3000/admin/reports
6.12 Database Schema for Reports
// Additional tables for BI reports
export const dailyMetrics = sqliteTable("daily_metrics", {
id: text("id").primaryKey(),
date: text("date").notNull(), // YYYY-MM-DD
newUsers: integer("new_users").default(0),
activeUsers: integer("active_users").default(0),
payingUsers: integer("paying_users").default(0),
revenue: integer("revenue").default(0), // in cents
apiCalls: integer("api_calls").default(0),
apiCost: integer("api_cost").default(0), // in cents
createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
});
export const userEvents = sqliteTable("user_events", {
id: text("id").primaryKey(),
userId: text("user_id").notNull(),
eventType: text("event_type").notNull(), // signup, activate, subscribe, churn, refer
metadata: text("metadata"), // JSON for additional data
createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
});
// Aggregation cron job: aggregate events → daily_metrics
6.13 Report Validation Checklist
After generating reports, verify:
Phase 7: Smart Seed Generation [v3.3 NEW]
Goal: Intelligently generate realistic test data based on detected business context, enabling immediate demo and validation without manual data entry.
7.1 When to Use This Phase
Prompt user after Phase 0 detection:
## Seed Data Generation
Would you like to generate test data for your admin dashboard?
- [x] Yes, generate realistic seed data (recommended for development/demo)
- [ ] No, I'll add data manually
If yes, select data volume:
- [ ] Minimal (50 records per entity)
- [x] Standard (100+ records per entity) - recommended
- [ ] Large (500+ records per entity)
7.2 Context-Aware Entity Detection
Automatically detect entities from existing schema:
// Schema analysis output
interface DetectedEntities {
users: {
table: "user" | "users" | "admin_user"
hasRole: boolean
hasEmail: boolean
hasPassword: boolean
}
businessEntities: {
name: string
tableName: string
fields: string[]
relationships: ForeignKey[]
statusField?: string
statusValues?: string[]
}[]
auditLogs?: {
table: string
actorField: string
actionField: string
}
subscriptions?: {
planTable: string
subscriptionTable: string
userField: string
}
metrics?: {
dailyTable: string
eventTable: string
}
}
7.3 Smart Data Generation Rules
7.3.1 User Data Generation
const userSeedRules = {
quantity: {
users: 100, // Base users
admins: 15, // 15% admin ratio
},
distribution: {
role: { user: 0.85, admin: 0.10, super_admin: 0.05 },
status: { active: 0.85, inactive: 0.10, banned: 0.05 },
verified: { true: 0.80, false: 0.20 },
},
timeDistribution: {
// More users created recently (growth simulation)
weight: (dayIndex: number, totalDays: number) => {
return 1 + (dayIndex / totalDays) * 0.5 // 50% growth over period
}
},
locale: "zh-CN", // Use Chinese names, phones, addresses
}
7.3.2 Business Entity Distribution
const statusDistributionRules = {
// Generic status patterns by entity type
content: { draft: 0.15, published: 0.75, archived: 0.10 },
order: {
pending: 0.05, processing: 0.10, shipped: 0.15,
delivered: 0.60, completed: 0.08, cancelled: 0.02
},
subscription: {
trial: 0.20, active: 0.65, expired: 0.10, cancelled: 0.05
},
ticket: { open: 0.25, in_progress: 0.15, resolved: 0.55, closed: 0.05 },
comment: { pending: 0.10, approved: 0.85, rejected: 0.05 },
// Auto-detect status field and values from schema
detectStatus: (entity: EntitySchema) => {
const statusField = entity.fields.find(f =>
f.name === "status" || f.name.endsWith("_status")
)
if (statusField?.enum) {
return deriveDistribution(statusField.enum)
}
return null
}
}
7.3.3 Time-Based Growth Simulation
const growthSimulation = {
// Simulate realistic business growth
pattern: "exponential", // linear | exponential | seasonal
// Value calculation with growth factor
calculateValue: (
baseValue: number,
dayIndex: number,
totalDays: number,
pattern: string
): number => {
const progress = dayIndex / totalDays
switch (pattern) {
case "linear":
return baseValue * (1 + progress * 0.3) // 30% linear growth
case "exponential":
return baseValue * Math.pow(1.3, progress) // 30% compound growth
case "seasonal":
return baseValue * (1 + Math.sin(progress * Math.PI) * 0.3)
default:
return baseValue
}
},
// Add random fluctuation
addNoise: (value: number, variance: number = 0.2): number => {
return Math.floor(value * (1 - variance + Math.random() * variance * 2))
}
}
7.3.4 Foreign Key Relationship Handling
const relationshipRules = {
// Ensure 100% valid foreign keys
validation: {
orphanRecords: false, // Never create orphan records
cascadeCreate: true, // Create parent records if needed
},
// Distribution of related records
oneToMany: {
// e.g., User has many Skills
min: 1,
max: 10,
average: 5,
distribution: "poisson", // normal | uniform | poisson
},
manyToMany: {
// e.g., Skill has many Categories (via join table)
min: 1,
max: 5,
average: 2,
},
// Ensure referential integrity order
creationOrder: (entities: EntitySchema[]) => {
return topologicalSort(entities, "foreignKeys")
}
}
7.4 BI Metrics Seed Data
const biMetricsSeedRules = {
dailyMetrics: {
days: 120, // 4 months of historical data
// Funnel conversion rates (R1)
conversion: {
visitorToSignup: { base: 0.20, variance: 0.05 }, // 15-25%
signupToActivation: { base: 0.60, variance: 0.10 }, // 50-70%
activationToPayment: { base: 0.20, variance: 0.05 }, // 15-25%
},
// Revenue metrics (R2)
revenue: {
baseDaily: 5000, // ¥50 base daily revenue
growthRate: 0.02, // 2% daily compound growth
planDistribution: {
basic: 0.70, // 70% basic plan
pro: 0.20, // 20% pro plan
team: 0.10, // 10% team plan
}
},
// Retention metrics (R3)
retention: {
baseChurnRate: 0.03, // 3% monthly churn
renewalRate: 0.85, // 85% renewal rate
},
// Cost metrics (C1-C4)
costs: {
apiCostPerCall: 0.001, // ¥0.001 per API call
baseInfrastructureCost: 1000, // ¥10/day base
infrastructureGrowthRate: 0.01, // 1% daily growth
}
},
userEvents: {
eventsPerUser: { min: 5, max: 20, average: 10 },
eventTypes: [
{ type: "visit", weight: 0.40 },
{ type: "signup", weight: 0.15 },
{ type: "activate", weight: 0.12 },
{ type: "subscribe", weight: 0.08 },
{ type: "renew", weight: 0.10 },
{ type: "refer", weight: 0.05 },
{ type: "churn", weight: 0.05 },
{ type: "upgrade", weight: 0.03 },
{ type: "downgrade", weight: 0.02 },
]
}
}
7.5 Seed Script Template
// scripts/seed-all.ts
import Database from "better-sqlite3"
interface SeedConfig {
dbPath: string
counts: {
users: number
admins: number
skills: number
auditLogs: number
dailyMetricsDays: number
eventsPerUser: number
}
locale: "zh-CN" | "en-US"
growth: "linear" | "exponential" | "seasonal"
}
const defaultConfig: SeedConfig = {
dbPath: "./sqlite.db",
counts: {
users: 100,
admins: 15,
skills: 120,
auditLogs: 500,
dailyMetricsDays: 120,
eventsPerUser: 10,
},
locale: "zh-CN",
growth: "exponential",
}
async function seedAll(config: SeedConfig = defaultConfig) {
const db = new Database(config.dbPath)
try {
console.log("🌱 Starting seed generation...")
// Order matters for foreign key relationships
const userIds = await seedUsers(db, config)
const adminIds = await seedAdmins(db, config)
const categoryIds = await seedCategories(db)
await seedSkills(db, config, userIds, categoryIds)
await seedAuditLogs(db, config, [...userIds, ...adminIds])
// BI Reports data (if reports module exists)
if (tableExists(db, "subscription_plan")) {
const planIds = await seedSubscriptionPlans(db)
await seedUserSubscriptions(db, userIds, planIds)
}
if (tableExists(db, "user_event")) {
await seedUserEvents(db, userIds, config)
}
if (tableExists(db, "daily_metrics")) {
await seedDailyMetrics(db, config)
}
console.log("✅ Seed generation complete!")
printSummary(db)
} finally {
db.close()
}
}
// Usage:
// npx tsx scripts/seed-all.ts
// npx tsx scripts/seed-all.ts --count=200 --growth=linear
7.6 Seed Commands
# Add to package.json scripts
"seed:all": "npx tsx ./scripts/seed-all.ts",
"seed:users": "npx tsx ./scripts/seed-all.ts --only=users",
"seed:metrics": "npx tsx ./scripts/seed-all.ts --only=metrics",
"seed:clean": "npx tsx ./scripts/seed-all.ts --clean"
# Usage examples
bun run seed:all # Generate all test data
bun run seed:all --count=200 # 200 base records per entity
bun run seed:all --growth=linear # Linear growth pattern
bun run seed:all --locale=en-US # English locale
bun run seed:clean # Clear all seed data
7.7 Volume Guidelines by Business Type
| Business Type | Core Entity | Base Count | Related Data | Total Records |
|---|
| Blog | posts | 100 | categories(15), tags(50), comments(200) | ~365 |
| E-commerce | products, orders | 100/250 | categories(20), customers(50) | ~420 |
| SaaS | tenants | 100 | plans(5), users(300), subscriptions(80) | ~485 |
| Education | courses | 100 | sections(300), lessons(900), students(200) | ~1500 |
| Skill Platform | skills | 120 | users(100), categories(10), audit_logs(500) | ~730 |
7.8 Integration with Mode Selection
Updated workflow:
Phase 0: Admin Detection
↓
├─ No admin → Mode A: Full Generation
│ ↓
│ Phases 1-5
│ ↓
│ [Ask] Generate seed data? → Phase 7
│
└─ Admin exists → Mode B: BI Enhancement
↓
Phase 6: Add Reports
↓
[Ask] Generate BI test data? → Phase 7 (metrics only)
7.9 Seed Data Validation Checklist
After generating seed data, verify:
Arbitrage Perspective
From the arbitrage mindset in cog.md
- Reduce Fixed Costs: Auto-generate based on business, no development from scratch
- Reduce Labor Costs: AI understands business and generates code automatically
- Reduce Trial-Error Costs: Pre-built templates avoid architecture mistakes
- Reduce Time Costs: 1 hour to generate complete business admin vs 1 week manual work
- [v3.0] Reduce Demo Costs: Auto-fill realistic test data for immediate validation
- [v3.1] Reduce CRUD Costs: Complete entity management with soft delete out of the box
- [v3.2] Reduce Decision Costs: BI reports enable data-driven decisions in minutes vs gut feelings
- [v3.2] Increase Revenue Visibility: 4减4增 framework reports directly track R1-R4 metrics
- [v3.3] Reduce Data Entry Costs: Smart seed generation creates realistic demo data automatically
- [v3.3] Accelerate Validation: Test full workflows immediately with contextual seed data
