adspecs 0.1.12

package/.adspecs/templates/19-/351/241/271/347/233/256/347/233/256/345/275/225/347/273/223/346/236/204/346/250/241/346/235/277.md

@@ -0,0 +1,468 @@
+# {项目名称} — 项目目录结构
+
+> **版本**: v{版本号}
+> **创建日期**: {创建日期}
+> **最后更新**: {更新日期}
+> **仓库**: `{仓库名称}`
+
+### 修订记录
+
+| 版本号 | 修订日期 | 修订人   | 修订内容                       |
+| ------ | -------- | -------- | ------------------------------ |
+| v1.0   | {日期}   | {修订人} | 初始版本：基于实际目录结构编写 |
+
+---
+
+## 一、仓库概览
+
+本仓库（`{仓库名称}`）是{项目描述}的 Monorepo，包含：
+
+| 目录               | 类型           | 用途                           | 技术栈       |
+| ------------------ | -------------- | ------------------------------ | ------------ |
+| `{后端demo目录}/`  | Java 后端 Demo | {平台}参考项目（3 模块 Maven） | {后端技术栈} |
+| `{前端shell目录}/` | Vue 3 前端     | 管理后台 Shell                 | {前端技术栈} |
+| `{业务前端目录}/`  | Vue 3 前端     | {项目简称}业务前端             | {前端技术栈} |
+| `{后端服务目录}/`  | Java 后端      | {项目简称}微服务后端           | {后端技术栈} |
+| `docs/`            | 文档           | 需求、架构、规范、模板         | Markdown     |
+<!-- 按项目实际目录增减 -->
+
+**根目录文件：**
+
+| 文件         | 用途                          |
+| ------------ | ----------------------------- |
+| `CLAUDE.md`  | 仓库全局指引，AI 辅助开发入口 |
+| `.gitignore` | Git 忽略规则                  |
+
+**隐藏目录：**
+
+| 目录         | 用途                              |
+| ------------ | --------------------------------- |
+| `.claude/`   | Claude Code 配置                  |
+| `.adspecs/`  | 插件配置、模板（templates/）、脚本 |
+<!-- 按项目实际隐藏目录填写 -->
+
+---
+
+## 二、文档目录（`docs/`）
+
+```
+docs/
+├── 00-customer-requirements/              # 客户原始需求
+│   └── {需求文档}                         #   {说明}
+│
+├── 10-architecture/                       # 架构设计文档
+│   ├── 01-{项目简称}_business_scenarios.md   #   综合业务场景（v{版本号}）
+│   ├── 02-{项目简称}_system_architecture.md  #   系统架构设计（v{版本号}）
+│   ├── 03-{项目简称}_sub_module_dependencies.md # 子模块依赖关系（v{版本号}）
+│   ├── 04-{项目简称}_unified_data_model.md     # 统一数据模型（v{版本号}）
+│   └── 05-project_directory_structure.md       # 项目目录结构（本文档）
+│
+├── 20-prd/                                # 产品需求文档（PRD）
+│   └── {模块名}/                          #   {模块} PRD
+│       └── {子模块}/                      #     {子模块} PRD
+│           ├── {需求规格说明书}.md
+│           ├── {功能规格说明书}.md
+│           └── checklists/
+│
+├── 30-system-design/                      # 系统设计规格
+│   └── {模块名}/                          #   {模块}详细设计
+│       ├── {系统设计文档}.md
+│       ├── {需求分析文档}.md
+│       └── {DDL脚本}.sql
+│
+├── 40-project_conventions/                # 项目编码规范
+│   ├── {后端规范目录}/                     #   后端规范（{N} 份）
+│   │   ├── 后端分层开发与数据库设计规范.md
+│   │   ├── ES使用规范.md
+│   │   ├── Redis使用规范.md
+│   │   ├── 分布式锁规范.md
+│   │   ├── 多语言及全局异常处理规范.md
+│   │   ├── 文件中心使用规范.md
+│   │   ├── 流程中心接入规范.md
+│   │   ├── IdToName使用规范.md
+│   │   ├── Liquibase 数据库变更管理规范.md
+│   │   ├── 编码自动生成规范.md
+│   │   └── 通用工具类使用规范.md
+│   └── {前端规范目录}/                     #   前端规范（{N} 份）
+│       ├── INDEX.md
+│       ├── project-overview.md
+│       ├── 前端编码规范.md
+│       ├── api-i18n-rules.md
+│       ├── 组件使用规范.md
+│       ├── page-development-rules.md
+│       └── page-template-index.md
+│
+├── 70-scripts/                            # 脚本工具（按环境分目录）
+│   ├── dev/                               #   开发环境
+│   ├── test/                              #   测试环境
+│   ├── uat/                               #   UAT 环境
+│   └── prod/                              #   生产环境
+│
+├── 80-development/                        # 开发和测试文档
+│
+├── 90-wiki/                               # Wiki 知识库
+│
+└── {规格文档目录}/                         # 功能规格说明书
+    ├── {spec文件1}.md
+    ├── {spec文件2}.md
+    └── ...
+```
+
+---
+
+## 三、后端 Demo（`{后端demo目录}/`）
+
+{平台}的代码参考项目，展示标准的三模块 Maven 结构和编码范式。
+
+### 3.1 模块划分
+
+```
+{后端demo目录}/
+├── pom.xml                                # 父 POM（{artifactId}）
+├── README.md
+│
+├── {端口}-demo-api/                       # API 模块：DTO + Feign 接口
+│   ├── pom.xml
+│   └── src/main/java/{包路径}/
+│       └── api/
+│           ├── client/                    #   Feign 客户端接口定义
+│           └── dto/                       #   传输 DTO
+│
+├── {端口}-demo-model/                     # Model 模块：实体 + DAO + XML
+│   ├── pom.xml
+│   └── src/main/java/{包路径}/
+│       ├── infra/                         #   常量/工具类
+│       └── model/
+│           ├── dao/                       #   DAO 接口 + MyBatis XML
+│           │   ├── {Entity}DAO.java
+│           │   └── {Entity}DAO.xml
+│           └── entity/                    #   实体类
+│               ├── {Entity}Entity.java
+│               └── readonly/              #   只读组合对象（Ro）
+│                   └── {Entity}EntityRo.java
+│
+└── {端口}-demo-application/               # Application 模块
+    ├── pom.xml
+    ├── Dockerfile                         #   多阶段 Docker 构建
+    └── src/main/
+        ├── java/{包路径}/
+        │   ├── {App}Application.java      #   启动类
+        │   ├── api/controller/            #   REST 控制器
+        │   ├── app/consume/               #   消息消费
+        │   ├── infra/config/              #   配置类
+        │   └── model/service/             #   Service 层
+        │       ├── II{Entity}.java
+        │       └── impl/
+        │           └── {Entity}Service.java
+        └── resources/
+            ├── application-{配置名}.yml   #   主配置
+            ├── bootstrap.properties       #   注册中心配置
+            ├── logback-spring.xml         #   日志配置
+            └── config/                    #   i18n 国际化
+```
+
+### 3.2 分层职责速查
+
+| 层         | 所属模块    | 基类                                     | 注解                                 | 关键约束                                  |
+| ---------- | ----------- | ---------------------------------------- | ------------------------------------ | ----------------------------------------- |
+| Entity     | model       | `BaseEntity<T>`                          | `@TableName` `@TableField` `@Schema` | 主键 `Long` + `IdType.ASSIGN_ID`          |
+| DTO        | api         | `ReqeustCommonDataBean`                  | `@JSONField` 校验分组                | 日期格式 `yyyy-MM-dd HH:mm:ss`            |
+| Ro         | model       | `Serializable`                           | —                                    | 手动字段声明，不映射表                    |
+| DAO        | model       | `BaseCommonDAO_HI<T>`                    | `@Component`                         | **禁止 QueryWrapper**，必须写 MyBatis XML |
+| Service    | application | `IBaseCommon<T>` / `BaseCommonServer<T>` | `@Component`                         | 接口 `II{Entity}` 双 I 前缀               |
+| Controller | application | `CommonAbstractService`                  | `@CheckToken`                        | 标准 REST 路径                            |
+
+### 3.3 标准文件清单（新增一个 CRUD 资源）
+
+以 `{示例Entity}` 为参考，新增一个标准 CRUD 资源需要以下 **11 类文件**：
+
+| #   | 文件                      | 模块         | 说明                                           |
+| --- | ------------------------- | ------------ | ---------------------------------------------- |
+| 1   | `{Entity}Dto.java`        | -api         | DTO，含 `saveXxx` / `updateXxx` 分组接口       |
+| 2   | `{Entity}Entity.java`     | -model       | 实体，`@TableName` + `@TableField` + `@Schema` |
+| 3   | `{Entity}EntityRo.java`   | -model       | 只读对象，手动声明字段                         |
+| 4   | `{Entity}DAO.java`        | -model       | DAO 接口，`@Component`                         |
+| 5   | `{Entity}DAO.xml`         | -model       | MyBatis XML，`resultMap` 含全部字段            |
+| 6   | `II{Entity}.java`         | -application | Service 接口，双 I 前缀                        |
+| 7   | `{Entity}Service.java`    | -application | Service 实现，`@Component`                     |
+| 8   | `{Entity}Controller.java` | -application | REST 控制器，`@CheckToken`                     |
+| 9   | `{Entity}ResponseMsgCode` | -application | 消息码枚举                                     |
+| 10  | 7 个 `*.properties`       | -application | i18n 国际化文件                                |
+| 11  | Liquibase changelog       | -application | 数据库变更管理（DDL/DML）                      |
+
+---
+
+## 四、前端管理后台 Shell（`{前端shell目录}/`）
+
+{前端框架}管理后台 Shell 应用，提供动态路由、微前端、动态表单和自定义报表等基础能力。
+
+### 4.1 根目录文件
+
+```
+{前端shell目录}/
+├── package.json                  # 项目配置与依赖
+├── index.html                    # HTML 入口
+├── vite.config.ts                # Vite 构建配置
+├── eslint.config.ts              # ESLint 配置
+├── .prettierrc.json              # Prettier 配置
+├── .editorconfig
+├── .npmrc                        # 私有仓库配置
+├── env.d.ts                      # 环境变量类型声明
+├── auto-imports.d.ts             # unplugin-auto-import 生成
+├── components.d.ts               # unplugin-vue-components 生成
+├── README.md
+├── public/                       # 静态资源
+│   ├── favicon.ico
+│   ├── apiurls.js                # API 地址配置
+│   └── config.js
+└── src/                          # 源代码
+```
+
+### 4.2 源码目录（`src/`）
+
+```
+src/
+├── main.ts                       # 应用入口
+├── App.vue                       # 根组件
+├── permission.ts                 # 路由权限守卫
+│
+├── api/                          # API 接口模块（按业务域分包）
+│   ├── login.ts
+│   ├── attachment.ts             #   附件 API（文件中心）
+│   ├── export.ts
+│   └── {业务模块}/               #   业务 API
+│
+├── components/                   # 全局组件
+│   ├── global-register.ts
+│   └── {组件目录}/
+│
+├── icons/                        # SVG 图标库
+│
+├── lang/                         # i18n 国际化
+│   └── modules/
+│       └── {模块语言包}/
+│
+├── plugins/                      # 插件配置
+│
+├── router/                       # 路由配置
+│
+├── store/                        # Pinia 状态管理
+│   └── modules/
+│       ├── app/
+│       ├── permission/
+│       ├── tagsView/
+│       ├── theme/
+│       └── user/
+│
+├── styles/                       # 样式
+│   └── theme/
+│
+├── utils/                        # 工具函数
+│
+└── views/                        # 页面视图
+    ├── layout/                   #   布局
+    ├── login/                    #   登录页
+    ├── home-page/                #   首页
+    └── {业务页面}/               #   业务页面
+```
+
+### 4.3 技术栈速查
+
+| 分类     | 技术       | 版本   |
+| -------- | ---------- | ------ |
+| 框架     | Vue 3      | {版本} |
+| 语言     | TypeScript | {版本} |
+| UI 库    | {UI框架}   | {版本} |
+| 构建     | Vite       | {版本} |
+| 状态管理 | Pinia      | {版本} |
+| 路由     | vue-router | {版本} |
+| 国际化   | vue-i18n   | {版本} |
+<!-- 按项目实际技术栈填写 -->
+
+### 4.4 常用命令
+
+| 命令             | 说明                          |
+| ---------------- | ----------------------------- |
+| `npm install`    | 安装依赖                      |
+| `npm run dev`    | 启动开发服务器（端口 {端口}） |
+| `npm run build`  | 类型检查 + 生产构建           |
+| `npm run lint`   | ESLint 检查（自动修复）       |
+| `npm run format` | Prettier 格式化               |
+
+---
+
+## 五、{项目简称}前端（`{业务前端目录}/`）
+
+{项目简称}业务前端项目，基于`{前端shell目录}`同源模板，结构与 §4 基本一致，差异在于 API 和页面模块为业务定制。
+
+### 5.1 与 {前端shell目录} 的主要差异
+
+| 差异项   | {前端shell目录}    | {业务前端目录}     |
+| -------- | ------------------ | ------------------ |
+| 定位     | 通用管理后台 Shell | {项目简称}业务前端 |
+| API 模块 | {通用模块}         | {业务模块}         |
+| 页面视图 | {通用页面}         | {业务页面}         |
+
+---
+
+## 六、{项目简称}后端微服务（`{后端服务目录}/`）
+
+> 后端按微服务拆分，每服务独立的三模块结构（`-api` / `-model` / `-application`）。
+
+### 6.1 已实现服务
+
+```
+{后端服务目录}/
+│
+├── {端口}-{服务名}/                           # {服务描述} — {分期}
+│   ├── pom.xml
+│   ├── .gitignore
+│   ├── {端口}-{服务名}-api/                   #   API 模块
+│   │   ├── pom.xml
+│   │   └── src/main/java/{包路径}/
+│   │       └── api/dto/
+│   │           └── {Dto名称}.java
+│   ├── {端口}-{服务名}-model/                 #   Model 模块
+│   │   ├── pom.xml
+│   │   └── src/main/java/{包路径}/
+│   │       └── model/
+│   │           ├── dao/
+│   │           │   ├── {DAO名称}.java
+│   │           │   └── {DAO名称}.xml
+│   │           └── entity/
+│   │               ├── {Entity名称}.java
+│   │               └── readonly/
+│   │                   └── {Entity名称}Ro.java
+│   └── {端口}-{服务名}-application/           #   Application 模块
+│       ├── pom.xml
+│       ├── Dockerfile
+│       └── src/main/
+│           ├── java/{包路径}/
+│           │   ├── {App}Application.java
+│           │   ├── api/controller/
+│           │   │   └── {Controller名称}.java
+│           │   ├── model/service/
+│           │   │   ├── II{Entity名称}.java
+│           │   │   └── impl/
+│           │   │       └── {Entity名称}Service.java
+│           │   └── infra/config/
+│           └── resources/
+│               ├── application-{配置名}.yml
+│               ├── bootstrap.properties
+│               ├── logback-spring.xml
+│               └── config/                    #   i18n（7 properties）
+│
+<!-- 为每个已实现服务复制此结构 -->
+```
+
+### 6.2 远期服务规划
+
+> 以下服务尚未创建代码目录，仅作端口预留和模块规划参考。
+
+| 服务     | 端口   | 包含模块   | 分期   | 说明   |
+| -------- | ------ | ---------- | ------ | ------ |
+| {服务名} | {端口} | {模块列表} | {分期} | {说明} |
+<!-- 按项目实际规划填写 -->
+
+### 6.3 服务端口速查
+
+| 端口   | 服务               | 状态            |
+| ------ | ------------------ | --------------- |
+| {端口} | {服务名}（{描述}） | {已实现/规划中} |
+<!-- 按项目实际端口填写 -->
+
+---
+
+## 七、路径规范
+
+### 7.1 路径表示约定
+
+AI 辅助开发中统一使用**相对路径**（相对于仓库根目录 `{仓库根路径}`），使用正斜杠 `/`：
+
+```
+docs/10-architecture/01-{项目简称}_business_scenarios.md
+{后端demo目录}/{模块}/src/main/java/{包路径}/entity/{Entity}.java
+{后端服务目录}/{服务}/{模块}/src/main/java/{包路径}/entity/{Entity}.java
+{业务前端目录}/src/views/{页面}/index.vue
+```
+
+### 7.2 路径分隔符
+
+- 文档和 AI 工具输入输出：正斜杠 `/`（跨平台兼容）
+- Windows 实际路径：反斜杠 `\`
+- 包路径：点 `.`（`{包路径示例}`）
+
+---
+
+## 八、文档路径索引（AI 辅助开发常用）
+
+### 8.1 架构与业务（必读）
+
+| 文档         | 路径                                                            | 用途                                    |
+| ------------ | --------------------------------------------------------------- | --------------------------------------- |
+| 仓库全局指引 | `CLAUDE.md`                                                     | 项目结构和开发约定总览                  |
+| 业务场景     | `docs/10-architecture/01-{项目简称}_business_scenarios.md`      | 模块定义、业务场景、分阶段规划          |
+| 系统架构     | `docs/10-architecture/02-{项目简称}_system_architecture.md`     | 技术栈、架构设计、规范、检查清单        |
+| 子模块依赖   | `docs/10-architecture/03-{项目简称}_sub_module_dependencies.md` | 子模块依赖矩阵、事件清单、集成测试      |
+| 统一数据模型 | `docs/10-architecture/04-{项目简称}_unified_data_model.md`      | 聚合根、实体、枚举、事件Schema、共享DTO |
+| 项目目录结构 | `docs/10-architecture/05-project_directory_structure.md`        | 本文档                                  |
+
+### 8.2 开发规范（强制）
+
+| 文档               | 路径                                                                         |
+| ------------------ | ---------------------------------------------------------------------------- |
+| 后端分层与 DB 设计 | `docs/40-project_conventions/{后端规范目录}/后端分层开发与数据库设计规范.md` |
+| 多语言与异常处理   | `docs/40-project_conventions/{后端规范目录}/多语言及全局异常处理规范.md`     |
+| Redis 使用规范     | `docs/40-project_conventions/{后端规范目录}/Redis使用规范.md`                |
+| ES 使用规范        | `docs/40-project_conventions/{后端规范目录}/ES使用规范.md`                   |
+| 分布式锁规范       | `docs/40-project_conventions/{后端规范目录}/分布式锁规范.md`                 |
+| 文件中心规范       | `docs/40-project_conventions/{后端规范目录}/文件中心使用规范.md`             |
+| 流程中心规范       | `docs/40-project_conventions/{后端规范目录}/流程中心接入规范.md`             |
+| Liquibase 规范     | `docs/40-project_conventions/{后端规范目录}/Liquibase 数据库变更管理规范.md` |
+| 编码自动生成规范   | `docs/40-project_conventions/{后端规范目录}/编码自动生成规范.md`             |
+| 通用工具类规范     | `docs/40-project_conventions/{后端规范目录}/通用工具类使用规范.md`           |
+| 前端编码规范       | `docs/40-project_conventions/{前端规范目录}/前端编码规范.md`                 |
+
+### 8.3 Demo 参考代码
+
+| 文件         | 路径                                                                         |
+| ------------ | ---------------------------------------------------------------------------- |
+| 父 POM       | `{后端demo目录}/pom.xml`                                                     |
+| Entity 示例  | `{后端demo目录}/{模块}/src/main/java/{包}/entity/{Entity}.java`              |
+| DTO 示例     | `{后端demo目录}/{模块}/src/main/java/{包}/dto/{Dto}.java`                    |
+| DAO 示例     | `{后端demo目录}/{模块}/src/main/java/{包}/dao/{Dao}.java`                    |
+| DAO XML 示例 | `{后端demo目录}/{模块}/src/main/java/{包}/dao/{Dao}.xml`                     |
+| Ro 示例      | `{后端demo目录}/{模块}/src/main/java/{包}/entity/readonly/{Entity}Ro.java`   |
+| Service 接口 | `{后端demo目录}/{模块}/src/main/java/{包}/service/II{Entity}.java`           |
+| Service 实现 | `{后端demo目录}/{模块}/src/main/java/{包}/service/impl/{Entity}Service.java` |
+| Controller   | `{后端demo目录}/{模块}/src/main/java/{包}/controller/{Controller}.java`      |
+| 启动类       | `{后端demo目录}/{模块}/src/main/java/{包}/{App}Application.java`             |
+| 应用配置     | `{后端demo目录}/{模块}/src/main/resources/application-{配置}.yml`            |
+| Dockerfile   | `{后端demo目录}/{模块}/Dockerfile`                                           |
+| i18n 示例    | `{后端demo目录}/{模块}/src/main/resources/config/{配置}_zh_CN.properties`    |
+
+### 8.4 {项目简称}后端参考
+
+| 文件                | 路径                                                                              |
+| ------------------- | --------------------------------------------------------------------------------- |
+| {服务} 父 POM       | `{后端服务目录}/{服务}/pom.xml`                                                   |
+| {Entity} Entity     | `{后端服务目录}/{服务}/{model模块}/src/main/java/{包}/entity/{Entity}.java`       |
+| {Entity} DTO        | `{后端服务目录}/{服务}/{api模块}/src/main/java/{包}/dto/{Dto}.java`               |
+| {Entity} DAO        | `{后端服务目录}/{服务}/{model模块}/src/main/java/{包}/dao/{Dao}.java`             |
+| {Entity} Controller | `{后端服务目录}/{服务}/{app模块}/src/main/java/{包}/controller/{Controller}.java` |
+
+### 8.5 前端参考
+
+| 路径                                   | 说明               |
+| -------------------------------------- | ------------------ |
+| `{前端shell目录}/src/api/`             | API 接口模块示例   |
+| `{前端shell目录}/src/store/modules/`   | Pinia 状态管理示例 |
+| `{前端shell目录}/src/views/`           | 页面视图示例       |
+| `{前端shell目录}/src/components/`      | 全局组件           |
+| `{前端shell目录}/src/lang/`            | i18n 语言包示例    |
+| `{业务前端目录}/src/api/{业务模块}/`   | 业务 API 示例      |
+| `{业务前端目录}/src/views/{业务页面}/` | 业务页面示例       |
+
+---
+
+*本文档基于 `{仓库名称}` 仓库实际目录结构编写，版本 v{版本号}。*