feat: 完善平台总后台模块
This commit is contained in:
@@ -63,7 +63,7 @@ flowchart LR
|
||||
| 基线 | 路径 | 使用要求 |
|
||||
| --- | --- | --- |
|
||||
| 前端标准库 | `sample/front` | 五个 Vue 管理系统从该工程统一前端框架、路由、状态管理、请求封装、权限指令、表格表单、主题、错误处理、国际化与测试规范 |
|
||||
| 后端标准库 | `sample/server` | Go API、Worker、IoT 进程统一沿用配置、日志、错误码、认证、数据库访问、迁移、任务、测试和发布规范 |
|
||||
| 后端标准库 | `sample/server` | Go API、Worker、IoT 进程统一沿用配置、日志、错误码、认证、数据库访问、任务、测试和发布规范 |
|
||||
|
||||
业务项目应通过共享包、模板或上游同步机制复用标准库，禁止将标准库目录复制到每个子项目后自行漂移。标准库升级需要记录版本、影响范围、兼容策略和回滚方式。
|
||||
|
||||
@@ -92,7 +92,6 @@ platforms/
|
||||
api/ # Go HTTP API、BFF、同步领域事务
|
||||
worker/ # Go 异步任务：派单、告警、通知、对账、超时扫描
|
||||
iot/ # Go MQTT 协议适配、设备命令、遥测与回执
|
||||
migrations/ # PostgreSQL 迁移、初始化数据与回滚说明
|
||||
contracts/
|
||||
openapi/ # HTTP API 契约及生成配置
|
||||
asyncapi/ # MQTT/Redis Streams 事件契约与 Schema
|
||||
@@ -150,7 +149,7 @@ platforms/
|
||||
- 所有主表必须包含 `identity` 字段，类型为 UUID V7，并作为该表的主键。UUID V7 由应用服务生成，保证时间有序性；禁止使用数据库自增主键、随机 UUID V4 或将业务编号作为主键。
|
||||
- 引用主表时，外键字段命名为 `<实体名>_identity`，例如 `order_identity`、`service_person_identity`。业务展示编号（订单号、设备编码、站点编码等）应使用独立字段并设置唯一约束，不能替代 `identity`。
|
||||
- 每个主表还应按需要包含 `created_at`、`updated_at`、`created_by_identity`、`updated_by_identity`、`status`、`version` 等审计/并发字段；资金流水、安全事件、审计日志等不可变记录不得被物理删除。
|
||||
- 数据库表、字段、索引、约束和枚举必须编写中文注释；注释说明业务含义、取值/单位、脱敏或留存要求。迁移脚本需同步维护注释，禁止只在设计文档中说明。
|
||||
- 数据库表、字段、索引、约束和枚举必须编写中文注释；注释说明业务含义、取值/单位、脱敏或留存要求。模型注释与接口契约必须同步维护，禁止只在设计文档中说明。
|
||||
|
||||
#### 实体名、文件名、表名、模型名一致性
|
||||
|
||||
@@ -163,25 +162,24 @@ platforms/
|
||||
| Flutter 模型文件/类型 | `org_gas_station.dart` / `OrgGasStation` | `gas_stations.dart`、`GasStationEntity` |
|
||||
| Vue 模型文件/类型 | `org_gas_station.ts` / `OrgGasStation` | `gasStation.ts`、`GasStations` |
|
||||
| OpenAPI/AsyncAPI Schema | `org_gas_station` | `GasStationDto`、`gas_stations` |
|
||||
| 迁移文件 | `<时间戳>_create_org_gas_station.sql` | `<时间戳>_create_gas_stations.sql` |
|
||||
|
||||
- 所有实体一律使用单数：一个 `org_gas_station` 既可表示单个站点模型，也可作为列表返回项的模型名称。列表、批量和分页仅在 API 动词或响应字段表达，例如 `GET /org/gas-station/list`、`items: []`；不改变实体名。
|
||||
- 关联表使用参与实体的单数词根和明确关系词，例如 `org_user_service_relation`、`idn_account_role_relation`，不得使用 `users_roles`、`user_roles` 等复数或含糊名称。
|
||||
- `ord_delivery_track` 是配送任务的状态轨迹主表，`dsp_delivery_track_point` 是其定位点明细表；二者均为独立实体，不得再创建同义的 `delivery_tracks`、`track_points` 等表或模型。定位点通过 `delivery_track_identity` 关联主表。
|
||||
- 钱包事实流水的唯一实体名为 `wal_wallet_ledger`；用户和服务人员的资金归属通过关联对象字段区分，禁止另建同义的 `wal_ledger`、`wallet_ledgers` 或 `service_wallet_ledger`。
|
||||
- 文件目录可以按业务模块组织，但目录名不参与实体命名；模型、迁移、契约、测试文件都必须能从其文件名唯一定位到同名的数据库表和模型。
|
||||
- 新增实体前应先登记规范名称；重命名须同时修改表、模型、文件、契约、迁移和中文注释，并进行全仓引用检查，禁止仅改其中一层。
|
||||
- 文件目录可以按业务模块组织，但目录名不参与实体命名；模型、契约、测试文件都必须能从其文件名唯一定位到同名的数据库表和模型。
|
||||
- 新增实体前应先登记规范名称；重命名须同时修改表、模型、文件、契约和中文注释，并进行全仓引用检查，禁止仅改其中一层。
|
||||
|
||||
### 7.2 代码与模型中文注释规范
|
||||
|
||||
- Go、Flutter 和 Vue 代码中的业务类型、领域模型、枚举、公开接口、复杂规则、状态机、金额计算、权限判断和异步事件必须使用中文注释说明业务意图。
|
||||
- 中文注释应解释“为什么”和业务口径，不重复代码字面含义；对外 API 的字段说明、OpenAPI/AsyncAPI Schema 描述和错误码说明同样必须为中文。
|
||||
- 模型注释应与数据库注释和接口契约保持一致。需求变更导致字段、状态或规则变化时，代码、迁移、模型和契约注释必须在同一变更中更新。
|
||||
- 模型注释应与数据库注释和接口契约保持一致。需求变更导致字段、状态或规则变化时，代码、模型和契约注释必须在同一变更中更新。
|
||||
- 注释中应使用与表名/模型名一致的中文业务名称，例如“气站”对应 `org_gas_station`，不能在同一业务语境混用“站点”“气站信息”“GasStations”等不同实体名。
|
||||
- 禁止以无意义拼音、英文缩写或临时注释代替业务说明；第三方库、协议标准和专有名词可保留其原文，并在首次出现处附中文解释。
|
||||
|
||||
- API 使用 OpenAPI；IoT/事件使用 AsyncAPI 或明确的版本化 Schema；客户端由契约生成类型。
|
||||
- Redis Streams 的生产者、消费者、重试和死信处理均须有监控；任何消费者可安全重复执行，Redis 不可用时由 Outbox 补偿投递。
|
||||
- 所有管理端沿用 `sample/front` 的鉴权、数据权限、错误处理和审计埋点；所有 Go 进程沿用 `sample/server` 的配置、日志、迁移和健康检查规范。
|
||||
- 所有管理端沿用 `sample/front` 的鉴权、数据权限、错误处理和审计埋点；所有 Go 进程沿用 `sample/server` 的配置、日志和健康检查规范。
|
||||
- 单元测试覆盖规则、金额、状态机、权限；集成测试覆盖支付回调、设备回执、派单和并发库存；端到端测试覆盖高风险安全闭环。
|
||||
- CI 必须执行静态检查、依赖漏洞扫描、迁移检查、契约兼容性检查和关键路径自动化测试；CD 必须先执行数据库迁移兼容性检查、健康检查和可回滚发布。
|
||||
- CI 必须执行静态检查、依赖漏洞扫描、契约兼容性检查和关键路径自动化测试；CD 必须执行健康检查和可回滚发布。
|
||||
|
||||
Reference in New Issue
Block a user