一个务实的、可交付的 AI-Native 全栈底座：Next.js（App Router）+ FastAPI。
它不是“又一个后台模板”，而是面向企业/交付团队的 多租户 + 权限边界 + 可升级 的工程基线，并配套一套能让 AI 协作开发“少返工、可验收、可复用”的 devdocs 交付体系。
- 更快上线：把多租户、RBAC、菜单路由、审计/通知等做成默认能力
- 更可控迭代：迁移链线性化（Alembic），种子与数据迁移闭环，避免“第二版开始变慢”
- 更好复用：业务模块按插件化思路扩展，减少重复造轮子
License：AGPL-3.0（见
LICENSE）。支持商业化交付/定制/集成（见文末）。
快速链接
- 文档总入口：
devdocs/README.md - 系统事实（先看这个）：
devdocs/foundation/PROJECT_DESIGN.md - 后端说明与 API 路由：
backend/README.md、backend/API_ROUTES.md - 前端说明与欢迎页：
frontend/README.md、frontend/public/README.md
- 多租户隔离（
tenant_id） - RBAC：Role ⇄ Menu，权限码承载在
menus.perms（无独立 permissions 表） - 动态菜单：后端输出
GET /api/v1/menus/routes，前端按权限渲染（避免权限边界漂移） - 数据权限（团队维度 DataScopeCtx，可选）
- Alembic 迁移（0→1 基线 + 后续线性增量）
- seed 初始化 + “菜单双写”闭环（新装 + 老租户升级都覆盖）
- 通用能力：通知、操作日志、积分
- 前端：Next.js + shadcn/ui，内置登录与 refresh token、演示模式（只读）
devdocs/flows/：端到端开发链路（新模块、菜单双写）devdocs/checklists/：质量门禁（减少返工）devdocs/guide_docs/：代码级落地手册（Service/事务/权限/数据权限等）devdocs/foundation/：系统事实（项目设计、插件规范、DB 基线、前端基线）.claude/CLAUDE.md：AI 开发入口（路径图谱，防止长对话迷路）
- SaaS / 创业团队：想把“多租户后台 + 权限边界 + 可升级”做成产品底座，把时间花在业务差异上
- 企业内部平台/中台团队：需要可审计、可复盘、可持续迭代的工程基线（尤其是权限/数据边界/升级路径）
- 交付/集成商：同时服务多个客户/多个业务线，想把交付从“项目制手工活”推进到“可复制的产品化交付”
如果你是买单者或交付负责人，通常最终会落到这 5 个问题：
- 多久能上线第一版（不是 demo，是可用的第一版）？
- 需求变了怎么办（能不能小步迭代，而不是推倒重来）？
- 风险谁来兜（权限/数据/审计/升级出了事能否追溯）？
- 长期成本多少（不是首期开发，而是后续一年两年的维护与扩展）？
- 能不能复用（下一个模块/下一个客户，能否少走一半弯路）？
aojuai-base 的价值是：尽量把这些“非业务但决定成败的能力”做成默认件。
- 后端：
38000 - 前端：
3000
- Python：
>= 3.11 - Node.js：建议
>= 20 - pnpm：建议
>= 9 - PostgreSQL：必需
- Redis：可选（当前仅预留，默认不强依赖）
示例（按你的实际账号密码替换）：
CREATE ROLE "devbase" LOGIN PASSWORD '<DB_PASSWORD>';
CREATE DATABASE "devbase" OWNER "devbase";后端读取 backend/.env（不入库）：
cp backend/.env.production.template backend/.env本地开发常用配置（示例）：
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=devbase
DB_PASSWORD=<DB_PASSWORD>
DB_NAME=devbase
DEBUG=true
ENV=development
# 首次启动可开启自动建表与种子数据（会创建 admin/Admin@123456）
AUTO_INIT_DB=true
AUTO_SEED_DATA=true安装依赖与启动：
cd backend
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 38000健康检查：
curl http://127.0.0.1:38000/health安装依赖并启动：
pnpm -C frontend install
BACKEND_PORT=38000 pnpm -C frontend dev打开：
http://127.0.0.1:3000/login
说明：前端通过
frontend/next.config.mjsrewrites 将/api/*代理到后端；本地推荐直接设置BACKEND_PORT=38000。
开启 AUTO_SEED_DATA=true 时会创建默认账号：
- 管理员：
admin / Admin@123456 - 测试用户：
test / Test@123456
前端支持演示模式：只允许只读请求（GET/HEAD/OPTIONS + 少量白名单 POST）。
NEXT_PUBLIC_DEMO_MODE=true BACKEND_PORT=38000 pnpm -C frontend dev注意：生产构建会读取
frontend/.env.production；若你需要可写操作，请确保NEXT_PUBLIC_DEMO_MODE=false。
devdocs/ 是本仓库的“交付系统”：系统事实、端到端流程、门禁清单、模板与可复用技能剧本都在这里。
建议先从：devdocs/README.md 开始。
-
devdocs/foundation/：系统事实（不要“凭感觉改”）devdocs/foundation/PROJECT_DESIGN.md：本仓库的架构事实与硬性约束（多租户/RBAC/菜单 IA 等）devdocs/foundation/DB_MIGRATION_BASELINE.md：迁移基线（0→1）与后续演进规则devdocs/foundation/PLUGIN_MODULES.md：插件式模块规范（安装/卸载/升级/菜单双写）devdocs/foundation/frontend/FRONTEND_BASELINES.md：Next.js + shadcn/ui 前端基线与约定
-
devdocs/flows/：端到端作业流（从需求到上线怎么走）devdocs/flows/DEVELOPMENT_WORKFLOW.md：稳定版闭环流程（需求→设计→开发→部署→验证→复盘）devdocs/flows/NEW_MODULE.md：新增模块的标准顺序（DB→权限/菜单→API→迁移/seed→前端→验收）devdocs/flows/MENUS_PERMS_DUALWRITE.md：菜单/权限“双写闭环”（seed + Alembic 数据迁移）devdocs/flows/SKILLS_MAP.md：按任务选择合适的 skill
-
devdocs/checklists/：质量门禁（上线前必须过）devdocs/checklists/DEV_CHECKLIST.md：开发自检清单（权限/菜单/路由/迁移/seed 等高频坑）devdocs/checklists/CORE_DEVELOPMENT_GUIDE.md：核心开发约束（统一口径）
-
devdocs/guide_docs/：代码级落地手册（怎么写才“对齐底座”）devdocs/guide_docs/API_ENDPOINT_GUIDE.md：端点规范（薄控制器、依赖注入、错误码）devdocs/guide_docs/SERVICE_LAYER_GUIDE.md：Service 分层规范（禁止 API 直接 DB）devdocs/guide_docs/DATABASE_TRANSACTION_GUIDE.md：事务与提交策略（避免脏写/乱 commit）devdocs/guide_docs/PERMISSION_CHECKER_GUIDE.md：权限校验（PermissionChecker）devdocs/guide_docs/DATA_PERMISSION_GUIDE.md：数据权限（DataScopeCtx）devdocs/guide_docs/MENU_SEED_MIGRATION_GUIDE.md：菜单/权限初始化与升级的落地指南devdocs/guide_docs/RESPONSE_USAGE_GUIDE.md：统一响应封装与错误处理
-
devdocs/skills/：可复用“剧本”（输入→步骤→输出→验收）devdocs/skills/skills.md：Skills 总入口与规格模板- 推荐常用：
devdocs/skills/aojuai-devbase-scaffold/SKILL.md：脚手架扩展总览（决策树）devdocs/skills/aojuai-backend-module/SKILL.md：后端新模块（Domain+Service+Endpoint）devdocs/skills/aojuai-backend-migrations/SKILL.md：迁移工作流（生成→审阅→upgrade）devdocs/skills/aojuai-backend-seed/SKILL.md：seed/菜单权限初始化与增量脚本devdocs/skills/aojuai-nextjs-shadcn-frontend/SKILL.md：Next.js 页面/布局/权限对接devdocs/skills/aojuai-menu-perms-dualwrite/SKILL.md：菜单/权限双写闭环
-
devdocs/templates/：模板（复制即可用）devdocs/templates/REQUIREMENTS_TEMPLATE.md：需求与验收模板devdocs/templates/DB_DESIGN_TEMPLATE.md：DB 设计模板devdocs/templates/API_CONTRACT_TEMPLATE.md：接口契约模板devdocs/templates/ALEMBIC_MIGRATION_TEMPLATE.md：迁移模板devdocs/templates/RELEASE_RUNBOOK_TEMPLATE.md：发布 runbook
-
devdocs/ai/：AI 作业流与提示词模板devdocs/ai/AI_ASSISTED_DEVELOPMENT.md：让 AI 输出“变更清单/权限/菜单/迁移/验证”的结构化交付
-
devdocs/issues/：踩坑库（把问题沉淀成资产）devdocs/issues/DEVBASE_PITFALLS.md：高频坑汇总devdocs/issues/*：按主题沉淀（ENV / MIGRATIONS_SEED / PERMISSIONS_MENUS / FRONTEND / BACKEND / TESTING）
我们不会把系统做成“按钮越来越多的迷宫”。更重要的方向是：在严谨权限与审计之上，提供 单入口 AI Assistant：
- 先只读：查询、定位、解释系统状态
- 再可写：变更必须可确认、可解释、可追溯
本项目采用 GNU Affero General Public License v3.0（AGPL-3.0）。
企业使用/二次开发/对外提供服务前，请务必评估合规与授权边界。
- 开源使用：你可以直接基于本仓库开发你的业务模块（推荐插件化思路）
- 商业支持：私有化部署、模块定制、系统集成、交付培训、长期维护与迭代
（可选）两个月、约 4 万美元 tokens：我们留下的 7 条规律
这不是“炫投入”，而是一次真实的迭代-推倒-再迭代。我们的结论很朴素：
AI 能加速产出，但没有底座与方法论，它也会更快地放大返工与混乱。
- AI 能加速产出，但不会自动加速对齐（目标/边界/验收仍要靠人写清楚）
- 传统开发最贵的是返工；AI 时代“输入不清晰”会让返工更贵
- 决定交付速度的是底座复用（多租户/权限/升级/审计是长期效率的来源）
- 上线只是开始，升级才是长期战争（新装怎么跑、老用户怎么升级）
- 流程与门禁比提示词更重要（提示词解决“像不像”，流程解决“能不能交付”）
- tokens 成本必须预算化（把试错燃料烧在可复用资产上）
- 单入口一定会来，但必须建立在严谨逻辑上（先只读再可写，可写必须可追溯）