Reglow 基础库改造与集成 —— 小白实操手册

┌──────────────────────────────────────────────────────┐
│                                                      │
│  就像麦当劳开分店：                                    │
│                                                      │
│  总部研发了炸鸡配方、收银系统、排班制度……                │
│  （这些 = Reglow 基础库：登录、权限、菜单、日志、素材）   │
│                                                      │
│  每家分店不用重新发明炸鸡，直接拿总部配方用。              │
│  分店自己只需要操心——当地特色菜、促销活动、装修风格。      │
│  （这些 = 像匠独有业务：门店管理、订单系统、修图工作台）    │
│                                                      │
│  总部升级配方 → 所有分店自动受用，炸鸡口味保持一致。       │
│                                                      │
└──────────────────────────────────────────────────────┘

请求进来
    ↓
┌──────────────────────────────┐
│  Controller（前台接待）        │  ← 只做三件事：接参数 → 调 Service → 返回响应
│  薄得像纸，零业务逻辑           │
├──────────────────────────────┤
│  Schema（安检门）              │  ← 声明输入输出的形状，脏数据止于此
│  类型即验证，类型即文档         │
├──────────────────────────────┤
│  Service（掌勺大厨）           │  ← 业务规则、流程编排、事务管理（核心大脑）
│  只管 raise 异常，不管怎么返回  │
├──────────────────────────────┤
│  Repository（仓库管理员）       │  ← 数据存取、查询封装、分页、数据权限
│  只跟数据库打交道，不碰业务      │
├──────────────────────────────┤
│  Model（食材规格书）            │  ← 纯表结构定义，零逻辑，10~20 行
│  换数据库只改 Repository       │
└──────────────────────────────┘

ReglowAdmin FastAPI App
│
├── /admin/api/v1/    ← 管理后台端（Web 后台）
│   └── 完整 CRUD + RBAC 权限 + 全字段
│   └── 鉴权：get_current_employee + PermissionChecker
│
├── /api/v1/          ← 用户端（App / 小程序 / H5 / 客服端）
│   └── 只读为主 + 微信/手机号登录 + 脱敏字段
│   └── 鉴权：get_current_client_user（在 core/dependencies_client.py）
│
└── /health           ← 健康检查（无需认证）

┌──────────────────────────────────────────┐
│  操作权限（RBAC）                          │
│  用户 → 角色 → 菜单/按钮权限               │
│  声明式：@router.get(...,                   │
│    dependencies=[PermissionChecker(         │
│      "admin:list")])                        │
├──────────────────────────────────────────┤
│  数据权限（行级过滤）                       │
│  全部/本部门及以下/本部门/本人/自定义         │
│  Repository 层自动加 WHERE 过滤             │
├──────────────────────────────────────────┤
│  多租户（P3 扩展）                          │
│  中间件自动提取 tenant_id                    │
│  Repository 自动加 WHERE tenant_id = ?      │
│  Service 层完全无感                         │
└──────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│              ReglowAdmin 通用后台             │
├──────────────────────────────────────────────┤
│                                              │
│  P0 核心必做                                  │
│  ├── 认证登录（账号密码 + 验证码 + 短信登录）    │
│  ├── 管理员管理（CRUD + 部门 + 岗位 + 工号）    │
│  ├── 角色管理（CRUD + 权限分配）               │
│  ├── 菜单管理（树形结构 + 按钮权限）            │
│  ├── 部门管理（树形组织架构）                   │
│  ├── 字典管理（枚举/下拉统一维护）              │
│  ├── 系统设置（短信/存储/备案信息）             │
│  └── 操作日志（变更前后快照）                   │
│                                              │
│  P1 重要                                      │
│  ├── 岗位管理                                 │
│  ├── 素材中心（图片/视频上传 + 生命周期清理）     │
│  ├── 数据权限（行级过滤）                       │
│  └── 代码生成器（一键生成模块）                 │
│                                              │
│  P2-P3 增强                                   │
│  ├── 通知公告                                 │
│  ├── 文章管理                                 │
│  ├── 照片/视频/相册管理                        │
│  ├── AI 生成（图片+视频）                       │
│  ├── 智能客服                                 │
│  ├── 消息模板                                 │
│  └── 多租户                                   │
│                                              │
└──────────────────────────────────────────────┘

改造前（现在）：                      改造后（目标）：

reglow_project/                     reglow_project/
├── coding/                         ├── reglow/          ← 📦 Python 基础库
│   ├── backend-python/             │   ├── core/              pip install reglow
│   │   ├── core/                   │   ├── common/
│   │   ├── common/                 │   └── modules/
│   │   ├── modules/                │       ├── auth/     # 认证（三端 Router）
│   │   └── main.py                 │       ├── employee/ # 管理员
│   └── frontend-admin/             │       ├── user/     # C端用户
│       └── src/                    │       ├── role/     # 角色
│                                   │       ├── menu/     # 菜单
│                                   │       ├── dept/     # 部门
│                                   │       ├── dict/     # 字典
│                                   │       ├── log/      # 日志
│                                   │       ├── config/   # 系统设置
│                                   │       ├── material/ # 素材
│                                   │       ├── notice/   # 通知
│                                   │       └── ...       # 更多
│                                   │
│                                   ├── frontend-reglow/  ← 📦 NPM 基础库
│                                   │   └── src/               @reglow/ui
│                                   │       ├── api/           API 客户端
│                                   │       ├── components/    组件库 reui
│                                   │       └── index.ts       统一导出
│                                   │
│                                   ├── reglow-app/      ← 🚀 Reglow 自己的后台
│                                   │   ├── backend/           from reglow import...
│                                   │   └── frontend/          import from @reglow/ui
│                                   │
│                                   └── pyproject.toml   # 包元信息
│
xiangjiang_project/                xiangjiang_project/
├── PRD/                           ├── PRD/
├── design/                        ├── design/
│                                   │
│                                   ├── backend/          ← 🚀 像匠后端
│                                   │   ├── main.py            from reglow import...
│                                   │   ├── requirements.txt   reglow==0.2.0
│                                   │   └── app/               每个模块自包含（store/, order/...）
│                                   │       ├── store/         门店模块（五层文件）
│                                   │       ├── order/         订单模块（五层文件）
│                                   │       └── ...            更多模块
│                                   │
│                                   └── admin/            ← 🚀 像匠 Web 后台
│                                       ├── package.json       "@reglow/ui": "^0.2.0"
│                                       └── src/pages/         照相馆业务页面

@reglow/ui（前端壳+组件）          reglow（后端地基）
        │                              │
        ├── ReglowAdmin 也用它         ├── ReglowAdmin 也用它
        ├── 像匠也用它                  ├── 像匠也用它
        └── 下贤趣也用它                └── 下贤趣也用它

                    ↓
        各自独立部署、独立域名、独立数据库
        但共享同一套代码（基础库）

[build-system]
requires = ["setuptools>=75", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "reglow"
version = "0.2.1"
description = "ReglowAdmin 通用后台管理系统基础库 —— 五层架构 + 三端分离 + 三维权限"
readme = "README.md"
license = {file = "LICENSE"}
requires-python = ">=3.12"
keywords = ["fastapi", "admin", "backend", "rbac", "multi-tenant"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Framework :: FastAPI",
    "Programming Language :: Python :: 3.12",
]

dependencies = [
    "fastapi>=0.115.12",
    "uvicorn[standard]>=0.34.2",
    "sqlalchemy[asyncio]>=2.0.41",
    "aiomysql>=0.2.0",
    "pymysql>=1.1.1",
    "aiosqlite>=0.20.0",
    "email-validator>=2.3.0",
    "pydantic>=2.11.4",
    "pydantic-settings>=2.9.1",
    "python-jose[cryptography]>=3.4.0",
    "bcrypt>=4.3.0",
    "python-multipart>=0.0.20",
    "redis>=5.3.0",
    "alembic>=1.16.1",
    "httpx>=0.28.1",
    "captcha>=0.6.0",
    "pillow>=11.2.1",
    "svg.path>=7.0",
    "boto3>=1.38.8",
    "python-dotenv>=1.1.0",
]

[project.optional-dependencies]
ai = [
    "opencv-python>=4.11.0.86",
    "moviepy>=2.1.2",
    "edge-tts>=6.1.19",
    "pysrt>=1.1.2",
]
dev = [
    "coverage>=7.8.0",
]

[tool.setuptools.packages.find]
include = ["reglow*"]

# 在 reglow_project 根目录执行（PowerShell）

# 创建 reglow 包目录
mkdir reglow\core
mkdir reglow\common
mkdir reglow\common\utils
mkdir reglow\modules

# 用 git mv 移动（保留历史）
git mv coding/backend-python/core/config.py              reglow/core/config.py
git mv coding/backend-python/core/database.py            reglow/core/database.py
git mv coding/backend-python/core/security.py            reglow/core/security.py
git mv coding/backend-python/core/dependencies.py        reglow/core/dependencies.py
git mv coding/backend-python/core/dependencies_client.py reglow/core/dependencies_client.py
git mv coding/backend-python/core/cache.py               reglow/core/cache.py
git mv coding/backend-python/core/redis_client.py        reglow/core/redis_client.py
git mv coding/backend-python/core/redis_keys.py          reglow/core/redis_keys.py
git mv coding/backend-python/core/rate_limit.py          reglow/core/rate_limit.py
git mv coding/backend-python/core/logging_config.py     reglow/core/logging_config.py
git mv coding/backend-python/core/observability.py       reglow/core/observability.py
git mv coding/backend-python/core/sms.py                 reglow/core/sms.py
git mv coding/backend-python/core/__init__.py            reglow/core/__init__.py

git mv coding/backend-python/common/response.py          reglow/common/response.py
git mv coding/backend-python/common/exceptions.py        reglow/common/exceptions.py
git mv coding/backend-python/common/exception_handler.py reglow/common/exception_handler.py
git mv coding/backend-python/common/middleware.py        reglow/common/middleware.py
git mv coding/backend-python/common/i18n.py              reglow/common/i18n.py
git mv coding/backend-python/common/utils/               reglow/common/utils/
git mv coding/backend-python/common/__init__.py          reglow/common/__init__.py

# 逐个模块移动
git mv coding/backend-python/modules/auth             reglow/modules/auth
git mv coding/backend-python/modules/user             reglow/modules/user
git mv coding/backend-python/modules/employee         reglow/modules/employee
git mv coding/backend-python/modules/role             reglow/modules/role
git mv coding/backend-python/modules/menu             reglow/modules/menu
git mv coding/backend-python/modules/dept             reglow/modules/dept
git mv coding/backend-python/modules/post             reglow/modules/post
git mv coding/backend-python/modules/dict             reglow/modules/dict
git mv coding/backend-python/modules/config           reglow/modules/config
git mv coding/backend-python/modules/log              reglow/modules/log
git mv coding/backend-python/modules/material         reglow/modules/material
git mv coding/backend-python/modules/notice           reglow/modules/notice
git mv coding/backend-python/modules/message          reglow/modules/message
git mv coding/backend-python/modules/article          reglow/modules/article
git mv coding/backend-python/modules/photo            reglow/modules/photo
git mv coding/backend-python/modules/video            reglow/modules/video
git mv coding/backend-python/modules/album            reglow/modules/album
git mv coding/backend-python/modules/ai               reglow/modules/ai
git mv coding/backend-python/modules/agreement        reglow/modules/agreement
git mv coding/backend-python/modules/customer_service reglow/modules/customer_service
git mv coding/backend-python/modules/__init__.py      reglow/modules/__init__.py

# reglow/modules/article/router.py（实际代码）
from .controller import router
__all__ = ["router"]

# reglow/modules/user/router.py（同时有管理端 + 用户端的模块）
from .controller import router
from .controller_client import client_router
__all__ = ["router", "client_router"]

# reglow/modules/material/router.py（一个模块拆出多个 router）
from .controller import router, group_router
__all__ = ["router", "group_router"]

# reglow/modules/article/controller.py
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession

from .model import Article, ArticleCollection
from .schema import CreateArticleRequest, UpdateArticleRequest, ArticleResponse, ...
from .service import ArticleService
from common.response import ApiResponse, PageData
from core.database import get_db
from core.dependencies import PermissionChecker, get_current_employee

# 关键：模块自己在 APIRouter 上声明 prefix + tags
# 不要靠 main.py 的 include_router(..., prefix=...) 补，否则路径散落两处
router = APIRouter(prefix="/articles", tags=["文章管理"])

@router.get(
    "/",
    response_model=ApiResponse[PageData[ArticleResponse]],
    dependencies=[Depends(PermissionChecker("content:article:list"))],
)
async def list_articles(
    page: int = Query(1, ge=1),
    size: int = Query(10, ge=1, le=100),
    keyword: str | None = Query(None),
    db: AsyncSession = Depends(get_db),
):
    service = ArticleService(db)              # Service 显式接收 db
    items, total = await service.list_articles(page, size, keyword)
    return ApiResponse.success(PageData(items=items, total=total, page=page, size=size))

# reglow/modules/article/controller_client.py（像匠需要时新建）
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
from .schema import ArticleResponse
from .service import ArticleService
from common.response import ApiResponse, PageData
from core.database import get_db
from core.dependencies_client import get_current_client_user   # 用户端鉴权

client_router = APIRouter(prefix="/articles", tags=["文章-用户端"])

@client_router.get("/", response_model=ApiResponse[PageData[ArticleResponse]])
async def list_published_articles(
    page: int = Query(1, ge=1),
    size: int = Query(10, ge=1, le=100),
    db: AsyncSession = Depends(get_db),
    _user=Depends(get_current_client_user),
):
    service = ArticleService(db)
    # Service 内部强制过滤 status=published，只返回已发布
    items, total = await service.list_published(page, size)
    return ApiResponse.success(PageData(items=items, total=total, page=page, size=size))

# 在像匠项目的虚拟环境中（开发期）
cd d:\Huolidev\xiangjiang_project\backend
.venv\Scripts\activate

# 方式一：本地可编辑安装（推荐，改 reglow 代码即时生效）
pip install -e "d:\Huolidev\reglow_project"

# 方式二：从 Git 安装（正式版本）
pip install "git+https://git.xxx.com/reglow_project.git@v0.2.1"

# 带 AI 模块一起装
pip install -e "d:\Huolidev\reglow_project[ai]"

// reglow_project/frontend-reglow/package.json
{
  "name": "@reglow/ui",
  "version": "0.2.1",
  "description": "ReglowAdmin 通用后台管理系统前端组件库 —— 布局框架 + reui 组件 + 通用页面",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "peerDependencies": {
    "vue": "^3.5",
    "@radix-icons/vue": "^1.0",
    "@tanstack/vue-table": "^8.0"
  },
  "scripts": {
    "build": "vite build",
    "dev": "vite build --watch"
  }
}

// frontend-reglow/src/index.ts —— 统一导出，一个 import 拿全部

// ─── API 客户端 ───
export { apiClient, setAuthToken, clearAuthToken } from "./api/client";
export * from "./api/index";

// ─── 布局框架（壳） ───
export { default as AdminLayout } from "./components/layout/AdminLayout.vue";
export { SidebarTree } from "./components/layout/SidebarTree.vue";
export { HeaderActions } from "./components/layout/HeaderActions.vue";
export { BreadcrumbNav } from "./components/layout/BreadcrumbNav.vue";
export { TabBar } from "./components/layout/TabBar.vue";
export { NoticeBell } from "./components/layout/NoticeBell.vue";
export { GlobalAiSidebar } from "./components/layout/GlobalAiSidebar.vue";

// ─── 通用页面（直接拿来用） ───
export { default as LoginPage } from "./pages/auth/LoginPage.vue";
export { default as RegisterPage } from "./pages/auth/RegisterPage.vue";
export { default as UserManagePage } from "./pages/user/UserManagePage.vue";
export { default as RoleManagePage } from "./pages/role/RoleManagePage.vue";
export { default as MenuManagePage } from "./pages/menu/MenuManagePage.vue";
export { default as DeptManagePage } from "./pages/dept/DeptManagePage.vue";
export { default as DictManagePage } from "./pages/dict/DictManagePage.vue";
export { default as SystemSettingsPage } from "./pages/config/SystemSettingsPage.vue";
export { default as OperationLogPage } from "./pages/log/OperationLogPage.vue";
export { default as MaterialCenterPage } from "./pages/material/MaterialCenterPage.vue";
export { default as NoticeManagePage } from "./pages/notice/NoticeManagePage.vue";

// ─── reui 组件库（表格/表单/弹窗/上传/编辑器...） ───
export * from "./components/reui/table";
export * from "./components/reui/form";
export * from "./components/reui/dialog";
export * from "./components/reui/drawer";
export * from "./components/reui/editor";
export * from "./components/reui/image-viewer";
export * from "./components/reui/date-picker";
export * from "./components/reui/notification";
export { default as ImageUploader } from "./components/common/ImageUploader.vue";
export { default as AvatarUploader } from "./components/common/AvatarUploader.vue";

// ─── 通用工具 ───
export { usePermission } from "./composables/usePermission";
export { useAuth } from "./composables/useAuth";

# 在像匠 Web 后台项目
cd d:\Huolidev\xiangjiang_project\admin
npm install "git+https://git.xxx.com/reglow_project.git#v0.2.1"

# 或本地开发联调
npm install "d:\Huolidev\reglow_project\frontend-reglow"

"""
像匠（XiangJiang）O2O 影像服务平台
基于 Reglow 基础库，零重复开发通用后台功能
"""
from contextlib import asynccontextmanager
from fastapi import FastAPI, APIRouter
from sqlalchemy.ext.asyncio import AsyncSession

from reglow.common.middleware import register_middlewares
from reglow.common.exception_handler import register_exception_handlers
from reglow.core.logging_config import setup_logging
from reglow.core.config import get_settings
from reglow.core.database import get_db
from reglow.core.observability import register_observability_routes

settings = get_settings()


@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动：连接池预热、Redis 连接、定时任务等
    yield
    # 关闭：清理资源


# ─── 从 reglow 直接引入：不需要写一行代码 ───
# 每个模块都导出主 `router`（管理端），命名统一为 `router`
# 个别模块需要用户端时再追加 `client_router` / `public_router` / `inbox_router` / `group_router` 等
from reglow.modules.auth.router import router as auth_router
from reglow.modules.employee.router import router as employee_router
from reglow.modules.user.router import router as user_router
from reglow.modules.role.router import router as role_router
from reglow.modules.menu.router import router as menu_router
from reglow.modules.dept.router import router as dept_router
from reglow.modules.post.router import router as post_router
from reglow.modules.dict.router import router as dict_router
from reglow.modules.config.router import router as config_router, settings_router
from reglow.modules.log.router import router as log_router
from reglow.modules.material.router import router as material_router, group_router as material_group_router
from reglow.modules.agreement.router import router as agreement_router, public_router as agreement_public_router
from reglow.modules.notice.router import router as notice_router
from reglow.modules.message.router import router as message_router, inbox_router
from reglow.modules.article.router import router as article_router
from reglow.modules.ai.router import router as ai_router
from reglow.modules.photo.router import router as photo_router
from reglow.modules.video.router import router as video_router
from reglow.modules.customer_service.router import (
    admin_router as cs_admin_router,
    client_router as cs_client_router,
)

# ─── 像匠独有业务路由（每个模块自包含，从 controller.py 导入 router） ───
from app.store.controller import router as store_router
from app.order.controller import router as order_router
from app.retouch.controller import router as retouch_router
from app.product.controller import router as product_router
from app.reservation.controller import router as reservation_router
from app.finance.controller import router as finance_router
from app.marketing.controller import router as marketing_router


def create_app() -> FastAPI:
    app = FastAPI(
        title="像匠 API",
        version="0.1.0",
        lifespan=lifespan,
        docs_url="/docs" if settings.DEBUG else None,
        redoc_url="/redoc" if settings.DEBUG else None,
    )

    register_middlewares(app)
    register_exception_handlers(app)

    # ========================================
    # Admin API —— 管理后台端 /admin/api/v1
    # ========================================
    # 注意：所有 prefix 都在模块内部 APIRouter(...) 上声明
    # 这里只在 admin_api 上声明顶层前缀，include_router 不再传 prefix
    admin_api = APIRouter(prefix="/admin/api/v1")

    # ─── Reglow 通用模块（开箱即用，一行不写） ───
    admin_api.include_router(auth_router,             tags=["认证"])
    admin_api.include_router(employee_router,          tags=["管理员"])
    admin_api.include_router(user_router,              tags=["用户"])
    admin_api.include_router(role_router,             tags=["角色"])
    admin_api.include_router(menu_router,             tags=["菜单"])
    admin_api.include_router(dept_router,             tags=["部门"])
    admin_api.include_router(post_router,             tags=["岗位"])
    admin_api.include_router(dict_router,             tags=["字典"])
    admin_api.include_router(config_router,           tags=["参数配置"])
    admin_api.include_router(settings_router,         tags=["系统设置"])
    admin_api.include_router(log_router,              tags=["操作日志"])
    admin_api.include_router(material_router,         tags=["素材管理"])
    admin_api.include_router(material_group_router,   tags=["素材分组"])
    admin_api.include_router(agreement_router,        tags=["协议管理"])
    admin_api.include_router(agreement_public_router, tags=["协议(公开)"])
    admin_api.include_router(notice_router,            tags=["通知公告"])
    admin_api.include_router(message_router,           tags=["系统消息"])
    admin_api.include_router(inbox_router,             tags=["收件箱"])
    admin_api.include_router(article_router,          tags=["文章管理"])
    admin_api.include_router(ai_router,                tags=["AI"])
    admin_api.include_router(photo_router,            tags=["照片管理"])
    admin_api.include_router(video_router,            tags=["视频管理"])
    admin_api.include_router(cs_admin_router,        tags=["智能客服"])

    # ─── 像匠独有业务路由（你写的，同样在模块内声明 prefix） ───
    admin_api.include_router(store_router,       tags=["门店"])
    admin_api.include_router(order_router,       tags=["订单"])
    admin_api.include_router(retouch_router,     tags=["修图"])
    admin_api.include_router(product_router,      tags=["产品"])
    admin_api.include_router(reservation_router, tags=["预约"])
    admin_api.include_router(finance_router,     tags=["财务"])
    admin_api.include_router(marketing_router,   tags=["营销"])

    app.include_router(admin_api)

    # ========================================
    # Client API —— 用户端 /api/v1（C 端 App / 小程序 / H5）
    # ========================================
    client_api = APIRouter(prefix="/api/v1")
    client_api.include_router(cs_client_router)   # 客服端
    # 像匠自己有 C 端业务时（如门店预约、订单查询），在这里 include_router
    # 例如：client_api.include_router(xj_reservation_client_router)
    app.include_router(client_api)

    # 健康检查 + 观测
    @app.get("/health")
    async def health():
        return {"status": "ok", "service": "xiangjiang", "version": "0.1.0"}

    register_observability_routes(app)

    # 静态文件（上传目录）
    from fastapi.staticfiles import StaticFiles
    import os
    os.makedirs(settings.UPLOAD_DIR, exist_ok=True)
    app.mount("/uploads", StaticFiles(directory=settings.UPLOAD_DIR), name="uploads")

    return app


app = create_app()

# ============= app/store/model.py =============
# 食材规格书：纯表结构定义，零逻辑
from sqlalchemy import String, Integer, Float, Text
from sqlalchemy.orm import Mapped, mapped_column
from reglow.core.database import AutoBigInt, Base, TimestampMixin


class Store(Base, TimestampMixin):
    __tablename__ = "xj_store"

    id: Mapped[int] = mapped_column(AutoBigInt, primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(String(100), comment="门店名称")
    address: Mapped[str] = mapped_column(String(255), comment="详细地址")
    phone: Mapped[str | None] = mapped_column(String(20), comment="联系电话")
    lat: Mapped[float | None] = mapped_column(Float, comment="纬度")
    lng: Mapped[float | None] = mapped_column(Float, comment="经度")
    cover_url: Mapped[str | None] = mapped_column(String(512), comment="封面图")
    business_hours: Mapped[str | None] = mapped_column(String(200), comment="营业时间")
    description: Mapped[str | None] = mapped_column(Text, comment="门店介绍")
    status: Mapped[int] = mapped_column(Integer, default=1, comment="1营业 2休息 3关闭")
    sort: Mapped[int] = mapped_column(Integer, default=0, comment="排序")


# ============= app/store/schema.py =============
# 安检门：声明式验证，类型即文档
from pydantic import BaseModel, Field
from datetime import datetime


class CreateStoreRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    address: str = Field(..., max_length=255)
    phone: str | None = Field(None, pattern=r'^1[3-9]\d{9}$')
    lat: float | None = None
    lng: float | None = None
    business_hours: str | None = None
    description: str | None = None


class UpdateStoreRequest(BaseModel):
    name: str | None = Field(None, min_length=1, max_length=100)
    address: str | None = None
    phone: str | None = None
    business_hours: str | None = None
    description: str | None = None
    status: int | None = None


class StoreResponse(BaseModel):
    id: int
    name: str
    address: str
    phone: str | None
    lat: float | None
    lng: float | None
    cover_url: str | None
    business_hours: str | None
    description: str | None
    status: int
    sort: int
    created_at: datetime

    model_config = {"from_attributes": True}


# ============= app/store/repository.py =============
# 仓库管理员：只跟数据库打交道（接收 db，不依赖 FastAPI Depends）
from sqlalchemy import select, func
from sqlalchemy.ext.asyncio import AsyncSession
from .model import Store


class StoreRepository:
    def __init__(self, db: AsyncSession):
        self.db = db

    async def find_all(self, page: int, size: int, keyword: str | None = None) -> tuple[list[Store], int]:
        query = select(Store)
        count_query = select(func.count()).select_from(Store)
        if keyword:
            query = query.where(Store.name.contains(keyword))
            count_query = count_query.where(Store.name.contains(keyword))
        query = query.order_by(Store.sort).offset((page - 1) * size).limit(size)
        items = (await self.db.execute(query)).scalars().all()
        total = (await self.db.execute(count_query)).scalar()
        return items, total

    async def find_by_id(self, store_id: int) -> Store | None:
        result = await self.db.execute(select(Store).where(Store.id == store_id))
        return result.scalar_one_or_none()

    async def create(self, **kwargs) -> Store:
        store = Store(**kwargs)
        self.db.add(store)
        await self.db.commit()
        await self.db.refresh(store)
        return store

    async def update(self, store: Store, data) -> Store:
        for k, v in data.model_dump(exclude_unset=True).items():
            setattr(store, k, v)
        await self.db.commit()
        await self.db.refresh(store)
        return store

    async def delete(self, store: Store) -> None:
        await self.db.delete(store)
        await self.db.commit()


# ============= app/store/service.py =============
# 掌勺大厨：业务逻辑的归属地（不依赖 FastAPI，便于单测）
from reglow.common.exceptions import AppException
from .repository import StoreRepository


class StoreService:
    def __init__(self, db: AsyncSession):
        # Service 持有 Repository；测试时可换 fake repo
        self.repo = StoreRepository(db)

    async def list_stores(self, page: int, size: int, keyword: str | None = None):
        return await self.repo.find_all(page, size, keyword)

    async def get_store(self, store_id: int) -> Store:
        store = await self.repo.find_by_id(store_id)
        if not store:
            raise AppException(4000, "门店不存在")
        return store

    async def create_store(self, data: CreateStoreRequest) -> Store:
        return await self.repo.create(**data.model_dump())

    async def update_store(self, store_id: int, data: UpdateStoreRequest) -> Store:
        store = await self.get_store(store_id)
        return await self.repo.update(store, data)

    async def delete_store(self, store_id: int) -> None:
        store = await self.get_store(store_id)
        await self.repo.delete(store)


# ============= app/store/controller.py =============
# 前台接待：薄得像纸，只做三件事（接参数 → 调 Service → 返回响应）
# 关键：模块内部声明 prefix + tags，main.py 不再补 prefix
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession

from reglow.core.database import get_db
from reglow.core.dependencies import get_current_employee, PermissionChecker
from reglow.common.response import ApiResponse, PageData
from .schema import CreateStoreRequest, UpdateStoreRequest, StoreResponse
from .service import StoreService

router = APIRouter(
    prefix="/stores",
    tags=["门店管理"],
    dependencies=[Depends(get_current_employee)],  # 整个模块都要求登录
)


@router.get(
    "/",
    response_model=ApiResponse[PageData[StoreResponse]],
    dependencies=[Depends(PermissionChecker("store:list"))],
)
async def list_stores(
    page: int = Query(1, ge=1),
    size: int = Query(10, ge=1, le=100),
    keyword: str | None = Query(None),
    db: AsyncSession = Depends(get_db),
):
    service = StoreService(db)
    items, total = await service.list_stores(page, size, keyword)
    return ApiResponse.success(PageData(items=items, total=total, page=page, size=size))


@router.post(
    "/",
    response_model=ApiResponse[StoreResponse],
    dependencies=[Depends(PermissionChecker("store:create"))],
)
async def create_store(
    data: CreateStoreRequest,
    db: AsyncSession = Depends(get_db),
):
    service = StoreService(db)
    store = await service.create_store(data)
    return ApiResponse.success(store, "门店创建成功")


@router.get("/{store_id}", response_model=ApiResponse[StoreResponse])
async def get_store(store_id: int, db: AsyncSession = Depends(get_db)):
    service = StoreService(db)
    return ApiResponse.success(await service.get_store(store_id))


@router.put(
    "/{store_id}",
    response_model=ApiResponse[StoreResponse],
    dependencies=[Depends(PermissionChecker("store:update"))],
)
async def update_store(
    store_id: int,
    data: UpdateStoreRequest,
    db: AsyncSession = Depends(get_db),
):
    service = StoreService(db)
    return ApiResponse.success(await service.update_store(store_id, data), "更新成功")


@router.delete(
    "/{store_id}",
    response_model=ApiResponse,
    dependencies=[Depends(PermissionChecker("store:delete"))],
)
async def delete_store(store_id: int, db: AsyncSession = Depends(get_db)):
    service = StoreService(db)
    await service.delete_store(store_id)
    return ApiResponse.success(msg="删除成功")

xiangjiang_project/
├── backend/                             # 🚀 像匠后端
│   ├── .env                             # 环境变量
│   ├── main.py                          # 组装 FastAPI（见 5.1）
│   ├── requirements.txt                 # reglow==0.2.1
│   ├── alembic.ini
│   ├── alembic/versions/                # xj_store, xj_order...迁移脚本
│   └── app/                             # 像匠独有代码（按模块分！）
│       ├── store/                       # 门店模块（自包含）
│       │   ├── model.py                 # xj_store 表定义
│       │   ├── schema.py                # 门店请求/响应声明式验证
│       │   ├── repository.py            # 门店数据访问
│       │   ├── service.py               # 门店业务逻辑
│       │   └── controller.py            # 门店接口（薄薄一层）
│       ├── order/                       # 订单模块
│       │   ├── model.py                 # xj_order
│       │   ├── schema.py
│       │   ├── repository.py
│       │   ├── service.py
│       │   └── controller.py
│       ├── product/                     # 产品/团购模块
│       │   └── ...（同上五层）
│       ├── reservation/                 # 预约模块
│       │   └── ...
│       ├── retouch/                     # 修图模块
│       │   └── ...
│       ├── finance/                     # 财务模块
│       │   └── ...
│       └── marketing/                   # 营销模块
│           └── ...
│
├── admin/                               # 🚀 像匠 Web 后台
│   ├── package.json                     # "@reglow/ui": "^0.2.1"
│   └── src/
│       ├── App.vue                      # 用 @reglow/ui 的 AdminLayout 壳
│       └── pages/                       # 🆕 只有照相馆业务页面
│           ├── store/                   # 门店列表
│           ├── order/                   # 订单管理
│           ├── retouch/                 # 修图工作台
│           ├── product/                 # 产品/团购
│           ├── reservation/             # 预约管理
│           ├── finance/                 # 财务报表
│           └── marketing/               # 营销活动
│
├── PRD/
└── design/

你：我要改「订单模块」的状态流转逻辑！

❌ 如果按层分（像匠退回按层）：在 5 个目录间跳来跳去

   app/models/order.py
   │   └→ class Order(Base):
   │       __tablename__ = "xj_order"
   │       status = mapped_column(Integer)     ← 改表字段
   │
   app/schemas/order.py
   │   └→ class UpdateOrderStatusRequest       ← 改校验规则
   │
   app/repositories/order.py
   │   └→ class OrderRepository:
   │       async def update_status(...)        ← 改查询
   │
   app/services/order.py
   │   └→ class OrderService:
   │       async def transition_status(...)     ← 改核心逻辑
   │
   app/api/order.py
       └→ @router.put("/{id}/status")          ← 改接口

   5 个文件散落 5 个目录，大脑还得拼一张「订单全景图」
   漏改一个就 Bug — 而且 90% 会漏。

✅ 按模块分：所有订单代码一个目录，秒定位

   app/order/
   ├── model.py          ← 改表
   ├── schema.py         ← 改校验
   ├── repository.py     ← 改查询
   ├── service.py        ← 改核心逻辑（状态机在这！）
   └── controller.py     ← 改接口

   进一个目录，5 个文件一览无余。
   Ctrl+P 搜 "order/service" 直接跳业务核心。

<script setup>
import { AdminLayout } from "@reglow/ui";
import {
  StoreIcon,
  ReceiptIcon,
  ImageIcon,
  PackageIcon,
  CalendarIcon,
  ChartBarIcon,
  MegaphoneIcon,
} from "@radix-icons/vue";
// AdminLayout 自带：侧边栏、顶栏、标签页、面包屑、通知铃铛、AI 侧边栏

// 菜单 icon 传组件而非字符串名，避免与 @reglow/ui peerDependencies 中的图标库不匹配
const menus = [
  { name: "门店管理", path: "/stores", icon: StoreIcon },
  { name: "订单管理", path: "/orders", icon: ReceiptIcon },
  { name: "修图工作台", path: "/retouch", icon: ImageIcon },
  { name: "产品管理", path: "/products", icon: PackageIcon },
  { name: "预约管理", path: "/reservations", icon: CalendarIcon },
  { name: "财务报表", path: "/finance", icon: ChartBarIcon },
  { name: "营销活动", path: "/marketing", icon: MegaphoneIcon },
  // ─── 以下是 @reglow/ui 自带的通用页面，直接配路由就行 ───
  { name: "用户管理", path: "/users" },
  { name: "角色权限", path: "/roles" },
  { name: "菜单管理", path: "/menus" },
  { name: "部门管理", path: "/depts" },
  { name: "素材中心", path: "/materials" },
  { name: "系统设置", path: "/settings" },
];
</script>

<template>
  <AdminLayout :menus="menus" app-name="像匠摄影">
    <router-view />
  </AdminLayout>
</template>

# reglow-app/backend/main.py —— ReglowAdmin 也是基础库的使用者
from reglow.core.config import Settings
from reglow.modules.auth.router import admin_router as auth_router
from reglow.modules.employee.router import admin_router as employee_router
# ... 所有模块从 reglow 包导入

app = FastAPI(title="ReglowAdmin")
admin_app = FastAPI(title="ReglowAdmin - Admin API")

admin_app.include_router(auth_router, prefix="/auth")
admin_app.include_router(employee_router, prefix="/employees")
# ... 自己也是组装者
app.mount("/admin/api/v1", admin_app)

# ─── 生产环境（推荐） ───
reglow==0.2.1        # 精确锁定，手动升级，稳如泰山

# ─── 开发环境 ───
reglow~=0.2.1        # 允许 patch 升级：>=0.2.1, <0.3.0
                      # Bug 修复自动升，大功能不改

# ─── 不推荐 ───
reglow>=0.2.0        # 啥都自动升，容易炸

步骤 1 ─→ 看 CHANGELOG
           └→ Reglow 发新版了，看变了啥
              ├── Bug 修复 → 放心升 ✅
              ├── 新功能 → 看用不用得上，放心升 ✅
              └── ⚠️ Breaking Change → 必须手动适配后再升

步骤 2 ─→ 锁版本升级
           └→ requirements.txt：reglow==0.2.1 → reglow==0.3.0
           └→ pip install -r requirements.txt

步骤 3 ─→ 跑全部测试
           └→ 红灯 = 不能上线，排查原因

步骤 4 ─→ 手动回归
           └→ 登录、增删改查走一遍

步骤 5 ─→ 提交
           └→ git commit -m "chore: 升级 reglow 到 v0.3.0"

# CHANGELOG

## [0.3.0] - 2026-07-15

### 新增

- `reglow.core.sms` 短信服务模块，支持阿里云/腾讯云/华为云短信
- `material` 模块新增浏览器素材提取器

### 修改

- `get_current_employee` 新增 `require_verified` 参数
- 操作日志增加变更前后快照

### ⚠️ Breaking Changes

- `Employee.superior_id` 类型从 `int` 改为 `int | None`
  → 旧代码如果不处理 None 会报类型错误，请检查所有引用

像匠需要新功能
│
├→ 先看 reglow 有没有
│   ├→ 有 → 直接用 ✅
│   └→ 没有 → 问自己：换一个项目（下贤趣）也需要吗？
│       ├→ 是 → 去 reglow 仓库开发，发新版本
│       └→ 否 → 在像匠自己的 app/ 目录下开发

# ============ 终端 1：Reglow 基础库 ============
cd d:\Huolidev\reglow_project
pip install -e .                    # 可编辑模式安装

# ============ 终端 2：像匠后端 ============
cd d:\Huolidev\xiangjiang_project\backend
pip install -r requirements.txt    # 从本地 .venv 读取 reglow
uvicorn main:app --reload

# 现在改 reglow/core/config.py → 像匠即时生效！