# 架构与设计原则

本规则用于指导架构决策、接口设计、数据库变更和技术选型。

## 核心原则

- 职责分明的模块架构优先于优雅代码，优雅代码优先于功能堆砌。
- 优先评估模块边界、数据流向、状态机、权限边界、错误边界和扩展点。
- 出现复杂度扩散、参数爆炸、数据流回溯、状态同步困难时，应优先建议调整模块关系或架构，而不是继续局部补丁。
- 默认偏好 Functional Programming 和可读的 DSL 化组织方式；除非项目已明确是面向对象架构。
- 新技术、新依赖、新服务引入前，说明理由、收益、成本、风险和替代方案，并等待确认。
- 接口设计优先明确契约：输入、输出、错误结构、状态码、幂等性、权限、兼容性。

## ADR 架构决策记录

- 重大技术决策必须写入 ADR，避免决策只存在于聊天或临时说明中。
- ADR 路径：`pmdocs/adr/YYYY-MM-DD-序号-主题.md`。
- ADR 触发条件：
  - 前端技术栈、后端技术栈、数据库或运行时选择。
  - 认证授权、权限模型、状态管理、路由结构或部署方式选择。
  - 重大模块边界调整、数据流调整、状态机调整。
  - 引入会影响长期维护成本的新依赖、新服务或基础设施。
  - 关键性能、安全、可扩展性方案选择。
- ADR 必须包含：背景、决策选项、最终选择、选择理由、影响后果、风险和回滚思路。
- ADR 只记录重要决策；普通实现细节不要过度记录。

### ADR 模板示例

```markdown
# ADR-001：选择 xxx

## 背景
为什么需要决策

## 选项
- A：优点 / 缺点
- B：优点 / 缺点

## 决策
选择哪个方案

## 后果
带来的收益、成本、风险
```

## API 变更约束

- API 变更必须明确：请求结构、响应结构、错误码、权限要求、幂等性、兼容性和废弃策略。
- API 变更必须同步到 `pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 或对应变更文档；如果项目已有 OpenAPI / GraphQL Schema / RPC IDL，也必须同步。
- 涉及权限码的 API 变更，必须同步权限码表、后端校验、前端权限门禁和测试用例。
- 破坏性 API 变更必须进入需求变更流程，并在 7 维度影响评估表中明确处理动作和状态。

### API 变更检查清单

- [ ] 请求结构（字段、类型、必填、默认值）
- [ ] 响应结构（字段、类型、状态码、错误码）
- [ ] 权限要求（角色、权限码、访问边界）
- [ ] 幂等性（POST / PUT / DELETE 是否幂等）
- [ ] 兼容性（新增字段 / 废弃字段 / 破坏性变更）
- [ ] 文档同步（PRD / 任务 / OpenAPI / GraphQL Schema）
- [ ] 测试覆盖（单元测试 / 集成测试 / 权限测试）

## 数据库变更约束

- 数据库变更必须明确：表、字段、索引、约束、迁移脚本、回滚脚本、seed 是否调整、历史数据兼容策略。
- 数据库变更必须评估查询性能、索引影响、默认值、空值、唯一约束和线上数据迁移风险。
- 涉及权限码的 DB 变更，必须同步权限码表、后端校验、前端权限门禁和测试用例。
- 破坏性 DB 变更必须进入需求变更流程，并在 7 维度影响评估表中明确处理动作和状态。

### 实体唯一代码规范

- 业务主体实体（用户、组织、部门、商品、订单、项目）和配置数据（角色、字典项、模板）必须有唯一业务代码。
- 唯一代码格式：`{前缀}_{业务含义}` 或 `{模块}_{编号}`，例如：
  - 用户：`USER_admin001`、`USER_john_doe`
  - 商品：`PROD_SKU12345`
  - 订单：`ORDER_20260705001`
  - 权限：`PERM_USER_CREATE`
- 唯一代码约束：
  - 必须有唯一索引
  - 一旦创建不可修改
  - 优先可读性，而非简洁性
- 其他表引用时，优先使用唯一业务代码作为外键，而不是自增 ID。
- 好处：数据可读、跨系统可追溯、数据库导入导出友好、便于调试。
- 权衡：查询性能可能略低于整数 ID，必须在唯一代码字段上建立索引。
- 不需要唯一代码的场景：纯关联表、日志、审计、历史记录、一次性临时数据、只在父实体内部使用的子表。

### 数据库变更检查清单

- [ ] 表、字段、索引、约束变化
- [ ] 迁移脚本（migration）
- [ ] 回滚脚本（rollback）
- [ ] seed 数据是否调整
- [ ] 历史数据兼容策略（默认值 / 数据填充 / 迁移脚本）
- [ ] 查询性能影响（索引 / 全表扫描 / 锁表风险）
- [ ] 空值、唯一约束、外键约束影响
- [ ] 线上数据迁移风险（停机 / 灰度 / 双写）
- [ ] 测试覆盖（单元测试 / 集成测试 / 迁移测试）

## 代码质量

- 遵循项目既有代码风格。
- 保持单一职责、高内聚、低耦合。
- 避免重复代码，避免过度抽象。
- 命名必须语义清晰。
- 注释只解释代码无法自解释的意图、约束和权衡，不写表面行为注释。

## 错误处理

- 不忽略错误。
- 用户可见错误要友好，内部错误要可诊断。
- 对关键边界做输入校验、权限校验和异常处理。
- 错误处理路径应有测试覆盖。

## 测试与验证

- 功能代码和测试代码尽量同步完成。
- 公共函数、核心业务规则、权限判断、错误处理和边界条件应有测试。
- 测试优先使用 Arrange-Act-Assert 或 Given-When-Then。
- 使用 Mock / Stub 隔离外部依赖。
- 测试应快速稳定，避免不必要的 sleep 或长等待。
- 完成实质性编辑后，检查 linter 或诊断；若引入错误，应修复。

## 安全

- 不在代码、规则、提交信息或文档中硬编码密钥、令牌、密码。
- 敏感信息应使用环境变量、密钥管理器或用户指定的安全存储方式。
- 验证所有用户输入，防止注入、XSS、越权访问等常见问题。
- 遵循最小权限原则。