Flask 后端代码生成
生成符合规范的 Flask API 代码：Resource、RequestParser、Service、Model、Schema、权限策略与测试。规范细节见 references/REFERENCE.md。
何时使用
-
用户要求「新增一个 user 资源」「写一个符合项目规范的 CRUD API」
-
用户提供 项目需求 ，需要据此生成/补全路由、Service、Model、测试等
生成流程
- 确认生成范围
向用户确认：
-
资源名与操作：如 users 的列表/详情/创建/更新/删除；是否需分页
-
数据模型：主要字段、是否软删除、与现有 Model 的关系
-
权限：资源与动作（如 user
- read /create /update /delete ），是否需在 policies.py 中新增
- 已有约定：项目内是否有 docs/xxx.md 、接口契约或错误码表，优先遵从
- 中间件与配置
-
优先使用常见中间件：开发过程中优先选用项目内或生态内常见的中间件（如 Redis、消息队列、缓存、日志等），避免自造轮子。
-
向用户询问访问方式：若涉及 Redis、消息队列、外部 API、数据库等，向用户询问访问方式（如连接串、主机/端口、认证方式、是否已有内网地址等），据此生成配置项说明与示例。
-
配置写入 .env.example：所有相关配置项（变量名、说明、示例值或占位符）补充到 .env.example ；不在代码中硬编码。
-
用法在 .env 中补充：实际连接串、密钥、地址等不在仓库提交，由开发者在本地 .env 中填写；在文档或注释中说明「具体用法/取值请在 .env 中补充」。
- 查阅规范
-
若存在 docs/xx规范.md：优先读取其中的接口规范、分页格式、错误码、DB 命名、权限元组、RequestParser 约定。
-
无则按 references/REFERENCE.md 的通用约定生成。
- 按规范生成代码
生成顺序与要点：
权限策略
在 app/permission/policies.py 中补充资源与操作（如 (role, resource, action) ）；如需同步到 Casbin，提示执行 flask sync-permissions 。
Model
-
继承 db.Model ，显式 tablename （小写下划线）。
-
必须含 id 、created_at 、updated_at ；可选 deleted_at （软删除）。
-
不写业务规则，仅表结构与简单查询封装。
Schema
请求/响应校验（Marshmallow 或 RequestParser）；与接口字段一致。
Service
-
所有业务逻辑、事务、外部调用放在 Service。
-
接收路由传入的普通参数与 user_id 等，不直接依赖 request /g 。
-
可注入 db 做 ORM；列表方法返回 (list, total) 供分页。
路由（Resource）
-
每个模块 *_api.py ：Blueprint + Api，Resource 类。
-
RequestParser：GET 用 location='args' ，POST/PUT/PATCH 用 location='json' ；分页统一 page 、size 。
-
需鉴权接口加 @permission_required(resource, action) 。
-
仅做：解析参数 → 调 Service → 用 AppResponse /AppException 返回；禁止在路由中写 SQL/ORM 或复杂业务。
响应格式
-
成功：AppResponse(data=...) ；列表分页：data 含 page 、size 、list 、total 。
-
业务异常：AppException(code=..., message=...) ；错误码段见 REFERENCE。
测试
-
tests/test_api_.py ：接口测试；tests/test_service_.py ：业务逻辑测试。
-
conftest.py 提供 app、client、db 等 fixture。
-
测试方法命名：test_{场景}_{预期} 。
- 代码规范
-
Python 3.12+；类型注解；PEP 8，建议 Ruff。
-
文件名小写下划线；类名大驼峰；函数/变量小写下划线；常量全大写下划线。
-
导入顺序：标准库 → 第三方 → 本地模块，空行分隔。
-
禁止：硬编码密钥/密码；在路由层直接写 SQL/ORM；绕过 Casbin 做权限判断；信任前端传参做权限。
-
配置与中间件：中间件与外部服务所需配置从环境变量读取；新增配置项写入 .env.example （含变量名与说明），实际取值在 .env 中由开发者补充。
- 交付物清单
单次生成应包含（按需）：
-
app/permission/policies.py 的变更或说明
-
app/models/{resource}.py （若为新资源）
-
app/schemas/{resource}_schema.py （若使用 Schema 校验）
-
app/service/{resource}_service.py 及方法
-
app/routes/{resource}_api.py （Resource + RequestParser + @permission_required）
-
tests/test_api_{resource}.py 和/或 tests/test_service_{resource}.py
-
若涉及中间件或外部服务（Redis、消息队列、外部 API 等），在 .env.example 中补充对应变量与说明，并注明「具体用法/取值请在 .env 中补充」
-
若接口/错误码有约定，同步更新 docs/ 或 context/ 下技术文档
资产与参考
-
规范与示例汇总：references/REFERENCE.md
-
统一响应与分页格式：assets/response-format.json
-
路由与 Service 代码片段：assets/code-snippets.md
-
项目内规范：docs/xx规范.md（若存在，优先遵从）
-
路由层违规检查（可选）：python scripts/check_route_layer.py app/routes/*_api.py