# Spec 约定（Spec Conventions）

通用系统管理脚手架 openspec spec 的**组织、粒度、编号、模块划分**唯一权威。
**新会话、新 change 必须遵守，违反即返工。**

> 本文是 spec 相关约定的**唯一事实源**；`CLAUDE.md` / `AGENTS.md` / `openspec/config.yaml`
> 只引用本文、不重复本文内容。改 spec 约定只改这里。

## 1. 事实源

- 本项目是**脚手架**，无外部 PRD；**单一事实源 = `openspec/specs/`**，其中
  `shared/data-model`（字段字典）是字段一致性唯一锚点，`shared/api-contract`（接口契约）
  是前后端联调唯一锚点。
- **功能文档**边实现边补，存 `docs/requirements/`（模块说明/产品方案），仅作说明，不凌驾于 spec。
- 原型仅作视觉参考。

## 2. 技术栈

| 端 | 工程 | 栈 |
|---|---|---|
| 后端 | `sources/sysmgr-nest` | NestJS 12 · TypeScript · Vitest |
| 管理后台前端 | `sources/sysmgr-admin` | Vue 3 · Vite · TypeScript · Pinia · UnoCSS |

- 运行时 Node 22.23.1，包管理 pnpm 12.10.1（以 `engines` / `packageManager` / `.nvmrc` 为准）。
- 前后端工程以 **Git submodule** 形式纳入主仓管理。

## 3. spec 三层结构

```
specs/
├── shared/                    ← 跨前后端公共契约（粘合剂）
│   ├── platform/              全局规范（设计令牌/文案/URL 契约/隐私红线）
│   ├── data-model/            数据模型（实体 + 枚举 + 状态机 = 字段字典）
│   └── api-contract/          API 契约（endpoint + 请求/响应 shape）
├── frontend/                  ← 前端 spec（Mock 独立验收）
│   └── AD/                    管理后台（当前唯一前端端）
└── backend/                   ← 后端 spec（API 独立验收）
    └── <域>/                  按 §9 域码清单
```

## 4. 粒度规则

- **前端**：细到「功能块」级。一个 spec = 一个可独立验收的功能单元。每页保留一个薄
  「页面级 spec」作容器（定位/导航/布局/流转）。
  - 判断标准：这个块能不能**独立验收、独立打勾**。能就拆，不能就合；简单页不强拆。
  - 同一页面 PC 与移动可合并为同一 spec（布局差异写在 spec 内部）。
- **后端**：按实体/域（见 §9 域码清单）。
- **共享**：platform / data-model / api-contract 三个。

## 5. 编号规则

格式：`<层>-<端/域>-<页面/实体>[.<功能块>]`

| 段 | 取值 |
|---|---|
| 层 | `SH` shared / `FE` frontend / `BE` backend |
| 端(FE) | `AD` 管理后台（当前唯一；将来用户端为 `FE`） |
| 域(BE) | 见 §9 域码清单 |
| 域(SH) | `PLT` platform / `DM` data-model / `AC` api-contract |
| 页面(FE) | 功能页英文 kebab-case（如 `user`、`role`、`resource`） |
| 功能块 | `.01` `.02` …（页面级 spec 无后缀） |

**顺序（读取即构建顺序）**：
1. 层序：`SH` → `FE` → `BE`
2. FE 内端序：`AD`（将来加 `FE` 用户端时排 `AD` 之后）
3. 域序按 §9 核心域顺序；块序 `.01` → `.02` …

**目录命名**：功能块目录带序号，如 `specs/frontend/AD/<页面>/03-<功能块>/`。

**例子**：`SH-DM`（数据模型，最前）· `FE-AD-<页面>.<块>`（前端功能块）· `BE-<域码>`（后端域）

## 6. 铁律

1. **单一事实源 = `openspec/specs/`**（无 PRD 权威）；冲突以 `shared/data-model` / `shared/api-contract` 为准。
2. **数据库 schema 是字段一致性的唯一锚点**：`data-model` 字段字典先行，前后端引用同一字段名，禁止各自命名。
3. **前端先行 + Mock**：前端对 Mock 验收，后端对 `SH-AC` 契约实现。
4. **字段/接口变更先改 `shared/`，再改对应 spec。**
5. **多租户**：业务实体一律带 `tenant_id`，查询统一按租户过滤（见 §9.2-1）。
6. **资源表统一授权**：菜单/按钮/接口统一为「资源」表，RBAC 授权锚点（见 §9.2-2）。
7. **数据权限**：行级可见性由 `ROLE.data_scope` 控制（见 §9.2-3）。

## 7. 构建顺序（Phase）

- **Phase 0 地基**：`sources/` 脚手架 + `shared/` 三层 spec（含 DB 设计）+ Mock
- **Phase 1 前端**：管理后台按 Mock 驱动实现
- **Phase 2 后端**：按 `SH-AC` 契约实现
- **Phase 3 联调与上线**：切真实 API → 端到端验证 → 上线

## 8. spec 文档结构（四段式，每个 spec 必含）

**每个 spec 是独立开发单元**：可独立开发、独立测试、独立交付。文档必须含以下四段：

### ① 模块边界（Scope）
- 包含什么功能 / **不包含什么功能**（明确列出「非目标」，防范围蔓延）
- 依赖声明：本 spec 引用哪些 `SH-*`（字段名 → data-model、接口 → api-contract、全局规则 → platform）

### ② 核心场景（Scenarios）
- 用 **WHEN / THEN / AND** 格式，覆盖**正常路径 + 异常路径**
- 与 openspec 原生 `#### Scenario:` 格式对齐

### ③ 数据结构（Data）
按层适配：

| 层 | 数据结构内容 |
|---|---|
| 前端 FE | 组件 Props（props 名 / 类型 / 必填 / 默认值 / 约束）+ 页面状态 |
| 后端 BE | 实体字段 + DTO（请求/响应字段、类型、校验约束）+ 状态机 |
| 共享 SH | data-model = 字段字典（实体/枚举/状态机）；api-contract = 接口 shape |

### ④ 验收标准（Acceptance）
- **ACCEPTANCE Checklist，可勾选**（`- [ ]` 形式）
- 每条对应一个可验证行为，锚定 `SH-AC` 契约或功能点编号

## 9. 模块清单与设计决策

### 9.1 域码清单（后端 spec 按此拆分）

| 层 | 域码 | 模块 | 说明 |
|---|---|---|---|
| 核心 | `TENANT` | 租户 | 仅 `tenant_id` 隔离，不做计费/SaaS 复杂化 |
| 核心 | `AUTH` | 认证 | 登录/登出、token、验证码、密码策略（横切：落 `SH-AC` + 守卫） |
| 核心 | `USER` | 用户 | CRUD、启停/锁定、密码重置、头像、关联角色/部门 |
| 核心 | `ROLE` | 角色 | 授权（资源）+ 数据权限范围 |
| 核心 | `RES` | 资源 | 菜单/按钮/接口统一资源表，RBAC 授权锚点 |
| 核心 | `ORG` | 组织 | 部门树、层级、负责人 |
| 核心 | `DICT` | 字典 | 类型 + 项，运行时 lookup |
| 建议 | `CONFIG` | 参数配置 | 系统键值参数 |
| 建议 | `AUDIT` | 操作日志 | 审计：谁/何时/对什么/做了什么 |
| 建议 | `LOGIN` | 登录日志 | 登录成功/失败、IP、UA |
| 建议 | `SESSION` | 在线会话 | 活跃会话、强退 |
| 扩展 | `POST` | 岗位 | 比「角色」更细的职位维度 |
| 扩展 | `NOTICE` | 通知公告 | 站内公告 |
| 扩展 | `JOB` | 定时任务 | 任务调度 |
| 扩展 | `FILE` | 文件存储 | 附件/OSS |
| 扩展 | `MSG` | 消息通知 | 邮件/短信/推送 |

### 9.2 三大设计决策

1. **多租户**：单租户式简单实现——所有业务实体带 `tenant_id`，后端统一租户过滤切面；
   登录时按账号/租户域识别当前租户。**不做**按量付费、套餐、租户配额。
2. **资源表（RES）**：菜单与权限合一为「资源」表，`type ∈ {菜单 MENU, 按钮 BUTTON, 接口 API}`；
   「目录」不设独立类型，由「菜单节点是否拥有菜单子节点」推导。
   - 后端鉴权三级：公开接口无需 token → 未登记接口仅校验登录 → 登记为「接口」资源的接口校验 token + 权限标识。
   - **约定**：写操作/敏感查询一律登记为「接口」资源，仅真正公开的留白。
3. **数据权限**：`ROLE.data_scope ∈ {全部 / 本部门 / 本部门及以下 / 本人 / 自定义}`；
   自定义时经 `role_org`（角色-部门）关联表；后端列表查询统一按可见部门过滤。