# 公司统一配置

> 第一层级配置（权重: 25），作用于全公司所有 AI 系统。定义公司级安全红线、技术选型原则、编码底线和沟通协作规范，是所有项目必须遵守的最低标准。
>
> **设计原则**：安全红线为只读不可覆盖；技术选型和编码底线可被 L2/L3 覆盖。语言/框架相关的详细规范由 `language/` 文件夹下按语言分类的子目录（java/、python/、vue/）负责。

---

## 一、安全红线（不可违反，只读规则）

> ⚠️ 以下规则为**强制性的、不可被任何层级覆盖的安全底线**

### 1.1 敏感信息管理
- **绝对禁止**在代码中硬编码任何密钥、密码、Token、API Key、私钥、证书
- **绝对禁止**将敏感信息提交到版本控制系统（包括历史提交）
- **绝对禁止**在日志/控制台输出中打印用户密码、Token、身份证号、银行卡号等敏感数据
- 敏感配置必须通过环境变量、密钥管理服务（如 Vault、KMS、AWS Secrets Manager）或安全的配置中心注入
- 代码中只引用环境变量名或配置键名，严禁明文存储

### 1.2 代码安全（跨语言通用）
| 风险类别 | 禁止行为 | 正确做法 |
|---|---|---|
| SQL 注入 | 拼接 SQL 字符串 | 使用参数化查询或 ORM |
| 命令注入 | 将用户输入拼接到 shell / system / exec 调用 | 使用参数化接口或白名单校验 |
| XSS | 直接渲染未转义的用户输入到 HTML | 对所有外部输入进行转义/编码 |
| 路径遍历 | 使用用户输入直接拼接文件路径 | 校验并规范化路径，限制访问目录 |
| 反序列化攻击 | 反序列化不受信的数据 | 使用安全的序列化格式或白名单类 |
| SSRF | 服务端发起用户可控的请求 | 校验和限制目标地址范围 |

### 1.3 数据与隐私保护
- 用户个人信息的收集和处理必须符合**最小必要原则**
- 涉及用户数据的接口必须有权限校验，不得存在未授权访问路径
- 生产环境日志中不得记录完整的用户身份信息（需脱敏处理）
- 必须遵守适用的数据保护法规（如 GDPR、个人信息保护法等）

### 1.4 依赖安全
- **禁止使用已停止维护超过 2 年的生产依赖**（存在安全风险且无补丁）
- 生产依赖必须在对应语言的包安全审计工具中 **无 high/critical 漏洞**方可上线
  - JavaScript/TypeScript: `npm audit` / `pnpm audit`
  - Python: `pip audit` / `safety`
  - Java: OWASP Dependency-Check / Snyk
  - Go: `govulncheck`
  - Rust: `cargo audit`
- 发现漏洞后必须在 **7 个工作日内**修复或升级，无法修复的需上报安全团队并记录原因

---

## 二、技术选型原则与技术栈偏好

> 本节定义了技术选型的**决策原则**和**默认选择倾向**。决策原则为硬性框架，技术栈偏好在 L2/L3 有明确约定时以 L2/L3 为准。

### 2.1 技术选型决策框架

选择任何技术栈时，必须回答以下问题并通过评审：

#### 必须满足的硬性条件（任一不通过则不可选用）
1. **活跃维护**：项目在过去 6 个月内有持续 commit 和 issue 响应
2. **社区规模**：有足够的使用者基数，非单人维护的"玩具项目"
3. **许可证合规**：许可证类型符合公司法务要求
4. **安全记录**：无已知的高危安全漏洞未修复
5. **版本策略**：有明确的版本发布计划和 breaking change 处理机制

#### 评分维度（综合评估）
| 维度 | 权重 | 说明 |
|---|---|---|
| 成熟度与稳定性 | 高 | 生产验证程度、API 稳定性 |
| 性能表现 | 高 | 是否满足业务场景的性能要求 |
| 团队熟悉度 | 中 | 团队学习成本和上手速度 |
| 生态完善度 | 中 | 文档质量、第三方集成、社区支持 |
| 可维护性 | 中 | 代码可读性、架构清晰度 |

### 2.2 全局禁用原则（跨语言）

| 类别 | 禁用原则 | 原因 |
|---|---|---|
| 语言特性 | 已被官方标记为 deprecated / removed 的语法/API | 兼容性、安全性、维护性 |
| 浏览器兼容 | IE-only hack 或针对已停止浏览器的特殊处理 | 无实际意义 |
| 同步阻塞 | 在支持异步的语言中强制使用同步阻塞 I/O 的模式 | 性能与资源利用率 |
| 已终止维护 | 官方宣布 EOL 且无社区接管的依赖/框架 | 安全风险 |

### 2.3 前端技术栈偏好

| 类别 | 首选 | 备选 | 说明 |
|---|---|---|---|
| UI 框架 | React 18+ | Vue 3.3+ / Svelte | 按项目需求二选一 |
| 类型系统 | TypeScript（strict 模式） | — | 新项目强制启用 |
| CSS 方案 | Tailwind CSS | CSS Modules | 优先原子化 CSS |
| 构建工具 | Vite | 已有项目沿用现有工具 | 新项目优先 Vite |
| 状态管理 | Zustand / TanStack Query | Redux Toolkit（大型项目） | 轻量优先 |
| 包管理器 | pnpm | npm / yarn | 统一使用 pnpm |

### 2.4 后端技术栈偏好

| 类别 | 首选 | 备选 | 说明 |
|---|---|---|---|
| 运行时语言 | Java | Go / Node.js / Python | 公司后端主流语言为 Java |
| Web 框架（Java） | Spring Boot / Spring Cloud | Quarkus / Micronaut | 优先使用成熟 Java 生态 |
| Web 框架（Node） | Fastify / Hono | Express（已有项目） | 新项目优先现代框架 |
| Web 框架（Python） | FastAPI | Flask / Django | 异步优先 |
| ORM | MyBatis-Plus / JPA（Java） | GORM（Go） / Prisma（Node） / SQLAlchemy（Py） | 按语言对应选择 |
| 数据库 | PostgreSQL | MySQL / SQLite | 关系型数据库首选 PG |

### 2.5 DevOps & 工具链偏好

| 类别 | 首选 | 说明 |
|---|---|---|
| 容器化 | Docker + Docker Compose | 本地开发和部署统一 |
| CI/CD | GitHub Actions | 优先使用 |
| 代码质量（JS/TS） | ESLint + Prettier | 统一代码风格 |
| 代码质量（Go） | golangci-lint | 官方推荐 lint 聚合器 |
| 代码质量（Python） | ruff | 比 flake8+black 更快更全 |
| 测试框架 | Vitest（前端） / go test（Go） / pytest（Python） | 按语言对应 |

---

## 三、编码质量底线（跨语言通用）

### 命名与可读性
1. **命名自解释**：变量、函数、类、模块名必须能表达其用途，禁止无意义命名（如 `a`, `tmp`, `data`, `foo`, `x`）
2. **遵循语言惯例**：使用该语言社区公认的命名风格（如 camelCase、snake_case、PascalCase）
3. **避免缩写谜题**：除非是行业通用缩写（如 URL、ID、HTTP），否则不使用难以理解的缩写

### 函数与方法
4. **单一职责**：单个函数/方法只做一件事，逻辑复杂时拆分
5. **参数控制**：函数参数数量建议不超过 5 个，超出时考虑使用对象/结构体/配置项封装
6. **尽早返回（Early Return）**：优先使用 early return 减少嵌套层级，避免"箭头型"代码
7. **纯函数优先**：无副作用函数优先，明确标识有副作用的函数

### 错误处理
8. **禁止静默吞错**：不允许空 catch / 忽略错误返回值，必须有明确的错误处理逻辑或向上传播
9. **错误信息有意义**：错误消息应包含足够的上下文帮助定位问题，禁止抛出空错误或通用错误字符串
10. **资源释放**：打开的资源必须确保释放，推荐使用语言提供的 RAII / try-finally / defer / using 等机制

### 代码组织
11. **DRY 原则**：相同逻辑出现 3 次以上必须抽取为公共函数/模块/组件
12. **文件长度控制**：单文件不超过 500 行（配置文件除外），超出则按职责拆分
13. **模块边界清晰**：模块/包之间依赖方向应单向，避免循环依赖

### 个人加严偏好（可被 L3 覆盖）
| 规则 | 底线 | 偏好（更严格） | 说明 |
|---|---|---|---|
| 单函数长度 | ≤ 80 行 | **≤ 50 行** | 个人偏好更短的函数 |
| 单文件长度 | ≤ 500 行 | **≤ 300 行** | 个人偏好更小的模块 |
| 提交信息 body | 可选 | **建议必填** | 复杂变更建议补充说明 |

---

## 四、Git 规范与 Code Review

### 4.1 提交信息格式
`<type>(<scope>): <subject>`
- type: `feat` / `fix` / `refactor` / `docs` / `style` / `perf` / `test` / `chore` / `ci` / `revert`
- scope: 可选，影响范围（如模块名、功能名）
- subject: 中文或英文，简洁描述做了什么（不是为什么）
- body: 可选，详细说明变更原因和影响

### 4.2 禁止提交的内容
- `node_modules`、`__pycache__`、`.class`、`target/`、`dist/`、`build/` 等依赖/编译产物
- `.env`、`.env.local`、`*.key`、`*.pem`、`credentials.*` 等敏感配置
- IDE 配置文件（`.idea/`、`.vscode/`）中的本地设置
- 操作系统生成的文件（`.DS_Store`、`Thumbs.db`）

### 4.3 分支命名规范
- 功能开发：`feature/<功能简述>` 或 `feature/<ticket-id>-<简述>`
- Bug 修复：`fix/<问题描述>` 或 `fix/<ticket-id>-<简述>`
- 紧急修复：`hotfix/<问题描述>`
- 版本发布：`release/<版本号>`

### 4.4 Code Review 标准
1. 每个 PR/MR 必须**至少 1 人 Review 通过**后方可合并
2. PR 描述中必须包含：**改了什么**、**为什么改**、**影响范围**
3. **高风险变更**必须由资深开发者 Review（数据库 Schema、权限/认证、支付/财务、安全配置）
4. Review 意见必须**逐条处理**

---

## 五、协作、沟通与 AI 行为

### 5.1 沟通与响应风格
- 默认使用**中文**回复，技术术语首次出现时保留英文原文
- **结论先行**：先给结论/方案，再解释原因
- **适度简洁**：避免冗长铺垫，但关键决策要说明理由
- **结构化输出**：多步骤任务用有序列表，并列项用无序列表
- 遇到歧义或多种可行方案时，**主动用 AskUserQuestion 询问**
- 涉及破坏性操作前必须确认

### 5.2 代码注释规范

> 统一使用 **JSDoc** 风格文档注释 + **#region** 代码分组，跨语言通用。各语言细节差异由 `language/` 下各语言子目录覆盖。

#### 5.2.1 通用原则

- **业务逻辑复杂处**必须添加注释解释"**为什么**"这样写
- **公共 API / 导出函数 / 导出类型**必须有文档注释
- **TODO / FIXME / HACK** 必须标注责任人和预期解决时间
- 注释与代码保持同步

#### 5.2.2 注释格式模板

**① 类型/接口注释（interface / type / class）**

```typescript
// #region {RegionName}

/**
 * {类型简述}
 *
 * {详细描述（可选，多行时每行前加 *）}
 */
interface {TypeName} {
  /**
   * {属性简述}
   * @default {默认值}       ← 有默认值时必填
   */
  propertyName?: string;

  /**
   * {属性简述}
   */
  requiredProperty: number;
}

// #endregion
```

**② 函数/方法注释**

```typescript
// #region {RegionName}

/**
 * {动词开头简述}（如：查询用户列表 / 新增订单 / 删除配置）
 * @param {paramName} {参数说明}
 * @returns {返回值说明}      ← 有返回值时标注，void 省略
 * @throws {Error} {异常说明}  ← 可能抛异常时标注
 */
export function doSomething(params: Params): Result {
  // ...
}

// #endregion
```

**③ 枚举注释**

```typescript
// #region {RegionName}

/**
 * {枚举简述}
 */
enum StatusEnum {
  /** 启用 */
  ENABLED = 1,
  /** 停用 */
  DISABLED = 0,
}

// #endregion
```

**④ 配置项/常量注释**

```typescript
// #region {RegionName}

/**
 * {配置项简述}
 * @default {默认值}
 */
const CONFIG_ITEM = 'value';

// #endregion
```

#### 5.2.3 #region 分组规则

| 规则 | 说明 |
|---|---|
| 必须使用 | 一个文件内存在 **2 个及以上** 逻辑分组时使用 |
| 可省略 | 整个文件只做一件事、代码量少时无需 region |
| 命名格式 | PascalCase，体现业务含义（如 `ArchiverPluginOptions`、`UserAPI`、`TableColumns`） |
| 嵌套 | **禁止嵌套** region，保持扁平结构 |
| 对称 | 每个 `#region` 必须有对应的 `#endregion` |
| 位置 | `#region` 紧跟在注释块上方，`#endregion` 独占一行 |

#### 5.2.4 JSDoc 标签使用规则

| 标签 | 使用场景 | 是否必填 |
|---|---|---|
| 描述（首行） | 所有公共导出 | **必填** |
| `@param` | 函数/方法每个参数 | **必填** |
| `@returns` | 有返回值的函数 | **必填**（void 省略） |
| `@default` | 属性/配置项有默认值时 | 有默认值时**必填** |
| `@throws` | 可能抛出异常时 | 可能抛异常时必填 |
| `@example` | 用法不直观时 | 可选 |
| `@deprecated` | 已废弃的 API | 废弃时**必填** |
| `@see` | 引用其他模块/文档时 | 可选 |

#### 5.2.5 禁止事项

- **禁止**使用单行注释 `//` 描述公共 API 的用途（应使用 JSDoc）
- **禁止** JSDoc 描述与代码行为不一致（注释是契约，必须同步更新）
- **禁止**无意义的注释（如 `// 设置name` → 应写 `// 设置用户显示名称，用于前端欢迎语`）
- **禁止**在 `#region` 命名中使用技术术语而非业务含义（如 ❌ `Region1` → ✅ `UserAPI`）

#### 5.2.6 各语言适配说明

| 语言 | #region 语法 | 文档注释语法 | 备注 |
|---|---|---|---|
| TypeScript / JavaScript | `// #region Name` / `// #endregion` | `/** ... */` | 原生支持 |
| Java | `// region Name` / `// endregion`（IDE 支持） | `/** ... */` | Javadoc 格式 |
| Python | `# region Name` / `# endregion` | `""" ... """` | docstring 格式 |
| Go | 不使用 region | `// ...`（godoc 格式） | Go 风格不同，按语言文件约定 |
| C# | `#region Name` / `#endregion` | `/// <summary>...` | XML 文档注释 |
| Vue (`<script>`) | `// #region Name` / `// #endregion` | `/** ... */` | 与 TS 一致 |

### 5.3 AI 行为偏好
1. **先理解再动手**：接到任务后先用 SearchCodebase / Grep 了解现有代码结构，不凭空假设
2. **最小改动原则**：满足需求的前提下改动范围尽可能小
3. **渐进式实现**：复杂功能先跑通主流程，再逐步完善细节
4. **跟随项目惯例**：即使个人偏好与项目现有风格不同，以项目为准
5. **主动提示风险**：发现潜在问题（性能、安全、兼容性）时主动提醒
6. 不编造不存在的 API 或库用法，不确定时明确说明
7. 不忽略用户明确的约束条件

---

## 六、前端通用规范（跨框架 / 跨版本）

> 本节定义所有前端项目（Vue 2 / Vue 3 / Vben v2 / Vben 5.0）共享的规范。框架/版本特定的语法、组件和代码模板由各语言文件负责。
>
> **原则**：公共规则只在此处定义一次，语言文件通过引用避免重复。语言文件可覆盖本节规则，但必须明确标注。

### 6.1 格式规范

| 规则 | 统一标准 |
|---|---|
| 缩进 | 2-space |
| 引号 | 单引号 |
| 分号 | 无分号 |
| Vue SFC 顺序 | `template` → `script` → `style scoped` |
| CSS 作用域 | 使用 `scoped`，避免全局污染 |
| 字符串拼接 | 模板字符串优先，避免 `+` 拼接 |

### 6.2 组件命名规范

| 类型 | 规则 | 示例 |
|---|---|---|
| 组件 `name` 属性 | PascalCase | `ContactDrawer`, `AccountModal` |
| 组件文件名 | PascalCase | `ContactDrawer.vue`, `AccountModal.vue` |
| 组件注册 | PascalCase | `components: { BasicTable, ContactDrawer }` |
| 目录名 | kebab-case | `alarm/contacts/` |
| 页面入口 | 固定 `index.vue` | `index.vue` |

### 6.3 API 方法命名规范

| 操作类型 | 命名模式 | 示例 |
|---|---|---|
| 列表查询 | `get{Feature}List` / `list{Feature}` | `getContactList`, `listEntity` |
| 详情查询 | `get{Feature}` | `getContact`, `getEntity` |
| 新增 | `add{Feature}` / `create{Feature}` | `addContact`, `createUser` |
| 更新 | `update{Feature}` | `updateContact`, `updateEntity` |
| 删除 | `delete{Feature}` / `del{Feature}` | `deleteContact`, `delEntity` |
| 保存或编辑 | `saveOrEdit{Feature}` | `saveOrEditContact` |
| 状态更新 | `set{Feature}Status` | `setContactStatus` |
| 导出 | `export{Feature}` | `exportEntity` |

> **版本差异**：Vue2 (Tofly) 使用 `listX` / `delX` 风格，Vben2/Vue3 使用 `getXList` / `deleteX` 风格，以各语言文件为准。

### 6.4 API 层组织原则

**核心原则：一个功能一个文件，按功能维度拆分，不按 HTTP 方法或角色拆分。**

- 以业务功能为最小单元，一个功能 = 一个文件
- 同一功能的增删改查方法放在同一个文件中
- 禁止将同一功能的方法拆散到多个文件（如按 CRUD 拆分）
- 禁止将不相关功能的方法混在一个文件中
- 公共接口放在公共文件中（由用户指定哪些是公共的）
- 原则上每个接口只写一次
- API 函数必须使用 JSDoc 注释（参见 §5.2 注释规范）

**各框架 API 目录结构**：

| 框架 | API 目录 | 路径别名 |
|---|---|---|
| Vue 2 (Tofly) | `src/api/<module>/<entity>.js` | `@/` |
| Vben v2 | `src/api/{module}/{feature}.ts` + `model/{feature}Model.ts` | `/@/` |
| Vue 3 (Vben 5.0) | `src/api/` 按功能模块组织 | `#/` |
| Vben v3 (成堪数智) | `src/api/{module}.ts` + `common.ts` 公共接口 | `#/` |

> 各框架 API 目录的详细结构和模板由语言文件定义。

### 6.5 权限控制模式

所有前端项目必须实现操作级权限控制，具体实现方式由各框架决定：

| 框架 | 实现方式 | 示例 |
|---|---|---|
| Vue 2 (Tofly) | `v-hasPermi` 指令 | `v-hasPermi="['module:resource:action']"` |
| Vben v2 | `Authority` 组件 + `auth` 属性 | `<Authority value="api:yt:module:post">` / `auth: 'api:yt:module:delete'` |
| Vue 3 (Vben 5.0) | `AccessControl` 组件 + `v-access` 指令 + `useAccess` hook | `<AccessControl :codes="['AC_100100']">` / `v-access:code="'AC_100100'"` |
| Vben v3 (成堪数智) | `v-auth` 指令 + `auth` 属性 + `directives` | `v-auth="'@ums:module:action'"` / `auth: '@ums:module:add'` / `directives: [{ name: 'auth', value: '@ums:module:edit' }]` |

**权限值命名约定**：`{前缀}:{模块}:{操作}:{细化}`

### 6.6 CRUD 页面架构模式

所有前端项目的 CRUD 页面遵循统一的结构模式：

**标准结构**：搜索表单 + 工具栏操作 + 数据表格 + 分页 + 新增/编辑表单

**标准状态**：
- 加载状态（loading）
- 选中状态（ids / single / multiple）
- 分页信息（pageNum/page + pageSize + total）
- 表单可见性（open / visible）
- 表单标题（title）

**标准方法**：
- 列表查询（getList / reload）
- 条件搜索（handleQuery）
- 重置搜索（resetQuery / resetFields）
- 新增（handleCreate / handleAdd）
- 编辑（handleEdit / handleUpdate）
- 删除（handleDelete）
- 批量删除（handleBatchDelete / handleDeleteOrBatchDelete）
- 表单提交（handleSubmit / submitForm）

**标准交互**：
- 删除/批量删除前二次确认
- 操作成功后刷新列表
- 操作结果通过消息提示反馈

> 各框架的具体组件、Hook 和代码模板由语言文件定义。

### 6.7 编辑前 Lint 流程

1. 对变更区域运行 lint 命令（各框架命令不同，见语言文件）
2. 运行类型检查（TypeScript 项目）
3. 修复新引入的 lint / 类型错误
4. 保持变更范围；不重新格式化无关文件

---

## 七、项目目录与命名规范

> 基于 Vue、微服务 Java、移动等多端开发通用目录结构，融合公司行业（供水、燃气、排水、水利等）和项目分类命名约定。适用于前端、后端、移动端源代码目录结构构建。

### 7.1 总则

| 序号 | 原则 | 说明 |
|---|---|---|
| 1 | **语义化** | 命名清晰反映目录内容或职责 |
| 2 | **小写 + 短横线** | 统一使用小写字母、数字和短横线（-）作为单词分隔符（如 `user-service`、`api-gateway`） |
| 3 | **避免缩写** | 除非是业界通用缩写（如 `api`、`ui`、`sdk`），否则不使用歧义缩写 |
| 4 | **根目录简洁** | 根目录下仅放置一级功能模块、文档、脚本和公共配置 |
| 5 | **物理隔离** | 产品核心代码与客户定制代码分目录（或分 Git 仓库） |
| 6 | **配置外置** | 实施场景下将配置文件、环境变量、脚本独立于产品源码 |
| 7 | **保留扩展点** | 产品自研预留扩展目录（如 `extensions/`、`customer-overrides/`），项目实施通过覆盖或组合方式引入 |

### 7.2 根目录结构

#### 标准根目录

```
project-root/
├── backend/               # 后端微服务相关代码
├── frontend/              # 前端应用代码
├── mobile/                # 移动应用源代码
├── shared/                # 跨模块共享代码、类型定义、协议等
├── docs/                  # 项目文档
├── scripts/               # 构建、部署、代码生成等脚本
├── compose/               # 本地开发
│   ├── docker-compose.yml
│   └── docker-compose.dev.yml
├── deployment/             # 生产部署
│   ├── k8s/               # Kubernetes（生产）
│   └── helm/              # Helm Charts（如需要）
├── .gitignore
├── README.md
└── LICENSE
```

#### 根目录命名规则

| 项目类型 | 命名格式 | 说明 |
|---|---|---|
| **项目导向类** | `pcs-{行业标识}-{项目自定义}` | pcs = Project-Customized Software（项目类定制化软件） |
| **自研类** | `sds-{行业标识}-{产品自定义}` | sds = Self-Developed System |

**行业标识表**：

| 序号 | 行业 | 行业标识 | 全称 |
|---|---|---|---|
| 1 | 燃气 | `gas` | Gas System |
| 2 | 供水 | `wss` | Water Supply System |
| 3 | 排水 | `dns` | Drainage Network System |
| 4 | 综合管网 | `uut` | Underground Utility Tunnel |
| 5 | 水利 | `wrs` | Water Resources System |

**示例**：`pcs-gas-jjk`（燃气-江家口项目）、`sds-wss-smartmeter`（供水-智能水表产品）

### 7.3 后端目录结构规范

#### 微服务模块命名

每个微服务独立为一个 Maven/Gradle 子模块，放置于 `backend/` 目录下。模块名采用短横线分隔的全小写形式，与 `spring.application.name` 保持一致。

**格式**：`{业务域}-{服务角色}` 或 `{业务域}-{子域}`

**示例**：
- `user-service` — 用户服务
- `order-service` — 订单服务
- `api-gateway` — API 网关
- `config-server` — 配置中心
- `auth-server` — 认证授权服务

#### 模块内部标准结构

```
user-service/
├─ src/
│  ├─ main/
│  │  ├─ java/com/tofly/userservice/  # 包名反转域名 + 服务名
│  │  └─ resources/                    # 配置文件、静态资源
│  └─ test/
│   	   └─ java/
├─ pom.xml
└─ README.md                         # 该服务的独立说明
```

**Java 包名规范**：包名使用公司域名的倒序 + 服务名（移除短横线且驼峰命名）。

示例：`com.tofly.userservice`、`com.tofly.orderservice`

#### 服务间公共模块

公共库（如通用异常、DTO、工具类）放入 `backend/common-lib` 或 `backend/shared-kernel` 中，作为独立模块被其他服务依赖。

### 7.4 前端目录结构规范

#### 根目录命名

前端代码统一放在 `frontend/` 目录下。如果项目有多个前端应用（如管理端、用户端），使用子目录区分。

```
frontend/
├── admin/        # 管理后台
├── client/       # 用户端
└── shared/       # 跨前端应用的组件、样式、工具
```

#### 项目内部结构

```
client/
├── public/                 # 静态资源
├── src/
│   ├── api/                # API 请求模块（按业务域划分）
│   │   ├── common.ts      # 公共API (deleteCommon/downLoadData等)
│   │   └── {module}.ts    # 模块API (CRUD + 特殊接口)
│   ├── assets/             # 样式、图片等
│   ├── components/         # 公共组件（PascalCase 目录/文件名，如 UserTable.vue）
│   ├── composables/        # 组合式函数（useXxx.js）
│   ├── layouts/            # 布局组件
│   ├── router/             # 路由配置（index.js）
│   ├── stores/             # Pinia 状态管理（userStore.js）
│   ├── utils/              # 工具函数
│   │   ├── index.ts       # 公共工具 (getTreeDataFullPath等)
│   │   └── request.ts     # 请求客户端
│   ├── views/              # 页面视图
│   │   └── {module}/      # 模块目录（kebab-case 文件名）
│   │       ├── index.vue  # 列表页主入口
│   │       ├── config.ts  # 表格+表单配置
│   │       └── drawer.vue # 抽屉(新增/编辑/详情)
│   ├── locales/            # 国际化
│   ├── App.vue
│   └── main.js
├── .env.*                   # 环境变量
├── index.html
├── package.json
├── vite.config.mts
├── tsconfig.json
└── README.md
```

**命名规则**：
- 组件文件：单文件组件使用 **PascalCase** 命名，如 `UserProfile.vue`
- 目录：除 `components/` 和 `views/` 内的业务模块可自定义外，其他目录统一**小写 + 短横线或单数**（如 `composables`、`stores`）

### 7.5 移动端目录结构规范

移动应用代码统一放在 `mobile/` 目录下，按平台或应用划分。如果项目有多个 app（如综合管理 app、抄表 app、普查 app），使用子目录区分，全小写命名。

```
mobile/
├── manage/        # 综合管理app
├── meter/         # 抄表app
└── census/        # 普查app
```

#### 跨平台框架（UniApp）

**工程形态（强制）**：UniApp（Vue 3）须采用 **Vite + `@dcloudio/vite-plugin-uni`** 的 **CLI 可编译、可运行** 形态，在 `mobile/{app}/uniapp/` 根目录提供 `package.json`、`vite.config.js`、`index.html`，业务源码落在 **`src/`** 下；禁止仅依赖 HBuilderX 私有工程而无法 `npm install` / `npm run dev:h5` / `npm run build:h5`。可选仍用 HBuilderX 打开同一目录做可视化调试，但与 CLI **共用** `src` 与 `manifest`。依赖版本宜与官方 [dcloudio/uni-preset-vue（vite 分支）](https://github.com/dcloudio/uni-preset-vue/tree/vite) 对齐或整组升级。

```
mobile/manage/uniapp/
├── package.json           # 依赖与脚本（含 dev:h5 / build:h5 等）
├── vite.config.js       # Vite 配置，须引入 @dcloudio/vite-plugin-uni
├── index.html           # H5 入口 HTML
├── README.md            # 启动与联调说明（可选）
└── src/
    ├── pages/           # 页面文件存放目录
    │   ├── index/
    │   │   └── index.vue
    │   └── ...
    ├── static/          # 静态资源目录（图片、字体等）
    ├── components/      # 通用 Vue 组件目录
    ├── uni_modules/     # UniApp 插件模块目录
    ├── App.vue          # 应用入口组件
    ├── main.js          # 应用入口文件
    ├── manifest.json    # 核心配置（应用 ID、名称、权限、h5.devServer 等）
    ├── pages.json       # 页面路由、窗口样式、原生 TabBar 等
    └── uni.scss         # 全局样式变量
```

#### 原生 Android

```
mobile/manage/android/
├─ app/
│  ├─ libs/                          # 存放本地jar、aar包资源
│  ├─ src/
│  │  ├─ main/
│  │  │  ├─ java/com/tofly/appname/  # 包名
│  │  │  │  ├─ base/                 # 基础类+app应用入口
│  │  │  │  ├─ module/               # 业务功能
│  │  │  │  │  └─ {feature}/        # 功能模块（如 meter/抄表）
│  │  │  │  │     ├─ data/         # 业务实体数据
│  │  │  │  │     ├─ activity/     # 活动类
│  │  │  │  │     ├─ fragment/     # 碎片类
│  │  │  │  │     ├─ adapter/      # 适配器
│  │  │  │  │     └─ impl/         # 接口实现类
│  │  │  │  ├─ ui/                   # 自定义ui
│  │  │  │  └─ utils/                # 工具类
│  │  │  ├─ AndroidManifest.xml     # 清单文件
│  │  │  └─ res/                    # 静态资源（layout/, drawable/ 等，全小写+下划线）
│  │  └─ androidTest/
│  ├─ .gitgnore
│  ├─ proguard-rules.pro             # 混淆配置文件
│  └─ build.gradle                   # 模块配置文件
├─ graffiti/                          # 拍照涂鸦模块
├─ latte-core/                        # 网络框架+基础核心代码模块
├─ build.gradle                        # 项目配置文件
└─ README.md
```

#### 混合开发

```
mobile/
├── manage/
│   ├── h5/            # 前端H5页面，目录同§7.4前端目录结构规范
│   ├── android/       # 原生底座，目录同上方原生Android
```

### 7.6 共享代码与通用模块

| 类别 | 存放位置 | 说明 |
|---|---|---|
| 跨前后端协议/类型定义 | `shared/proto/`（gRPC/protobuf）或 `shared/openapi/`（OpenAPI 规范） | 接口契约 |
| 跨服务数据模型 | `shared/schemas/` | JSON Schema / Thrift / GraphQL Schema 等 |
| UI 组件库/设计系统 | `shared/ui-kit/` | 单独建仓库或作为 monorepo 包 |

### 7.7 文档与脚本

- **文档**：`docs/` 下按类别使用目录，如 `docs/architecture/`、`docs/api/`、`docs/deployment/`，使用 Markdown 文件
- **脚本**：`scripts/` 下放置 shell、Python 等辅助脚本，命名使用小写+下划线（如 `build_all.sh`、`deploy_stack.py`）

### 7.8 版本控制忽略文件

每个技术栈应配置正确的 `.gitignore`（可分层配置）：
1. 根目录 `.gitignore` 忽略 IDE、OS 和公共构建产物（如 `node_modules/`、`target/`、`*.log`）
2. 各子模块可拥有自己的 `.gitignore`（极少需要，推荐在根统一管理）

---

## 八、语言约束索引

> 各语言的详细编码规范、框架约束和代码模板已独立存放在 `language/` 文件夹下按语言分类的子目录中，按需动态加载。

| 语言 | 文件 | 主要内容 |
|---|---|---|
| **Java / Spring Boot / Tofly** | [language/java/java.md](./language/java/java.md) | Tofly 分层架构、Controller/Service/Mapper 规则、代码模板 |
| **Tofly Vue2** | [language/vue/vue2.md](./language/vue/vue2.md) | Vue2 专属语法、Element UI 模板、Flowable 页面模式 |
| **Vben Admin v2** | [language/vue/vben2.md](./language/vue/vben2.md) | Vben2 专属组件/Hooks、CRUD 代码模板、树形/分栏模式 |
| **Vben v3 (成堪数智)** | [language/vue/vben3.md](./language/vue/vben3.md) | Vben3 专属 EditTable+AddForm 四件套、Element Plus 模板、qiankun 微前端 |
| **Vue 3 / Vben Admin 5.0** | [language/vue/vue3.md](./language/vue/vue3.md) | Vben 5.0 Monorepo、路由/偏好配置、主题定制、环境变量 |
| **Python** | [language/python/python.md](./language/python/python.md) | PEP 8、类型注解、路径处理、依赖管理 |
| **Android (Ylgs)** | [language/android/java.md](./language/android/java.md) | LatteActivity/ViewBinding、Fastjson、GreenDao、Tab+Fragment 模板 |
| **数据库设计** | 规范正文：[rules/database-design.mdc](../../rules/db/database-design.mdc)；索引：[language/database/db-design.md](./language/database/db-design.md) | 命名规范、表/字段/索引设计、SQL编写、跨数据库兼容（MySQL/PG/Oracle/达梦） |

---

## 九、与 L2/L3 的关系

```
公司统一配置 (L1, 权重25)  ← 本文件（安全红线为只读，其余可被 L2/L3 覆盖）
    ↓ 被覆盖
仓库共享配置 (L2, 权重75)  ← 项目级技术栈、架构约定、构建命令
    ↓ 被覆盖
本地私有配置 (L3, 权重100)  ← 最高优先级，本地环境 + 个人偏好 + 用户习惯
    ↓ 被细化
语言约束文件 (language/*/)  ← 框架/版本专属模板与语法，不可覆盖 L1 安全红线
```

- **安全红线部分（§一）为只读规则**，L2/L3 不可覆盖
- 其余规则可被 L2/L3 合理覆盖
- 无法确定时，主动询问用户确认

---

*最后更新：2026-05-06*
*版本：5.1.0（3层架构版 + 项目目录与命名规范）*