---
title: 模块开发规范与验证命令
type: rule
permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/模块开发规范与验证命令
stable_id: 3e6dcfc1-f561-415d-9356-b387347c9193
scope: project
project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
memory_type: rule
status: active
revision: 1
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
created_at: '2026-09-23T15:10:30.838746+00:00'
updated_at: '2026-09-23T15:10:30.838801+00:00'
tags:
- module
- convention
- testing
- rbac
---

1) 新业务按模块目录开发，不散改框架核心。前端 web/src/modules/<key>/（index.ts defineModule / api.ts / views / permissions.ts / i18n），key 用短横线；后端 server/app/modules/<key>/（__init__.py AppModule + api/services/repositories/models/schemas），key 用下划线。脚手架：node scripts/create-module.mjs。2) 权限 code 统一 `action:<resource>:<action>`（create/delete/update/read/operate），`read` 充当页面/导航访问门槛（授予任一动作自动展开 read）；路由型页面权限已弃用。3) 建表：新增 model 即自动 create_all；加列用模块 table_syncs；稳定迁移用 migrations。4) 验证：前端 `cd web && npm run test:smoke && npm run build`（vue-tsc 严格、有 noUnusedLocals，未用导入会构建失败）；后端 `python -m compileall -q server/app` + `.venv\Scripts\python.exe -m pytest server/tests/test_<module>.py -q`。5) 高危写操作用 require_web_session 限制仅 Web 登录态可调（API Token 不可）。