129 lines
10 KiB
Markdown
129 lines
10 KiB
Markdown
# AI 开发入口 [!IMPORTANT]
|
||
|
||
- **本文档要求**：本文档为当前仓库的项目级规范和重要导航，进入源码前必须先读。
|
||
- **本文档要求**：优先在现有目录职责内做增删改；若要新增一级目录、基础设施或工程约定，必须先更新本文档和对应文档。
|
||
- **本文档要求**：后续新增/删除 `.ai-specs` 文档时，必须同步更新 `## 项目文档`。
|
||
- **文档要求**：规范型文档是给 AI 的顶层入口文档，要求短、硬、可判定，不写泛泛背景说明。
|
||
- **代码优化**：先复用再新增；允许抽公共逻辑，但边界必须清晰。
|
||
- **代码优化**：优化时必须同时考虑冗余、命名、复杂度、边界条件、兼容性和包体积，不能只追求功能跑通。不要擅自修改 UI/UX 视觉效果，除非需求明确。
|
||
- **代码默认遵循**：业务实现优先采用微信原生小程序主流做法，保持可维护、可调试、可发布。
|
||
- **代码默认遵循**：强制工作流：按 `## 项目文档` 定位需要的文档 -> 读取匹配文档 -> 进入源码。
|
||
|
||
## 工具使用规则
|
||
|
||
- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `node_modules`、`miniprogram_npm`、`coverage` 等生成或依赖目录。
|
||
- **读写**：所有文件读取/写入统一使用 UTF-8（建议无 BOM）。
|
||
- **读写**：PowerShell/脚本读取项目文件必须显式指定 `-Encoding utf8`。
|
||
- **生成产物**：不要直接编辑微信开发者工具生成目录，例如 `miniprogram_npm`。
|
||
- **画图**：优先使用 `mermaid flowchart`。
|
||
- **对话/文档编写**：必须以中文为主体语言，技术术语保留英文原文。
|
||
- **命令执行**：运行依赖、测试、格式化、CI 前，先读取 `package.json` 中已有 scripts，不重复发明命令入口。
|
||
|
||
## 项目架构
|
||
|
||
- **技术栈**：本项目为 `微信原生小程序 + JavaScript + npm + TDesign`，运行时采用 `glass-easel` 组件框架；工程化使用 `ESLint`、`Prettier`、`Jest`、`miniprogram-ci`。
|
||
- **代码链路**：本项目采用 `Page / Component -> services/api -> services/request -> RuntimeConfig / SessionStore -> Backend`。
|
||
- **状态与配置**：`config` 管理环境与常量，`stores` 管理跨页共享状态，`utils` 只放纯工具函数。
|
||
|
||
├── app.js / app.json / app.wxss (应用初始化、路由注册、全局样式)
|
||
├── pages (主包页面：首屏、登录、公共能力)
|
||
├── packages (分包页面，按业务域拆分)
|
||
├── components
|
||
│ ├── base (基础组件)
|
||
│ └── biz (业务组件)
|
||
├── services
|
||
│ ├── api (按业务模块封装接口)
|
||
│ └── request (统一请求、鉴权、重试、去重)
|
||
├── stores
|
||
│ └── modules (跨页共享状态)
|
||
├── config (环境配置、常量)
|
||
├── utils (纯工具函数)
|
||
├── tests (Jest 测试)
|
||
└── scripts/ci (小程序 CI 脚本)
|
||
|
||
| 层级 | 职责 | 命名规范 |
|
||
|:---|:---|:---|
|
||
| App | 初始化运行时配置、注册全局拦截与跳转、同步 `globalData` | 固定使用 `app.js`、`app.json`、`app.wxss` |
|
||
| Page | 承载页面数据、交互、路由跳转；不直接承载通用请求封装与跨页状态持久化 | 主包目录固定 `pages/<name>/index.*`；分包目录固定 `packages/<pkg>/pages/<name>/index.*` |
|
||
| Component | 承载可复用视图和局部交互，通过 `properties` / `events` 与页面通信 | 基础组件放 `components/base/<name>`；业务组件放 `components/biz/<name>` |
|
||
| API | 按业务封装接口方法，屏蔽 URL / Method / payload 细节；不直接持有页面 UI 状态 | 目录固定 `services/api/<module>.js`；聚合出口固定 `services/api/index.js` |
|
||
| Request | 统一处理 `baseURL`、header、token、超时、鉴权失效、重试和请求去重 | 目录固定 `services/request/index.js` |
|
||
| Store | 管理跨页共享和本地持久化状态；不与具体页面强耦合 | 模块固定 `stores/modules/<name>.js`；聚合出口固定 `stores/index.js` |
|
||
| Config | 管理环境、常量、timeout、storage key；避免魔法值散落 | 目录固定 `config/*.js` |
|
||
| Utils | 存放纯函数；禁止依赖页面实例、组件实例或全局 UI 状态 | 目录固定 `utils/*.js` |
|
||
|
||
- 主包只放首屏、登录、Tab 和全局公共能力；新业务页面优先考虑放进对应分包。
|
||
- 页面和组件里不要直接调用 `wx.request`；统一走 `services/request`。
|
||
- 跨页共享状态统一放 `stores`；页面局部状态留在 `Page` / `Component` 的 `data` 内。
|
||
- 环境切换、`baseURL` 和 `timeout` 统一走 `config/env.js` 与 `config/constants.js`。
|
||
- 新增接口模块时，先补 `services/api/<module>.js`，再决定页面如何消费；不要把请求细节散落到页面。
|
||
|
||
### 架构关系
|
||
|
||
- 关系总线：`Page / Component -> API -> Request -> Env + SessionStore -> Backend`，其中 `app.js` 负责运行时初始化、登录态同步和未授权跳转。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
APP["app.js<br/>运行时初始化 / 未授权跳转"] --> SESSION["stores/modules/session.js<br/>登录态持久化"]
|
||
PAGE["Page / Component"] --> API["services/api/*.js"]
|
||
PAGE --> COMPONENT["components/base + components/biz"]
|
||
API --> REQUEST["services/request/index.js"]
|
||
REQUEST --> ENV["config/env.js"]
|
||
REQUEST --> SESSION
|
||
SESSION --> STORAGE["wx storage"]
|
||
REQUEST --> BACKEND["Backend API"]
|
||
```
|
||
|
||
- 改 `app.json`：必须同步检查 `pages`、`subPackages`、`preloadRule`、实际目录路径和页面跳转路径是否一致。
|
||
- 改 `pages/*` 或 `packages/*`：必须同步检查路由注册、导航目标、页面 JSON 中的组件注册、对应 API / Store 依赖。
|
||
- 改 `components/base/*` 或 `components/biz/*`：必须同步检查 `index.js`、`index.json`、`index.wxml`、`index.wxss` 四件套，以及引用方的 `properties` / `events` 契约。
|
||
- 改 `services/api/*`：必须同步检查 URL、Method、payload、response contract 和所有调用页的 loading / error / empty state。
|
||
- 改 `services/request/index.js`：必须同步检查 `config/env.js`、`config/constants.js`、`stores/modules/session.js`、`app.js` 的未授权处理，以及所有 API 模块的调用预期。
|
||
- 改 `stores/modules/session.js`：必须同步检查 storage key、`app.js` 中的 hydrate / subscribe、登录页和依赖权限的页面逻辑。
|
||
- 改 `config/env.js` 或 `config/constants.js`：必须同步检查请求层默认值、环境切换行为、CI 脚本和登录态相关逻辑。
|
||
- 新增/修改业务功能时，默认顺序是：先定页面归属与路由 -> 再定 API / Store 契约 -> 再落页面与组件 -> 最后回查 `app.json`、聚合导出和项目文档；禁止只改单点不回查上下游。
|
||
|
||
## 项目文档
|
||
|
||
- **当前已启用文档**：根目录 `README.md`、`.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md`、`.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md`、`.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-implementation-plan.md`
|
||
- **预留扩展目录**：`.ai-specs`（已创建；后续新增/删除文档必须在本节登记）
|
||
- **要求**：开始修改前，先按任务类型定位文档；有对应文档必须先读；未命中时按本文件通用规则和现有同层代码风格实现。
|
||
|
||
### root-docs
|
||
|
||
| 路径 | 用途 | 说明 |
|
||
|:---|:---|:---|
|
||
| `README.md` | 项目启动、目录、命令、CI、分包落点说明 | 涉及本地运行、构建 npm、测试、格式化、CI 上传、目录归属时必读 |
|
||
|
||
### .ai-specs 规划
|
||
|
||
| 分类 | 用途 | 说明 |
|
||
|:---|:---|:---|
|
||
| `coding-specs` | 存放页面分包、接口封装、状态管理、组件复用等实现规范 | 仓库复杂度上来后优先补齐 |
|
||
| `logic-specs` | 存放业务流程、页面信息架构、角色权限等业务说明 | 涉及多页面串联和复杂交互时补齐 |
|
||
| `sys-specs` | 存放环境、发布、CI、版本管理等系统级规则 | 涉及发布流程和工程治理时补齐 |
|
||
|
||
### .ai-specs 已启用文档
|
||
|
||
| 路径 | 用途 | 说明 |
|
||
|:---|:---|:---|
|
||
| `.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md` | `pages/profile/index` 未登录态静态页面设计 | 涉及本页结构复刻、静态数据组织、样式边界与验收范围时必读 |
|
||
| `.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md` | `frontend` 老项目静态页面迁移设计 | 涉及旧项目页面迁移、分包归属、静态数据边界、导航与交互约束时必读 |
|
||
| `.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-implementation-plan.md` | `frontend` 老项目静态页面迁移实施计划 | 涉及实现顺序、文件落点、测试策略和分任务执行时必读 |
|
||
|
||
### 后端接口文档
|
||
D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-dict 字典参考
|
||
D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-api\admin 后端 api文档
|
||
|
||
## 可复用代码/组件
|
||
|
||
| 中文 | 代码文件名 | 说明 |
|
||
|:---|:---|:---|
|
||
| 统一请求封装 | `services/request/index.js` | 统一处理 `baseURL`、token 注入、鉴权失效、超时、重试和请求去重 |
|
||
| 用户接口模块 | `services/api/user.js` | 用户资料查询与更新的 API 封装示例 |
|
||
| Session Store | `stores/modules/session.js` | 登录态持久化、hydrate、订阅变更 |
|
||
| Store 聚合出口 | `stores/index.js` | 统一导出 store，供 `app.js` 和页面引用 |
|
||
| App Button | `components/base/app-button` | 基础按钮组件，透出常用主题、尺寸和形态 |
|
||
| Entry Card | `components/biz/entry-card` | 首页 / 工作台入口卡片组件 |
|
||
| 运行时环境配置 | `config/env.js` | 根据微信环境选择 `baseURL` 与 `timeout` |
|