公司统一配置

第一层级配置（权重: 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 技术选型决策框架

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

必须满足的硬性条件（任一不通过则不可选用）

活跃维护：项目在过去 6 个月内有持续 commit 和 issue 响应
社区规模：有足够的使用者基数，非单人维护的"玩具项目"
许可证合规：许可证类型符合公司法务要求
安全记录：无已知的高危安全漏洞未修复
版本策略：有明确的版本发布计划和 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）	按语言对应

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

命名与可读性

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

函数与方法

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

错误处理

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

代码组织

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

个人加严偏好（可被 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 标准

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

五、协作、沟通与 AI 行为

5.1 沟通与响应风格

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

5.2 代码注释规范

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

5.2.1 通用原则

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

5.2.2 注释格式模板

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

// #region {RegionName}

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

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

// #endregion

② 函数/方法注释

// #region {RegionName}

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

// #endregion

③ 枚举注释

// #region {RegionName}

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

// #endregion

④ 配置项/常量注释

// #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 行为偏好

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

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

本节定义所有前端项目（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 流程

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

七、项目目录与命名规范

基于 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 分支）对齐或整组升级。

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（可分层配置）：

根目录 .gitignore 忽略 IDE、OS 和公共构建产物（如 node_modules/、target/、*.log）
各子模块可拥有自己的 .gitignore（极少需要，推荐在根统一管理）

八、语言约束索引

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

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

company_unified_config.md 32 KB History Raw