项目开发规范与空应用模板（适用于本项目） v0.5.0.0

本文档基于当前 /opt/web2py-cxmj/applications 目录现状整理，重点参考 service_center 的认证与菜单实现方式，并提供一个可直接复用的空应用模板。

1. 统一认证数据库获取方式

1.1 统一入口

所有新应用必须使用 service_center 的统一认证初始化逻辑，避免各应用重复定义 Auth/DAL，确保账号与会话在各应用间共享。

统一入口模块：

统一调用方式（放在应用 models/00_db.py）：


# 共享模块路径：用于跨应用的认证初始化。
shared_modules = os.path.join(request.folder, '..', 'service_center', 'modules')
if shared_modules not in sys.path:
    sys.path.append(shared_modules)

from service_center_auth import apply_service_center_auth
apply_service_center_auth(globals())

1.2 关键约定

2. 菜单定义规范（静态与动态）

2.1 顶部全局菜单

全局顶部菜单统一定义在：

该文件定义 rmenu 并设置：


response.menu = rmenu

其他应用必须加载该菜单文件，避免各应用顶部导航不一致。推荐在 models/00_db.py 中加载：


service_center_menu = os.path.join(
    request.folder, '..', 'service_center', 'models', 'xx_menu.py'
)
exec(compile(open(service_center_menu, 'r', encoding='utf-8').read(),
             'xx_menu.py', 'exec'), globals())

2.2 侧边栏菜单（应用私有）

应用侧边栏菜单放在本应用：

推荐变量名：app_sub_menu。 菜单结构规范（与现有布局兼容）：


(标题, 是否禁用, URL, [子菜单...])

示例：


app_sub_menu = [
    (T('首页'), False, URL('default', 'index')),
    (T('功能分组'), False, '#', [
        (T('子页面A'), False, URL('default', 'page', vars={'tab': 'a'})),
    ]),
]

控制器中统一赋值：


response.sub_menu = app_sub_menu

2.3 动态菜单（可选）

如需菜单后台管理，可参考：

其中已包含 menu_items 表结构与 get_menu_tree() 方法，适合由后台维护菜单并在页面加载。

3. 前端资源统一管理与引用方式

3.1 统一资源位置

公共前端资源建议集中放在：

推荐用途：

3.2 引用规范

跨应用引用公共资源时统一使用：


URL('service_center', 'static', 'css/bootstrap.min.css')
URL('service_center', 'static', 'js/jquery.js')

应用私有资源放在本应用 static/ 下，使用：


URL('static', 'css/xxx.css')

3.3 布局文件规范

每个应用必须维护自己的 views/layout.html，但应保持以下约定：

4. 空应用模板（可直接复用）

已创建空应用模板目录：

4.1 模板结构


app_template/
├── __init__.py
├── VERSION
├── controllers/
│   └── default.py
├── models/
│   ├── 00_db.py
│   └── menu.py
├── views/
│   ├── layout.html
│   └── default/
│       ├── index.html
│       ├── page.html
│       └── user.html
└── static/
    └── images/
        └── favicon.ico

4.2 模板功能

4.3 新建应用流程

  1. 复制模板目录并改名：

   cp -r app_template 新应用名
  1. 修改 controllers/default.py 中的标题、页面逻辑。
  2. 修改 models/menu.py 生成本应用侧边栏菜单。
  3. 如需在顶部导航添加入口，请更新 service_center/models/xx_menu.py。
  4. 如果新增应用有专属静态资源，放入新应用 static/。

5. 约束与注意事项